@bradtech/sensor-soil 1.1.0

package/src/SoilMoistureConverter.ts

@@ -0,0 +1,95 @@
+import { BaseSensorConverter, type ConversionContext, type ConversionOutput } from '@bradtech/sensor'
+
+/**
+ * Raw input parameters for soil volumetric water content evaluation.
+ */
+export interface SoilMoistureInput {
+   /** Sensor depth probe location in centimeters (10, 20, 30 cm) */
+   depthCm: 10 | 20 | 30 | number
+   /** Raw dielectric permittivity or capacitive reading from the probe */
+   rawValue: number
+   /** Soil temperature at the same depth in °C for thermal drift compensation */
+   soilTemperature?: number
+}
+
+/**
+ * Multi-depth Soil Moisture & Volumetric Water Content (VWC %) Converter.
+ *
+ * Implements:
+ * - Texture-specific linear regression calibration curves (Sand, Loam, Clay, Silt, Peat):
+ *   $$VWC = a \cdot \text{raw} + b$$
+ * - Custom plot-specific laboratory calibration model overrides ($y = \text{slope} \cdot x + \text{intercept}$).
+ * - Dielectric permittivity temperature compensation normalized to 20°C:
+ *   $$VWC_{comp} = VWC - (T_{soil} - 20) \cdot 0.04$$
+ */
+export class SoilMoistureConverter extends BaseSensorConverter<SoilMoistureInput> {
+   /** Sensor domain family classification */
+   readonly sensorFamily = 'soil'
+   /** Unique algorithmic model code */
+   readonly modelCode = 'soil-vwc-texture-calibrated'
+   /** Algorithm semver version */
+   readonly modelVersion = '1.0.0'
+   /** Human-readable model description */
+   readonly description = 'Texture-calibrated multi-depth soil volumetric water content converter'
+
+   /** Standard USDA soil texture regression coefficients [slope a, intercept b] */
+   private static TEXTURE_COEFFICIENTS: Record<string, { slope: number; intercept: number }> = {
+      sand: { slope: 0.92, intercept: -0.5 },
+      loam: { slope: 1.0, intercept: 0.0 },
+      clay: { slope: 1.15, intercept: 1.2 },
+      silt: { slope: 1.05, intercept: 0.5 },
+      peat: { slope: 1.25, intercept: 2.0 },
+      default: { slope: 1.0, intercept: 0.0 },
+   }
+
+   /**
+    * Converts raw capacitive probe readings into physical volumetric water content percentage (% VWC).
+    *
+    * @param raw - Raw sensor reading containing depth and uncalibrated value.
+    * @param context - Optional context providing soil texture classification or custom laboratory calibration models.
+    * @returns Array containing the calibrated soil moisture metric for the corresponding depth.
+    */
+   convert(raw: SoilMoistureInput, context?: ConversionContext): ConversionOutput[] {
+      const textureKey = context?.soilTexture || 'default'
+      const presetCoeff = SoilMoistureConverter.TEXTURE_COEFFICIENTS[textureKey] || SoilMoistureConverter.TEXTURE_COEFFICIENTS.default
+
+      // Check for plot-specific custom linear regression calibration model: y = slope * x + intercept
+      const customRegression = context?.soilLinearRegression || context?.calibration?.linearRegression
+      const slope = typeof customRegression?.slope === 'number' ? customRegression.slope : presetCoeff.slope
+      const intercept = typeof customRegression?.intercept === 'number' ? customRegression.intercept : presetCoeff.intercept
+      const calibrationType = customRegression ? 'custom_linear_regression' : 'texture_preset'
+
+      // Apply linear regression calibration: VWC (%) = a * raw + b
+      let vwc = raw.rawValue * slope + intercept
+
+      // Apply temperature compensation if soil temperature is known (standard reference at 20°C)
+      if (raw.soilTemperature !== undefined) {
+         const tempDelta = raw.soilTemperature - 20.0
+         // Dielectric permittivity of water decreases ~0.4%/°C
+         vwc = vwc - tempDelta * 0.04
+      }
+
+      // Clamp between 0% (oven dry) and 100% (free water saturation)
+      const clamped = this.clampWithConfidence(vwc, 0, 100, 0, 70)
+      const depth = raw.depthCm || 10
+
+      return [
+         {
+            metric: `okf:soil/moisture/${depth}cm`,
+            value: clamped.value,
+            unit: '%',
+            qudtUri: 'qudt:unit/PERCENT',
+            confidence: clamped.confidence,
+            metadata: {
+               depthCm: depth,
+               soilTexture: textureKey,
+               calibrationType,
+               calibrationSlope: slope,
+               calibrationIntercept: intercept,
+               customModelLabel: customRegression?.modelLabel,
+               rawInput: raw.rawValue,
+            },
+         },
+      ]
+   }
+}

package/src/SoilTemperatureConverter.ts

@@ -0,0 +1,49 @@
+import { BaseSensorConverter, type ConversionContext, type ConversionOutput } from '@bradtech/sensor'
+
+/**
+ * Raw input reading for depth-specific soil temperature.
+ */
+export interface SoilTemperatureInput {
+   /** Sensor depth probe location in centimeters (e.g. 10, 20, 30 cm) */
+   depthCm: number
+   /** Soil temperature in °C */
+   temperature: number
+}
+
+/**
+ * Multi-depth Soil Temperature Profile Converter.
+ * Normalizes multi-depth soil thermistor measurements with agronomic plausibility clamping.
+ */
+export class SoilTemperatureConverter extends BaseSensorConverter<SoilTemperatureInput> {
+   /** Sensor domain family classification */
+   readonly sensorFamily = 'soil'
+   /** Unique algorithmic model code */
+   readonly modelCode = 'soil-temperature-evaluator'
+   /** Algorithm semver version */
+   readonly modelVersion = '1.0.0'
+   /** Human-readable model description */
+   readonly description = 'Multi-depth soil profile temperature converter'
+
+   /**
+    * Converts raw soil temperature into depth-tagged physical metric records.
+    *
+    * @param raw - Object containing probe depth and measured temperature.
+    * @param _context - Optional environmental context.
+    * @returns Array containing the depth-tagged soil temperature metric.
+    */
+   convert(raw: SoilTemperatureInput, _context?: ConversionContext): ConversionOutput[] {
+      const depth = raw.depthCm || 10
+      const clamped = this.clampWithConfidence(raw.temperature, -20, 60, -10, 45)
+
+      return [
+         {
+            metric: `okf:soil/temperature/${depth}cm`,
+            value: clamped.value,
+            unit: '°C',
+            qudtUri: 'qudt:unit/DEG_C',
+            confidence: clamped.confidence,
+            metadata: { depthCm: depth },
+         },
+      ]
+   }
+}

package/src/SoilWaterPotentialConverter.ts

@@ -0,0 +1,96 @@
+import { BaseSensorConverter, type ConversionContext, type ConversionOutput } from '@bradtech/sensor'
+
+/**
+ * Input parameters for matric water potential and pF calculation.
+ */
+export interface SoilWaterPotentialInput {
+   /** Sensor depth probe location in centimeters */
+   depthCm: number
+   /** Volumetric water content in % (0 - 100) */
+   vwcPercent: number
+}
+
+/**
+ * Soil Matric Water Potential ($\Psi_m$ in kPa) & pF Retention Converter.
+ *
+ * Implements the Mualem-van Genuchten hydraulic retention model to relate volumetric
+ * water content ($\theta$) to matric suction pressure head ($h$ in cm of water) and logarithmic pF scale:
+ *
+ * $$S_e = \frac{\theta - \theta_r}{\theta_s - \theta_r}, \quad m = 1 - \frac{1}{n}$$
+ * $$h = \frac{1}{\alpha} \left(S_e^{-1/m} - 1\right)^{1/n}, \quad \Psi_m = -h \cdot 0.0980665 \text{ kPa}$$
+ * $$pF = \log_{10}(h_{cm})$$
+ */
+export class SoilWaterPotentialConverter extends BaseSensorConverter<SoilWaterPotentialInput> {
+   /** Sensor domain family classification */
+   readonly sensorFamily = 'soil'
+   /** Unique algorithmic model code */
+   readonly modelCode = 'soil-water-potential-van-genuchten'
+   /** Algorithm semver version */
+   readonly modelVersion = '1.0.0'
+   /** Human-readable model description */
+   readonly description = 'Van Genuchten soil water retention and pF water potential calculator'
+
+   /** Van Genuchten soil hydraulic retention parameters [$\alpha$, $n$, $\theta_r$, $\theta_s$] */
+   private static SOIL_VG_PARAMS: Record<string, { alpha: number; n: number; thetaR: number; thetaS: number }> = {
+      sand: { alpha: 0.145, n: 2.68, thetaR: 4.5, thetaS: 43.0 },
+      loam: { alpha: 0.036, n: 1.56, thetaR: 7.8, thetaS: 43.0 },
+      clay: { alpha: 0.008, n: 1.09, thetaR: 6.8, thetaS: 38.0 },
+      silt: { alpha: 0.016, n: 1.37, thetaR: 3.4, thetaS: 46.0 },
+      default: { alpha: 0.036, n: 1.56, thetaR: 7.8, thetaS: 43.0 },
+   }
+
+   /**
+    * Converts volumetric water content percentage into matric water potential (kPa) and pF availability scale.
+    *
+    * @param raw - Object containing probe depth and VWC percentage.
+    * @param context - Optional context specifying soil textural class.
+    * @returns Array containing both matric potential (kPa) and pF metrics.
+    */
+   convert(raw: SoilWaterPotentialInput, context?: ConversionContext): ConversionOutput[] {
+      const textureKey = context?.soilTexture || 'default'
+      const params = SoilWaterPotentialConverter.SOIL_VG_PARAMS[textureKey] || SoilWaterPotentialConverter.SOIL_VG_PARAMS.default
+
+      const theta = Math.min(params.thetaS - 0.1, Math.max(params.thetaR + 0.1, raw.vwcPercent))
+      const Se = (theta - params.thetaR) / (params.thetaS - params.thetaR) // Effective saturation
+      const m = 1.0 - 1.0 / params.n
+
+      // Matric suction head (h in cm of water column): h = (1/alpha) * (Se^(-1/m) - 1)^(1/n)
+      const hCm = (1.0 / params.alpha) * Math.pow(Math.pow(Se, -1.0 / m) - 1.0, 1.0 / params.n)
+
+      // Convert head cm to matric potential in kPa: 1 cm H2O ≈ 0.0980665 kPa
+      const potentialKpa = -(hCm * 0.0980665)
+
+      // pF = log10(h in cm)
+      const pF = Math.log10(Math.max(1.0, hCm))
+
+      const pFClamped = this.clampWithConfidence(pF, 0, 7.0)
+      const kpaClamped = this.clampWithConfidence(potentialKpa, -2000, 0)
+      const depth = raw.depthCm || 10
+
+      return [
+         {
+            metric: `okf:soil/potential/matric/${depth}cm`,
+            value: kpaClamped.value,
+            unit: 'kPa',
+            qudtUri: 'qudt:unit/KiloPA',
+            confidence: pFClamped.confidence,
+            metadata: {
+               depthCm: depth,
+               soilTexture: textureKey,
+            },
+         },
+         {
+            metric: `okf:soil/potential/pf/${depth}cm`,
+            value: pFClamped.value,
+            unit: 'pF',
+            qudtUri: 'qudt:unit/UNITLESS',
+            confidence: pFClamped.confidence,
+            metadata: {
+               depthCm: depth,
+               soilTexture: textureKey,
+               waterAvailabilityState: pF < 2.0 ? 'saturated' : pF < 2.5 ? 'field_capacity' : pF < 3.8 ? 'readily_available' : pF < 4.2 ? 'water_stress' : 'wilting_point',
+            },
+         },
+      ]
+   }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './SoilMoistureConverter'
+export * from './SoilWaterPotentialConverter'
+export * from './SoilTemperatureConverter'
+export * from './SoilElectricalConductivityConverter'