4.Experiment

Last step is to add information about the experiment which is a specific implementation of a workflow that can be used to reproduce a scientific output and generate a Product. An Experiment captures the full context of how a Product was generated, linking together workflows, inputs, and configuration in a way that makes results reusable and reproducible.
Experiments follow OGC record specifications as the Workflow entry. It is also stored in JSON record, with distinct, citable components—input.yaml and environment.yaml—to capture parameters and the execution environment. All resources are retrievable over open HTTPS, and catalog metadata persists even if external endpoints change. Interoperability is achieved via OSC themes (e.g., cryosphere) and standard representations (JSON/YAML), while qualified links connect the experiment to its generating workflow and resulting product. The record declares a license and aligns with EO community standards (OGC API Records; notebook environment specified via jupyter_kernel_info).

See example experiment metadata directly at open science catalogue metadata repository on GitHub to compare the list of required parameters and their format: See example experiment:ESA CCI permafrost

LICENSE: In this step you are required to select one of the available licenses for each of your experiment. Please have a look at available list of license and pick the one that fits your needs: osc-licence schemas.

If you have an experiment with non-defined license, we cannot proceed with publishing the experiment. Please use the list of licenses by SPDX and select the most appropriate one.
Visit EarthCODE Best Practices to learn more about Open Data & Licensing

This notebook shows how to add an OSC experiment record using the current earthcode API, save it in a local OSC catalog clone, and validate the full catalog.

from datetime import datetime
from pathlib import Path

from earthcode.metadata_input_definitions import ExperimentMetadata
from earthcode.static import create_experiment_record
from earthcode.git_add import save_experiment_record_to_osc
from earthcode.validator import validate_catalog

# experiment info
# Experiment id
experiment_id = ""
experiment_title = ""
experiment_description = ""
experiment_license = ""
experiment_keywords = [""]

# Define the input output formats that this experiment works with
# i.e. GeoTIFF, Zarr, netCDF, etc
experiment_formats = [""]

# Define themes i.e. land. Pick one or more from:
# - atmosphere, cryosphere, land, magnetosphere-ionosphere, oceans, solid-earth.
experiment_themes = [""]

# link to the specification of the input parameters for the experiment
experiment_input_parameters_link = ""
# link to the enviroment in which the experiment was performed
experiment_enviroment_link = ""

## ID and title of the associated workflow
workflow_id = ""
workflow_title = ""

## ID and title title of the associated product
product_id = ""
product_title = ""

# Optional experiment record fields
experiment_contacts = None
experiment_s = -180.0
experiment_w = -90.0
experiment_n = 180.0
experiment_e = 90.0
experiment_start_year = 2021
experiment_start_month = 1
experiment_start_day = 1
experiment_end_year = 2021
experiment_end_month = 12
experiment_end_day = 31
include_experiment_bbox = False
include_experiment_time = False

# Local OSC clone root path (assumed one folder above repository root)
catalog_root = str(Path("../open-science-catalog-metadata").resolve())

Create Experiment record

ℹ️ Note
This function creates an experiment metadata record and automatically generates record.json and all required links.
It connects the experiment with related project, workflow, themes and updates existing entries as needed.
Run the cell below to automatically create new entry.

catalog_root = Path(catalog_root)

experiment_metadata = ExperimentMetadata(
    experiment_id=experiment_id,
    experiment_title=experiment_title,
    experiment_description=experiment_description,
    experiment_license=experiment_license,
    experiment_keywords=experiment_keywords,
    experiment_formats=experiment_formats,
    experiment_themes=experiment_themes,
    experiment_input_parameters_link=experiment_input_parameters_link,
    experiment_enviroment_link=experiment_enviroment_link,
    workflow_id=workflow_id,
    workflow_title=workflow_title,
    product_id=product_id,
    product_title=product_title,
    contacts=experiment_contacts,
    experiment_bbox=[[experiment_w, experiment_s, experiment_e, experiment_n]] if include_experiment_bbox else None,
    experiment_start_datetime=datetime(experiment_start_year, experiment_start_month, experiment_start_day) if include_experiment_time else None,
    experiment_end_datetime=datetime(experiment_end_year, experiment_end_month, experiment_end_day) if include_experiment_time else None,
)

experiment_record = create_experiment_record(experiment_metadata)
save_experiment_record_to_osc(experiment_record, catalog_root)

errors, error_files = validate_catalog(catalog_root)
if errors or error_files:
    raise AssertionError(f"Catalog validation failed. errors={len(errors)} files={len(error_files)}")

print(f"Saved experiment: {experiment_record['id']}")
print("Catalog validation passed.")