Ocean model validation made easy in Python.

To learn more about the package, visit the OceanVal website. The

OceanVal is designed for the automated creation of validation reports. You provide the model and validation data. OceanVal does the rest. A short example of what the report looks like can be found here.

Using built-in recipes

You can register a standard observation climatology without manually listing all metadata:

import oceanval

oceanval.add_gridded_comparison(
    name="temperature",
    source="WOA23",
    model_variable="temp",
    recipe={"temperature": "woa23"},
    start=2005,
    end=2014,
    climatology=True,
)

This uses the v0.2.0 recipe system for datasets such as WOA23, NSBC, OCCCI and GLODAP.

Generating a matchup script

create_recipes writes the script for you. It scans your model output, works out which model variable holds each observational variable — matching on the netCDF long_name attributes, so your variables need not be named after the observations — and writes out every built-in recipe. Recipes it found a model variable for are live, with that variable filled in; the rest are commented out for you to complete by hand. Where a variable has a recipe in more than one region (e.g. temperature), domain picks which one is left live — "global" or "nwes" (Northwest European Shelf) — and a variable with a recipe only outside that domain still gets that one.

import oceanval

oceanval.create_recipes(
    simdir="/path/to/model/output",
    ndown=2,   # how many directories down the output files sit
    out="matchup.py",
    domain="global",
    start=2005,   # passed straight through to matchup()
    end=2014,
)

Comparing multiple validation outputs

To compare validation reports from multiple simulations:

import oceanval

oceanval.compare(
    model_dict={
        "model_a": "/path/to/model_a",
        "model_b": "/path/to/model_b",
    },
    view=True,
    ask=True,
)

This recreates the v0.2.0 comparison workflow and writes the shared comparison report to oceanval_comparison/compare/_build/html/index.html.

Installation

OceanVal should be used with Python versions 3.10-3.13.

You can install the latest release OceanVal from conda-forge as follows:

conda install conda-forge::oceanval

You can install the development version of OceanVal from GitHub using the following steps.

First, clone this directory:

git clone https://github.com/pmlmodelling/oceanval.git

Then move to this directory.

cd oceanval

Second, set up a conda environment. If you want the envionment to called something other than oceanval, you can change the name in the oceanval.yml file.

conda env create -f oceanval.yml

Activate this environment.

conda activate oceanval

Now, sometimes R package installs go wrong in conda. Run the following command to ensure Rcpp is installed correctly.

Rscript -e "install.packages('Rcpp', repos = 'https://cloud.r-project.org/')"

Now, install the package.

pip install .

```sh
conda activate oceanval

Now, install the package.

pip install .

Alternatively, install the conda environment and package using the following commands:

    conda env create --name oceanval -f https://raw.githubusercontent.com/pmlmodelling/oceanval/main/oceanval.yml
    conda activate oceanval​
    pip install git+https://github.com/pmlmodelling/oceanval.git​