{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pedotransfer Functions\n",
    "\n",
    "*Martin Vonk (2025)*\n",
    "\n",
    "## Overview\n",
    "\n",
    "Pedotransfer functions (PTFs) are empirical relationships that estimate soil hydraulic parameters from easily measured soil properties. They solve a practical problem: direct measurement of soil hydraulic properties is expensive and time-consuming, but soil particle size distribution and bulk density are relatively quick to measure.\n",
    "\n",
    "`pedon` implements multiple pedotransfer functions from the literature, allowing you to estimate soil hydraulic parameters when:\n",
    "- Particle size distribution (sand, silt, clay percentages) is known\n",
    "- Bulk density and organic matter content are available\n",
    "- Only limited data has been measured\n",
    "\n",
    "This notebook demonstrates several PTF methods and shows how their predictions compare."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "import pedon as pe"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a Soil Sample\n",
    "\n",
    "To use pedotransfer functions, we first create a `SoilSample` with measured soil properties. Let's use a typical loamy soil with moderate sand content."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create soil sample\n",
    "sand_p = 50  # sand [%]\n",
    "silt_p = 20  # silt [%]\n",
    "clay_p = 30  # clay [%]\n",
    "rho = 1.5  # bulk density [g/cm3]\n",
    "om_p = 10  # organic matter [%]\n",
    "m50 = 150  # median sand fraction [um]\n",
    "ts = False  # topsoil boolean\n",
    "\n",
    "ss = pe.SoilSample(\n",
    "    sand_p=sand_p, silt_p=silt_p, clay_p=clay_p, rho=rho, om_p=om_p, m50=m50\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Available Pedotransfer Functions\n",
    "\n",
    "`pedon` provides several PTF options. Each has different input requirements and outputs. Apply one or more PTFs to see predictions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# wosten pedotransfer function (van Genuchten)\n",
    "wos = ss.wosten(ts=ts)\n",
    "\n",
    "# wosten pedotransfer function for sand (van Genuchten)\n",
    "woss = ss.wosten_sand(ts=ts)\n",
    "\n",
    "# wosten pedotransfer function for clay (van Genuchten)\n",
    "wosc = ss.wosten_clay()\n",
    "\n",
    "# cosby pedotransfer function (Brook-Corey)\n",
    "cosb = ss.cosby()\n",
    "\n",
    "# rosetta database (options between version 1, 2 and 3)\n",
    "ros = ss.rosetta(version=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# More extensive plot method\n",
    "f, axs = plt.subplots(1, 2, figsize=(8, 6), sharey=True, layout=\"tight\")\n",
    "\n",
    "pe.plot_swrc(wos, ax=axs[0], label=\"Wosten\")\n",
    "pe.plot_swrc(woss, ax=axs[0], label=\"Wosten Sand\")\n",
    "pe.plot_swrc(wosc, ax=axs[0], label=\"Wosten Clay\")\n",
    "pe.plot_swrc(cosb, ax=axs[0], label=\"Cosby\")\n",
    "pe.plot_swrc(ros, ax=axs[0], label=\"Rosetta\")\n",
    "\n",
    "axs[0].set(\n",
    "    yscale=\"log\",\n",
    "    title=\"Soil Water Retention Curve\",\n",
    "    xlabel=\"\\N{GREEK SMALL LETTER THETA} [-]\",\n",
    "    xlim=(0, 0.5),\n",
    "    ylabel=\"|\\N{GREEK SMALL LETTER PSI}| [cm]\",\n",
    ")\n",
    "axs[0].legend(loc=\"lower left\")\n",
    "\n",
    "\n",
    "pe.plot_hcf(wos, ax=axs[1], label=\"Wosten\")\n",
    "pe.plot_hcf(woss, ax=axs[1], label=\"Wosten Sand\")\n",
    "pe.plot_hcf(wosc, ax=axs[1], label=\"Wosten Clay\")\n",
    "pe.plot_hcf(cosb, ax=axs[1], label=\"Cosby\")\n",
    "pe.plot_hcf(ros, ax=axs[1], label=\"Rosetta\")\n",
    "\n",
    "axs[1].set(\n",
    "    yscale=\"log\",\n",
    "    xscale=\"log\",\n",
    "    title=\"Hydraulic Conductivity Function\",\n",
    "    xlabel=\"Ks [cm/d]\",\n",
    "    xlim=(1e-10, 1e3),\n",
    ")\n",
    "axs[1].legend(loc=\"lower left\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The plots above compare the predictions of different PTFs. Notice how different methods can give quite different results, particularly for the hydraulic conductivity function. This highlights the uncertainty inherent in PTFs and the importance of validating with measured data when possible."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "If you have measured data (water retention or conductivity values), proceed to the **Curve Fitting** notebook to refine these estimates. If you only have a single measurement (e.g., saturated conductivity), try the **HYPAGS** notebook for parameter estimation from limited data."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "pedon (3.13.5)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.5"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}