eomatch.Matchup.return_matchup_dataset

Matchup.return_matchup_dataset(collection_read_args: dict | None = None, crop_to_shared_valid_extent: bool | None = None) → DataTree

Return match-up dataset by downloading the products if required, reading in data for each product and assembling a match-up DataTree.

Per-collection vars_sel, read_params, and processors defaults are read from the read section of the context config (see _resolve_read_kwargs() for the full merge order). collection_read_args overrides those defaults at call time.

Basic usage — rely entirely on config defaults:

dt = matchup.return_matchup_dataset()

Select specific bands per collection — each collection has its own variable names, so override per collection keyed by STAC collection ID. vars_sel within a collection is a full replacement:

dt = matchup.return_matchup_dataset(
    collection_read_args={
        "S2_MSI_L1C":   {"vars_sel": {"meas": ["B02", "B03", "B04", "B08"]}},
        "LANDSAT_C2L1": {"vars_sel": {"meas": ["B2",  "B3",  "B4",  "B5" ]}},
    }
)

Apply specific processors per collection:

dt = matchup.return_matchup_dataset(
    collection_read_args={
        "S2_MSI_L1C": {"processors": {"toa_reflectance": {}}},
    }
)

Nudge a read parameter for one collection — read_params within a collection entry is merged at the sub-key level:

dt = matchup.return_matchup_dataset(
    collection_read_args={
        "LANDSAT_C2L1": {"read_params": {"use_chunks": True}},
    }
)

Crop to the shared valid-data extent — on by default; disable per call, or set read.crop_to_shared_valid_extent: false in the context config to disable it for every call unless overridden here:

dt = matchup.return_matchup_dataset(crop_to_shared_valid_extent=False)

Parameters:

• collection_read_args – per-collection call-time overrides, keyed by STAC collection ID. Each value is a dict with any of the keys vars_sel (full replacement), read_params (sub-key merge), and processors (full replacement). Takes precedence over config defaults for that collection.

• crop_to_shared_valid_extent – if True/False, overrides the read. crop_to_shared_valid_extent context config setting for this call (see _resolve_crop_to_shared_valid_extent()). If None (the default), that config setting is used.

Returns:

match-up DataTree with one node per sensor (sensor_1, sensor_2, …)

Raises:

ValueError – if no products are set on this matchup, or – only when cropping is enabled – if two or more products’ valid-data extents don’t overlap (see crop_to_shared_valid_extent()). Both cases raise the same exception type; catch code relying on ValueError to detect “no products” specifically should not assume that’s the only cause when cropping is enabled.