agri.growing-degree-days

export function growingDegreeDays(days: readonly DailyTemperature[], baseCelsius: number, upperCelsius: number | null, method: DegreeDayMethod): DegreeDays

/** One day's extremes in °C, taken to 0.1 °C. */
export interface DailyTemperature {
  readonly min: number;
  readonly max: number;
}

export type DegreeDayMethod = "average" | "clamped";

/** The total, and each day's contribution. */
export interface DegreeDays {
  /** sum of the exact daily values, then rounded half up to 0.1 */
  readonly total: number;
  /** each day exactly, a multiple of 0.05 */
  readonly daily: readonly number[];
}

import { growingDegreeDays } from "#fune/agri.growing-degree-days@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import { type DailyTemperature, type DegreeDayMethod, type DegreeDays } from "./agri_growing_degree_days_types.ts";

function tenths(value: number, message: string): number {
  if (typeof value !== "number" || !Number.isFinite(value) || value < -100 || value > 100) {
    throw new RangeError(message);
  }
  return Math.round(roundFloat(value, 1) * 10);
}

/**
 * Growing degree days, McMaster and Wilhelm (1997), in tenths of a degree.
 *
 * Each day is (max + min) / 2 - base with the temperatures taken to 0.1 °C,
 * so it is an exact multiple of 0.05 and the total is summed exactly and
 * rounded once. Rounding each day to 0.1 first and adding drifts: three days
 * of 0.05 are 0.15 (0.2 to one place), not 0.3.
 */
export function growingDegreeDays(
  days: readonly DailyTemperature[],
  baseCelsius: number,
  upperCelsius: number | null,
  method: DegreeDayMethod,
): DegreeDays {
  const base = tenths(baseCelsius, "baseCelsius must be a finite number from -100 to 100");
  let upper: number | null = null;
  if (upperCelsius !== null && upperCelsius !== undefined) {
    upper = tenths(upperCelsius, "upperCelsius must be a finite number from -100 to 100");
    if (upper <= base) throw new RangeError("upperCelsius must be above baseCelsius");
  }
  if (method !== "average" && method !== "clamped") {
    throw new RangeError(`unknown method "${method}": use average or clamped`);
  }
  const cap = (t: number): number => (upper !== null && t > upper ? upper : t);
  const daily: number[] = [];
  let sum = 0;
  days.forEach((day, i) => {
    const message = `day ${i + 1}: temperatures must be finite numbers from -100 to 100 °C`;
    let lo = tenths(day.min, message);
    let hi = tenths(day.max, message);
    if (lo > hi) throw new RangeError(`day ${i + 1}: min must not be above max`);
    lo = cap(lo);
    hi = cap(hi);
    let twice: number;
    if (method === "clamped") {
      twice = Math.max(lo, base) + Math.max(hi, base) - 2 * base;
    } else {
      twice = Math.max(lo + hi - 2 * base, 0);
    }
    // twice is 2 x (mean - base) in tenths, so the day is twice / 20 degrees.
    daily.push(twice / 20);
    sum += twice;
  });
  return { total: roundDiv(sum, 2, "half-up") / 10, daily };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add agri.growing-degree-days

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./agri.growing-degree-days-1.0.0-typescript.fune, or fetch it from a terminal with fune pull agri.growing-degree-days@1.0.0:typescript.

The whole function, every language, is one file too: agri.growing-degree-days-1.0.0.fune, 16,359 bytes, sha256 32de959c3bba666eb438eecb3ef515d8cd611fdb6ab664a9e7bfaf32c5c31bc8. It installs into a project of any language.

// fune: before agri.growing-degree-days

// fune: after agri.growing-degree-days

// fune: replace math.round-div in agri.growing-degree-days
// fune: replace math.round-float in agri.growing-degree-days

// fune: step agri.growing-degree-days after <n|label>

More from the author

McMaster and Wilhelm (1997) showed that "the" GDD equation is read two ways, and that the difference matters most on cool days, so the method is an argument rather than a hidden choice:

- **average** (their method 1): the day is (max + min) / 2 - base, and a negative day counts as 0. With an upper cap, max and min above the cap are first lowered to it. - **clamped** (their method 2, and the US "86/50" maize method): max and min are each held within base..upper first, then averaged and the base subtracted. A day that is 5 °C at dawn and 35 °C in the afternoon counts 10 GDD at base 10, cap 30, where averaging gives 7.5.

The upper cap is optional (null for none). Neither method models the hours above the cap (no triangle or sine methods).

## Exactness

Temperatures and the base are taken to 0.1 °C (half away from zero, `math.round-float`), so each day is an exact multiple of 0.05 and is returned as it is. The total adds the exact daily values and rounds once, half up, to 0.1. Rounding each day first would make three days of 0.05 into 0.3; this gives 0.2 (0.15 rounded).

## Limits

Temperatures, base and cap are -100 to 100 °C; the cap must be above the base; a day's min must not be above its max. An empty list is 0. The function does not know crop bases: 10 °C for maize, 0 °C for wheat thermal time and grass T-sum, 5 or 6 °C for many temperate crops are the caller's choice.

## Source

G. S. McMaster and W. W. Wilhelm, "Growing degree-days: one equation, two interpretations", Agricultural and Forest Meteorology 87 (1997) 291-300, https://doi.org/10.1016/S0168-1923(97)00027-0.

Files