Registering analysis results

Registering analysis results#

After computing a comparison or validation result for a matchup, you can attach the output file to the matchup’s STAC item as a versioned asset. This keeps the catalogue as the single source of truth: anyone querying the central catalogue can see what analysis has been run on each matchup and retrieve the result directly from the item metadata.

Two asset keys are written each time:

{prefix}:YYYY-MM-DD — a dated snapshot that is never overwritten. Each run adds a new dated key alongside any previous ones.
{prefix}:latest — always updated to point at the most recently registered file. Useful when you only want the current result without having to know its date.

The default prefix is comparison; you can supply any prefix to distinguish different kinds of analysis (e.g. validation, uncertainty).

—

From the command line#

eomatch-add-asset \
    --catalogue /data/my_catalogue \
    --collection-id LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A \
    --item-id     LC09_L1GT_089087_20220607_20220616_02_T2--S3A_EFR_20220607 \
    --file        /data/results/comparison_20260512.nc

This writes two assets to the item JSON on disk:

comparison:2026-05-12 (today’s date by default)
comparison:latest

Override the date, prefix, or MIME type if needed:

eomatch-add-asset \
    --catalogue /data/my_catalogue \
    --collection-id LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A \
    --item-id     LC09_L1GT_... \
    --file        /data/results/validation_run2.nc \
    --key-prefix  validation \
    --date        2026-05-01 \
    --media-type  application/x-netcdf \
    --title       "Validation run 2"

Add --push to also upsert the updated item directly into the running pgSTAC database (requires the ingest extra and a reachable database):

eomatch-add-asset \
    --catalogue /data/my_catalogue \
    --collection-id LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A \
    --item-id     LC09_L1GT_... \
    --file        /data/results/comparison_20260512.nc \
    --push \
    --db-host     your-server

Without --push, run eomatch-ingest afterwards to synchronise the whole catalogue (or just this item’s collection) with pgSTAC.

—

From Python#

import datetime as dt
from eomatch.add_asset import register_analysis

register_analysis(
    catalogue_path="/data/my_catalogue",
    collection_id="LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A",
    item_id="LC09_L1GT_089087_20220607_20220616_02_T2--S3A_EFR_20220607",
    file_path="/data/results/comparison_20260512.nc",
)

Retrieve the item afterwards to confirm both keys were registered:

from eomatch.mu_stac import MatchupCatalogue

cat = MatchupCatalogue.open("/data/my_catalogue")
col = cat.catalog.get_child("LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A")
item = next(col.get_items("LC09_L1GT_..."))

print(item.assets.keys())
# dict_keys(['comparison:2026-05-12', 'comparison:latest'])

print(item.assets["comparison:latest"].href)
# /data/results/comparison_20260512.nc

Multiple runs accumulate dated snapshots while latest rolls forward:

register_analysis(..., file_path="comparison_v1.nc", date=dt.date(2026, 5, 1))
register_analysis(..., file_path="comparison_v2.nc", date=dt.date(2026, 5, 12))

# item.assets now contains:
# comparison:2026-05-01  →  comparison_v1.nc
# comparison:2026-05-12  →  comparison_v2.nc
# comparison:latest      →  comparison_v2.nc

Push to pgSTAC in the same call by passing push=True:

register_analysis(
    catalogue_path="/data/my_catalogue",
    collection_id="LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A",
    item_id="LC09_L1GT_...",
    file_path="/data/results/comparison_20260512.nc",
    push=True,
    db_host="your-server",
    db_name="eomatch",
)

Connection parameters fall back to the ingest section of your eomatch config if not supplied explicitly:

# ~/.config/eomatch/user_config.yaml
ingest:
  db_host: your-server
  db_name: eomatch
  db_user: postgres

Pass the password via the PGPASSWORD environment variable rather than storing it in the config file:

export PGPASSWORD=your-postgres-password

—

Media type detection#

The MIME type is inferred from the file extension when media_type is not given:

Extension	MIME type
`.nc`	`application/x-netcdf`
`.zarr`	`application/vnd.zarr`
`.tif`	`image/tiff`
`.tiff`	`image/tiff`
`.json`	`application/json`
`.csv`	`text/csv`
`.png`	`image/png`
`.jpg`	`image/jpeg`
other	`application/octet-stream`

—

How assets appear in the central catalogue#

Assets with file:// hrefs (NFS paths) are visible on the internal API (/api/) but are stripped from responses served by the external API (/external/). This means:

Internal users (VPN access) see all assets, including analysis NetCDFs on NFS.
External collaborators using the STAC Browser or eomatch-query see the matchup metadata but not the file paths.

To expose an analysis result to external users, serve it over HTTP and register it with an http:// href rather than a local path.

—

Full reference#

eomatch.add_asset.register_analysis(catalogue_path: str, collection_id: str, item_id: str, file_path: str, key_prefix: str = 'comparison', date: date | None = None, media_type: str | None = None, title: str | None = None, push: bool = False, config=None, db_host: str | None = None, db_port: int | None = None, db_name: str | None = None, db_user: str | None = None, db_password: str | None = None, assets_base_url: str | None = None) → None[source]#

Register an analysis output file as versioned STAC assets on a matchup item.

Adds two assets to the item in the local catalogue:

{key_prefix}:{YYYY-MM-DD} — dated snapshot, never overwritten by future runs.
{key_prefix}:latest — always updated to point at the most recent file.

The local catalogue JSON is written immediately. Pass push=True to also upsert the updated item into the running pgSTAC database.

Example:

from eomatch.add_asset import register_analysis

register_analysis(
    catalogue_path="/data/catalogue",
    collection_id="LANDSAT_C2L1-Landsat-8-vs-S2_MSI_L1C-S2A",
    item_id="L8-S2A-20220613T001234",
    file_path="/data/results/comparison_20260512.nc",
    push=True,
    db_host="localhost",
    db_name="eomatch",
)

Parameters:

catalogue_path – path to the root catalogue directory or catalog.json.
collection_id – STAC collection ID containing the target item.
item_id – STAC item ID to attach the asset to.
file_path – path to the analysis output file.
key_prefix – prefix for the asset keys; defaults to "comparison".
date – date for the dated snapshot key; defaults to today.
media_type – MIME type for the asset; auto-detected from extension if None.
title – human-readable title for the asset; defaults to the filename.
push – if True, upsert the updated item into pgSTAC after saving locally.
config – path to a eomatch YAML config file, or a dict of overrides.
db_host – pgSTAC database host (used only when push is True).
db_port – pgSTAC database port.
db_name – pgSTAC database name.
db_user – pgSTAC database user.
db_password – pgSTAC database password.
assets_base_url – HTTP base URL at which catalogue assets are served; used to rewrite file:// hrefs when pushing to pgSTAC.