Wrappers

A METplus wrapper is a small Python class that stands in front of a single MET tool (or utility). It reads your METplus configuration, figures out which input files exist for each time you asked to process, assembles the exact command line and temporary config the tool expects, and runs it. The point is that you describe what to verify in plain config variables, and the wrappers handle the repetitive bookkeeping of files, times, and command syntax for you.

What a wrapper is

MET (the Model Evaluation Tools) is a suite of standalone command-line programs — point_stat, grid_stat, mode, and so on. Each is powerful but expects you to hand it precise file paths, a fully written config file, and the right arguments, one run at a time. When you want to verify months of forecasts across many lead times, doing that by hand is tedious and error-prone.

METplus wraps each MET tool in a Python class. Instead of calling the tool directly, you list the wrapper in your METplus configuration and set a handful of variables. The wrapper then does four jobs on your behalf:

1 · Read configuration — It pulls METplus config variables (your time range, lead times, fields, directories, and filename templates) out of the .conf files you pass on the command line.

2 · Find input files by time — For each time step in the loop, it expands your filename templates — substituting the initialization time, valid time, and forecast lead — to locate the actual forecast and observation files on disk.

3 · Build the command and config — It writes a temporary MET config (and sets environment variables the MET tool reads) and assembles the precise command line, with the right input paths, output directory, and flags for that tool.

4 · Run the tool — It executes the underlying MET program (or, for a few wrappers, an analysis script or plotting utility), then moves on to the next time step.

Mental model

Think of a wrapper as an adapter: METplus config goes in one side, a correctly-formed MET tool invocation comes out the other. You write declarative settings; the wrapper turns them into imperative commands, once per time in your loop.

Ecosystem link

The programs being wrapped come from MET. Several wrappers don’t wrap a MET tool at all — they drive plotting scripts that belong to METplotpy, or run user-supplied Python embedding code (where a small user Python script supplies the input data in place of a file MET would otherwise read).

Anatomy of one run

Every wrapper run is built from three kinds of information you supply through configuration. Keeping these straight makes the rest of METplus much easier to read.

The loop

A range of times and a set of forecast lead hours. The wrapper iterates over every combination, doing one tool run per time. This is where LOOP_BY, the time-range variables, and LEAD_SEQ live.

The files

Filename templates with time placeholders, plus the directories that hold them. At each loop step the wrapper expands the template to a concrete path and checks that the file is there before running.

The tool settings

What the underlying MET tool needs: which fields to read, thresholds, interpolation, output line types, and a MET config template the wrapper fills in. These are passed through to the tool, not interpreted by the loop.

Because this shape is shared, learning one wrapper teaches you most of the next. The differences between, say, PointStat and GridStat are mostly in the “tool settings” column — the loop and file-finding mechanics are common infrastructure.

How a wrapper runs

The diagram below shows a single wrapper instance. Configuration variables feed the wrapper; the wrapper finds input files via time templates, builds the command, and invokes its MET tool, which writes output. The whole sequence repeats inside a time loop driven by your time range and LEAD_SEQ.

Figure 1. A wrapper instance: config in, files located by time template, command built, MET tool run, output written — repeated for every time and lead in the loop.

The common config pattern

Almost every METplus configuration shares the same backbone. These variables live in the [config] section of a .conf file and control which wrappers run and how the time loop is built.

Variable	What it controls	Example
PROCESS_LIST	The ordered list of wrappers to run. METplus runs them in the order given, so reformatting steps can precede statistics steps.	PCPCombine, GridStat
LOOP_BY	Whether the time loop advances by initialization time (INIT / RETRO) or by valid time (VALID / REALTIME).	VALID
VALID_BEG / VALID_END	First and last valid time of the loop when looping by valid time. (Init looping uses INIT_BEG / INIT_END.)	20210101_00
VALID_TIME_FMT / INIT_TIME_FMT	The strptime-style format string — the standard C/Python date-format syntax (e.g. %Y%m%d_%H means YYYYMMDD_HH) — that the begin/end times are written in.	%Y%m%d_%H
VALID_INCREMENT / INIT_INCREMENT	How far the loop advances each step. Must be at least 60 seconds — the wrappers do not support sub-minute intervals.	21600 (6 h)
LEAD_SEQ	Forecast lead times to process at each loop time. Three interchangeable forms: an explicit list of hours (0, 6, 12), values with explicit units (6H, 12H — hours are assumed when no unit is given), or the begin_end_incr(start,end,step) shorthand. begin_end_incr(0,12,3) is exactly equivalent to 0, 3, 6, 9, 12.	begin_end_incr(0,12,3)

Override by order

You typically pass several .conf files on the command line. Each later file overrides values set in earlier ones, so a shared base config can be specialized per run without copying everything.

Where things live: the config sections

A METplus config is organized into a few named sections, each with a clear job:

[config] — Timing and processing directives — the loop variables above, the PROCESS_LIST, and the per-tool field and output settings.

[dir] — Directory paths: where input data lives and where output should be written.

[filename_templates] — The file-discovery patterns, written with time placeholders, that the wrapper expands at each loop step to build concrete paths.

[user_env_vars] — Extra environment variables you want exported into the MET tool’s environment.

Filename templates & time

The piece that makes the loop useful is the filename template: a path with curly-brace placeholders that the wrapper fills in with the current time and lead. This is how one short config processes thousands of files without listing any of them by name.

Placeholder	Substitutes	Example output
{init?fmt=%Y%m%d%H}	Forecast initialization time	2021010100
{valid?fmt=%Y%m%d}	Valid (verification) time	20210101
{lead?fmt=%3H}	Forecast lead, zero-padded hours	006

A directory from [dir] plus a template from [filename_templates] combine into a path the wrapper checks at each step. If the file exists, the tool runs for that time; if not, the wrapper reports the missing input and moves on.

Watch the format codes

A mismatched format — for example a 2-digit hour where the data uses 3-digit lead hours — is the most common reason a wrapper “finds no files.” The times are correct; the rendered path simply doesn’t match what is on disk.

The wrapper catalog

METplus ships a wrapper for each MET tool plus several utilities and analysis/plotting helpers. The table groups them by purpose. Names are taken from the current METplus wrapper documentation; descriptions are condensed for readability.

Group	Wrapper	What it does
Reformat & prep	PB2NC	Converts PrepBUFR point-observation files into NetCDF for use by point tools.
Reformat & prep	ASCII2NC	Converts ASCII point observations into NetCDF.
Reformat & prep	MADIS2NC	Converts MADIS point-observation files into NetCDF.
Reformat & prep	IODA2NC	Converts IODA-format observations into NetCDF.
Reformat & prep	PCPCombine	Combines or extracts from files to build the precipitation accumulation interval you need.
Reformat & prep	RegridDataPlane	Regrids gridded fields to a new projection (configurable interpolation) and can convert GRIB to NetCDF.
Reformat & prep	Point2Grid	Maps point observations onto a grid.
Reformat & prep	GenVxMask	Generates masking regions (a “verification mask”) for restricting where statistics are computed.
Reformat & prep	GempakToCF	Converts GEMPAK files to CF-compliant NetCDF (utility wrapper).
Reformat & prep	DataIngest	Downloads input files from remote URLs and optionally decompresses them (needs the requests package).
Statistics	PointStat	Grid-to-point verification: gridded forecasts against point (NetCDF) observations.
Statistics	GridStat	Grid-to-grid verification over matched forecast and observation grids.
Statistics	EnsembleStat	Ensemble verification and ensemble-product statistics.
Statistics	GenEnsProd	Generates ensemble products (e.g., means, spreads) used in ensemble verification.
Statistics	MODE	Object-based verification — the Method for Object-based Diagnostic Evaluation.
Statistics	MTD	MODE Time Domain: object-based verification extended through time.
Statistics	WaveletStat	Wavelet (scale-decomposition) verification statistics.
Statistics	SeriesAnalysis	Computes statistics in a time/space series across many cases at each grid point.
Statistics	GridDiag	Builds histograms and joint histograms of gridded fields for diagnostics.
Tropical cyclone	TCPairs	Matches forecast tracks (ATCF A-deck files) against the observed best track (the post-storm reference, ATCF B-deck); also reformats non-ATCF tracks into ATCF.
Tropical cyclone	TCStat	Filters and summarizes the track-pair output from TCPairs.
Tropical cyclone	TCGen	Verifies tropical-cyclone genesis forecasts.
Tropical cyclone	TCDiag	Computes tropical-cyclone diagnostics along tracks.
Tropical cyclone	TCRMW	Produces a radius-of-maximum-wind (storm-following) coordinate analysis.
Tropical cyclone	RMWAnalysis	Aggregates statistics produced in the radius-of-maximum-wind framework.
Tropical cyclone	ExtractTiles	Regrids and extracts subregion tiles around TC tracks paired by TCPairs.
Tropical cyclone	GFDLTracker	Runs the GFDL vortex tracker to produce cyclone tracks.
Analysis	StatAnalysis	Summarizes and filters MET .stat files (aggregation, partial sums, scores).
Analysis	METdbLoad	Loads MET output into a METviewer/METdataio database.
Plotting	PlotDataPlane	Quick-look plot of a single gridded field (via the MET plotting tool).
Plotting	PlotPointObs	Plots point observations on a map.
Plotting	CyclonePlotter	Plots cyclone tracks; drives plotting logic rather than a MET tool.
Glue & extension	UserScript	Runs an arbitrary user command/script at a chosen point in the process list.
Glue & extension	PyEmbedIngest	Runs RegridDataPlane to ingest data produced by user Python-embedding scripts into NetCDF.
Glue & extension	PairStat	Drives the MET pair_stat tool, which takes forecast–observation pairs that are already matched in time and space (e.g. MPR output from Point-Stat, or supplied via Python embedding), filters and groups them, and computes continuous, categorical, and probabilistic statistics — skipping the regridding and interpolation that Point-Stat performs.
Glue & extension	Example	A teaching wrapper that demonstrates looping and command building without running a tool.

Not every wrapper wraps a MET tool

Most wrappers front a MET program of the same name, but some — UserScript, CyclonePlotter, Example, and the database/ingest helpers — exist to run scripts, plotting code, or glue logic. They still use the same loop and file-finding machinery, which is why they belong in the same process list.

How wrappers chain

The real power of METplus is that PROCESS_LIST lets you run several wrappers in sequence, with the output of one becoming the input of the next. A typical chain prepares the data, computes statistics, then aggregates them.

Figure 2. One process list, three wrappers: reformat → verify → aggregate. Each stage hands its output to the next through files on disk.

Because the stages communicate through files, the boundary between wrappers is just a filename template: the producing wrapper writes to a directory, and the consuming wrapper’s template points at it. This makes chains easy to extend — add a wrapper to PROCESS_LIST and wire its input template to the previous stage’s output.

Ecosystem link

Reformatting wrappers feed the statistics wrappers, whose .stat output flows to StatAnalysis and on to METplotpy and METviewer for plots and dashboards. Concrete end-to-end chains are documented as use cases.

Writing your first run

Setting up a wrapper run follows the same handful of steps regardless of which tool you are driving.

1. Pick the wrappers. Decide what you are verifying and list the wrappers in PROCESS_LIST, in execution order (reformat before statistics).
2. Define the time loop. Set LOOP_BY, the begin/end times and their format, the increment, and the LEAD_SEQ of forecast hours to process.
3. Point at the data. In [dir] give the input and output directories; in [filename_templates] write the patterns with {init}, {valid}, and {lead} placeholders.
4. Configure the tool. Set the per-tool variables — fields, thresholds, masks, output line types — that the wrapper passes into the MET config template.
5. Run METplus. Invoke run_metplus.py with your config files. The wrappers expand the loop, locate files, build commands, and run the tools, writing logs and output as they go.
6. Inspect & iterate. Check the run log for which files were found and which commands were issued, then refine templates or tool settings and re-run.

The log is your friend

When a run does nothing useful, the log almost always tells you why: the exact command that was (or wasn’t) built and the paths that were searched. Reading it top to bottom is faster than guessing at config.

---

A derived, human-readable re-presentation — not official documentation. Sources: METplus User’s Guide — Python Wrappers