Statistics YAML Configuration

This page describes the structure and fields of the YAML file used to configure the Statistics module in VCasT. This file controls how forecast/reference file pairs are located, optionally interpolated, and compared to compute verification metrics.

Example YAML File

Sample Statistics Configuration YAML
# ====================================================
# Date and Time Settings
# ====================================================
start_date: "2024-04-01_02:00:00"      # Starting date and time for processing
end_date: "2024-04-01_03:00:00"        # Ending date and time for processing
interval_hours: "1"                    # Time interval (in hours) at which processing is performed

# Optional forecast lead time settings.
start_lead_time: 0                     # Starting lead time (e.g., forecast offset in hours)
end_lead_time: 5                       # Ending lead time
interval_lead_time: 1                  # Lead time step (e.g., each 1 hour)

# Or provide an explicit list instead of the start/end/interval triplet above:
# lead_times: [0, 1, 2]

members: ["ens_0", "ens_1"]            # Optional; loops over ensemble members if set

# ====================================================
# Forecast Configuration
# ====================================================
vars: "T2M"                            # Variable name (e.g., 2-meter temperature)

fcst_model: "HRRR"                     # Forecast model name (used to look up the variable table)
fcst_file_template: "/path/to/{year}{month}{day}/{members}/uppfiles/WRFPRS.GrbF{lead_time}.grib2"
  # Template used to locate forecast files.

# ====================================================
# Reference Configuration
# ====================================================
ref_model: "HRRR"                      # Reference model name
ref_file_template: "/path/to/{valid_year}{valid_month}{valid_day}/hrrr.t{valid_hour}z.wrfprsf00.grib2"
  # Template used to locate reference files.

# ====================================================
# Output Configuration
# ====================================================
output_dir: "."                        # Directory for saving the output files
output_filename: "output.data"         # File name for the output file

# ====================================================
# Statistical Metrics
# ====================================================
stat_type: "det"                       # "det" for deterministic, "ens" for ensemble
stat_name:                             # List of statistical metrics to calculate
  - "rmse"
  - "bias"
  - "fss:20:20:1"

# ====================================================
# Grid and Interpolation Settings
# ====================================================
interpolation: true                    # Whether to interpolate forecast/reference data
target_grid: "/path/to/domain_grid.nc"
  # The grid specification or file used as the target for interpolation

# ====================================================
# Parallel Processing
# ====================================================
processes: 1                           # Number of processes to run in parallel

Configuration Sections

Date, Time, and Lead Time Settings

  • start_date / end_date: Processing window, in YYYY-MM-DD_HH:MM:SS format.

  • interval_hours: Time step (in hours) between successive processing dates.

  • start_lead_time / end_lead_time / interval_lead_time: Optional. Defines a range of forecast lead times (in hours) to process. If any one is set, all three are required. If omitted, lead_times must be supplied directly, or a single lead time of 0 is assumed.

  • lead_times: Optional explicit list of lead times, used instead of the start/end/interval triplet above (e.g. [0, 1, 2]).

  • members: Optional list of ensemble member identifiers. If provided, VCasT loops over each member (deterministic mode) or treats them as one ensemble (stat_type: ens).

Forecast and Reference Settings

  • vars: Variable name (or list of names) to process, e.g. T2M. Names are resolved via the model/variable lookup table bundled with VCasT.

  • fcst_model / ref_model: Model identifiers used to resolve variable names, levels, and units for the forecast and reference sources respectively.

  • fcst_file_template / ref_file_template: Path templates for locating forecast and reference files. Templates support {year}, {month}, {day}, {hour}, {lead_time}, {members}, and the equivalent {valid_year}/{valid_month}/ {valid_day}/{valid_hour} fields for the observation valid time.

  • vtable: Optional path to a custom variable lookup table, overriding VCasT’s bundled default (util/lookup_table-v2.txt). This tab-separated file maps a variable/model pair (as given in vars/fcst_model/ ref_model) to the underlying GRIB2/NetCDF variable name, level, level type, and units, e.g.:

    variable  model  model_variable  level_name       units  level  description
T2M       HRRR   2t              heightAboveGround  K    2      Temperature at 2m

    Use this to add support for a model or variable not already present in the default table.

Output Configuration

  • output_dir: Directory where the output file is written. Must already exist.

  • output_filename: Name of the tab-separated output file.

Statistical Metrics

  • stat_type: det for deterministic (per-file) statistics, or ens for ensemble statistics computed across all members at once.

  • stat_name: List of metrics to compute. Continuous metrics (rmse, bias, mae, stdev, corr, quantiles) take no parameters. Categorical metrics (gss, fbias, pod, far, sr, csi) and fss require a metric:fcst_threshold:ref_threshold:radius or metric:fcst_threshold:ref_threshold:window_size specifier, e.g. "gss:290:290:2" or "fss:20:20:1".

Grid and Interpolation Settings

  • interpolation: [true, false] Whether forecast and reference fields should be interpolated onto a common target grid before computing statistics.

  • target_grid: Path to a NetCDF file defining the target grid. Required when interpolation is true.

Parallel Processing

  • processes: Number of worker processes used to compute statistics in parallel across dates, lead times, and members.

—

For a working example, see the all_stats cases in the VCasT-tests repository under examples/Stats.