API reference

This page provides an auto-generated summary of eomatch’s API. For more details and examples, refer to the relevant chapters in the user guide.

Domain model

MatchupEvent(collections, platforms, ...[, ...])	Interface event of satellites crossing each other
MatchupEvent.to_stac_item()	Return a STAC Item representing this matchup event.
MatchupEvent.from_stac_item(item)	Reconstruct a MatchupEvent from a STAC Item.
MatchupEvent.get_scrappi_queries()	Prepare one scrappi query per collection/platform pair in this MatchupEvent.
MatchupEvent.stac_id	STAC Item ID for this matchup event.
MatchupEvent.platformstring	Return platform names joined by underscore.
MatchupEvent.plot([ax, show_bbox, tick_step])	Plot the product footprints for all matchups in this event's matchup_set, coloured by collection.
MatchupEventSet([events])	Container for MatchupEvent objects
Matchup([products, context, assets, properties])	Interface collocated products
Matchup.collocation_region	Returns polygon of collocation region for matchup products
Matchup.plot_geometries([ax])	plot geometries in matchup set
Matchup.product_time_bounds	Returns earliest start time and latest stop time of matchup products
Matchup.time_diff_abs	Returns the absolute time difference between matchup product start times in seconds
Matchup.time_diff([collection1, collection2])	Returns the time difference collection2 - collection1 in total seconds.
Matchup.return_matchup_dataset([...])	Return match-up dataset by downloading the products if required, reading in data for each product and assembling a match-up DataTree.
Matchup.to_stac_item([event_id])	Return a STAC Item representing this matchup.
Matchup.from_stac_item(item[, context])	Reconstruct a Matchup from a STAC Item.
Matchup.stac_id	STAC Item ID for this matchup, or None if no products are set.
MatchupSet([matchups])	Container for Matchup objects
MatchupSet.collections	Returns collection sets of matchups within matchup set

Discovery

Sat2SatMUFinder(*args, **kwargs)	Finder for collocated pairs of satellite image products.
Sat2SatMUFinder.finder()	Run the full matchup discovery pipeline.
Sat2SatMUFinder.get_orbitx_ds()	Return an orbitx matchup dataset, either from a cached NetCDF or by running the propagator.
Sat2SatMUFinder.filter_events(data)	Filter a list of raw orbitx events against the bounds in the context config.
Sat2SatMUFinder.to_matchup_event(events)	Convert raw orbitx event dicts to MatchupEvent objects.
Sat2SatMUFinder.to_matchup_set(mu_events)	Query scrappi for each event and build per-event MatchupSet objects.

Sat2InSituMUFinder(*args, **kwargs)	Finder for collocated pairs of satellite and in-situ (ground-based) products.
Sat2InSituMUFinder.finder()	Run the full matchup discovery pipeline.
Sat2InSituMUFinder.identify_mu_events()	Identify candidate matchup events between the satellite and in-situ site.
Sat2InSituMUFinder.parse_matchup_events(products)	Split products into clusters by time gap, returning cluster boundary indices.
Sat2InSituMUFinder.to_matchup_set(mu_events)	Query scrappi for each event and build per-event MatchupSet objects.

Cataloguing

MatchupCatalogue([id, description, path, ...])	STAC catalogue organising matchup events and matchup items.
MatchupCatalogue.add_event(event)	Add a MatchupEvent to the catalogue, returning its STAC Item.
MatchupCatalogue.add_matchup(matchup[, event_id])	Add a Matchup and its source products to the catalogue, returning its STAC Item.
MatchupCatalogue.get_events([collections, ...])	Return MatchupEvents from the catalogue, each with its MatchupSet populated.
MatchupCatalogue.remove_matchup(matchup_id)	Remove a matchup Item from the catalogue by ID, tolerating a missing or corrupted item file.
MatchupCatalogue.save([path, catalog_type])	Normalise hrefs and write the catalogue to disk.
MatchupCatalogue.open(path[, context])	Open an existing catalogue from a root catalog.json path.
MatchupCatalogue.download_products([...])	Download all source products for the given events and register each as a "data" STAC asset on the matching product Item in the catalogue.
MatchupCatalogue.add_product_asset(product, ...)	Add or replace a STAC asset on a product Item in the catalogue.
MatchupCatalogue.add_asset_by_id(...[, ...])	Add or replace a STAC asset on an item identified by collection and item ID.
MatchupCatalogue.add_event_asset(event, ...)	Add or replace a STAC asset on a matchup event Item in the catalogue.
MatchupCatalogue.add_matchup_asset(matchup, ...)	Add or replace a STAC asset on a matchup Item in the catalogue.
MatchupCatalogue.add_matchup_collection_asset(...)	Add or replace a STAC asset on the matchup Collection (e.g. LANDSAT_C2L1-vs-S3_EFR).
MatchupCatalogue.add_event_collection_asset(...)	Add or replace a STAC asset on the matchup-events Collection (e.g. matchup-events-LANDSAT_C2L1-vs-S3_EFR).
MatchupCatalogue.remove_product_asset(...[, ...])	Remove a STAC asset from a product Item, optionally deleting the local file.
MatchupCatalogue.remove_event_asset(event, ...)	Remove a STAC asset from a matchup event Item, optionally deleting the local file.
MatchupCatalogue.remove_matchup_asset(...[, ...])	Remove a STAC asset from a matchup Item, optionally deleting the local file.
MatchupCatalogue.remove_matchup_collection_asset(...)	Remove a STAC asset from the matchup Collection, optionally deleting the local file.
MatchupCatalogue.remove_event_collection_asset(...)	Remove a STAC asset from the matchup-events Collection, optionally deleting the local file.
MatchupCatalogue.add_collection_asset(...[, ...])	Add or replace a STAC asset on a child Collection.
MatchupCatalogue.remove_collection_asset(...)	Remove a STAC asset from a child Collection, optionally deleting the local file.

Central catalogue

ingest([catalogue_path, config, db_host, ...])

Push a local pystac catalogue into a pgSTAC database.

query(api_url, output_path[, collections, ...])

Pull items from a STAC API and write them to a local pystac catalogue.

Enrichment

enrich(catalogue, enrichers[, overwrite, ...])

Apply enrichers to matchup items in catalogue.

cloud_cover(matchup)

Return the highest cloud fraction among this matchup's products.

insitu_time_diff(matchup)

Return the real-data proximity of this matchup's in-situ product(s) to the crossover.

roi_cloud_cover(matchup[, ...])

Return the percentage of this matchup's collocation region flagged as cloud.

roi_valid_fraction(matchup[, ...])

Return the fraction of this matchup's collocation region with valid satellite data.

time_diff(matchup)

Return the signed time difference between the two sensor overpasses.

geometric(matchup)

Return the area and centroid of the collocation region.

solar_elevation(matchup)

Return the solar elevation angle at the collocation centroid midpoint.

land_fraction(matchup)

Return the fraction of the collocation region that lies over land.

Pipeline

find_and_catalogue([context, path, ...])

Run Sat2SatMUFinder and persist all found events and matchups to a STAC catalogue.

find_and_catalogue_insitu([context, path])

Run Sat2InSituMUFinder and persist all found events and matchups to a STAC catalogue.

Datasets and previews

BuildMUDT([context])	Utility class for building matchup DataTree datasets.
BuildMUDT.run(matchup[, ...])	Build a matchup DataTree from a Matchup.
BuildMUDT.read_products(product_item_set, roi)	Read each product in product_item_set, subsetting spatial (raster) products to roi.
BuildMUDT.to_datatree(product_ds[, ...])	Assemble an xarray.DataTree from a list of per-sensor datasets.
resolve_product_path(product[, download])	Resolve the local filesystem path for product, downloading it first if needed.

preview_matchup(matchup[, output_path, ...])

Generate a side-by-side preview image for a matchup.

generate_previews(catalogue_path[, ...])

Generate preview thumbnails for matchups and events in a STAC catalogue.

Managing assets and products

register_analysis(catalogue_path, ...[, ...])	Register an analysis output file as versioned STAC assets on a matchup item.
generate_missing_assets(items, asset_key, ...)	Generate and register asset_key for every item in items that doesn't already have it.

download_catalogue_products([context, path, ...])	Download source products for catalogue events matching the given filters.
remove_catalogue_products([context, path, ...])	Remove downloaded product files for catalogue events matching the given filters.

status(api_url[, config])

Print a status summary of the central catalogue to stdout.

Utilities

crop_to_shared_valid_extent(product_ds)

Crop gridded products to the lat/lon bounding box where all of them have valid measurement data.