libera_utils.footprint_matching.aggregation#

PSF aggregation engine: collapse a footprint’s native samples to one value.

Where this sits in the pipeline#

This is the last core-processing stage of footprint matching. Upstream, a reader has served the native SampleSet inside a footprint’s PSF bounding box, and the weighting module has assigned each sample a PSF weight. This module takes those (values, weights) and produces a single statistic per variable – the number that lands in the SSF-style output product. It is the only place a sample’s value is combined with another’s.

Two layers#

  1. Pure strategy functions (weighted_mean, weighted_mode, weighted_log_mean …). Each takes 1-D values and weights arrays and returns a small dict of named sub-results, following the methods in design doc section 2.8.1.4. These are reusable by scientists directly and are what the unit tests exercise. NaN values are excluded from every computation (doc: “NaN values are excluded from all computations”).

  2. A product-facing projection (aggregate_sample_variables()) that walks a reader’s product variable specifications, picks the right value row for each, dispatches to the correct strategy, and returns the single scalar the product definition stores for that variable, once per footprint per source. stack_product_values() then collects a reader’s stacked specs (its PRODUCT_STACKS, e.g. ERA5 pressure levels) into one array per stacked product variable.

CERES heritage#

The weighted statistics implement CERES ATBD v2.2 Eq. 4.4-17 xbar = sum(w*x) / sum(w) and its companions, and follow the CERES SSF convention of log-space averaging for pixel cloud optical depth. See https://ceres.larc.nasa.gov/documents/ATBD/pdf/r2_2/ceres-atbd2.2-s4.4.pdf

Optical depth is averaged in log space only where the samples are imager pixels, as CERES does when it convolves pixels into a footprint (see weighted_log_mean()). An optical depth a source has already averaged over its own footprint or grid cell, and every aerosol optical depth, is combined with the arithmetic mean: CERES takes “an arithmetic mean … of all imager pixels in the angular bin before they are weighted by the PSF” for aerosol optical depth (SSF-137, CERES SSF Collection Guide, Release 2, p. 101, https://ceres.larc.nasa.gov/documents/collect_guide/pdf/SSF_CG_R2V1.pdf).

Functions

aggregate(strategy, values, weights, **kwargs)

Run a named aggregation strategy and wrap it with sample bookkeeping.

aggregate_sample_variables(reader_cls, ...)

Aggregate one footprint's samples from one source to one scalar per product variable.

check_coverage(coverage, *[, ...])

Apply the CERES 75%/95% coverage rule.

stack_product_values(reader_cls, scalars)

Shape one footprint's per-spec scalars from one source into its product variables.

weighted_log_mean(values, weights, **_)

PSF-weighted geometric mean exp(sum(w*ln x)/sum(w)).

weighted_mean(values, weights, **_)

PSF-weighted mean xbar = sum(w*x)/sum(w) (CERES ATBD Eq.

weighted_mode(values, weights, *[, n_categories])

PSF-weighted mode argmax_c sum(w*[x==c]) for categorical variables.

weighted_mode_primary(values, weights, *[, ...])

Most common category by PSF weight (rank 0).

weighted_mode_secondary(values, weights, *)

Second most common category by PSF weight (rank 1).

weighted_mode_tertiary(values, weights, *[, ...])

Third most common category by PSF weight (rank 2).

weighted_positive_std(values, weights, **_)

PSF-weighted standard deviation over the strictly positive samples.

weighted_std(values, weights, **_)

PSF-weighted standard deviation sqrt(sum(w*x^2)/sum(w) - xbar^2).

Classes

AggregationResult(values, n_valid, n_total)

Output of a single aggregation, with sample bookkeeping.