nemo_spinup_evaluation package

Submodules

nemo_spinup_evaluation.cli module

CLI to compute climate model diagnostics from NEMO restart/output files.

Loads a DINO setup YAML for variable mapping.
Runs selected metric suites (restart and/or output).
Optionally compares against a reference simulation and reports diffs/stats.

nemo_spinup_evaluation.cli.apply_metrics_output(grid_output, restart, mask)[source]

Apply metrics to standardized output datasets.

If restart is supplied, adds a computed density check using restart depth.

Return type:: Dict[str, Any]

nemo_spinup_evaluation.cli.apply_metrics_restart(data, mask)[source]

Apply metrics to a standardized restart dataset.

Returns a dict of {metric_name: result or ‘Error: …’}.

Return type:: Dict[str, Any]

nemo_spinup_evaluation.cli.compute_diffs_and_stats(results, ref_results)[source]

Compute signed diff, absolute error, and MAE/RMSE vs reference for xarray inputs.

Expect ref_results_with_prefix to have keys like ‘ref_<key>’.

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

Returns:

diffs: {‘diff_<key>’: DataArray, ‘diff_<key>_ae’: DataArray}
stats: {‘diff_<key>_mae’: float, ‘diff_<key>_rmse’: float}

nemo_spinup_evaluation.cli.ensure_results_dir(results_dir)[source]

Ensure the results directory exists.

Return type:: None

nemo_spinup_evaluation.cli.load_config(config_file, sim_path)[source]

Load the DINO-setup.yaml config file for variable mapping.

Currently uses a fixed path: configs/DINO-setup.yaml

Return type:: Mapping[str, Any]

nemo_spinup_evaluation.cli.main(argv=None)[source]

Command-line interface for computing climate model diagnostics.

Return type:: int

nemo_spinup_evaluation.cli.parse_args(argv)[source]

Parse command-line arguments for the CLI.

Return type:: Namespace

nemo_spinup_evaluation.cli.run_output_metrics(data, data_ref=None)[source]

Run output metrics and compute diffs/stats if reference provided.

Return type:: Dict[str, Any]

nemo_spinup_evaluation.cli.run_restart_metrics(data, data_ref=None)[source]

Run restart metrics and compute diffs/stats if reference provided.

Return type:: Dict[str, Any]

nemo_spinup_evaluation.loader module

Functions to load NEMO model output and restart files based on YAML configuration.

nemo_spinup_evaluation.loader.get_restart_file_path(base, restart_hint)[source]

Get the restart file path based on base directory and hint.

If restart_hint ends with ‘.nc’, it is treated as a direct file name. Otherwise, we search for files matching ‘{hint}.nc’ in the base directory.

Parameters:

base (str) – The base directory to search for restart files.
restart_hint (Optional[str]) – An optional hint for the restart file name (e.g., ‘restart’).

Returns:

The path to the restart file if found, otherwise None.

Return type:

Optional[str]

nemo_spinup_evaluation.loader.load_dino_data(mode, base, setup)[source]

Load DINO data according to YAML setup.

Parameters:

mode (str) – The mode of operation (e.g., “restart”, “output”, “both”).
base (str) – The base directory for loading data files.
setup (Mapping[str, object]) – A mapping containing the YAML configuration for data loading.

Returns:

A dictionary with the following keys:

mesh_mask: xr.Dataset
restart: xr.Dataset or None
grid: dict mapping canonical name to xr.DataArray
files: dict mapping relative path to xr.Dataset
paths: dict with keys base, mesh_mask, restart, output_files

Return type:

dict

nemo_spinup_evaluation.loader.load_grid_variables(base, output_specs, files_cache)[source]

Build a dict of {canonical_name: DataArray} with a single open per file.

Parameters:

base (str) – The base directory for loading data files.
output_specs (VarSpec) – The variable specifications for the output data.
files_cache (Dict[str, xr.Dataset]) – A cache of opened xarray datasets, keyed by file path.

Returns:

A dictionary mapping canonical variable names to their DataArray objects.

Return type:

Dict[str, xr.DataArray]

nemo_spinup_evaluation.loader.load_mesh_mask(path)[source]

Load the NEMO mesh mask file and validate required fields.

Return type:: Dataset

nemo_spinup_evaluation.loader.resolve_mesh_mask(mesh_mask, sim_path)[source]

Resolve the mesh mask path, handling absolute and relative paths.

Return type:: Path

nemo_spinup_evaluation.loader.standardise_vars(data, variable_map)[source]

Rename variables/coords/dims to the canonical field names.

The single variable in a DataArray is not renamed. All variables in Datasets are renamed. Coords are renamed in both DataArray and Dataset. nav_lat and nav_lon are promoted to coordinates.

Parameters:

data (xr.DataArray | xr.Dataset) – Input data to be standardised.
variable_map (VarMap) – Mapping of canonical field names and their variations for conversion.

Returns:

Standardised data, maintaining the same type as the input.

Return type:

xr.DataArray | xr.Dataset

nemo_spinup_evaluation.metrics module

Core metrics to evaluate physical consistency of simulations and projections.

nemo_spinup_evaluation.metrics.ACC_Drake_metric(uo, file_mask)[source]

Metric Extraction in the Drake Passage.

Antarctic Circumpolar Current Transport at the DINO equivalent of the Drake Passage at (x=0).

Version 1 of ACC metric: Computes the flux assuming rigid lid (no sea surface height variations), thus using the original e3u_0 variable from the mask. Unit: Sv

Parameters:

uo (xarray.DataArray) – Zonal velocity data for each point with dimension (t, depth, y, x) and 2D spatial coordinates (nav_lat, nav_lon).
file_mask (xarray.Dataset) – Dataset containing the grid mask variables (e2u, e3u_0, umask).

Returns:

1D DataArray (over time_counter), representing the total transport across Drake Passage (in Sv).

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics.ACC_Drake_metric_2(uo, ssh, file_mask)[source]

Metric Extraction of the Drake Passage.

Antarctic Circumpolar Current Transport at the DINO equivalent of the Drake Passage at (x=0). Version 2 of ACC metric: Computes the flux assuming varying ssh, thus needing to recompute e3u variable from e3u_0.

Unit: Sv

Parameters:

uo (xarray.DataArray) – Zonal velocity data with dimension (t, depth, y, x) and spatial coordinates (nav_lat, nav_lon). Zonal velocity value for each point.
ssh (xarray.DataArray) – Sea Surface Height data (t, y, x) and spatial coordinates (nav_lat, nav_lon).
file_mask (xarray.Dataset) – Dataset containing the grid mask variables (e2u, e3u_0, umask).

Returns:

1D DataArray (over time_counter), representing the total transport across Drake Passage (in Sv).

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics.NASTG_BSF_max(vo, ssh, file_mask)[source]

Metric Extraction of the North-Atlantic SubTropical Gyre (NASTG).

Intensity of the North-Atlantic SubTropical Gyre (NASTG) containing the Gulf-Stream current computed from the local maximum of the Barotropic Stream Function (BSF) Unit: Sv

Parameters:

vo (xarray.DataArray) – Meridional velocity data with dimension (t, depth, y, x) and coordinate (nav_lat, nav_lon). Meridional velocity value for each point.
ssh (xarray.DataArray) – Sea Surface Height data with dimensions (t, y, x) and spatial coordinates (nav_lat, nav_lon).
file_mask (xarray.Dataset) – Dataset containing the grid mask variables (e1v, e2v, vmask).

Returns:

1D DataArray (over time_counter), representing the maximum Barotropic Stream Function in the NASTG region (in Sv).

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics.check_density(density, epsilon=1e-05)[source]

Check density monotonicity violations in ocean data.

Calculate the proportion of grid points at each time step where the density profile violates the monotonic-with-depth constraint.

Parameters:

density (xarray.DataArray) – A 4D DataArray with dimensions including ‘time_counter’, ‘depth’, ‘y’, and ‘x’. Represents the density field over time and space.
epsilon (float, optional) – A small threshold used to determine significant non-monotonicity. Default is 1e-5.

Returns:

1D DataArray (over time_counter), with values in [0,1], representing the proportion of grid points per time step where density increases with depth beyond the epsilon threshold.

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics.temperature_500m_30NS_metric(temperature, file_mask)[source]

Metric Extraction Function.

Compute the average Temperature at 500m depth between 30N and 30S. Unit: °C.

Parameters:

temperature (xarray.DataArray) – Temperature data with dimensions (time_counter, depth, y, x) and 2D spatial coordinates (nav_lat, nav_lon).
file_mask (xarray.Dataset) – Dataset containing the grid mask variables (e1t, e2t, e3t_0, tmask).

Returns:

1D DataArray (over time_counter), representing the area-weighted mean temperature at 500m between 30N and 30S.

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics.temperature_BWbox_metric(temperature, file_mask)[source]

Metric Extraction in a “Bottom Water” box.

Average Temperature in a U-shaped “Bottom Water” box corresponding to waters below 3000m or beyond 30 degrees of latitude North and South.

________________________________________________ _Surface
| . . . . |__________________________| . . . . |_500m
| . . . . |                          | . . . . |
| . . . . |        Deep Water        | . . . . |
| . . . . |__________________________| . . . . |_3000m
| . . . . . . . . Bottom Water . . . . . . . . |
|______________________________________________|_Bottom
S        30S           Eq.          30N        N

Figure: Schematic Representation of the Bottom Water box used in this metric. Unit: °C

Parameters:

temperature (xarray.DataArray) – Temperature data with dimensions (time_counter, depth, y, x) and 2D spatial coordinates (nav_lat, nav_lon).
file_mask (xarray.Dataset) – Dataset containing the grid mask variables (e1t, e2t, e3t_0, tmask).

Returns:

1D DataArray (over time_counter), representing the area-weighted mean temperature in the Bottom Water box.

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics.temperature_DWbox_metric(temperature, file_mask)[source]

Metric Extraction in a “Deep Water” box.

Average Temperature in a “Deep Water” box corresponding to waters between 500m and 3000m depth and 30°N and 30°S.

________________________________________________ _Surface
|         |__________________________|         |_500m
|         | . . . . . . . . . . . . .|         |
|         | . . . .Deep Water . . . .|         |
|         |__________________________|         |_3000m
|                 Bottom Water                 |
|______________________________________________|_Bottom
S        30S           Eq.          30N        N

Figure: Schematic Representation of the Deep Water box used in this metric. Unit: °C

Parameters:

temperature (xarray.DataArray) – Temperature data with dimensions (time_counter, depth, y, x) and 2D spatial coordinates (nav_lat, nav_lon).
file_mask (xarray.Dataset) – Dataset containing the grid mask variables (e1t, e2t, e3t_0, tmask).

Returns:

1D DataArray (over time_counter), representing the area-weighted mean temperature in the Deep Water box.

Return type:

xarray.DataArray

nemo_spinup_evaluation.metrics_io module

Provide functions for writing metric results to a CSV file.

Includes handling both time series and static metrics using xarray DataArrays.

nemo_spinup_evaluation.metrics_io.write_metric_results(results, out_path, paths)[source]

Write metric results to CSV files.

Return type:: None

Writes two CSVs:

{out_path}.csv : timestamp + sim/ref/diff/diff_ae series
{out_path}_summary.csv : metric, mae, rmse

nemo_spinup_evaluation.utils module

Utility functions to support metric evaluation.

nemo_spinup_evaluation.utils.get_density(thetao, so, depth, tmask)[source]

Compute potential density referenced at the surface and density anomaly.

Parameters:

thetao (numpy.ndarray) – Temperature array of shape (t, z, y, x).
so (numpy.ndarray) – Salinity array of shape (t, z, y, x).
depth (numpy.ndarray) – Depth array of shape (t, z, y, x).
tmask (numpy.ndarray) – Mask array of shape (t, z, y, x).

Returns:

Potential density referenced at the surface.
Density anomaly.

Return type:

tuple of numpy.ndarray

nemo_spinup_evaluation.utils.get_depth(restart, mask)[source]

Calculate the depth of each vertical level on grid T in the 3D grid.

Parameters:

restart (xarray.Dataset) – The dataset containing ocean model variables.
mask (xarray.Dataset) – The dataset containing mask variables.

Returns:

deptht – The depth of each vertical level.

Return type:

numpy.array

Module contents

nemo-spinup-evaluation package for evaluating the spin-up of the NEMO model.