METcalcpy

METcalcpy is a stand-alone Python package that re-implements the statistical calculations used across the METplus tools. It is not a graphical tool you click through — it is a library of reusable functions for aggregating statistics, equalizing events, computing bootstrap confidence intervals, interpolating vertically, and producing specialized indices. By centralizing this math, it lets METviewer, METexpress, METplotpy, and METplus all compute statistics the same way.

What METcalcpy is

The Model Evaluation Tools (MET) verification system writes its results as plain ASCII statistics files. Several downstream tools then need to take those numbers, combine them across cases, and turn them into plots, dashboards, and reports. Historically each of those tools carried its own copy of the statistics math. METcalcpy exists to remove that duplication: it is “a stand-alone package and a Python version of the statistics calculation functionality” shared across the ecosystem.

Because it is a library rather than an application, you generally do not run METcalcpy directly to look at a result. Instead, other tools import it — for example a plotting package calls a METcalcpy aggregation function to compute the numbers it then draws. The payoff is consistency: when two tools report the same statistic, they get the same answer because they ran the same code.

Plain-language definition

A matched pair is a single forecast value paired with the observation it is being checked against (same place, same time). Partial sums and contingency counts are compact summaries MET writes so that statistics can be recomputed later without re-reading every pair. METcalcpy consumes these so it can aggregate — combine many cases into one summary statistic with an uncertainty estimate.

Where it sits in the workflow

Think of METcalcpy as the middle stage of a pipeline. MET produces the raw verification output; METcalcpy turns that into aggregated statistics with confidence intervals and significance; and the presentation tools render those numbers for a human. The diagram below traces that path.

Figure 1. MET writes matched pairs and partial sums; METcalcpy aggregates them, equalizes events, attaches bootstrap confidence intervals and significance, and hands the result to the presentation tools.

Capability areas

METcalcpy bundles a number of distinct utilities. The table below summarizes the main statistics-and-diagnostics capability areas from its User’s Guide, each of which has its own module or set of functions. It is a curated selection, not the full feature list — supporting facilities such as the package’s integrated logging are documented in the source but omitted here.

Capability	What it does
Aggregation	Computes aggregated statistics and confidence intervals from reformatted MET stat output. Implemented in agg_stat.py via the AggStat class.
Event equalization	Optional step (the event_equal flag) that keeps only cases present across all series being compared, so aggregated statistics are computed over a common, fair sample.
Bootstrapping & CIs	Resampling-based confidence intervals, including circular block bootstrap, controlled by parameters such as alpha, num_iterations, and random_seed.
Vertical interpolation	Pressure-to-height conversion for TC-RMW data via vertical_interp.py, interpolating fields from pressure to target height levels.
Difficulty Index	Quantifies how hard a forecast decision is, given an ensemble, around a threshold (e.g. wind speed or significant wave height) as a function of space and time.
Write MPR	Writes matched forecast–observation pairs to a .stat file in MET’s Matched Pair (MPR) format via write_mpr_file(...), computing the observation-input and total-observation values the MPR line format requires.
Land-surface diagnostics	The metcalcpy.diagnostics.land_surface module: convective triggering potential (calc_ctp), low-level humidity index (calc_humidity_index), and the terrestrial coupling index (calc_tci).

A note on scope

The published overview page is brief and frames METcalcpy as a Python version of the statistics in METviewer, METexpress, and METplotpy. Items such as scorecard math and statistical significance are part of the aggregation workflow (significance follows from the bootstrap confidence intervals and the alpha level) rather than separate top-level chapters. Treat this page as an orientation; the linked source pages carry the authoritative parameter lists.

Deep dives

Two areas are large enough to warrant their own pages. Start here if you want the mechanics rather than the overview.

Aggregation, event equalization & CIs Workflow — How agg_stat.py turns reformatted MET line-type statistics (such as the ECNT line type from ensemble-stat) into aggregated values, equalizes events, and attaches bootstrap confidence intervals.

The Difficulty Index Index — The decision-difficulty metric for ensembles: how ensemble spread, the probability split around a threshold, and a mean-value weighting factor combine into a per-point difficulty value.

Land-surface diagnostics

The metcalcpy.diagnostics.land_surface module provides three coupling diagnostics drawn from the land–atmosphere interaction literature. They are reference implementations: each is a function you call with profiles or fields and that returns a single diagnostic value (or a gridded field).

calc_ctp — Convective Triggering Potential — Computes CTP, defined as R_d ∫ (T_env − T_MALR) d ln p integrated over a pressure layer above the surface — a measure of low-level atmospheric instability relevant to convection initiation. Takes pressure (hPa) and temperature (K) profiles, with layer offsets defaulting to 100 hPa (bottom) and 300 hPa (top) below the start pressure. Returns a float. After Findell & Eltahir (2003), J. Hydrometeorology.

calc_humidity_index — Low-level Humidity Index (HI) — Computes HI_low = (T − D)_{950 hPa} + (T − D)_{850 hPa}: the sum of temperature-minus-dewpoint differences at two low levels, indicating how moist the boundary layer is. Takes pressure (hPa), temperature (K), and dewpoint (K) inputs. Returns a float. Also after Findell & Eltahir (2003).

calc_tci — Terrestrial Coupling Index (TCI) — Measures the coupling between soil moisture and surface heat flux. Takes soil_data (the moisture variable) and sfc_flux_data (the latent-heat-flux variable) as xarray DataArrays or pandas Series, with a skipna flag. Returns a gridded DataArray (for xarray inputs) or a single float (for Series inputs). After Dirmeyer (2011), Geophys. Res. Lett..

Why these live here

Putting CTP, HI, and TCI in METcalcpy means any ecosystem tool that wants to evaluate land–atmosphere coupling computes them from the same vetted, citable implementation — the same design goal as the aggregation engine, applied to physical diagnostics instead of verification statistics.

Source note: the specific layer offsets (100 hPa / 300 hPa), the 950 hPa and 850 hPa humidity levels, and the literature citations above are taken from the functions’ own docstrings in the METcalcpy source rather than from a rendered User’s Guide page — treat the code and its cited papers as the authority for exact values.

Ecosystem connections

METcalcpy is a dependency, not a destination. It is imported by the tools that present and plot verification results, and it is part of the broader METplus orchestration story.

Imported by

METcalcpy’s functions are called from METplotpy (plotting), METviewer (database-backed plots and dashboards), METexpress (interactive verification displays), and are part of the METplus ecosystem that wires the tools together. When these tools report the same statistic, METcalcpy is the reason they agree.

---

A derived, human-readable re-presentation — not official documentation. Sources: METcalcpy User’s Guide — Overview