eoio.processors.stack.processor module

eoio.processors.stack.processor

Stack per-variable EO bands into cube-like DataArrays.

Many EO products are represented with one variable per band (e.g. B01, B02, …). This processor groups variables that share the same physical quantity (measurand attribute) and spatial grid (dimension names), then concatenates them along a new stacking dimension to produce a single cube-like DataArray per group.

Variables without a measurand attribute are left unchanged.

Per-band ancillary variables (identified via CF ancillary_variables attributes) are stacked automatically alongside their parent group, inheriting the parent’s stacking coordinates. This ensures e.g. per-band viewing angles share the same wavelength axis as the reflectance cube they annotate.

Example output for a Sentinel-2 dataset:

toa_reflectance_10m(stack_dim_10m, y_10m, x_10m)     # B02, B03, B04, B08
viewing_zenith_angle_10m(stack_dim_10m, y_10m, x_10m) # VZA_B02, VZA_B03, …
toa_reflectance_20m(stack_dim_20m, y_20m, x_20m)     # B05, B06, B07, …

The stacking dimension name includes the grid suffix so that cubes on different grids use different dimension names and can coexist in the same Dataset.

User config example:

processors = {
    "stack.cubes": {},
}

# Use wavelength values as the stacking coordinate:
processors = {
    "stack.cubes": {"dim_coord_attr": "central_wavelength"},
}

# Use a value nested inside a metadata dict:
processors = {
    "stack.cubes": {"dim_coord_attr": "product_metadata.central_wavelength"},
}

# Use a custom stacking dimension name:
processors = {
    "stack.cubes": {"stack_dim": "band"},
}

# Keep per-variable originals alongside the cubes:
processors = {
    "stack.cubes": {"drop_originals": False},
}

class eoio.processors.stack.processor.StackCubes(params: Dict[str, Any] | None = None, context: Dict[str, Any] | None = None)

Bases: BaseProcessor

Stack compatible per-variable EO bands into cube-like DataArrays.

Variables are grouped by measurand attribute and spatial grid (inferred from dimension names). Each group with two or more variables is concatenated along a new stacking dimension.

Per-band ancillary variables (those listed in constituent variables’ ancillary_variables attributes, following CF conventions) are stacked automatically using the same coordinate values as their parent group. This allows e.g. per-band viewing angles to share a wavelength axis with the reflectance cube they annotate.

By default, variables are sorted lexicographically by name and the stacking coordinate contains the original variable names. When dim_coord_attr is set, coordinate values are taken from the named attribute on each variable and the stacking order follows the attribute values (ascending).

Processor parameters

param stack_dim:

Base name for the stacking dimension. The grid suffix is appended automatically so cubes on different grids get unique dimension names (e.g. "stack_dim" → "stack_dim_10m", "stack_dim_20m"). Default: "stack_dim".

param dim_coord_attr:

Attribute path (dot-separated) whose value is used as the stacking coordinate instead of the variable name. A simple key such as "central_wavelength" reads da.attrs["central_wavelength"]; a dotted path such as "product_metadata.central_wavelength" traverses nested dicts. If any variable in a group is missing the resolved value, the group falls back to variable names as coordinates. Default: None (use variable names).

param drop_originals:

If True (default), remove the original per-variable entries from the dataset after stacking. Set to False to keep them alongside the cube.

param stack_ancillaries:

If True (default), automatically stack per-band ancillary variables (identified via CF ancillary_variables attributes) alongside their parent group using the parent’s stacking coordinates.

param coord_attrs:

List of per-band attribute names to promote to auxiliary coordinate variables on the stacking dimension. For example, ["central_wavelength", "bandwidth"] makes those values accessible as labelled coordinates rather than list attrs. Attributes not listed here but that still differ across variables are kept as list attrs in stacking order. Default: None (no promotion).

param measurand_attr:

Variable attribute used to identify the physical quantity. Default: "measurand". Change this if your reader uses a different attribute name (e.g. "standard_name").

param dim_attrs:

Dictionary of attributes to set on the stacking dimension coordinate variable. Applied after any auto-detected attributes (e.g. units from a _unit sibling), so entries here take precedence. For example, {"long_name": "centre wavelength", "standard_name": "radiation_wavelength"}. Default: None.

name = 'stack'

run(ds: Dataset) → Dataset

Stack compatible variables into cubes and return the updated dataset.

Parameters:

ds – Input dataset.

Returns:

Dataset with cube variables added (and originals removed if drop_originals is True).