Use cases

A use case is a worked example you can actually run. It bundles a configuration file, a documentation page, and a known set of sample input data so that you can reproduce a complete verification workflow end to end — then adapt it to your own forecasts and observations. Use cases are how most people learn METplus and how many real evaluation pipelines begin.

What a use case is

The METplus documentation puts it plainly: use cases “provide a low-level workflow which includes setting paths to data, dates to process, the order of processing, and configuration options.” In other words, a use case is a complete recipe. Rather than starting from a blank configuration and guessing which variables matter, you start from a working example that someone has already wired together and documented.

Each use case is built around wrappers — the thin Python layers METplus places around the underlying MET tools. A wrapper translates plain configuration variables into the command line and parameter files that a MET tool expects, finds the right input files for each run time, and hands the results to the next step. A use case strings one or more wrappers together so that data flows from ingest, through statistics, to aggregated output.

Why they exist

Verification has a lot of moving parts: file naming, time loops, regridding, masking, and the specific options each MET tool needs. Use cases capture a correct, tested combination of all of that, so newcomers have a safe starting point and experienced users have a reproducible reference.

Two families of use cases

The User’s Guide organizes every use case into two families. The split is about scope: is the example teaching you one tool, or is it solving a real evaluation problem in a particular science domain?

MET tool use cases

Focused on a single MET tool or feature. These are the building blocks — each one shows the minimal configuration needed to drive one wrapper (for example, converting observations, computing point statistics, or building a verification mask). They live under parm/use_cases/met_tool_wrapper/.

one tool · teaching examples · building blocks

Model applications use cases

Organized by application area — precipitation, medium range, tropical cyclones, and more. These typically chain several wrappers to answer a domain question with realistic data, and are closer to a production pipeline. They live under parm/use_cases/model_applications/.

chained wrappers · by science domain · realistic

Tip · finding a use case fast

Don’t read the list top to bottom. The documentation site has a search box, and the use-case indexes are grouped by tool name and by application category — so the quickest path is to search for the tool you want to learn (say PointStat) or the domain you work in (say precipitation) and jump straight to the matching example.

MET tool use cases

The MET tool family covers the individual wrappers. Many tools ship more than one use case to show different modes — a basic run, a run that pulls data through Python embedding (feeding a tool data computed by your own Python instead of a file on disk), or a variation such as running once per field. A representative sample of the wrappers covered:

Pre-processing & ingest

ASCII2NC, PB2NC, MADIS2NC, IODA2NC, PCPCombine, RegridDataPlane, Point2Grid, GenVxMask, PyEmbedIngest, GempakToCF, DataIngest

Statistics & verification

PointStat, GridStat, EnsembleStat, GenEnsProd, MODE, MTD, SeriesAnalysis, WaveletStat, PairStat, GridDiag

Aggregation & analysis

StatAnalysis, METdbLoad, ExtractTiles, RMWAnalysis

Tropical cyclone

TCPairs, TCStat, TCGen, TCDiag, TCRMW, GFDLTracker, CyclonePlotter

Plotting

PlotDataPlane, PlotPointObs

Workflow & scripting

UserScript, Example

Start with Example

The simplest use case is literally named Example. Per the docs, it “does not utilize any of the MET tools, but simply demonstrates how the Common Config Variables control a use case run.” It is the recommended first thing to run because it proves your METplus install and time loop work before any real data is involved.

Model applications use cases

The model applications family is grouped by science domain. Each category collects use cases that address verification problems common to that area. The table below lists the categories exactly as the documentation names them, with a coarse sense of how deep coverage currently runs in each.

Category	What it tends to evaluate	Coverage
Air Quality and Composition	Pollutants and atmospheric chemistry fields	low
Climate	Long-period and climatological comparisons	low
Clouds	Cloud fields and satellite-derived products	medium
Data Assimilation	Observation feedback and analysis diagnostics	low
Fire	Wildfire-related forecast fields	low
Land Surface	Surface and soil-related variables	medium
Marine and Cryosphere	Ocean, sea ice, and snow fields	high
Medium Range	Several-day forecast verification	high
Planetary Boundary Layer	Near-surface vertical structure	low
Precipitation	Accumulated precipitation, often object-based	high
Subseasonal to Seasonal	Weeks-to-months lead verification	medium
Subseasonal to Seasonal: Mid-Latitude	Mid-latitude S2S patterns	medium
Subseasonal to Seasonal: Madden-Julian Oscillation	MJO indices and diagnostics	medium
Subseasonal to Seasonal: Soil Moisture	S2S soil moisture signals	low
Subseasonal to Seasonal: Stratosphere	Stratospheric S2S diagnostics	medium
Short Range	Short-lead and convection-relevant forecasts	high
Space Weather	Space-environment fields	low
Tropical Cyclone and Extra Tropical Cyclone	TC and ET track / genesis verification	medium
Unstructured Grids	Native unstructured-mesh output	low

Coverage is a coarse signal that grows with each release — Short Range, Medium Range, Marine and Cryosphere, and Precipitation are currently the deepest. Check the live index for the exact current set.

Ecosystem link

Use-case output is usually plotted downstream. Many model-applications examples feed METplotpy for figures and METcalcpy for statistics, and aggregated results can be loaded into a database via the METdbLoad wrapper for METviewer.

Anatomy of a use case

However simple or complex, every use case is made of the same three parts. Knowing them makes it obvious what to copy and what to change when you adapt one.

1 · The configuration file (.conf) — The runnable artifact. It sets the wrappers to use and their order (PROCESS_LIST), the time loop (init/valid times and forecast leads), the input file templates, the fields to verify, and tool-specific options. This is the file you point run_metplus.py at.

2 · The documentation page — A human-readable write-up of the example — what it does, which datasets it uses, what the output looks like, and the keywords it is tagged with. This is what you find through the documentation search and the use-case indexes.

3 · The expected sample data — A known set of input files, distributed in versioned tarballs, that the .conf is written to consume. Because the data is fixed, the example is reproducible: run it and you should get the documented output.

Don't edit the shipped conf in place

The use-case .conf hard-codes paths relative to INPUT_BASE and OUTPUT_BASE. You set those three required variables — INPUT_BASE, OUTPUT_BASE, and MET_INSTALL_DIR (your MET install location) — in a separate user configuration file that you pass on the command line. Leave the use-case file itself untouched so it stays a clean reference.

A use case as a pipeline

The clearest way to picture a model-applications use case is as a small assembly line: sample data enters on the left, each wrapper transforms it, and statistics and plots come out on the right. The example below is a classic point-verification chain — convert PrepBUFR observations to NetCDF, match forecasts against them, aggregate the resulting statistics, and plot.

Figure 1. A use case is a chain of wrappers. The PROCESS_LIST in the .conf fixes the order; each wrapper reads from sample data (or a previous step's output) and writes intermediate artifacts, ending in aggregated statistics and a plot. Tool names shown are illustrative of a point-verification chain.

Getting the sample data

Use cases are reproducible only because they run against a fixed, downloadable dataset. The data is not bundled with the METplus source — you obtain it separately and point METplus at it.

Sample tarballs are versioned to match a METplus Coordinated Release — a group of component releases (MET, METplus, and the companion packages) that were developed and tested together — and named by use-case category. Per the documentation, a tarball is “named with the X.Y version of the corresponding METplus Coordinated Release and the name of the use case category separated by a dash, e.g. 4.1-data_assimilation or 4.0-met_tool_wrapper.” The leading X.Y is the METplus release line, so download the tarball whose X.Y matches the METplus version you cloned. The MET tool examples pull from a met_tool_wrapper tarball, and each model-applications category has its own.

Three paths you must set

In your user configuration file, set INPUT_BASE to the directory where you uncompressed the sample-data tarball, OUTPUT_BASE to where results should be written, and MET_INSTALL_DIR to your MET installation. The use-case .conf builds every file path on top of these.

Run your first use case

Running a use case is a single command: run_metplus.py <use_case.conf> <user_system.conf>. The first argument is the shipped example; the second is your own configuration that supplies the paths above. Here is the full path from nothing to output.

1. Get the sample data. Download the tarball that matches your METplus release and the category you want — for the introductory examples, the one that starts with sample_data-met_tool_wrapper. Uncompress it somewhere you can write to.

2. Write a user configuration file. Create a small user_system.conf that sets INPUT_BASE to the uncompressed sample-data directory, OUTPUT_BASE to an output directory, and MET_INSTALL_DIR to your MET install. You reuse this file for every use case.

3. Run the simplest example first. Confirm your install works before touching real data:

   run_metplus.py \
     /path/to/METplus/parm/use_cases/met_tool_wrapper/Example/Example.conf \
     /path/to/user_system.conf

   This exercises the common config variables and time loop without invoking any MET tool.

4. Run a real tool use case. Point at a use case that drives an actual tool, for example GridStat:

   run_metplus.py \
     /path/to/METplus/parm/use_cases/met_tool_wrapper/GridStat/GridStat.conf \
     /path/to/user_system.conf

5. Confirm success. A complete run ends with the message METplus has successfully finished running. Find your results under OUTPUT_BASE.

6. Chain configs to sweep combinations. You can pass several .conf files in sequence; later files override earlier ones (the same override-by-order rule covered in Getting started). This is how you reuse one use case across multiple forecast/observation pairs by layering small config fragments. Here forecastA.conf, observationA.conf, and use_case_name.conf are use-case fragments; your machine-specific user_system.conf still belongs last so its paths win:

   run_metplus.py forecastA.conf observationA.conf use_case_name.conf user_system.conf
   run_metplus.py forecastA.conf observationB.conf use_case_name.conf user_system.conf
   run_metplus.py forecastB.conf observationA.conf use_case_name.conf user_system.conf
   run_metplus.py forecastB.conf observationB.conf use_case_name.conf user_system.conf

Tip · pick your starting point by goal

Learning a single tool? Reach for a MET tool use case. Trying to verify a real forecast in your domain? Start from the closest model applications category, then retarget its .conf to your own data by editing only the paths and field settings in your user configuration.

---

A derived, human-readable re-presentation — not official documentation. Sources: metplus.readthedocs.io · Users_Guide/usecases.html