pcmdi_metrics.effective_resolution.compute_effective_resolution

pcmdi_metrics.effective_resolution.compute_effective_resolution(ds, uvar='ua', vvar='va', levels=(250.0, 500.0), ntrunc=None, gridtype='auto', fit_window=20, fit_anchor='right', steepening_factor=0.25, wavenumber_ratio=2.0, min_wavenumber=32, n_confirm=2, rsphere=6371000.0, plev_name=None, grid_box_distance_km=None, temporal_averaging='slopes', model='model', exp=None, member=None, debug=False, save_interim_netcdf=False, output_dir='./output')[source]

Compute effective-resolution metrics from an already-opened Dataset.

This is the pure-computation entry point: no file I/O, no output files, no plots. Suitable for notebooks, pipelines and unit tests. ds is assumed to be on the model’s native grid; regridding beforehand destroys the very information the diagnostic measures.

Parameters:

  • ds (xarray.Dataset) – Dataset holding uvar and vvar on (time, plev, lat, lon). Coordinate names are resolved from the dataset’s own axis metadata, and the vertical coordinate may be in Pa or hPa. Klaver et al. use 6-hourly instantaneous winds over four months of a single year; sub-daily sampling matters because the diagnostic lives in the transient, small-scale part of the flow.

  • uvar, vvar (str, optional) – Zonal and meridional wind variable names. Defaults "ua", "va".

  • levels (tuple of float, optional) – Pressure levels to analyse, in hPa. Default (250.0, 500.0).

  • ntrunc (int or None, optional) – Triangular truncation. Default None (nlat - 1). Pass an explicit smaller value when matching studies that truncate below the model’s grid-implied limit.

  • gridtype ({"auto", "regular", "gaussian"}, optional) – Latitude grid type. Default "auto".

  • fit_window (int, optional) – Sliding-window width for the slope fit, in wavenumbers. Default 20.

  • fit_anchor ({"center", "right", "left"}, optional) – Window anchoring for the slope fit; see ~pcmdi_metrics.effective_resolution.lib.spectral_slope.fit_spectral_slope.

  • steepening_factor (float, optional) – Fractional exponent increase defining steepening. Default 0.25, described by the authors as ad hoc; vary it to test sensitivity.

  • wavenumber_ratio (float, optional) – Wavenumber ratio over which the increase is measured. Default 2.0.

  • min_wavenumber (int, optional) – Smallest wavenumber at which detection is attempted. Default 32.

  • n_confirm (int, optional) – Number of spectra that must show steepening. Default 2 (of 3).

  • rsphere (float, optional) – Sphere radius in metres. Default is ~pcmdi_metrics.effective_resolution.lib.ke_spectra.EARTH_RADIUS.

  • plev_name (str or None, optional) – Vertical coordinate name. Default resolves it from ds.

  • grid_box_distance_km (float or None, optional) – Representative grid box diagonal \(\tilde{L}_{box}\) in km. If None (default) it is derived from ds’s own grid. Pass an explicit value for reduced Gaussian or octahedral grids, where the Dataset’s rectilinear coordinates misrepresent the mesh.

  • temporal_averaging ({"spectra", "slopes"}, optional) – Temporal averaging strategy. Default "slopes" matches Klaver et al. (2020) Appendix S3: compute spectrum for each month separately, fit slopes to each monthly spectrum, then average the slopes across months. "spectra" uses the original implementation: average spectra across all time steps first, then fit a single slope curve. The two methods produce different results because fitting is a non-linear operation. Use "slopes" (default) for published-paper agreement; "spectra" for backward compatibility with earlier PMP versions.

  • model, exp, member (str or None, optional) – Labels used as keys in the returned metrics dict.

  • debug (bool, optional) – Print intermediate diagnostics. Default False.

  • save_interim_netcdf (bool, optional) – If True, save interim netCDF files containing:

    1. KE spectra file (ke_spectra_interim_{tag}.nc): Contains all rotational and divergent KE spectra (ke_rot_250, ke_div_250, ke_rot_500, ke_div_500) and spectral slopes in wavenumber space.

    2. Vorticity/divergence file (vorticity_divergence_{tag}.nc): Contains vorticity and divergence fields in physical space with dimensions (time, lat, lon) for each pressure level (vorticity_250, divergence_250, vorticity_500, divergence_500).

    Default False.

  • output_dir (str, optional) – Directory where interim netCDF files will be saved when save_interim_netcdf=True. Default "./output".

Returns:

  • metrics (dict) – Nested {model: {member: {...}}} in PMP style. The inner dict holds effective_wavenumber (\(l_{eff}\), None if fewer than n_confirm spectra steepen), effective_resolution_km (\(L_{eff}\), Eq. 3), grid_box_distance_km (\(\tilde{L}_{box}\)), resolution_ratio (\(L_{eff}/\tilde{L}_{box}\), the grid-independent headline metric, 2.7-4.8 across the paper’s models), resolution_ratio_dx_convention, is_upper_limit, n_spectra_steepening, steepening_wavenumber and steepening_eddy_scale_km per spectrum (keyed "div_250", "rot_250", "rot_500"), and steepening_wavenumber_range.

  • diagnostics (dict) – spectra ({level_hPa: Dataset}), slopes, detections and dataset – a single Dataset merging spectra and slopes, ready for to_netcdf or for ~pcmdi_metrics.effective_resolution.lib.plot.plot_spectra_and_slope.

Notes

Scales smaller than \(L_{eff}\) are dynamically unreliable and, per the authors, “should be disregarded in the context of interpretational climate studies”. The diagnostic says nothing about the fidelity of scales larger than \(L_{eff}\): a model can have a good effective resolution and a poor spectrum in the resolved range. Because this is a global, vertically sparse, time-mean spectrum, a single \(L_{eff}\) may also mask phenomenon-dependent behaviour, a caveat the authors raise explicitly.

Examples

>>> metrics, diags = compute_effective_resolution(
...     ds, model="HadGEM3-GC31-HM", member="r1i1p1f1"
... )
>>> metrics["HadGEM3-GC31-HM"]["r1i1p1f1"]["effective_wavenumber"]
108.0