openairclim.repository

Resolves, downloads, and caches OpenAirClim’s repository data (background concentration scenarios and response-surface lookup tables).

That data is published independently of this package, in https://github.com/dlr-pa/oac-data, with its own Zenodo-backed versioning (see REPOSITORY_DATA_RECORD_DOI).

openairclim.repository.DEFAULT_REPOSITORY_DATA_VERSION = '0.1.0'

Data repository release that this installed version of openairclim expects by default. Deliberately independent of openairclim’s own version number.

openairclim.repository.ENV_CACHE_DIR = 'OPENAIRCLIM_DATA_DIR'

Env var to override the shared cache location entirely.

openairclim.repository.REPOSITORY_DATA_RECORD_DOI = '10.5281/zenodo.22146823'

DOI of any already-published record (any version) in the dlr-pa/oac-data Zenodo deposition - NOT the “concept DOI” Zenodo shows in its “Cite all versions” box, which isn’t itself a queryable record via the API. Any real version’s DOI works as an anchor and returns every sibling version via fetch_record_versions, so this never needs updating as new versions are published - it is NOT tied to DEFAULT_REPOSITORY_DATA_VERSION below. Synced by dlr-pa/oac-data’s own “Sync to Zenodo” GitHub Actions workflow, not Zenodo’s built-in GitHub integration, because that only archives whole-repo zips, which doesn’t match the per-file record this module expects.

openairclim.repository.REQUIRED_FILES = ['co2_bg.nc', 'ch4_bg.nc', 'n2o_bg.nc', 'ch4_for_swv_calc.nc', 'resp_RF.nc', 'resp_RF_O3.nc', 'resp_ch4.nc', 'resp_cont.nc', 'resp_cont_lf.nc']

Filenames the repository dataset must contain.

openairclim.repository.check_data(cache_dir: str | Path) → list[str][source]

Return the names of any REQUIRED_FILES missing from cache_dir.

Parameters:

cache_dir (str or Path) – Directory to check.

Returns:

Filenames from REQUIRED_FILES not found in cache_dir.

Empty if everything is present.

Return type:

list[str]

openairclim.repository.download_data(record_or_doi: str | None = None, output_dir=None, data_version: str | None = None, force: bool = False) → Path[source]

Download OpenAirClim’s repository data from Zenodo into a local cache.

Parameters:

  • record_or_doi (str, optional) – Zenodo record ID or DOI to fetch, overriding the version-matched default.

  • output_dir (str or Path, optional) – Directory to download into. Defaults to get_cache_dir(data_version).

  • data_version (str, optional) – Data-repo release to fetch if record_or_doi isn’t given. Defaults to DEFAULT_REPOSITORY_DATA_VERSION. Ignored if record_or_doi is given.

  • force (bool, optional) – Re-download and overwrite even if a file already exists and passes checksum verification. Defaults to False.

Returns:

The directory the files were downloaded into.

Return type:

Path

Raises:

RuntimeError – If a downloaded file’s checksum doesn’t match the Zenodo record’s metadata.

openairclim.repository.get_cache_dir(data_version: str | None = None) → Path[source]

Resolve the shared cache directory for repository data.

Does not create the directory or check its contents.

Parameters:

data_version (str, optional) – Repository data version to namespace the cache directory by. Defaults to DEFAULT_REPOSITORY_DATA_VERSION.

Returns:

The resolved cache directory. If the ENV_CACHE_DIR environment

variable is set, it is returned as-is. Otherwise, a per-OS user data directory, namespaced by data_version.

Return type:

Path

openairclim.repository.is_data_present(cache_dir: str | Path, record: dict | None = None, verify_checksums: bool = False) → bool[source]

Check whether cache_dir already holds a complete, valid data set.

Parameters:

  • cache_dir (str or Path) – Directory to check.

  • record (dict, optional) – A fetched Zenodo record’s metadata, used for checksum verification. Required if verify_checksums=True.

  • verify_checksums (bool, optional) – If True, also verify each required file’s checksum against record. Defaults to False (existence-only check).

Returns:

True if every file in REQUIRED_FILES is present (and, if

requested, checksum-valid).

Return type:

bool

openairclim.repository.main()[source]

Parse command-line arguments and download OpenAirClim’s repository data.

openairclim.repository.resolve_record_id(data_version: str | None = None) → str[source]

Resolve the Zenodo record ID for a repository data version.

Parameters:

data_version (str, optional) – Data repository release to look for (e.g. “0.1.0”). Defaults to DEFAULT_REPOSITORY_DATA_VERSION.

Returns:

The matching Zenodo record ID.

Return type:

str

Raises:

ValueError – If no record with a matching metadata.version is found among REPOSITORY_DATA_RECORD_DOI’s sibling versions (no fallback to “latest”.)