SensorInfo Documentation¶

Overview¶

The SensorInfo class stores metadata about a CRNS site. These values are normally constant over time, such as sensor latitude and longitude. If the sensor is moved, treat it as a new site.

SensorInfo Class¶

The SensorInfo class stores site-specific information. Here is an example of how you could create one in your pipeline:

from neptoon.config.configuration_input import SensorInfo

sensor_info = SensorInfo(
    name="MyStation",
    install_date="2024-01-01T00:00:00",
    latitude=52.3676,
    longitude=4.9041,
    elevation=100,
    time_zone=0,
    avg_dry_soil_bulk_density=1.5,
    avg_lattice_water=0.02,
    avg_soil_organic_carbon=0.01,
    site_cutoff_rigidity=3.5,
    reference_incoming_neutron_value=150,
)

Key Attributes¶

Attribute	Type	Description	Impact on Processing
`name`	str	Name identifier for the station	Used in output file naming and reports
`identifier`	Optional[str]	Stable sensor/site identifier	Distinguishes stations and appears in metadata
`install_date`	datetime	Sensor installation date	Preserved in configuration and report metadata
`time_zone`	int	Legacy UTC offset metadata	Prefer explicit IANA zones in `time_series_data.key_column_info` for timestamp parsing
`latitude`	float	Latitude in decimal degrees	Used in spatial corrections and footprint calculations
`longitude`	float	Longitude in decimal degrees	Used in spatial corrections and site-specific retrievals
`elevation`	float	Elevation in meters	Affects pressure-based corrections
`reference_incoming_neutron_value`	float	Legacy fixed incoming-neutron reference	Fallback only; prefer `correction_steps.incoming_radiation.reference_value` or `reference_column` in the process config
`avg_dry_soil_bulk_density`	float	Average dry soil bulk density (g/cm³)	Critical for converting neutron counts to volumetric soil moisture
`avg_lattice_water`	float	Average lattice water content (g/g)	Affects neutron moderation and soil moisture calculations
`avg_soil_organic_carbon`	float	Average soil organic carbon content (g/g)	Influences neutron moderation similar to water
`site_cutoff_rigidity`	Optional[float]	Geomagnetic cutoff rigidity (GV)	Used for cosmic ray intensity corrections
`mean_pressure`	Optional[float]	Mean atmospheric pressure (hPa)	Legacy/static site metadata; the current correction default reference is documented with the selected pressure method
`N0`	Optional[float]	Legacy/default calibration parameter	Links neutron counts to soil moisture when no matching method-specific calibration profile is selected
`beta_coefficient`	Optional[float]	Atmospheric-pressure attenuation coefficient	Used by the pressure correction; calculated from site metadata when omitted
`above_ground_biomass`	Optional[float]	Legacy static biomass value	Accepted for older station configurations; current workflows can provide a time-varying biomass column

Using SensorInfo with CRNSDataHub¶

The SensorInfo object should be attached to a CRNSDataHub instance for data processing:

from neptoon.hub import CRNSDataHub
import pandas as pd

# Assume we have pre-formatted CRNS data
crns_data = pd.DataFrame(...)

# Create the data hub with sensor information
data_hub = CRNSDataHub(
    crns_data_frame=crns_data,
    sensor_info=sensor_info
)

# The sensor_info can also be added or updated later
data_hub.sensor_info = sensor_info

Adding SensorInfo to your time series¶

Once you have your SensorInfo attached to your data_hub there is an important step you must take:

# Prepare static values in the data frame from sensor_info
data_hub.prepare_static_values()

This method will take each of the values in the SensorInfo class and attach them to your time series data as columns of data (1 value repeated).

Why this step?

The reason behind this is that some values can be provided as time-series inputs when they vary over time. Attaching them to the data table ensures that correction methods use the same column-based interface as the rest of the processing workflow.

Characterize a new site from external priors¶

When local soil metadata are incomplete, neptoon.site can collect SoilGrids, DEM, land-cover, and biomass context before configuration. These products are recorded as external priors and should be checked against field measurements rather than treated as automatic replacements.

Best Practices¶

Data Completeness: Provide as much information as possible, even optional attributes, to ensure accurate processing.
Metadata Sources: Information like soil properties should ideally come from direct field measurements, but literature values can be used when site-specific data is unavailable.
Calibration: The N0 value should be determined through field calibration rather than assumed. More on this later.
Configuration Files: For reproducibility, consider storing SensorInfo in YAML configuration files that can be version-controlled.

Impact on Processing¶

The SensorInfo values directly influence key processing steps:

Correction Factors: Values like elevation and cutoff rigidity affect atmospheric and cosmic ray corrections
Soil Moisture Conversion: N0, avg_dry_soil_bulk_density, avg_lattice_water, and avg_soil_organic_carbon determine the relationship between neutron counts and volumetric soil moisture

Configuration-Based Approach¶

For production workflows, creating SensorInfo through configuration files is recommended:

from neptoon.io.read import DataHubFromConfig

# Load from a YAML configuration file
hub_creator = DataHubFromConfig(path_to_sensor_config='sensors/my_station.yaml')
data_hub = hub_creator.create_data_hub()

# The sensor_info is automatically created and attached

This approach ensures consistent processing across multiple runs and simplifies reproducibility.

Site Cutoff Rigidity¶

Site cutoff rigidity is required by cutoff-aware incoming-neutron methods such as Hawdon (2014) and McJannet–Desilets (2023), and by pressure methods when Neptoon must derive a missing beta coefficient. It is not required by every correction. External tools such as CRNSLab can also estimate it.

You can also leave this blank and we have supplied a look up table which will provide a reasonable estimate of the cut-off rigidity using latitude and longitude of the site. When creating the SensorInfo class (either in a notebook or with the config system), if you leave site_cutoff_rigidity as None, Neptoon performs this lookup automatically from latitude and longitude.

You can also invoke this directly with the following code:

from neptoon.data_prep.cutoff_rigidity_lookup import GVLookup

lat = 10
lon = 10

gv = GVLookup().get_gv(lat=lat, lon=lon)
print(f'The site GV is: {gv}')