pedophysics.predict package

Submodules

pedophysics.predict.air_perm module

pedophysics.predict.air_perm.AirPerm(soil)

Set missing values of soil.df.air_perm and return.

If any value of the air_perm attribute is missing (NaN), it will be set to a default value of 1.2. Corresponding information in the soil’s info dataframe will be updated accordingly.

Parameters

soilobject

A custom soil object that contains:

• air_permarray-like

  Soil air real relative dielectric permittivity phase [-]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

numpy.ndarray

soil.df.air_perm.values: an array of updated soil air real relative dielectric permittivity phase values.

Example

>>> sample = Soil()
>>> sample.df.air_perm
0   NaN
Name: air_perm, dtype: float64
>>> AirPerm(sample)
>>> sample.df.air_perm
0    1.2
Name: air_perm, dtype: float64

pedophysics.predict.bulk_ec module

pedophysics.predict.bulk_ec.BulkEC(soil)

Calculate missing values of soil.df.bulk_ec and return

This function checks for NaN values in the soil’s bulk EC data. If any are found, it performs a series of operations to estimate the bulk EC, including direct current (DC) conversion and adjustment for non-DC components. The operations involve calling the BulkECDC function for DC conversion, followed by additional conversion functions to account for non-DC factors.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

A pandas DataFrame containing the soil states with columns for bulk_ec.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

Returns

np.ndarray

soil.df.bulk_ec.values: an array of updated or original soil bulk real electrical conductivity values

External Functions

BulkECDC : Compute missing values of soil.df.bulk_ec_dc and return conversion : Set missing values of soil.df.bulk_ec equal to soil.df.bulk_ec_dc_tc or soil.df.bulk_ec_dc if similar dc_to_non_dc : Calculate missing values of soil.df.bulk_ec based on soil.df.bulk_ec_dc

pedophysics.predict.bulk_ec.conversion(soil)

Set missing values of soil.df.bulk_ec equal to soil.df.bulk_ec_dc_tc or soil.df.bulk_ec_dc if similar

This function iterates over the soil states to update the ‘bulk_ec’ values in soil.df and to annotate corresponding entries in soil.info[‘bulk_ec’]. The updates are based on the presence of NaN values in the original ‘bulk_ec’ data and specific conditions related to soil temperature and frequency of EC measurements. Annotations indicate the basis for the updated values, referencing either soil.df.bulk_ec_dc_tc or soil.df.bulk_ec_dc, as determined by the conditions met during the update process.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: bulk_ec, temperature, and frequency_ec.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• n_states: int

  Number of soil states

Returns

None

This function updates the soil object in-place and does not return any value.

Notes

• The function checks for NaN values in ‘bulk_ec’ and updates them based on the soil temperature being exactly 298.15K and the frequency of EC measurements being 5Hz or less.

• Annotations in soil.info[‘bulk_ec’] provide insight into the source of the updated values, whether they are derived from ‘bulk_ec_dc_tc’ or ‘bulk_ec_dc’, aiding in the traceability of the data.

pedophysics.predict.bulk_ec.dc_to_non_dc(soil)

Calculate missing values of soil.df.bulk_ec based on soil.df.bulk_ec_dc

This function iterates over the soil states to update the ‘bulk_ec’ values in soil.df for cases where the electromagnetic frequency is 5Hz or higher. It applies the LongmireSmithEC function to account for the frequency shift from zero Hz to the actual frequency. The updated ‘bulk_ec’ values are then rounded off to a precision defined by soil.roundn+3. Corresponding entries in soil.info[‘bulk_ec’] are annotated to indicate that the adjustment was made using the LongmireSmithEC function from the predict.bulk_ec.dc_to_non_dc module.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: frequency_ec, bulk_ec, bulk_ec_dc and other relevant attributes.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• roundnint

  Number of decimal places to round results.

• n_statesint

  Number of soil states.

Returns

None

This function updates the soil object in-place and does not return any value.

Notes

• The function specifically targets soil states with a frequency of EC measurements of 5Hz or higher.

• Annotations in soil.info[‘bulk_ec’] detail the use of the LongmireSmithEC function for EM frequency adjustments, enhancing the traceability of the data adjustments.

External Functions

• LongmireSmithEC : Calculate the soil bulk real electrical conductivity using the Longmire-Smith model and return

pedophysics.predict.bulk_perm module

pedophysics.predict.bulk_perm.BulkPerm(soil)

Computes missing values of soil.df.bulk_perm and return.

Uses the given electromagnetic frequency to determine the method to estimate bulk permittivity. If no frequency is provided or all frequencies are the same, different methods or conditions are invoked.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: bulk_perm and frequency_perm.

• n_statesint

  Number of soil states

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

Returns

numpy.ndarray

soil.df.bulk_perm.values: Array containing updated soil bulk real relative dielectric permittivity values

Notes

The function modifies the soil object in-place by updating the df and info attributes based on the given conditions and returns the updated values of bulk permittivity.

External Functions

• FrequencyPerm : Set missing values of soil.df.frequency_perm and return

• fixed_freq, changing_freq : Functions invoked based on the condition of the EM frequency provided.

Example

>>> sample = Soil( water = [0.3, 0.1, 0.15, 0.23, 0.02],
            porosity = 0.434,
            texture = 'Silt loam',
            instrument = 'GPR')

>>> predict.BulkPerm(sample) 
array([18.563,  6.781,  9.328, 13.973,  3.357])

pedophysics.predict.bulk_perm.changing_freq(soil)

calculate missing values of soil.df.bulk_perm based on soil.df.bulk_ec_dc

This function determines the bulk permittivity of soil based on given conditions and the LongmireSmithP pedophysical model. It specifically addresses cases where the electromagnetic (EM) frequency is not constant.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: bulk_perm, frequency_perm, bulk_ec_dc, clay, sand, and bulk_perm_inf.

• roundnint

  Number of decimal places to round results.

Returns

None

The function directly modifies the soil object’s df and info attributes and does not return any value.

Notes

The function modifies the soil object in-place by updating the df and info attributes.

External Functions

• BulkPermInf : Set missing values of soil.df.bulk_perm_inf and return

• BulkECDC : Compute missing values of soil.df.bulk_ec_dc and return

• LongmireSmithP : Calculate the soil bulk real relative dielectric permittivity using the Wunderlich model and return

pedophysics.predict.bulk_perm.fitting(soil)

Calculate missing values of soil.df.bulk_perm using a fitting approach

This function fits the WunderlichP function to the soil data to determine the bulk permittivity values. It can either calculate the Lw parameter or use a provided value. The accuracy of the fitting is determined by the R2 score.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state. Includes: water, water_perm, and bulk_perm

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• Lwfloat

  Soil scalar depolarization factor of water aggregates (effective medium theory)

• roundnint

  Number of decimal places to round results.

• range_ratiofloat

  Ratio to extend the domain of the regression by fitting approach.

• n_statesint

  Number of soil states

Returns

None

The function directly modifies the soil object’s df and info attributes and does not return any value.

Notes

The function modifies the soil object in-place by updating the df and info attributes based on the fitting results.

External Functions

• Temperature : Set missing values of soil.df.temperature and return

• WaterPerm : Calculate or set missing values of soil.df.water_perm and return

• WunderlichP : Calculate the soil bulk real relative dielectric permittivity using the Wunderlich model and return

pedophysics.predict.bulk_perm.fixed_freq(soil)

Decide between fitting and non-fitting approaches.

Based on the given soil state data, chooses between two methodologies - fitting or non-fitting to determine the bulk permittivity values for a fixed frequency.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: bulk_perm, water, and frequency_perm.

• n_statesint

  Number of soil states

Returns

None

Notes

The function modifies the soil object in-place based on the given conditions.

External Functions

• fitting : Calculate missing values of soil.df.bulk_perm using a fitting approach

• non_fitting : Calculate missing values of soil.df.bulk_perm using a non fitting approach.

pedophysics.predict.bulk_perm.non_fitting(soil)

Calculate missing values of soil.df.bulk_perm using a non fitting approach

This function determines the bulk permittivity of soil based on given conditions and known empirical relationships. Depending on the electromagnetic (EM) frequency range provided, various functions are used.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: water, bulk_perm, frequency_perm, bulk_ec, bulk_perm_inf, porosity, clay, air_perm, solid_perm, water_perm, and CEC.

• roundnint

  Number of decimal places to round results.

Returns

None

The function directly modifies the soil object’s df and info attributes and does not return any value.

Notes

The function modifies the soil object in-place by updating the df and info attributes based on the chosen approach.

External Functions

• BulkPermInf : Determines the bulk permittivity at infinite frequency.

• BulkEC : Estimates the soil’s bulk electrical conductivity.

• Temperature : Set missing values of soil.df.temperature and return

• Porosity : Calculate missing values of soil.df.porosity and return

• AirPerm : Set missing values of soil.df.air_perm and return

• SolidPerm : Set missing values of soil.df.solid_perm and return

• WaterPerm : Calculate or set missing values of soil.df.water_perm and return

• Texture : Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return

• LongmireSmithP : Calculate the soil bulk real relative dielectric permittivity using the Longmire-Smith model and return

• LR_MV : Calculate the soil volumetric water content using the Lichtenecker and Rother model modified by Mendoza-Veirana and return

• LR : Calculate the soil volumetric water content using the Lichtenecker and Rother model.

• LR_W : Calculate the soil volumetric water content using the Lichtenecker and Rother model modified by Wunderlich and return

pedophysics.predict.bulk_perm_inf module

pedophysics.predict.bulk_perm_inf.BulkPermInf(soil)

Set missing values of soil.df.bulk_perm_inf and return.

If any value of the bulk_perm_inf attribute is missing (NaN), it will be set to a default value of 5. Corresponding information in the soil’s info dataframe will be updated accordingly.

Parameters

soilobject

A custom soil object that contains:

• bulk_perm_infarray-like

  Soil bulk real relative permittivity at infinite frequency [-]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.bulk_perm_inf.values: an array of updated soil bulk real relative permittivity at infinite frequency values

Example

>>> sample = Soil()
>>> sample.df.bulk_perm_inf
0   NaN
Name: bulk_perm_inf, dtype: float64
>>> BulkPermInf(sample)
>>> sample.df.bulk_perm_inf
0    5
Name: bulk_perm_inf, dtype: float64

pedophysics.predict.frequency_ec module

pedophysics.predict.frequency_ec.FrequencyEC(soil)

Return and set missing values of the soil.df.frequency_ec attribute.

If any value of the frequency_ec attribute is missing (NaN), it will be set to a default value of 0 Hz (direct current). Corresponding information in the soil’s info dataframe will be updated accordingly.

Parameters

soilobject

A custom soil object that contains: - frequency_ec : array-like

Frequency of electric conductivity measurement [Hz]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state.

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated. includes: frequency_ec

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.frequency_ec.values: an array of updated frequency of electric conductivity measurement values.

External functions

Inst2FreqEC : Function to calculate missing frequency_ec attribute based on soil.instrument.

Example

>>> sample = Soil()
>>> sample.df.frequency_ec
0   NaN
Name: frequency_ec, dtype: float64
>>> FrequencyEC(sample)
>>> sample.df.frequency_ec
0    0
Name: frequency_ec, dtype: float64

pedophysics.predict.frequency_perm module

pedophysics.predict.frequency_perm.FrequencyPerm(soil)

Set missing values of soil.df.frequency_perm and return

If any value of the frequency_perm attribute is missing (NaN), it will be computed using the Inst2FreqP function from the instruments module.

Parameters

soilobject

A custom soil object that contains:

• frequency_permarray-like

  Frequency of dielectric permittivity measurement [Hz]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state. Includes: frequency_perm

Returns

np.ndarray

soil.df.frequency_perm.values: an array of updated frequency of dielectric permittivity measurement values

Notes

This function modifies the soil object in-place, updating the df dataframe if necessary.

External functions

Inst2FreqP : Set missing values of soil.df.frequency_perm and return

Example

>>> sample = Soil(instrument = 'GPR')
>>> sample.df.frequency_perm
0   NaN
Name: frequency_perm, dtype: float64
>>> FrequencyPerm(sample)
>>> sample.df.frequency_perm
0    1e9
Name: frequency_perm, dtype: float64

pedophysics.predict.particle_density module

pedophysics.predict.particle_density.ParticleDensity(soil)

Calculate or set missing values of soil.df.particle_density and return

If any value of the particle_density attribute is missing (NaN), it will first be computed using the Schjonnen function based on the clay and organic matter values. If it remains missing, it’s set to a default value of 2.65.

Parameters

soilobject

A custom soil object that contains:

• particle_densityarray-like

  Soil particle density [kg/m**3]

• clayarray-like

  Soil clay content [g/g]*100

• orgmarray-like

  Soil organic matter [g/g]*100

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.particle_density.values: an array of updated soil particle density values

Notes

This function modifies the soil object in-place, updating the df dataframe and info dataframe if necessary.

External functions

Texture : Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return Schjonnen : Calculate the soil particle density using the Schjonnen model and return

Example

>>> sample = Soil()
>>> sample.df.particle_density
0   NaN
Name: particle_density, dtype: float64
>>> ParticleDensity(sample)
>>> sample.df.particle_density
0    2.65
Name: particle_density, dtype: float64

pedophysics.predict.salinity module

pedophysics.predict.salinity.Salinity(soil)

Calculate missing values of soil.df.salinity and return

If any value of the salinity attribute is missing (NaN), it will first compute the missing values by optimizing the SenGoode function based on the soil’s water electrical conductivity and temperature.

Parameters

soilobject

A custom soil object that contains:

• temperaturearray-like

  Soil bulk temperature [K]

• salinityarray-like

  Soil salinity (NaCl) of the bulk pore fluid [mol/L]

• water_ecarray-like

  Soil water real electrical conductivity [S/m]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.salinity.values: an array of soil salinity (NaCl) of the bulk pore fluid values

Notes

This function modifies the soil object in-place, updating the df dataframe and info dataframe if necessary.

External functions

WaterEC : Compute missing values of soil.df.water_ec and return Temperature : Set missing values of soil.df.temperature and return SenGoode : Calculate soil water real electrical conductivity using the Sen and Goode model and return

Example

>>> sample = Soil(water_ec = 0.1)
>>> sample.df.salinity
0   NaN
Name: salinity, dtype: float64
>>> Salinity(sample)
>>> sample.df.salinity
0    0.00846
Name: salinity, dtype: float64

pedophysics.predict.solid_ec module

pedophysics.predict.solid_ec.SolidEC(soil)

Set missing values of soil.df.solid_ec and return

If any value of the solid_ec attribute is missing (NaN), it will be set to a default value of 0. Corresponding information in the soil’s info dataframe will be updated accordingly.

Parameters

soilobject

A custom soil object that contains:

• solid_ecarray-like

  Soil solid real electrical conductivity [S/m]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.solid_ec.values: an array of updated soil solid real electrical conductivity values

Example

>>> sample = Soil()
>>> sample.df.solid_ec
0   NaN
Name: solid_ec, dtype: float64
>>> SolidEC(sample)
>>> sample.df.solid_ec
0    0
Name: solid_ec, dtype: float64

pedophysics.predict.solid_perm module

pedophysics.predict.solid_perm.SolidPerm(soil)

Set missing values of soil.df.solid_perm and return

If any value of the solid_perm attribute is missing (NaN), it will be set to a default value of 4. Corresponding information in the soil’s info dataframe will be updated accordingly.

Parameters

soilobject

A custom soil object that contains:

• solid_permarray-like

  Soil solid real relative dielectric permittivity phase [-]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing the qualitative information about all array-like soil attributes for each state

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.solid_perm.values: an array of updated soil solid real relative dielectric permittivity phase values

Example

>>> sample = Soil()
>>> sample.df.solid_perm
0   NaN
Name: solid_perm, dtype: float64
>>> SolidPerm(sample)
>>> sample.df.solid_perm
0    4
Name: solid_perm, dtype: float64

pedophysics.predict.temperature module

pedophysics.predict.temperature.Temperature(soil)

Set missing values of soil.df.temperature and return

If any value of the temperature attribute is missing (NaN), it will be set to a default value of 298.15. Corresponding information in the soil’s info dataframe will be updated accordingly.

Parameters

soilobject

A custom soil object that contains:

• temperaturearray-like

  Soil bulk temperature [K]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.temperature.values: an array of updated soil bulk temperature values

Example

>>> sample = Soil()
>>> sample.df.temperature
0   NaN
Name: temperature, dtype: float64
>>> Temperature(sample)
>>> sample.df.temperature
0    298.15
Name: temperature, dtype: float64

pedophysics.predict.texture module

pedophysics.predict.texture.Texture(soil)

Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return

If any value of the sand, silt, or clay attribute is missing, this function will: 1. Warn if the sum of texture fractions does not equate to 100%. 2. Calculate missing texture fraction if only two out of three are given. 3. Assign default texture fractions based on the texture attribute of the soil object.

Parameters

soilobject

A custom soil object that contains:

• clayarray-like

  Soil clay content [g/g]*100

• sandarray-like

  Soil sand content [g/g]*100

• siltarray-like

  Soil silt content [g/g]*100

• texturestr

  Soil texture according to USDA convention: “Sand”, “Loamy sand”, “Sandy loam”, “Loam”, “Silt loam”, “Silt”, “Sandy clay loam”, “Clay loam”, “Silty clay loam”, “Sandy clay”, “Clay”, “Silty clay”

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Notes

This function modifies the soil object in-place, updating the df and info dataframes.

External functions

warnings.warn : Issue a warning, or maybe ignore it or raise an exception.

Example

>>> sample = Soil(clay = 20,
                silt = 40)
>>> sample.df.sand
0   NaN
Name: sand, dtype: float64
>>> Texture(sample)
>>> sample.df.sand
0    40
Name: sand , dtype: float64

pedophysics.predict.water_ec module

pedophysics.predict.water_ec.WaterEC(soil)

Compute missing values of soil.df.water_ec and return

This function evaluates soil states to determine the appropriate approach for estimating water EC. It considers non-fitting approaches based on salinity and bulk electrical conductivity, as well as fitting approaches using the Rhoades or Hilhorst functions depending on the availability of water content, bulk electrical conductivity, and bulk permeability data.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: water, bulk_ec_dc_tc, water_ec, salinity, and potentially bulk_perm.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• n_states: int

  The number of soil states represented in the df.

Returns

numpy.ndarray

soil.df.water_ec.values: array containing the updated soil water pore real electrical conductivity values.

Notes

• Non-fitting approaches are applied when specific data are available, such as salinity or bulk electrical conductivity, without the need for additional parameters.

• Fitting approaches, such as those using the Rhoades or Hilhorst functions, are applied when there are sufficient data points with known water content or bulk permeability.

External Functions

• Temperature : Set missing values of soil.df.temperature and return

• FrequencyEC : Set missing values of soil.df.frequency_ec and return

• shift_to_bulk_ec_dc_tc : Compute missing values of soil.df.bulk_ec_dc_tc based on soil.df.bulk_ec or soil.df.bulk_ec_dc

• from_salinity : Calculate missing values of soil.df.water_ec based on soil.df.salinity

• from_ec : Calculate missing values of soil.df.water_ec based on soil.df.bulk_ec_dc_tc

• fitting_rhoades : Calculate missing values of soil.df.water_ec using the Rhoades function in a fitting approach

• fitting_hiolhorst : Calculate missing values of soil.df.water_ec using the Hilhorst function in a fitting approach

Example

>>> sample = Soil( bulk_ec=[0.02, 0.03, 0.04, 0.05, 0.06], 
            bulk_perm=[11.5, 14.8, 17, 20, 22.7],
            clay=5,
            porosity=0.44,
            instrument='TDR')

>>> predict.WaterEC(sample)
array([0.289855, 0.289855, 0.289855, 0.289855, 0.289855])

pedophysics.predict.water_ec.fitting_hilhorst(soil)

Calculate missing values of soil.df.water_ec using the Hilhorst function in a fitting approach

This function selects calibration data based on available bulk electrical conductivity, bulk permeability, and water permeability, and applies the Hilhorst function

to estimate soil water electrical conductivity and an offset parameter for permeability. It then performs a fitting process to optimize parameters using the objective function that minimizes the residuals between the calculated and observed bulk permeability.

Parameters

soilobject

A custom soil object containing:

dfDataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: bulk_ec, bulk_perm, water_perm, offset_perm, and water_ec.

n_statesint

The count of soil states.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

roundnint

Number of decimal places to round results.

Returns

None

The function updates the soil object’s df and info attributes with estimated values and additional information regarding the calculation.

External Functions

WaterPerm : Calculate or set missing values of soil.df.water_perm and return Hilhorst : Calculate the soil bulk real relative dielectric permittivity using the Hilhorst model and return R2_score : Calculate the coefficient of determination (R^2) of a prediction and return.

Notes

• The function targets soil states with known bulk electrical conductivity and bulk permeability greater than or equal to 10.

• A least squares optimization is used to find the best parameters that fit the Hilhorst function to the calibration data.

pedophysics.predict.water_ec.fitting_rhoades(soil)

Calculate missing values of soil.df.water_ec using the Rhoades function in a fitting approach

This function selects calibration data based on available water content and bulk electrical conductivity data, removes NaNs, and uses the Rhoades function within a minimization process to estimate water_ec and s_ec parameters. It then fixes these parameters to estimate the remaining parameters of the Rhoades function, E and F. The quality of the fit is evaluated using the R2 score.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. includes: water, bulk_ec_dc_tc, water_ec, s_ec, and potentially other related parameters.

• n_states: int

  The number of soil states represented in the df.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• roundn: int

  The number of decimal places for rounding estimated parameter values.

Returns

None

The function directly modifies the soil object’s df and info attributes with the estimated parameters and does not return any value.

Notes

• The fitting process involves two steps: first, estimating water_ec and s_ec with fixed E and F, and second, estimating E and F with fixed water_ec and s_ec.

• The process uses calibration data where both water content and bulk electrical conductivity are known.

External Functions

• Rhoades : Calculate the soil bulk real electrical conductivity using the Rhoades model and return

• R2_score : Calculate the coefficient of determination (R^2) of a prediction and return.

pedophysics.predict.water_ec.from_ec(soil)

Calculate missing values of soil.df.water_ec based on soil.df.bulk_ec_dc_tc

This function applies the Fu function within a minimization process to estimate soil water EC based on soil properties such as water content, clay content, porosity, solid EC, dry EC, and saturated EC. The estimation is performed for each soil state where water EC is unknown.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: water, clay, porosity, solid_ec, dry_ec, sat_ec, bulk_ec_dc_tc, and potentially water_ec.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• n_states: int

  The number of soil states represented in the df.

• roundn: int

  The number of decimal places for rounding estimated water EC values.

Returns

None

The function directly modifies the soil object’s df and info attributes with the estimated water EC values and does not return any value.

External Functions

• Texture : Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return

• Porosity : Calculate missing values of soil.df.porosity and return

• SolidEC : Set missing values of soil.df.solid_ec and return

• Fu : Calculate the soil bulk real electrical conductivity using the Fu model and return

pedophysics.predict.water_ec.from_salinity(soil)

Calculate missing values of soil.df.water_ec based on soil.df.salinity

This function estimates water EC for each soil state based on temperature and salinity data using the SenGood function. Estimated water EC values are saved in the soil DataFrame, and an information string indicating the use of the SenGood function for calculation is appended to each relevant entry in the soil information dictionary.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: temperature, salinity, and potentially water_ec.

• n_states: int

  The number of soil states represented in the df.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

Returns

None

The function directly modifies the soil object’s df and info attributes with the estimated water EC values and does not return any value.

External Functions

• SenGoode : Calculate soil water real electrical conductivity using the Sen and Goode model and return

pedophysics.predict.water_perm module

pedophysics.predict.water_perm.WaterPerm(soil)

Calculate or set missing values of soil.df.water_perm and return

Determines the soil water phase real dielectric permittivity using either the MalmbergMaryott function or the Olhoeft function based on the soil’s salinity and frequency permittivity. If the permittivity cannot be determined by either method, it defaults to a value of 80.

Parameters

soilobject

A custom soil object that contains:

• water_permarray-like

  Soil water phase real dielectric permittivity [-]

• temperaturearray-like

  Soil bulk temperature [K]

• salinityarray-like

  Soil salinity (NaCl) of the bulk pore fluid [mol/L]

• frequency_permarray-like

  Frequency of dielectric permittivity measurement [Hz]

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.water_perm.values: array containing the updated soil water phase real dielectric permittivity values.

Notes

This function modifies the soil object in-place by updating the df and info dataframes.

External functions

MalmbergMaryott : Calculate soil water phase real dielectric permittivity using the Malmberg & Maryott model and return Olhoeft : Calculate soil water phase real dielectric permittivity using the Olhoeft (1986) model and return

Example

>>> sample = Soil()
>>> sample.df.water_perm
0   NaN
Name: water_perm, dtype: float64
>>> WaterPerm(sample)
>>> sample.df.water_perm
0    80
Name: water_perm, dtype: float64

pedophysics.predict.water module

pedophysics.predict.water.Water(soil)

Return and compute missing values of the soil.df.water attribute using soil.df.bulk_perm or soil.df.bulk_ec.

This function performs calculations to fill in missing water content values in the soil DataFrame based on bulk permeability (bulk_perm) and electrical conductivity (bulk_ec_dc_tc). It employs different strategies based on available data and sets conditions for water content calculation.

Parameters

soilobject

A custom soil object that contains:

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state. Includes columns: water, bulk_perm, frequency_perm, and bulk_ec_dc_tc

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

np.ndarray

soil.df.water.values: an array of updated or original soil volumetric water content values

External functions

Temperature : Set missing values of soil.df.temperature and return FrequencyPerm : Set missing values of soil.df.frequency_perm and return WaterFromPerm : Calculate missing values of soil.df.water based on soil.df.bulk_perm WaterFromEC : Calculate missing values of soil.df.water based on soil.df.bulk_ec_dc_tc FrequencyEC : Set missing values of soil.df.frequency_ec and return shift_to_bulk_ec_dc_tc : Compute missing values of soil.df.bulk_ec_dc_tc based on soil.df.bulk_ec or soil.df.bulk_ec_dc

Example

>>> sample = Soil( bulk_ec = [0.01, 0.02, 0.025, 0.030, 0.040],
                clay = 10,
                porosity = 0.47,
                water_ec = 0.5)

>>> Water(sample) 
array([0.105, 0.162, 0.185, 0.206, 0.243])

pedophysics.predict.water_from_ec module

pedophysics.predict.water_from_ec.WaterFromEC(soil)

Calculate missing values of soil.df.water based on soil.df.bulk_ec_dc_tc

This function evaluates the availability of water content and bulk electrical conductivity data (bulk_ec_dc_tc) across soil states. A fitting approach is applied if there are at least three soil states with known water content and bulk electrical conductivity. A non-fitting approach is considered when water content is unknown and bulk electrical conductivity is known for any soil state.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: water and bulk_ec_dc_tc.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• n_states: int

  The number of soil states represented in the df.

Returns

None

Notes

• The fitting approach requires at least three soil states with known water content and bulk electrical conductivity for reliable estimation.

• The non-fitting approach is applied to individual soil states where water content is unknown but bulk electrical conductivity is available.

External Functions

FrequencyEC : Set missing values of soil.df.frequency_ec and return fitting : Calculate missing values of soil.df.water using a fitting approach. non_fitting : Calculate missing values of soil.df.water using a non-fitting approach.

Example

>>> sample = Soil( bulk_ec = [0.01, np.nan, 0.025, 0.030, 0.040],
            clay = 10,
            porosity = 0.47,
            water_ec = 0.5)

>>> WaterFromEC(sample) 
>>> sample.df.water
0    0.105
1    Nan
2    0.185
3    0.206
4    0.243
Name: water, dtype: float64

pedophysics.predict.water_from_ec.fitting(soil)

Calculate missing values of soil.df.water using a fitting approach.

This function evaluates soil states with known water content and bulk electrical conductivity to determine initial parameters for the WunderlichEC model. If the Lw parameter associated with the model is unknown, it is optimized based on the root mean square error (RMSE) between estimated and actual bulk electrical conductivity. Water content is then estimated for all soil states within a valid bulk electrical conductivity range using the optimized Lw parameter and the WunderlichEC model.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: water, bulk_ec_dc_tc, water_ec, and potentially Lw.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• n_states: int

  The number of soil states represented in the df.

• range_ratio: float

  A ratio used to determine the range of bulk electrical conductivity values considered valid for the model.

• roundn: int

  The number of decimal places for rounding calculated water content values.

• Lw: float or np.nan

  The WunderlichEC model parameter, if known; otherwise, np.nan.

Returns

None

The function directly modifies the soil object’s df and info attributes with the estimated water content and does not return any value.

Notes

This function modifies the soil object in-place by updating the df and info dataframes. The function either estimates or uses the known Lw parameter for the WunderlichEC model and fits the model to the calibration data.

External Functions

WunderlichEC: Calculate the soil bulk real electrical conductivity using the Wunderlich model and return WaterEC: Compute missing values of soil.df.water_ec and return

pedophysics.predict.water_from_ec.non_fitting(soil)

Calculate missing values of soil.df.water using a non-fitting approach.

This function applies the Fu function within a minimization process to estimate soil water content based on soil properties such as clay content, porosity, water electrical conductivity (EC), solid EC, dry EC, and saturated EC. The estimation is performed for each soil state where water content is unknown.

Parameters

soilSoil Object

An object representing the soil, which must have the following attributes: - df: DataFrame

Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: clay, porosity, water_ec, solid_ec, dry_ec, sat_ec, bulk_ec_dc_tc, and potentially water.

• info: DataFrame

  Data Frame containing descriptive information about how each array-like attribute was calculated.

• n_states: int

  The number of soil states represented in the df.

• roundn: int

  The number of decimal places for rounding estimated water content values.

bulk_ec_dcarray-like

Soil bulk real electrical conductivity at DC frequency [S/m].

Notes

• The Fu function is utilized in a minimization process to estimate water content by minimizing the difference between the estimated and actual bulk ECDCTC.

• The estimation process is applied to each soil state where water content is unknown.

External functions

Fu: Calculate the soil bulk real electrical conductivity using the Fu model and return Texture: Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return Porosity: Calculate missing values of soil.df.porosity and return WaterEC: Compute missing values of soil.df.water_ec and return SolidEC: Set missing values of soil.df.solid_ec and return

pedophysics.predict.water_from_perm module

pedophysics.predict.water_from_perm.WaterFromPerm(soil)

Calculate missing values of soil.df.water based on soil.df.bulk_perm

This function checks if the permittivity frequency (frequency_perm) across all soil states is constant. If it is, a specific adjustment is made using the fixed_freq function. If the frequencies vary across soil states, a different adjustment is applied using the changing_freq function.

Parameters

soilobject

A custom soil object that contains:

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state. Includes: water and frequency_perm.

• infoDataFrame

  Data Frame containing descriptive information about how each attribute was determined or modified.

• n_statesint

  Number of states or records in the dataframe.

Returns

None

External functions

fixed_freq: Decide between fitting and non-fitting approaches to calculate soil.df.water changing_freq: Calculate missing values of soil.df.bulk_dc_ec when soil.df.frequency_perm is not constant

Example

>>> sample = Soil(frequency_perm = 1e9, 
                clay = 15,             
                porosity = 0.434,
                bulk_perm = [8, 10, 15])
>>> WaterFromPerm(sample) 
>>> sample.df.water
0    0.125
1    0.162
2    0.246
Name: water, dtype: float64

pedophysics.predict.water_from_perm.changing_freq(soil)

Calculate missing values of soil.df.bulk_dc_ec when soil.df.frequency_perm is not constant.

This function iterates through soil states to calculate the bulk EC for states where it is undefined. The calculation is performed by minimizing the difference between the calculated permeability using the Longmire-Smith P function and the known bulk permeability. Warnings are issued for soil states where the Longmire-Smith P function’s applicability is uncertain due to soil conditions.

Parameters

soilobject

A custom soil object that contains:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: frequency_perm, frequency_ec, bulk_ec_dc, and bulk_perm.

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• n_statesint

  Number of soil states.

Returns

None

The function directly modifies the soil object’s df and info attributes and does not return any value.

External Functions

Texture : Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return BulkPermInf : Set missing values of soil.df.bulk_perm_inf and return LongmireSmithP : Calculate the soil bulk real relative dielectric permittivity using the Wunderlich model and return

Notes

• The function uses the scipy.optimize.minimize method for the minimization process.

• Warnings are issued for soil states where the frequency of permittivity exceeds 200 MHz and either clay content is above 10% or sand content is below 90%, as the validity of the Longmire-Smith P model is uncertain in these conditions.

pedophysics.predict.water_from_perm.fitting(soil)

Calculate missing values of soil.df.water using a fitting approach.

This function utilizes the WunderlichP model to estimate the soil’s volumetric water content based on its bulk real relative dielectric permittivity at constant frequency. It calculates the model’s parameters and fits them to the provided calibration data. The accuracy of the fitting is determined by the R2 score.

Parameters

soilobject

A custom soil object that contains:

• dfDataFrame

  Data Frame containing all the quantitative information of soil array-like attributes for each state. Includes: water, bulk_perm, and water_perm.

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• Lwfloat

  Soil scalar depolarization factor of water aggregates (effective medium theory)

• roundnint

  Number of decimal places to round results.

• range_ratiofloat

  Ratio to extend the domain of the regression by fitting approach.

• n_statesint

  Number of soil states

Returns

None

The function directly modifies the soil object based on the selected approach and does not return any value.

Notes

This function modifies the soil object in-place by updating the df and info dataframes. The function either estimates or uses the known Lw parameter for the WunderlichP model and fits the model to the calibration data.

External functions

WunderlichP : Calculate the soil bulk real relative dielectric permittivity using the Wunderlich model and return WaterPerm : Calculate or set missing values of soil.df.water_perm and return R2_score : Calculate the coefficient of determination (R^2) of a prediction and return.

pedophysics.predict.water_from_perm.fixed_freq(soil)

Decide between fitting and non-fitting approaches to calculate soil.df.water

This function determines the calculation approach for soil water content based on the availability of data for water content and bulk permeability, as well as the range of frequency of permittivity. It applies a fitting approach if there are at least three soil states with known water content and bulk permeability. Otherwise, it considers a non-fitting approach when water content is unknown, bulk permeability is known, and the frequency of permittivity falls within a specified range.

Parameters

soil : object A custom soil object that contains:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: frequency_perm, water, and bulk_perm.

• n_statesint

  Number of soil states.

Returns

None

The function directly modifies the soil object based on the selected approach and does not return any value.

Notes

This function modifies the soil object in-place, using either the fitting or the non_fitting function depending on the criteria described above.

External functions

fitting: Calculate missing values of soil.df.water using a fitting approach. non_fitting: Calculate missing values of soil.df.water using a non-fitting approach.

pedophysics.predict.water_from_perm.non_fitting(soil)

Return and compute soil.df.water using a non-fitting approach.

This function estimates soil bulk electrical conductivity (EC) and water content by applying different models based on the EM frequency range. For frequencies between 5 Hz and 30 MHz, the Longmire-Smith P function is used to calculate bulk EC. For frequencies between 30 MHz and 100 MHz, 100 MHz and 200 MHz, and 200 MHz and 30 GHz, different linear regression models (LR_MV, LR, LR_W) are applied to estimate water content.

Parameters

soilobject

A custom soil object containing:

• dfDataFrame

  Data Frame containing the quantitative information of all soil array-like attributes for each state. Includes: water, bulk_perm, frequency_perm, and bulk_ec_dc for each soil state.

• n_statesint

  Number of soil states.

• infoDataFrame

  Data Frame containing descriptive information about how each array-like attribute was determined or modified.

• roundnint

  Number of decimal places to round results.

Returns

None

The function directly modifies the soil object based on the selected approach and does not return any value.

Notes

• The function chooses the estimation model based on the EM frequency range of the soil states.

• For frequencies between 5 Hz and 30 MHz, bulk EC is estimated.

For higher frequencies, water content is estimated using different linear regression models tailored to specific frequency ranges.

External Functions

Porosity : Calculate missing values of soil.df.porosity and return AirPerm : Set missing values of soil.df.air_perm and return SolidPerm : Set missing values of soil.df.solid_perm and return WaterPerm : Calculate or set missing values of soil.df.water_perm and return Texture : Calculate missing values of soil.df.sand, soil.df.silt, and soil.df.clay and return BulkPermInf : Set missing values of soil.df.bulk_perm_inf and return LongmireSmithP : Calculate the soil bulk real relative dielectric permittivity using the Longmire-Smith model and return LR_W : Calculate the soil volumetric water content using the Lichtenecker and Rother model modified by Wunderlich and return LR : Calculate the soil volumetric water content using the Lichtenecker and Rother model. LR_MV : Calculate the soil volumetric water content using the Lichtenecker and Rother model modified by Mendoza-Veirana and return

Module contents