ptfkit.dharumarajan2019

def calc_ptf_dharumarajan2019_infiltration(
    *,
    sand: float | ArrayLike,
    silt: float | ArrayLike,
    clay: float | ArrayLike,
    out: NDArray[floating] | None = None,
) -> floating | NDArray[floating]:
    """Estimate infiltration rate for Karnataka soils from texture fractions.

    Arguments:
        sand: Sand content in the Karnataka infiltration dataset. (%)
        silt: Silt content in the Karnataka infiltration dataset. (%)
        clay: Clay content in the Karnataka infiltration dataset. (%)
        out: Optional output arrays for in-place calculation.

    Returns:
        infiltration_rate: Soil infiltration rate measured with a double-ring infiltrometer. (mm/h)

    Territory:
        Karnataka, India

    Models:
        $k(h)$: Multiple linear regression for infiltration rate

    Notes:
        Prediction target: Infiltration rate from sand, silt, and clay contents.
        The model was fitted to 100 Karnataka soil observations.
        The reported model R-squared is 41%, and the reported RMSE is 6.71%.

    Warning:
        Predictor calibration ranges are not reported for the 100-observation dataset.

    """
    return _call(
        _calc_ptf_dharumarajan2019_infiltration,
        sand,
        silt,
        clay,
        out=out,
    )

def calc_ptf_dharumarajan2019_nkp(
    *,
    clay: float | ArrayLike,
    sand: float | ArrayLike,
    cation_exchange_capacity: float | ArrayLike,
    out: Dharumarajan2019WaterRetentionResult[NDArray[floating]] | None = None,
) -> (
    Dharumarajan2019WaterRetentionResult[floating]
    | Dharumarajan2019WaterRetentionResult[NDArray[floating]]
):
    r"""Estimate field capacity and wilting point for Northern Karnataka soils.

    Arguments:
        clay: Clay content. (%)
        sand: Sand content. (%)
        cation_exchange_capacity: Cation exchange capacity. (C mol p+/kg)
        out: Optional output arrays for in-place calculation.

    Returns:
        Dharumarajan2019WaterRetentionResult: Results grouped by result attributes.

    Territory:
        Northern Karnataka Plateau

    Models:
        $h(\theta)$: Point water-retention estimates from multiple linear regression

    Notes:
        Prediction target: Water content at field capacity and permanent wilting point from clay,
            sand, and cation exchange capacity.
        The model was fitted to 512 soil-layer observations.
        Reported cross-validation RMSE values are 5.25% for FC and 3.71% for PWP.

    Warning:
        The paper does not state whether its water-content percentages are gravimetric or
            volumetric.
        The source gives inconsistent profile counts and district lists for the Northern dataset;
            see the scientific notes.

    """
    values = _call(
        _calc_ptf_dharumarajan2019_nkp,
        clay,
        sand,
        cation_exchange_capacity,
        out=out,
    )

    return Dharumarajan2019WaterRetentionResult(*values)

def calc_ptf_dharumarajan2019_nkp_clay(
    *,
    clay: float | ArrayLike,
    out: Dharumarajan2019WaterRetentionResult[NDArray[floating]] | None = None,
) -> (
    Dharumarajan2019WaterRetentionResult[floating]
    | Dharumarajan2019WaterRetentionResult[NDArray[floating]]
):
    r"""Estimate Northern Karnataka field capacity and wilting point from clay.

    Arguments:
        clay: Clay content. (%)
        out: Optional output arrays for in-place calculation.

    Returns:
        Dharumarajan2019WaterRetentionResult: Results grouped by result attributes.

    Territory:
        Northern Karnataka Plateau

    Models:
        $h(\theta)$: Point water-retention estimates from simple linear regression

    Notes:
        Prediction target: Water content at field capacity and permanent wilting point from clay
            content alone.
        The paper recommends this model when clay content is the only available predictor.
        Reported cross-validation RMSE values are 7.05% for FC and 4.74% for PWP.

    Warning:
        The paper does not state whether its water-content percentages are gravimetric or
            volumetric.
        The source gives inconsistent profile counts and district lists for the Northern dataset;
            see the scientific notes.

    """
    values = _call(
        _calc_ptf_dharumarajan2019_nkp_clay,
        clay,
        out=out,
    )

    return Dharumarajan2019WaterRetentionResult(*values)

def calc_ptf_dharumarajan2019_skp(
    *,
    clay: float | ArrayLike,
    sand: float | ArrayLike,
    cation_exchange_capacity: float | ArrayLike,
    out: Dharumarajan2019WaterRetentionResult[NDArray[floating]] | None = None,
) -> (
    Dharumarajan2019WaterRetentionResult[floating]
    | Dharumarajan2019WaterRetentionResult[NDArray[floating]]
):
    r"""Estimate field capacity and wilting point for Southern Karnataka soils.

    Arguments:
        clay: Clay content. (%)
        sand: Sand content. (%)
        cation_exchange_capacity: Cation exchange capacity. (C mol p+/kg)
        out: Optional output arrays for in-place calculation.

    Returns:
        Dharumarajan2019WaterRetentionResult: Results grouped by result attributes.

    Territory:
        Southern Karnataka Plateau

    Models:
        $h(\theta)$: Point water-retention estimates from multiple linear regression

    Notes:
        Prediction target: Water content at field capacity and permanent wilting point from clay,
            sand, and cation exchange capacity.
        The model was fitted to 228 soil samples from 43 profiles.
        Reported cross-validation RMSE values are 3.05% for FC and 2.17% for PWP.

    Warning:
        The paper does not state whether its water-content percentages are gravimetric or
            volumetric.

    """
    values = _call(
        _calc_ptf_dharumarajan2019_skp,
        clay,
        sand,
        cation_exchange_capacity,
        out=out,
    )

    return Dharumarajan2019WaterRetentionResult(*values)

def calc_ptf_dharumarajan2019_skp_clay(
    *,
    clay: float | ArrayLike,
    out: Dharumarajan2019WaterRetentionResult[NDArray[floating]] | None = None,
) -> (
    Dharumarajan2019WaterRetentionResult[floating]
    | Dharumarajan2019WaterRetentionResult[NDArray[floating]]
):
    r"""Estimate Southern Karnataka field capacity and wilting point from clay.

    Arguments:
        clay: Clay content. (%)
        out: Optional output arrays for in-place calculation.

    Returns:
        Dharumarajan2019WaterRetentionResult: Results grouped by result attributes.

    Territory:
        Southern Karnataka Plateau

    Models:
        $h(\theta)$: Point water-retention estimates from simple linear regression

    Notes:
        Prediction target: Water content at field capacity and permanent wilting point from clay
            content alone.
        The paper recommends this model when clay content is the only available predictor.
        Reported cross-validation RMSE values are 5.39% for FC and 3.13% for PWP.

    Warning:
        The paper does not state whether its water-content percentages are gravimetric or
            volumetric.

    """
    values = _call(
        _calc_ptf_dharumarajan2019_skp_clay,
        clay,
        out=out,
    )

    return Dharumarajan2019WaterRetentionResult(*values)