API Reference

APIs

Unless specified, the following Application Programming Interfaces (APIs) are available in pcmdi_metrics (> v3.6.1) or higher.

Analysis & Diagnostics

PMP is currently expanding its public APIs for diagnostics and metrics. This effort is intended to make more of PMP’s capabilities available through a cleaner, more flexible and accessible for users and developers. As the API surface grows, additional diagnostics and metric calculations will be exposed in a way that supports both programmatic use and integration into workflows, while maintaining consistency with the package’s existing design and documentation conventions.

Note

variability_mode.eof_classification and sea_ice.calc_iiee_annual_cycle APIs are available in pcmdi_metrics version v4.1 and later.
mjo.compute_mjo_ewr_from_dataset API is available in pcmdi_metrics version v4.1.1 and later.
variability_mode, qbo, and hadley_cell APIs are available in version v4.2 or later.
effective_resolution APIs are available in version v4.2.2 or later.

Atmospheric Circulation & Dynamics

Effective Resolution Diagnostics:

`effective_resolution.compute_effective_resolution`(ds)	Compute effective-resolution metrics from an already-opened Dataset.
`effective_resolution.compute_effective_resolution_scalar`(field)	Compute effective resolution from a single 2D scalar field.
`effective_resolution.process_effective_resolution`(params)	Compute effective-resolution metrics from input file paths.

Spectral Analysis (Standalone):

Compute kinetic energy or power spectra without running the full effective resolution diagnostic. Useful for turbulence analysis, model evaluation, or custom spectral studies.

`effective_resolution.compute_ke_spectra`(ds)	Rotational and divergent KE spectra for a single 2-D wind field.
`effective_resolution.compute_ke_spectra_timeseries`(ds)	KE spectra for every time step at one pressure level, optionally averaged.
`effective_resolution.compute_power_spectrum`(...)	Compute power spectrum of a 2D scalar field via spherical harmonics.

Other Diagnostics:

`hadley_cell.hadley_cell_metrics`(vwnd_ds, ...)	Calculate Hadley cell meridional stream function and edge positions.
`qbo.compute_qbo_mjo_metrics`(ds, ds2, ...[, ...])	Compute QBO-MJO metrics from already-opened xarray Datasets.

Tropical Variability

mjo.compute_mjo_ewr_from_dataset(ds, data_var)

Compute the MJO east-west power ratio from an open xarray Dataset.

Extratropical Variability Modes

`variability_mode.NAO`(model_ds[, data_var, ...])	Compute North Atlantic Oscillation (NAO) diagnostics and metrics.
`variability_mode.NAM`(model_ds[, data_var, ...])	Compute Northern Annular Mode (NAM) diagnostics and metrics.
`variability_mode.SAM`(model_ds[, data_var, ...])	Compute Southern Annular Mode (SAM) diagnostics and metrics.
`variability_mode.PNA`(model_ds[, data_var, ...])	Compute Pacific North American Pattern (PNA) diagnostics and metrics.
`variability_mode.NPO`(model_ds[, data_var, ...])	Compute North Pacific Oscillation (NPO) diagnostics and metrics.
`variability_mode.PSA1`(model_ds[, data_var, ...])	Compute Pacific-South American Pattern 1 (PSA1) diagnostics and metrics.
`variability_mode.PSA2`(model_ds[, data_var, ...])	Compute Pacific-South American Pattern 2 (PSA2) diagnostics and metrics.
`variability_mode.PDO`(model_ds[, data_var, ...])	Compute Pacific Decadal Oscillation (PDO) diagnostics and metrics.
`variability_mode.NPGO`(model_ds[, data_var, ...])	Compute North Pacific Gyre Oscillation (NPGO) diagnostics and metrics.
`variability_mode.AMO`(model_ds[, data_var, ...])	Compute Atlantic Multidecadal Oscillation (AMO) diagnostics and metrics.
`variability_mode.eof_classification`([...])	Classify model EOFs as East Atlantic (EA) or Scandinavian (SCA) patterns.

Cryosphere

sea_ice.calc_iiee_annual_cycle(ds_obs, ds_model)

Compute the monthly climatological annual cycle of Integrated Ice-Edge Error (IIEE) between observational and model sea ice concentration datasets.

Custom calendars

Functions for computing seasonal averages and departures with custom calendar definitions.

`utils.custom_season_average`(ds, data_var, season)	Calculates the average of a user defined season in each year.
`utils.custom_season_departure`(ds, data_var, ...)	Calculate the departure from a reference seasonal climatology for each season in a given year.
`utils.replace_date_pattern`(filename, replacement)	Replace the 'YYYYMM-YYYYMM' pattern in a filename with a specified replacement.

Data load

Load climate model and observational datasets using xCDAT.

io.xcdat_open(infile[, data_var, ...])

Open input file (netCDF, or xml generated by cdscan)

Date

Utilities for date string formatting, parsing, and finding overlapping time periods.

`utils.date_to_str`(date_obj)	Convert a date object to a string in 'YYYY-MM-DD' format.
`utils.extract_date_components`(ds[, index])	Extract year, month, and day from a dataset's time dimension.
`utils.find_overlapping_dates`(ds, start_date, ...)	Find the overlapping period between given dates and a dataset's time range.

Land-sea mask

Create and apply land-sea masks to datasets for ocean-only or land-only analysis.

`utils.create_land_sea_mask`(obj[, lon_key, ...])	Generate a land-sea mask (1 for land, 0 for sea) for a given xarray Dataset or DataArray.
`utils.apply_landmask`(obj[, data_var, ...])	Apply a land-sea mask to a given DataArray or Dataset.
`utils.apply_oceanmask`(obj[, data_var, ...])	Apply an ocean mask to a given DataArray or Dataset.

Graphics

Plotting functions for model evaluation and intercomparison. Example usages are available in the demo notebooks.

`graphics.parallel_coordinate_plot`(data, ...)	Create a parallel coordinate plot for visualizing multi-dimensional data.
`graphics.portrait_plot`(data, xaxis_labels, ...)	Create a portrait plot for visualizing 2D data arrays.
`graphics.TaylorDiagram`(stddev, corrcoef, refstd)	Create a Taylor diagram.

Grid and regrid

Functions for creating target grids and regridding datasets to different spatial resolutions.

`utils.create_target_grid`([lat1, lat2, lon1, ...])	Generate a uniform grid for given latitude/longitude ranges and resolution
`utils.regrid`(ds, data_var, target_grid[, ...])	Regrid the dataset to a given grid.

Region handling

Tools for defining, loading, and subsetting spatial regions from global datasets.

`io.load_regions_specs`()	Load predefined geographic region specifications for climate data analysis.
`io.region_subset`(ds, region[, data_var, ...])	Subset a dataset or data array based on a specified region.
`io.region_from_file`(data, rgn_path, attr, ...)	Return data masked from a feature in the input file.

Retrieve data from xarray Dataset

Helper functions for extracting coordinates, axes, and metadata from xarray Datasets.

`io.get_grid`(d)	Get grid information
`io.get_axis_list`(ds)	Retrieve coordinate key names from the dataset or data array.
`io.get_data_list`(ds)	Retrieve data variable names from the dataset or data array.
`io.get_latitude`(ds)	Extract latitude coordinate data.
`io.get_latitude_bounds`(ds)	Extract latitude bounds data.
`io.get_latitude_key`(ds)	Get the key for the latitude dimension.
`io.get_longitude`(ds)	Extract longitude coordinate data.
`io.get_longitude_bounds`(ds)	Extract longitude bounds data.
`io.get_longitude_key`(ds)	Get the key for the longitude dimension.
`io.get_time`(ds)	Extract time coordinate data.
`io.get_time_bounds`(ds)	Extract time bounds data.
`io.get_time_bounds_key`(ds)	Get the key for the time bounds.
`io.get_time_key`(ds)	Get the key for the time dimension.
`io.select_subset`(ds[, lat, lon, time])	Select a subset of the given xarray dataset based on specified latitude, longitude, and time ranges.

Quality control (QC) and repair

Functions for checking and repairing time axes in climate datasets.

`utils.check_daily_time_axis`(ds[, time_key])	Check if the time axis in an xarray dataset follows a correct daily sequence, considering all CFTime calendars.
`utils.check_monthly_time_axis`(ds[, time_key])	Check if the time axis of a dataset follows a correct monthly sequence.
`utils.regenerate_time_axis`(ds[, start_str, ...])	Regenerate the time axis and bounds for an xarray Dataset.

Miscellaneous tools

General utility functions for file system operations and template string formatting.

`utils.sort_human`(input_list)	Sort a list of strings in natural order.
`utils.fill_template`(template, **kwargs)	Fill in a template string with keyword values.
`utils.tree`()	Create a nested defaultdict with infinite depth.

Viewer

Generate interactive HTML output viewer for multi-model metric results. Available in pcmdi_metrics (> v3.9.1) or higher.

viewer.generate_pmp_output_viewer_multimodel([...])

Writes out bokeh layout objects as HTML files and creates base gallery style HTML file with links to each summary metric page based on mip, exp, and metrics.