@bradtech/sensor-air 1.1.0

package/src/EvapotranspirationConverter.ts

@@ -0,0 +1,77 @@
+import { BaseSensorConverter, type ConversionContext, type ConversionOutput } from '@bradtech/sensor'
+
+/**
+ * Daily temperature and radiation inputs required for reference evapotranspiration computation.
+ */
+export interface EvapotranspirationInput {
+   /** Daily minimum canopy temperature in °C ($T_{min}$) */
+   tempMin: number
+   /** Daily maximum canopy temperature in °C ($T_{max}$) */
+   tempMax: number
+   /** Daily mean canopy temperature in °C ($T_{mean}$) */
+   tempMean: number
+   /** Global extraterrestrial or measured solar radiation flux in $\text{MJ}/(\text{m}^2\cdot\text{day})$ ($R_a$) */
+   solarRadiationMj?: number
+   /** Geographic plot latitude in decimal degrees (e.g. 44.8378 for Bordeaux) */
+   latitudeDegrees?: number
+   /** Julian day of year ($1 - 366$) */
+   dayOfYear?: number
+}
+
+/**
+ * Agronomic Daily Reference Evapotranspiration ($ET_0$) Converter.
+ *
+ * Implements the internationally recognized FAO-56 Hargreaves-Samani temperature-radiation formulation:
+ * $$ET_0 = 0.0023 \cdot (T_{mean} + 17.8) \cdot \sqrt{T_{max} - T_{min}} \cdot R_a \cdot 0.408$$
+ *
+ * where $0.408$ represents the inverse of the latent heat of vaporization ($\lambda^{-1}$ in $\text{mm}/(\text{MJ}\cdot\text{m}^{-2})$).
+ */
+export class EvapotranspirationConverter extends BaseSensorConverter<EvapotranspirationInput> {
+   /** Sensor domain family classification */
+   readonly sensorFamily = 'air'
+   /** Unique algorithmic model code */
+   readonly modelCode = 'evapotranspiration-hargreaves-fao56'
+   /** Algorithm semver version */
+   readonly modelVersion = '1.0.0'
+   /** Human-readable model description */
+   readonly description = 'FAO-56 Hargreaves-Samani daily reference evapotranspiration (ET0) calculator'
+
+   /**
+    * Converts daily temperature extremes and radiation into daily reference crop evapotranspiration ($ET_0$ in mm/day).
+    *
+    * @param raw - Object containing $T_{min}, T_{max}, T_{mean}$, and optional radiation $R_a$.
+    * @param _context - Optional environmental context.
+    * @returns Single-element array containing the $ET_0$ metric in mm/day.
+    */
+   convert(raw: EvapotranspirationInput, _context?: ConversionContext): ConversionOutput[] {
+      const deltaT = Math.max(0, raw.tempMax - raw.tempMin)
+      const tMean = raw.tempMean
+
+      // Extraterrestrial radiation estimate (Ra) if not provided directly
+      let Ra = raw.solarRadiationMj
+      if (!Ra || Ra <= 0) {
+         // Default approximation for temperate European agricultural latitudes (~44°N)
+         Ra = 25.0
+      }
+
+      // Hargreaves-Samani equation: ET0 = 0.0023 * (Tmean + 17.8) * sqrt(Tmax - Tmin) * Ra * 0.408
+      const et0 = 0.0023 * (tMean + 17.8) * Math.sqrt(deltaT) * Ra * 0.408
+
+      const clamped = this.clampWithConfidence(et0, 0, 15, 0, 10)
+
+      return [
+         {
+            metric: 'okf:agronomy/evapotranspiration/et0',
+            value: clamped.value,
+            unit: 'mm/day',
+            qudtUri: 'qudt:unit/MilliM',
+            confidence: clamped.confidence,
+            metadata: {
+               method: 'Hargreaves-Samani-FAO56',
+               tempRange: Number(deltaT.toFixed(2)),
+               radiationMj: Ra,
+            },
+         },
+      ]
+   }
+}

package/src/GroundFrostRiskConverter.ts

@@ -0,0 +1,79 @@
+import { BaseSensorConverter, type ConversionContext, type ConversionOutput } from '@bradtech/sensor'
+
+/**
+ * Microclimate temperature and relative humidity inputs for frost risk evaluation.
+ */
+export interface GroundFrostInput {
+   /** Air temperature measured at plant/canopy height in °C ($T$) */
+   canopyTemperature: number
+   /** Relative humidity measured at plant/canopy height in % ($RH$) */
+   canopyHumidity: number
+}
+
+/**
+ * Radiative Ground Frost Risk & Wet-Bulb Temperature Converter.
+ *
+ * Implements the Roland Stull empirical formulation to compute the Psychrometric Wet-Bulb
+ * Temperature ($T_w$ in °C), which is the exact physical temperature reached by plant leaves
+ * and vegetative buds under radiative night cooling:
+ *
+ * $$T_w = T \cdot \arctan\left(0.151977 \cdot (RH + 8.313659)^{1/2}\right) + \arctan(T + RH) - \arctan(RH - 1.676331) + 0.00391838 \cdot RH^{3/2} \cdot \arctan(0.023101 \cdot RH) - 4.686035$$
+ */
+export class GroundFrostRiskConverter extends BaseSensorConverter<GroundFrostInput> {
+   /** Sensor domain family classification */
+   readonly sensorFamily = 'air'
+   /** Unique algorithmic model code */
+   readonly modelCode = 'ground-frost-risk-evaluator'
+   /** Algorithm semver version */
+   readonly modelVersion = '1.0.0'
+   /** Human-readable model description */
+   readonly description = 'Radiative ground frost risk and wet-bulb temperature calculator'
+
+   /**
+    * Converts canopy microclimate readings into wet-bulb temperature ($T_w$) and discrete agronomic frost severity index.
+    *
+    * @param raw - Object containing canopy temperature and relative humidity.
+    * @param _context - Optional environmental conversion context.
+    * @returns Array containing the wet-bulb temperature and the discrete frost risk index (0 to 3).
+    */
+   convert(raw: GroundFrostInput, _context?: ConversionContext): ConversionOutput[] {
+      const T = raw.canopyTemperature
+      const RH = raw.canopyHumidity
+
+      // Stull formula for Wet Bulb Temperature (Tw in °C):
+      const Tw =
+         T * Math.atan(0.151977 * Math.pow(RH + 8.313659, 0.5)) +
+         Math.atan(T + RH) -
+         Math.atan(RH - 1.676331) +
+         0.00391838 * Math.pow(RH, 1.5) * Math.atan(0.023101 * RH) -
+         4.686035
+
+      // Frost Risk Level: 0 (No risk), 1 (Monitoring, Tw < 3°C), 2 (Warning, Tw < 1°C), 3 (Severe Frost, Tw < 0°C)
+      let frostRisk = 0
+      if (Tw <= -0.5) frostRisk = 3
+      else if (Tw <= 1.0) frostRisk = 2
+      else if (Tw <= 3.0) frostRisk = 1
+
+      const twClamped = this.clampWithConfidence(Tw, -40, 50)
+
+      return [
+         {
+            metric: 'okf:agronomy/microclimate/wet_bulb_temperature',
+            value: twClamped.value,
+            unit: '°C',
+            qudtUri: 'qudt:unit/DEG_C',
+            confidence: twClamped.confidence,
+         },
+         {
+            metric: 'okf:agronomy/risk/frost_index',
+            value: frostRisk,
+            unit: 'level',
+            qudtUri: 'qudt:unit/UNITLESS',
+            confidence: 1.0,
+            metadata: {
+               frostState: frostRisk === 3 ? 'severe' : frostRisk === 2 ? 'warning' : frostRisk === 1 ? 'watch' : 'none',
+            },
+         },
+      ]
+   }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './CanopyMicroclimateConverter'
+export * from './EvapotranspirationConverter'
+export * from './GroundFrostRiskConverter'