pcmdi_metrics.effective_resolution.compute_effective_resolution_scalar

pcmdi_metrics.effective_resolution.compute_effective_resolution_scalar(field, field_name=None, ntrunc=None, gridtype='auto', fit_window=20, fit_anchor='right', steepening_factor=0.25, wavenumber_ratio=2.0, min_wavenumber=32, rsphere=6371000.0, grid_box_distance_km=None, model='model', member=None)[source]

Compute effective resolution from a single 2D scalar field.

This function extends the wind-based effective resolution diagnostic to work with any 2D atmospheric or oceanic field. Instead of kinetic energy spectra from vorticity/divergence, it computes a power spectrum directly from the field’s variance at each wavenumber.

Parameters:

field (xarray.DataArray) – 2D spatial field with dimensions (lat, lon) or (time, lat, lon). If time dimension is present, will average over time before computing spectrum. Examples: temperature, geopotential height, precipitation, sea surface temperature, etc.
field_name (str, optional) – Name of the field for labeling. Default is field.name or 'field'.
ntrunc (int or None, optional) – Triangular truncation wavenumber. Default None is nlat - 1.
gridtype ({"auto", "regular", "gaussian"}, optional) – Grid type for selecting quadrature weights. Default "auto" attempts to detect grid type automatically.
fit_window, fit_anchor, steepening_factor, wavenumber_ratio, min_wavenumber – Same as compute_effective_resolution(). Control slope fitting and steepening detection behavior.
rsphere (float, optional) – Earth radius in meters. Default is EARTH_RADIUS.
grid_box_distance_km (float or None, optional) – Explicit grid box distance. Default None computes from coordinates.
model (str, optional) – Model identifier for output structure. Default "model".
member (str or None, optional) – Member identifier for output structure. Default None uses "unspecified".

Returns:

metrics (dict) – Nested {model: {member: {...}}} structure containing:
- effective_wavenumberfloat or None
  Detected steepening wavenumber.
- effective_resolution_kmfloat or None
  Effective resolution length scale in km.
- grid_box_distance_kmfloat
  Nominal grid spacing.
- resolution_ratiofloat or None
  Ratio L_eff / L_box.
- resolution_ratio_dx_conventionfloat or None
  Ratio in Skamarock (2004) dx convention.
- is_upper_limitbool
  True if steepening detected at minimum wavenumber (upper limit only).
- steepening_wavenumberdict
  Single-element dict {field_name: l_eff}.
- steepening_eddy_scale_kmdict
  Single-element dict {field_name: L_eff}.
- field_namestr
  Name of analyzed field.
- analysis_typestr
  Set to 'scalar_field' to distinguish from wind analysis.
- criteriondict
  Detection parameters used.
- referencestr
  Citation string.
diagnostics (dict) – Contains:
- spectrumxarray.Dataset
  Power spectrum with power_spectrum, wavenumber, eddy_scale.
- slopexarray.DataArray
  Fitted spectral slope n(l).
- detectiondict
  Steepening detection information.

Notes

Physical Interpretation

Wind fields: KE spectrum → resolved kinetic energy scales
Scalar fields: Power spectrum → resolved variance scales

“Effective resolution” = scale below which variance is artificially damped by numerical diffusion, filters, or parameterizations.

Differences from Wind-Based Analysis

Single spectrum instead of rotational/divergent decomposition
No 2-of-3 confirmation rule (only one spectrum available)
Physical meaning depends on the field being analyzed

Use Cases

Temperature: Identify resolved temperature gradient scales
Geopotential: Understand resolved pressure system scales
Precipitation: Effective resolution of precipitation patterns
SST: Resolved ocean surface temperature scales
Any 2D field: General spectral analysis

Examples

>>> # Temperature at 500 hPa
>>> import xarray as xr
>>> ds = xr.open_dataset('model_output.nc')
>>> temp = ds['ta'].sel(plev=50000)
>>> metrics, diags = compute_effective_resolution_scalar(
...     temp,
...     field_name='temperature_500hPa',
...     model='HadGEM3-GC31-HM',
...     member='r1i1p1f1'
... )
>>> print(f"Effective resolution: {metrics['HadGEM3-GC31-HM']['r1i1p1f1']['effective_resolution_km']:.1f} km")

>>> # Sea surface temperature (with time dimension)
>>> sst = ds['tos']  # (time, lat, lon)
>>> metrics, diags = compute_effective_resolution_scalar(
...     sst,
...     field_name='SST',
...     model='CESM2'
... )