openairclim.utils.output_metadata

Functions relating to the OpenAirClim-specific output metadata.

openairclim.utils.output_metadata.get_metadata(path: str | Path, full: bool = False, recursive: bool = False) → dict[str, dict[str, Any]] | dict[str, str]

Return OpenAirClim metadata for a file or folder of output/figure files.

Useful for identifying which simulation an output netCDF file or figure belongs to, e.g. when you have a config_hash but can’t remember which run it came from.

Parameters:

• path (str or Path) – A single file, or a directory to scan for .nc and .png files.

• full (bool) – Return each file’s full metadata dict. Otherwise, return just the config_hash of files that carry one. Defaults to False.

• recursive (bool) – Scan subdirectories of path too. Defaults to False.

Returns:

If full, maps filename -> metadata for every file found that carries OpenAirClim metadata. If not full, maps filename -> config_hash.

Return type:

dict

openairclim.utils.output_metadata.main_get_metadata()

Parse command-line arguments and print/save OpenAirClim metadata.

openairclim.utils.output_metadata.main_write_config_from_netcdf()

Parse command-line arguments and recover a config from an output file.

openairclim.utils.output_metadata.read_metadata(path: str | Path) → dict[str, Any] | None

Read OpenAirClim metadata from a single output or figure file.

Parameters:

path (str or Path) – Path to a .nc or .png file.

Returns:

Metadata found in the file, or None if its suffix isn’t recognised, it can’t be opened, or it carries no OpenAirClim metadata (not an OpenAirClim output, or predating metadata support).

Return type:

dict or None

openairclim.utils.output_metadata.write_config_from_netcdf(nc_path: str | Path, toml_path: str | Path, relative_to: str | Path | None = None) → dict

Recover the config embedded in an OpenAirClim output file as TOML.

Useful for replicating a previous simulation if you have the results netCDF file but not the config TOML file. Or, for viewing the config of a previous simulation in a human-readable way.

Parameters:

• nc_path (str or Path) – A netCDF output file written by OpenAirClim, whose global attrs include a config_json dump written by gen_sim_metadata().

• toml_path (str or Path) – Destination path for the recovered config.

• relative_to (str or Path, optional) – If given, the config’s directory fields (inventories/background/responses/output/time dir, and inventories.base.dir) are rewritten relative to this directory, rather than being left as absolute files. See also prepare_for_save().

Returns:

The configuration written to toml_path.

Return type:

dict

Raises:

KeyError – If nc_path carries no embedded config metadata.