eomatch.mu_stac.MatchupCatalogue

eomatch.mu_stac.MatchupCatalogue#

class eomatch.mu_stac.MatchupCatalogue(id: str | None = None, description: str | None = None, path: str | None = None, catalog: Catalog | None = None, context: EOMatchContext | None = None)[source]#

STAC catalogue organising matchup events and matchup items.

Structure:

catalogue/
├── catalog.json
├── {collection-1}/
│   ├── collection.json
│   └── YYYY/MM/DD/{item-id}.json     # one per source product
├── {collection-2}/
│   └── …
├── matchup-events-{col-1}-{plat-1}-vs-{col-2}-{plat-2}/
│   ├── collection.json
│   └── YYYY/MM/DD/{item-id}.json     # one per MatchupEvent
└── {col-1}-{plat-1}-vs-{col-2}-{plat-2}/
    ├── collection.json
    └── YYYY/MM/DD/{item-id}.json     # one per Matchup

Each matchup Item links to its source products via derived_from and references its parent event via a matchup:event_id property and a related link.

__init__(id: str | None = None, description: str | None = None, path: str | None = None, catalog: Catalog | None = None, context: EOMatchContext | None = None) → None[source]#

Construct a new empty catalogue, wrap an existing pystac.Catalog, or reopen a catalogue already saved at path.

If catalog is not given and path points at a directory containing a catalog.json, that catalogue is reopened — preserving its existing collections and items — instead of starting a new, empty one. This lets a catalogue be built up incrementally by re-constructing (or calling save() again) with the same path across multiple runs.

Parameters:

  • id – STAC catalogue ID, used only when creating a new catalogue. Falls back to matchup_catalogue.id in context, then "matchup-catalogue".

  • description – STAC catalogue description, used only when creating a new catalogue. Falls back to matchup_catalogue.description in context, then "Matchup catalogue".

  • path – root directory for the catalogue on disk. Falls back to matchup_catalogue.path in context. If it contains an existing catalog.json, that catalogue is reopened.

  • catalog – an existing pystac.Catalog to wrap directly, bypassing id/description and the reopen check.

  • context – EOMatchContext supplying defaults; defaults to EOMatchContext().

Methods

__init__([id, description, path, catalog, ...])

Construct a new empty catalogue, wrap an existing pystac.Catalog, or reopen a catalogue already saved at path.

add_asset_by_id(collection_id, item_id, ...)

Add or replace a STAC asset on an item identified by collection and item ID.

add_event(event)

Add a MatchupEvent to the catalogue, returning its STAC Item.

add_event_asset(event, asset_key, asset)

Add or replace a STAC asset on a matchup event Item in the catalogue.

add_event_collection_asset(event, asset_key, ...)

Add or replace a STAC asset on the matchup-events Collection (e.g. matchup-events-LANDSAT_C2L1-vs-S3_EFR).

add_matchup(matchup[, event_id])

Add a Matchup and its source products to the catalogue, returning its STAC Item.

add_matchup_asset(matchup, asset_key, asset)

Add or replace a STAC asset on a matchup Item in the catalogue.

add_matchup_collection_asset(matchup, ...)

Add or replace a STAC asset on the matchup Collection (e.g. LANDSAT_C2L1-vs-S3_EFR).

add_product_asset(product, asset_key, asset)

Add or replace a STAC asset on a product Item in the catalogue.

download_products([event_set, filesystem])

Download all source products for the given events and register each as a "data" STAC asset on the matching product Item in the catalogue.

get_events([collections, platforms, ...])

Return MatchupEvents from the catalogue, each with its MatchupSet populated.

open(path)

Open an existing catalogue from a root catalog.json path.

remove_event_asset(event, asset_key[, ...])

Remove a STAC asset from a matchup event Item, optionally deleting the local file.

remove_event_collection_asset(event, asset_key)

Remove a STAC asset from the matchup-events Collection, optionally deleting the local file.

remove_matchup_asset(matchup, asset_key[, ...])

Remove a STAC asset from a matchup Item, optionally deleting the local file.

remove_matchup_collection_asset(matchup, ...)

Remove a STAC asset from the matchup Collection, optionally deleting the local file.

remove_product_asset(product, asset_key[, ...])

Remove a STAC asset from a product Item, optionally deleting the local file.

save([path, catalog_type])

Normalise hrefs and write the catalogue to disk.