Phenological Metrics — Phenology Pipeline

This page covers metrics computed by the phenology pipeline (src/vi_phenology.py): one row per year per region in a CSV, enabled with the --metrics flag.

The pixel phenology pipeline computes a related but distinct set of 19 per-pixel metrics stored as spatial map layers (one band per metric in a NetCDF). See Pixel Phenology Pipeline — Metrics.

Computed per year, per region, per VI from the smoothed daily series. Enable with --metrics. Requires a smoothing method (--smooth-method must not be none).

Metrics

Metric	Column	Description
SOS	`sos_date`, `sos_doy`	Start of Season: first date VI crosses the amplitude threshold going up
POS	`pos_date`, `pos_doy`, `pos_value`	Peak of Season: date and value of annual maximum
EOS	`eos_date`, `eos_doy`	End of Season: last date VI is still above the amplitude threshold
LOS	`los_days`	Length of Season: EOS − SOS in days
IVI	`ivi`	Integrated VI: trapezoidal area under the smooth curve between SOS and EOS
Greening rate	`greening_rate`	Mean slope (VI/day) from SOS to POS
Senescence rate	`senescence_rate`	Mean slope (VI/day) from POS to EOS (negative for a declining curve)
Floor NDVI	`floor_ndvi`	Annual minimum of the smooth curve (dry-season trough). Derived directly from the curve — no biome-specific DOY window needed.
Ceiling NDVI	`ceiling_ndvi`	Annual maximum of the smooth curve (= POS value)
Season length	`season_length_days`	Days above `floor + sos_threshold × amplitude`; computed from actual dates (cross-year safe)
Green-up rate	`greenup_rate`	`(ceiling − floor) / (peak_date − floor_date).days`
Peak count	`n_peaks`	Number of peaks detected by `scipy.signal.find_peaks` (prominence + distance thresholds)
Peak separation	`peak_separation_days`	Calendar days between the two tallest peaks (NaN if n_peaks < 2)
Relative peak amplitude	`relative_peak_amplitude`	`min(h1, h2) / max(h1, h2)` ratio between the two tallest peaks (NaN if n_peaks < 2)
Valley depth	`valley_depth`	Normalised trough depth between peaks: `((h1+h2)/2 − valley) / ((h1+h2)/2)` (NaN if n_peaks < 2)
CV	`cv`	Coefficient of variation of raw (unsmoothed) observations across the full time series. Same value on every year row for a given (vi, region).

SOS/EOS Threshold

SOS and EOS are determined relative to the annual amplitude:

baseline  = annual minimum VI
amplitude = annual peak − baseline
threshold = baseline + sos_threshold × amplitude

--sos-threshold controls the fraction of amplitude (default 0.20 = 20%).

Annual Windows — `--year-start-doy`

--year-start-doy sets the day of year at which each annual phenology window begins (default 1 = January 1). The correct value depends on biome and rainfall regime, not simply on hemisphere.

The rule: place the window boundary at the VI minimum for the target region. Placing it at or near the seasonal peak will cause SOS/EOS detection to fail or produce nonsensical results.

Biome / regime	Peak VI	VI minimum	Recommended `--year-start-doy`
Northern Hemisphere temperate	Jun–Aug	Dec–Jan	`1` (January 1)
Southern Hemisphere summer-rainfall (Savanna, Highveld)	Dec–Jan	Jun–Jul	`182` (July 1)
Southern Hemisphere winter-rainfall (Cape fynbos, Mediterranean)	Jun–Aug	Dec–Jan	`1` (January 1)

--year-start-doy only affects how annual windows are split for metric computation. It does not affect the annual phenology plot, which always groups by calendar year and displays January through December.

CLI Parameters

Argument	Default	Description
`--metrics`	off	Compute and export phenological metrics
`--sos-threshold FRACTION`	`0.20`	Amplitude fraction for SOS/EOS detection
`--year-start-doy DOY`	`1`	Day of year to begin each annual phenology window (1–365)
`--peak-prominence NDVI`	`0.05`	Minimum NDVI prominence for a peak to be counted by bimodality detection (only active when `--metrics` is set)
`--peak-min-distance DAYS`	`45`	Minimum separation in days between detected peaks (only active when `--metrics` is set)

Output Files

Per-region metrics are written to {VI}_{region}_metrics.csv in the per-region subdirectory. When --shapefile-field yields multiple regions for a shapefile, a combined {VI}_{shapefile_stem}_metrics.csv is also written to the shapefile root folder.

For full output file details, see Output.