libera_utils.footprint_matching.aggregation.aggregate_sample_variables#

libera_utils.footprint_matching.aggregation.aggregate_sample_variables(reader_cls: type[AncillaryReader], samples: SampleSet, weight_field: WeightField) → dict[str, float]#

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

For the given reader, this picks the correct value row for each product variable (see _map_product_specs), dispatches to that variable’s aggregation strategy with the PSF weight_field, and returns the single scalar the product stores – keyed by the bare spec name (the caller prefixes it with <READER_KEY>_ to form the product variable name).

An empty or all-NaN sample set yields NaN for every variable (the aggregation strategies return NaN when nothing is usable), which is the signal for a region the source does not cover.

Parameters:

  • reader_cls (type[AncillaryReader]) – The reader class whose product variables to compute.

  • samples (SampleSet) – The native samples inside this footprint’s PSF bounding box.

  • weight_field (WeightField) – Per-sample PSF weights aligned to samples.lats / samples.lons.

Returns:

{spec.name: scalar} for every variable in reader_cls.product_variable_specs().

Return type:

dict[str, float]

Raises:

ValueError – If a product variable cannot be mapped to a read variable or names an unregistered aggregation (see _map_product_specs); if samples.values is not (len(reader_cls.VARIABLES), samples.n_samples); or if weight_field.weights does not hold one weight per sample.

Notes

Only the scalar each strategy yields is returned, so this dispatches to the strategy cores directly rather than through aggregate(). Coverage is the weigher’s (WeightField.coverage, scored by check_coverage()), not computed here. Because many product variables derive from the same data plane – a variable and its _Standard_Deviation companion, or IGBP’s four ranked-mode scenes off one Surface_Type plane – the per-plane _usable mask (continuous) and category histogram (categorical) are computed once and reused across those variables.