i7aof.convert

Conversion utilities and workflows for TEOS-10 operations and CT/SA/TF generation. The TEOS-10 steps use GSW via NumPy/xarray wrappers. See i7aof.convert for developer details and CMIP Inputs for usage and performance tips (e.g., time chunking).

TEOS-10 conversion utilities to compute Absolute Salinity (SA) and Conservative Temperature (CT) from Practical Salinity (SP) and potential temperature (PT), with xarray/dask support.

This module is I/O-free and operates on xarray DataArray/Dataset, keeping variable and dimension names flexible.

i7aof.convert.teos10.compute_ct(pt: DataArray, sa: DataArray) → DataArray

Compute Conservative Temperature (CT).

Parameters:

  • pt (xr.DataArray) – Potential temperature (degC), aligned with sa.

  • sa (xr.DataArray) – Absolute Salinity (g kg-1), aligned with pt.

Returns:

Conservative Temperature (degC) broadcast to the common grid and with attributes units and long_name set.

Return type:

xr.DataArray

i7aof.convert.teos10.compute_ct_freezing(sa: DataArray, z_or_p: DataArray, lat: DataArray | None = None, is_pressure: bool = False, use_poly: bool = True) → DataArray

Compute Conservative Temperature at the freezing point (CT_freezing).

Parameters:

  • sa (xr.DataArray) – Absolute Salinity (g kg-1).

  • z_or_p (xr.DataArray) – Depth (m, positive down) or TEOS-10 z (m, negative down) or pressure (dbar) if is_pressure=True. Will be broadcast to SA.

  • lat (xr.DataArray, optional) – Latitude in degrees, required when is_pressure is False to convert depth to pressure. Can be 1D (Y,) or 2D (Y,X).

  • is_pressure (bool, optional) – If True, interpret z_or_p as pressure (dbar). Otherwise, compute pressure from depth and latitude.

  • use_poly (bool, optional) – If True (default), use the computationally efficient polynomial fit gsw.CT_freezing_poly (approx error ~5e-4 to 6e-4 K). If False, use the exact method gsw.CT_freezing (Newton-Raphson based).

Returns:

Conservative Temperature at the freezing point (degC), aligned with sa and with attributes units and long_name set.

Return type:

xr.DataArray

i7aof.convert.teos10.compute_ct_sa(sp: DataArray, pt: DataArray, z_or_p: DataArray, lon: DataArray, lat: DataArray, is_pressure: bool = False, normalize_lon: bool = True) → Tuple[DataArray, DataArray]

Compute SA and CT together.

Parameters:

  • sp (xr.DataArray) – Practical Salinity (PSS-78, unitless).

  • pt (xr.DataArray) – Potential temperature (degC), aligned or broadcastable to sp.

  • z_or_p (xr.DataArray) – Depth (m, positive down), TEOS-10 z (m, negative down), or pressure (dbar) if is_pressure=True.

  • lon (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • lat (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • is_pressure (bool, optional) – If True, interpret z_or_p as pressure (dbar). Otherwise, compute pressure from depth and latitude.

  • normalize_lon (bool, optional) – Normalize longitudes to [0, 360).

Returns:

Tuple of (sa, ct), where sa is Absolute Salinity (g kg-1) and ct is Conservative Temperature (degC), both broadcast to the common grid and with standard attributes set.

Return type:

(xr.DataArray, xr.DataArray)

i7aof.convert.teos10.compute_sa(sp: DataArray, z_or_p: DataArray, lon: DataArray, lat: DataArray, is_pressure: bool = False, normalize_lon: bool = True) → DataArray

Compute Absolute Salinity (SA) from Practical Salinity (SP).

Parameters:

  • sp (xr.DataArray) – Practical Salinity (PSS-78, unitless).

  • z_or_p (xr.DataArray) – Depth (m, positive down) or TEOS-10 z (m, negative down) or pressure (dbar) if is_pressure=True. Will be broadcast to SP.

  • lon (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • lat (xr.DataArray) – Geographic coordinates in degrees. 1D or 2D accepted.

  • is_pressure (bool) – If True, interpret z_or_p as pressure (dbar). Otherwise, compute pressure from depth and latitude.

  • normalize_lon (bool) – Normalize longitudes to [0, 360).

Returns:

Absolute Salinity (g kg-1) with the same grid as sp and attributes units and long_name set.

Return type:

xr.DataArray

i7aof.convert.teos10.convert_dataset_to_ct_sa(ds_thetao: Dataset | DataArray, ds_so: Dataset | DataArray, thetao_var: str = 'thetao', so_var: str = 'so', lat_var: str = 'lat', lon_var: str = 'lon', depth_var: str = 'lev', depth_positive: str | None = None) → Dataset

Convert a thetao/so pair to a dataset with ct and sa.

Parameters:

  • ds_thetao (xr.Dataset or xr.DataArray) – Dataset containing potential temperature variable thetao_var (or a DataArray of potential temperature).

  • ds_so (xr.Dataset or xr.DataArray) – Dataset containing Practical Salinity variable so_var (or a DataArray of Practical Salinity).

  • thetao_var (str, optional) – Name of the potential temperature variable in ds_thetao.

  • so_var (str, optional) – Name of the Practical Salinity variable in ds_so.

  • lat_var (str, optional) – Names of the latitude and longitude coordinate variables.

  • lon_var (str, optional) – Names of the latitude and longitude coordinate variables.

  • depth_var (str, optional) – Name of the depth coordinate (commonly ‘lev’).

  • depth_positive ({"down", "up", None}, optional) – Explicit direction of depth_var. If None, inferred from CF attributes when available.

Returns:

Dataset with variables: - ct (degC): Conservative Temperature - sa (g kg-1): Absolute Salinity Common coordinates (time, depth_var, lat_var, lon_var) are attached when present in inputs. Basic provenance comments are set.

Return type:

xr.Dataset

i7aof.convert.paths.get_ct_sa_output_paths(config, model: str, scenario: str, workdir: str) → List[str]

Derive absolute output paths for converted ct_sa files based on the thetao and so file lists in the config. Filenames are formed by replacing the variable token (thetao/so) in the thetao basename with ‘ct_sa’ and writing into:

{workdir}/convert/{model}/{scenario}/Omon/ct_sa/

Returns a list of absolute output filenames, one per input pair, in the same order as the thetao list.

Parameters:

  • config (mpas_tools.config.MpasConfigParser) – Configuration object containing file lists under [{scenario}_files] for thetao and so.

  • model (str) – Name of the CMIP model (used to build the output directory path).

  • scenario (str) – Scenario key (e.g., historical, ssp585) used to select file lists from the config.

  • workdir (str) – Base working directory where converted files are written under convert/{model}/{scenario}/Omon/ct_sa.

Returns:

Absolute paths to ct_sa output files, one per thetao/so pair, in the same order as the thetao list.

Return type:

List[str]

i7aof.convert.cmip_to_ct_sa.convert_cmip_to_ct_sa(model: str, scenario: str, inputdir: str | None = None, workdir: str | None = None, user_config_filename: str | None = None) → None

Convert thetao/so monthly files to ct/sa for a CMIP model.

Conversion is performed per thetao/so pair. Outputs store only ct & sa plus coordinate variables; bounds variables for depth/lat/lon are injected only in the final merged file to avoid acquiring a spurious time dimension.

Parameters:

  • model (str) – Name of the CMIP model (used to select the model config and to construct output paths).

  • scenario (str) – Scenario key (e.g., ‘historical’, ‘ssp585’) used to pick input file lists from the config.

  • inputdir (str, optional) – Base directory where the relative input file paths are resolved. If not provided, uses [inputdir] base_dir from the config.

  • workdir (str, optional) – Base working directory where outputs will be written. If not provided, uses [workdir] base_dir from the config.

  • user_config_filename (str, optional) – Optional user config that overrides defaults (paths, variable names, chunk sizes, etc.).

i7aof.convert.cmip_to_ct_sa.main() → None
i7aof.convert.ct_sa_to_tf.clim_ct_sa_to_tf(clim_name: str, *, workdir: str | None = None, user_config_filename: str | None = None, progress: bool = True) → None

Compute TF from extrapolated climatology CT/SA (no time dimension).

Discovers extrapolated CT/SA files under:

workdir/extrap/climatology/<clim_name>

and writes TF files next to them by replacing _ct_extrap with _tf_extrap in the filenames (preserving any _z suffix).

i7aof.convert.ct_sa_to_tf.cmip_ct_sa_to_tf(model: str, scenario: str, clim_name: str, workdir: str | None = None, user_config_filename: str | None = None, time_chunk: int | None = None, progress: bool = True) → None

Compute monthly thermal forcing from bias-corrected CT/SA.

Discovers bias-corrected monthly ct/sa files under:

workdir/biascorr/<model>/<scenario>/<clim_name>/Omon/ct_sa

and writes monthly thermal forcing into:

workdir/biascorr/<model>/<scenario>/<clim_name>/Omon/tf

Output filenames replace “ct” with “tf” (e.g., *_ct.nc -> *_tf.nc).

Parameters:

  • model (str) – CMIP model name.

  • scenario (str) – Scenario key (e.g., ‘historical’, ‘ssp585’).

  • clim_name (str) – Name of the reference climatology used in bias correction.

  • workdir (str, optional) – Base working directory; if omitted, uses config “[workdir] base_dir”.

  • user_config_filename (str, optional) – Optional user config overriding defaults.

  • time_chunk (int | None, optional) – Number of time steps per processing chunk. If None, read from config section [ct_sa_to_tf] time_chunk; if missing, process all time at once.

  • progress (bool, optional) – If True (default), show a tqdm progress bar over time chunks.

i7aof.convert.ct_sa_to_tf.main_clim() → None
i7aof.convert.ct_sa_to_tf.main_cmip() → None