Quickstart

Validating ecosystem models with OceanVal is a three step process. First you register the model-observation mappings you want to validate against. Next, you matchup your model output with those observations. Finally, you build the validation report, which computes statistics and generates the HTML report you can view in your browser.

Step 1: Register the model-observation mappings

Work from a fresh, empty directory: OceanVal writes its matchup files and report there. Register the observations you need:

import oceanval

# 1. Register: compare the model variable "thetao" with WOA23 temperature
oceanval.add_gridded_comparison(
    name="temperature",
    model_variable="thetao",
    recipe={"temperature": "woa23"},
    start=2005,
    end=2014,
    climatology=True,
)

Replace thetao with the temperature variable name used in your model's NetCDF files.

To use other variables or your own observation files, see Recipes and How to use OceanVal.

Step 2: Matchup model and observations

Once your datasets are registered, pair the model output against them with matchup:

# 2. Match: pair model output with the observations
oceanval.matchup(
    sim_dir="/path/to/model/output",
    start=2005,
    end=2014,
    cores=4,
)

OceanVal will scan sim_dir, report the file pattern it has identified, and ask you to confirm before matching. The matched data is written to an oceanval_matchups directory.

Step 3: Build the validation report

Run validation from the same directory:

# 3. Report: compute statistics and build the HTML report
oceanval.validate()

The report is written below oceanval_report and opens in your browser when the build completes. It includes climatology maps, bias maps, seasonality analysis, spatial correlation tables, and full documentation of the methods used.

Next steps

• Add more variables: each recipe is one extra add_gridded_comparison call.
• Validate against your own gridded or in-situ data: see How to use OceanVal.
• Compare several simulations side by side with oceanval.compare().

Troubleshooting

If no matchups are produced, check the model directory structure, variable names, time resolution, units, and climatology setting. The most common issue with monthly model output and in-situ observations is using daily matching precision; see the time resolution guidance in How to use OceanVal, or browse the Q&A.