OceanVal Q&A

Use the out_dir option in oceanval.matchup, and the data_dir / out_dir options in oceanval.validate, so output is stored in separate folders. When one simulation is done, reset before starting the next:

oceanval.reset()

This clears any observational matchups previously added with add_point_comparison / add_gridded_comparison, giving you a clean slate.

By default OceanVal uses 6 CPU cores for matchups. Change this with the cores argument:

oceanval.matchup(..., cores=12, ...)

Matchups are stored in the oceanval_matchups directory inside your output directory — gridded data in gridded/ as .nc files, point data in point/ as .csv files.

Yes. Use add_gridded_comparison as usual, with a path ending in ".nc" and thredds=True:

oceanval.add_gridded_comparison(
    name="temperature",
    obs_path="https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.mean.nc",
    obs_variable="sst",
    model_variable="temperature",
    thredds=True,
)

Use as_missing in oceanval.matchup. For example, to treat 0 as missing:

oceanval.matchup(..., as_missing=0, ...)

Use lon_lim and lat_lim in oceanval.matchup or oceanval.validate. For example, to validate only the North Atlantic:

oceanval.matchup(..., lon_lim=[-80, 0], lat_lim=[0, 60], ...)

Use start and end in oceanval.matchup:

oceanval.matchup(..., start=2000, end=2010, ...)

For finer control, set start/end in add_point_comparison or add_gridded_comparison instead — e.g. to use 2010–2015 there.

Set vertical=True when registering the comparison, then specify thickness in oceanval.matchup. Use "z_level" for fixed-depth data:

oceanval.add_point_comparison(..., vertical=True, ...)

oceanval.matchup(..., thickness="z_level", ...)

For a varying-thickness grid, pass a file path or the variable name containing thicknesses — OceanVal will search for and extract it:

oceanval.matchup(..., thickness="/path/to/thickness_file.nc", ...)

OceanVal assumes model and observational data share units. Adjust the observations with obs_multiplier or obs_adder. For example, converting mol/m³ to mmol/m³:

oceanval.add_point_comparison(..., obs_multiplier=1000, ...)

Note: there is special handling for a variable named "temperature" — OceanVal converts the observation to the model's units automatically.

Without it, gridded data is ambiguous. A file might carry a timestamp of "year 2000" but actually represent a climatology — without being told, OceanVal can't know whether to match it only to the year 2000, or to a multi-year model average.

Temporary files are normally cleaned up automatically, but can be left behind after a crash. OceanVal will warn you on import if this happens; clear them with:

import oceanval
oceanval.deep_clean()

Alternatively, find and delete files with "_ecoval_output" in your temporary directory.

Yes — to tweak a plot colour scale or wording, open the Jupyter notebooks in oceanval_report/notebooks, edit them, then rebuild the report:

oceanval.rebuild(data_dir="/foo/bar")

This overwrites the original report with the results of the modified analysis.

Maps shown side by side, such as the model and observation climatologies, share a single colour bar when nctoolkit 1.3.2 or later is installed. OceanVal then draws them with nctoolkit's panel_plot, without longitude and latitude labels. With older versions of nctoolkit, each map gets its own colour bar. The colour scale is the same either way. To get the shared colour bar, upgrade nctoolkit and run validate or compare again:

conda install -c conda-forge "nctoolkit>=1.3.2"

OceanVal identifies the file path pattern for a variable automatically and reports the pattern plus an example file. By default it's strict about naming, so files must match the example's character length exactly:

eORCA1_1m_**_**_grid_T_**-**.nc
eORCA1_1m_20100101_grid_T_20101231.nc

If your files aren't strictly consistent, use exclude to ignore files containing certain strings, or set strict_names=False to stop filtering by basename length:

oceanval.matchup(..., exclude=["badpattern1", "badpattern2"], ...)
oceanval.matchup(..., strict_names=False, ...)

OceanVal isn't explicitly designed for this, but you can treat one simulation as "observations" in a gridded comparison — this only works for gridded, not point, comparisons. It's a good way to see how simulations compare climatologically and across time.

Please open an issue on the OceanVal GitHub page.