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.

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.