How to use OceanVal

Validating a simulation involves three steps: register the observational datasets, matchup the simulation output against them, and generate statistics and an HTML report. Always create a new directory before running OceanVal for a new simulation, and run all commands from within it. Once you have reports for multiple simulations, you can also compare them side by side.

Step 1: Register observational datasets

Register the observational datasets you want to validate against by specifying the location of the data files and any necessary metadata, using oceanval.add_point_comparison and oceanval.add_gridded_comparison.

Setting up gridded observational data

Register a gridded (NetCDF) dataset by pointing OceanVal at a directory of observation files and saying whether the data is a climatology:

oceanval.add_gridded_comparison(
    name="oxygen",
    source="CMEMS",
    source_info="Gridded observations from the Copernicus Marine Environment Monitoring Service",
    short_name="oxygen concentration",
    model_variable="oxygen",
    obs_variable="O2_concentration",
    obs_path="/path/to/obs_data/",
    climatology=False,
)

Required parameters:

• namerequired

  A name for the dataset, e.g. "temperature".

• sourcerequired

  The source of the observational data, e.g. "CMEMS".

• model_variablerequired

  The name of the model variable to compare against the observations.

• obs_pathrequired

  Path to the directory containing the observational data files.

• obs_variable

  Name of the variable in the observational files. If omitted, OceanVal assumes a single variable is present.

• climatologyrequired

  Whether the observational data is a climatology.

Using built-in recipes for gridded data

Built-in recipe definitions make it easy to register standard observational datasets — especially useful for a standard climatology such as WOA23 or GLODAP, without manually specifying all the metadata.

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

This uses the built-in metadata and file locations for the WOA23 temperature climatology. recipe also works for salinity, oxygen, nitrate, phosphate, silicate, chlorophyll and pH — see all recipes. The underlying helper can also be used directly:

recipe = oceanval.parsers.find_recipe({"temperature": "woa23"}, start=2005, end=2014)
print(recipe["source"], recipe["obs_variable"])

Browse the full recipe catalogue to see every supported observational dataset, with the exact call to use for each.

Setting up point (in-situ) observational data

Register an in-situ dataset by pointing OceanVal at a CSV (or directory of CSVs) and naming the model variable to compare it against:

oceanval.add_point_comparison(
    name="nitrate",
    source="ICES",
    source_info="In-situ observations from the International Council for the Exploration of the Sea",
    short_name="nitrate concentration",
    model_variable="temp",
    obs_path="/path/to/obs_data/",
)

Required parameters:

• namerequired

  A name for the dataset, e.g. "temperature" — used internally to keep track of things. Letters and numbers only.

• sourcerequired

  The source of the observational data, e.g. "NOAA".

• model_variablerequired

  The name of the model variable to compare against the observations.

• obs_pathrequired

  Path to a file or directory containing the observational data. If a directory, ensure it only contains files relevant to this variable — OceanVal recursively uses all NetCDF files inside it.

Step 2: Matchup model output with observations

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

oceanval.matchup(
    sim_dir="/path/to/simulation/output/",
    start=2000, end=2010,
    cores=4,
    lon_lim=[-80, 0], lat_lim=[20, 60],
    thickness="cell_thickness",
)

Required parameters:

• sim_dirrequired

  Path to the directory containing the model simulation output files.

• start / endrequired

  First / last year of the simulation to use for validation.

• cores

  Number of CPU cores to use for parallel processing.

• lon_lim / lat_lim

  Longitude / latitude limits for the validation region, e.g. [-180, 180].

• thicknessvertical only

  "z_level" or a variable name containing cell thickness — required for vertical validation.

Note: for monthly-resolution simulations, set point_time_res=["year", "month"] when matching up in-situ observations — otherwise day-of-year will almost never match and few matchups will be found.

Summing simulation output: to compare observations against the sum of multiple model variables, set something like "var1+var2+var3" as model_variable.

Step 3: Build the validation report

Once matched, compute statistics and generate plots with oceanval.validate, run from the same directory as the matchup step:

oceanval.validate()

This generates and opens an HTML page you can view in a web browser.

Comparing validation outputs from multiple simulations

Once you have validation reports for different simulations, compare them with oceanval.compare, which summarises the differences between them:

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

model_dict maps a short name for each model to its validation output directory. The HTML comparison report is written to oceanval_comparison/compare/_build/html/notebooks/comparison_seasonal.html.