Skip to content

neptoon.calibration

station_calibration

Classes:

Functions:

CalibrationConfiguration 

CalibrationConfiguration(hours_of_data_around_calib=6, converge_accuracy=0.01, neutron_conversion_method='desilets_etal_2010', koehli_parameters='Mar21_mcnp_drf', horizontal_weight_method='schroen_etal_2017', vertical_weight_method='schroen_etal_2017', calib_data_date_time_column_name=None, calib_data_date_time_format='%Y-%m-%d %H:%M', sample_depth_column=None, distance_column=None, bulk_density_of_sample_column=None, profile_id_column=None, soil_moisture_gravimetric_column=None, soil_organic_carbon_column=None, lattice_water_column=None, temperature_column=None, relative_humidity_column=None, abs_air_humidity_column=None, neutron_column_name=None, air_pressure_column_name=None, value_avg_lattice_water=None, value_avg_bulk_density=None, value_avg_soil_organic_carbon=None)

User facing configuration class for calibration steps. Here a user can add information required for calibration. Defaults can often also be used if following similar data structure and naming as neptoon uses as standard.

User-facing configuration for calibration parameters.

Parameters:

Name Type Description Default
hours_of_data_around_calib int

Number of hours of neutron count data to include around the datetime stamp for calibration. This window is used to gather measurements from sensors during the calibration period. Default is 6.

 6
converge_accuracy float

The convergence threshold for when finding n0. Default is 0.01.

 0.01
neutron_conversion_method (desilets_etal_2010, koehli_etal_2021)

The conversion method used to translate raw neutron counts into soil moisture estimates. Options are "desilets_etal_2010" or "koehli_etal_2021". Default is "desilets_etal_2010".

 "desilets_etal_2010"
koehli_parameters str

Parameter set to use when koehli_etal_2021 method is selected. Default is "Mar21_mcnp_drf".

 'Mar21_mcnp_drf'
horizontal_weight_method (schroen_etal_2017, equal)
"schroen_etal_2017"
optional

Method for horizontal weighting. Default is "schroen_etal_2017".

 required
vertical_weight_method (schroen_etal_2017, equal)
"schroen_etal_2017"
optional

Method for vertical weighting. Default is "schroen_etal_2017".

 required
calib_data_date_time_column_name str

The name of the column containing date‐time information for each calibration day. If None, uses default from ColumnInfo.

 None
calib_data_date_time_format str

Format string for parsing date-time values. Default is "%Y-%m-%d %H:%M".

 '%Y-%m-%d %H:%M'
sample_depth_column str

The name of the column with sample depth values (cm). If None, uses default from ColumnInfo.

 None
distance_column str

The name of the column stating the distance of the sample from the sensor (meters). If None, uses default from ColumnInfo.

 None
bulk_density_of_sample_column str

The name of the column with bulk density values of the samples (g/cm^3). If None, uses default from ColumnInfo.

 None
profile_id_column str

Name of the column with profile IDs. If None, uses default from ColumnInfo.

 None
soil_moisture_gravimetric_column str

Name of the column with gravimetric soil moisture values (g/g). If None, uses default from ColumnInfo.

 None
soil_organic_carbon_column str

Name of the column with soil organic carbon values (g/g). If None, uses default from ColumnInfo.

 None
lattice_water_column str

Name of the column with lattice water values (g/g). If None, uses default from ColumnInfo.

 None
temperature_column str

Name of the column with temperature values. If None, uses default from ColumnInfo.

 None
relative_humidity_column str

Name of the column with relative humidity values. If None, uses default from ColumnInfo.

 None
abs_air_humidity_column str

Name of the column with absolute air humidity values (g/cm3). If None, uses default from ColumnInfo.

 None
neutron_column_name str

Name of the column with corrected neutrons in it. If None, uses default from ColumnInfo.

 None
air_pressure_column_name str

Name of the column with air pressure values in it. If None, uses default from ColumnInfo.

 None
value_avg_lattice_water float | None

The actual site average lattice water value. Default is 0.

 None
value_avg_bulk_density float | None

The actual site average dry soil bulk density. Default is 0.

 None
value_avg_soil_organic_carbon float | None

The actual site average soil organic carbon. Default is 0.

 None

CalibrationContext dataclass 

CalibrationContext(hours_of_data_around_calib=None, converge_accuracy=None, neutron_conversion_method=None, koehli_parameters=None, horizontal_weight_method=None, vertical_weight_method=None, calib_data_date_time_column_name=None, calib_data_date_time_format=None, sample_depth_column=None, distance_column=None, bulk_density_of_sample_column=None, profile_id_column=None, soil_moisture_gravimetric_column=None, soil_organic_carbon_column=None, lattice_water_column=None, temperature_column=None, relative_humidity_column=None, abs_air_humidity_column=None, neutron_column_name=None, air_pressure_column_name=None, value_avg_lattice_water=None, value_avg_bulk_density=None, value_avg_soil_organic_carbon=None, value_avg_soil_organic_carbon_water_equiv=None, unique_calibration_days=list(), list_of_data_frames=list(), list_of_profiles=list(), calib_day_df_dict=dict(), calib_metrics_dict=dict(), calibration_results_by_day=dict(), weights_df=DataFrame())

Internal context for data processing - outputs of each stage are written here. Contains resolved column names and processed values.

from_config classmethod 

from_config(config)

Convert configuration to context, resolving all None values to defaults from ColumnInfo and calculating derived values.

Parameters:

Name Type Description Default
config CalibrationConfiguration

User configuration object

 required

Returns:

Type Description
CalibrationContext

Internal processing context with all values resolved

CalibrationStation 

CalibrationStation(calibration_data, time_series_data, config)

Abstract which does the complete claibration steps. Can be used on its own, but is mainly designed to facilitate CRNSDataHub calibration. Simply include the calibration data, the time series data and the config object and run find_n0_value(), to return the optimum N0.

find_n0_value 

find_n0_value()

Runs the full process to obtain an N0 estimate.

Returns:

Type Description
float

N0 estimate after calibration.

return_calibration_results_data_frame 

return_calibration_results_data_frame()

Returns the daily results as a data frame. When multiple days calibration is undertaken on each day. The outputs of this are saved and this method returns them for viewing.

Returns:

Type Description
DataFrame

data frame with the results in it.

return_weighting_dataframe 

return_weighting_dataframe()

Returns the information about the weighting procedure

Returns:

Type Description
DataFrame

dataframe with weights

SampleProfile 

SampleProfile(soil_moisture_gravimetric, depth, bulk_density, site_avg_bulk_density, site_avg_organic_carbon, site_avg_lattice_water, calibration_day, distance=1, lattice_water=None, soil_organic_carbon=None, pid=None)

Initialise SampleProfile instance.

Parameters:

Name Type Description Default
soil_moisture_gravimetric array

array of soil moisture gravimetric values in g/g

 required
depth array

The depth of each soil moisture sample

 required
bulk_density array

bulk density of the samples in g/cm^3

 required
distance int

distance of the profile from the sensor, by default 1

 1
lattice_water array - like

Lattice water from the samples , by default 0

 None
soil_organic_carbon int

description, by default 0

 None
pid _type_

description, by default None

 None

PrepareCalibrationData 

PrepareCalibrationData(calibration_data_frame, context)

Prepares the calibration dataframe for processing.

  • ensures datetime index
  • splits multiple days into individual data frames
  • for each calibration day, converts data into a list of SampleProfiles
  • calculates site averages of key information (e.g., bulk density)
  • gap fills key info with averages when missing

Instantiate attributes

Parameters:

Name Type Description Default
calibration_data_frame DataFrame

The dataframe with the calibration sample data in it. If multiple calibration days are available these should be stacked in the same dataframe.

 required

prepare_calibration_data 

prepare_calibration_data()

Prepares the calibration data into a list of profiles.

PrepareNeutronCorrectedData 

PrepareNeutronCorrectedData(corrected_neutron_data_frame, context)

extract_calibration_day_values 

extract_calibration_day_values()

Extracts the rows of data for each calibration day.

IndicesExtractor 

IndicesExtractor(corrected_neutron_data_frame, context)

Extracts indices from the corrected neutron data based on the supplied calibration days

Attributes.

Parameters:

Name Type Description Default
corrected_neutron_data_frame DataFrame

The corrected neutron data frame

 required
calibration_data_prepper PrepareCalibrationData

The processed object

 required
hours_of_data_to_extract int

The number of hours of data around the calibration date time stamp to collect., by default 6

 required

extract_calibration_day_indices 

extract_calibration_day_indices()

Extract indices for each calibration day within a time window.

Returns:

Type Description
Dict

Indicies for each calibration day

CalibrationWeightsCalculator 

CalibrationWeightsCalculator(context=None)

set_values 

set_values(config, calibration_df, absolute_humidity, air_pressure)

Set required values for calculating weights on calibration data. Use this when you already have derived values (e.g., air pressure during calibration period), and want to submit them directly.

Parameters:

Name Type Description Default
config CalibrationConfiguration

Calibration config with required information for finding sample weights.

 required
calibration_df DataFrame

Calibration sample data

 required
absolute_humidity list

List of absolute humidity values, one for each calibration day in the order they appear in the dataframe.

 required
air_pressure list

List of atmospheric pressure values, one for each calibration day in the order they appear in the dataframe.

 required
bulk_density float | None

Bulk Density for the site, by default None

 required
lattice_water float | None

Lattice water, by default None

 required
soil_organic_carbon float | None

Soil organic carbon, by default None

 required

calculate_all_sample_weights 

calculate_all_sample_weights()

Applies the weighting procedure to multiple calibration days if present.

Returns:

Type Description
CalibrationContext

With more context

return_output_dict_as_dataframe 

return_output_dict_as_dataframe()

Returns the dictionary of information created for each calibration day during processing as a pandas DataFrame

Returns:

Type Description
DataFrame

DataFrame with information created during processing.

return_weighting_dataframe 

return_weighting_dataframe()

Returns the information about the weighting procedure

Returns:

Type Description
DataFrame

dataframe with weights

CalculateN0 

CalculateN0(context=None)

find_optimal_N0_old 

find_optimal_N0_old()

Finds the optimal N0 number for the site using the weighted field average soil mositure.

Returns:

Type Description
average_n0

The optimal n0 across all the supplied calibration days.