i7aof.clim

Purpose: Bundled climatology configurations used across the workflows (remap → extrapolate → bias correction → TF, etc.). This package ships versioned config files and serves as a stable reference for climatology metadata.

Public Python API (by module)

How configuration is loaded

  • i7aof.config.load_config() merges, in order:

    1. Base defaults from i7aof/default.cfg.

    2. Optional model config from i7aof.cmip (if a model is specified).

    3. Climatology config from i7aof.clim when clim_name is specified: config.add_from_package('i7aof.clim', f'{clim_name}.cfg').

    4. Optional user config file.

  • The argument clim_name is the stem of the file, e.g., zhou_annual_06_nov (without the .cfg extension).

What’s included

These packaged climatologies reflect curated variants. Current files include (examples):

  • zhou_annual_06_nov.cfg (preferred v2)

  • zhou_2000_annual_06_nov.cfg (v2, 2000-only variant)

  • zhou_summer_06_nov.cfg (v2, summer-only)

  • Legacy 30_sep variants retained for completeness and reproducibility.

See the user docs for recommendations and workflows that prefer the 06_nov (v2) set.

Config schema (section: [climatology])

Common options across the packaged files:

  • Variable and dimension names:

    • lat_var, lon_var, lev_var

    • lat_dim, lon_dim, lev_dim

  • Data arrays:

    • ct_var (Conservative Temperature)

    • sa_var (Absolute Salinity)

    • Optional MSE arrays: ct_mse_var, sa_mse_var

  • Quality control:

    • mse_threshold (omit values where MSE exceeds this threshold)

  • Input path:

    • filename: relative path to the source NetCDF under the configured input directory

  • Bias-correction window:

    • start_year, end_year used when forming the CMIP model climatology for bias correction

Example (zhou_annual_06_nov.cfg):

[climatology]
lat_var = latitude
lon_var = longitude
lat_dim = ny
lon_dim = nx
lev_var = pressure
lev_dim = nz
filename = Updated_TS_Climatology/OI_Climatology_v2/OI_Climatology.nc
ct_var = ct
sa_var = sa
ct_mse_var = ct_mse
sa_mse_var = sa_mse
mse_threshold = 1e9
start_year = 1995
end_year = 2024

Required config options

  • None in code. These files are consumed by higher-level steps that expect the keys above.

Outputs

  • No direct outputs from this package; consuming steps write outputs (remap/extrap/biascorr/convert/time).

Data model

Runtime and external requirements

  • None beyond the project’s standard environment; these are static configuration assets.

Usage

Programmatic:

from i7aof.config import load_config

config = load_config(clim_name="zhou_annual_06_nov", workdir="/work", inputdir="/inputs")
rel_path = config.get('climatology', 'filename')

CLI (via consuming steps):

  • Remap climatology: ismip7-antarctic-remap-clim -c zhou_annual_06_nov ...

  • Extrapolate climatology: ismip7-antarctic-extrap-clim -c zhou_annual_06_nov ...

  • Convert climatology CT/SA → TF: ismip7-antarctic-clim-ct-sa-to-tf -c zhou_annual_06_nov ...

Internals (for maintainers)

  • Packaged under i7aof/clim/*.cfg and included via setuptools package data; see pyproject.toml [tool.setuptools.package-data].

  • Consuming code references the [climatology] section keys to determine variable names, dimensions, thresholds, and source filename.

Edge cases / validations

  • Dim/var casing differences exist across upstream datasets (e.g., NY/NX vs ny/nx); the configs reflect each file’s reality.

  • If a required key is missing, consuming code will raise an error when it attempts to access it.

Extension points

  • Adding new climatologies: contribute new *.cfg files following the schema above.

  • Consider adding validation for the config schema during load, and docstring links in consuming modules to the config keys they require.