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", ...)

The model variable has to be one through the water column: a 2D field such as a sea surface temperature cannot be matched at depth, and matchup stops with an error saying so.

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. In the oceanval window, the Units step does this for you: it lists the units of each matchup, and fills these in where it can tell how to convert the observations. It reads units however models write them, such as mmol N/m**3, mmolN/m3 or meq/m**3, converts between a mass and moles where the units name what the mass is of (mg N/m3, or mg/l of oxygen, taken as O₂), and warns you where the simulation gives Absolute Salinity or Conservative Temperature (TEOS-10), which observations seldom are. You always have to confirm the units there before the matchup starts. In Python, 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. The oceanval window also checks when it opens, and lists any files you own that no running session is using, asking whether to remove them. Only remove them if nobody else is sharing the disk space or using OceanVal on the same machine, as they may still be in use. Outside the window, clear them with:

import oceanval
oceanval.deep_clean()

Alternatively, find and delete files with "_oceanval_output" in your temporary directory. Files left by older versions of OceanVal have "_ecoval_output" in their names instead.

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, ...)

Some models, GETM among them, date a time mean at the end of the period it covers: a daily mean at 00:00 the next day, and January’s mean at 00:00 on 1 February. Matched up as they are, each mean is taken for the next day or month, and the year’s last mean falls in the next year and is left out.

Without time bounds a file cannot say whether its times are the start or the end of their periods, so OceanVal never decides this itself. matchup checks the model variables that are time means (by their cell_methods): if their times are all at 00:00 and run one past the end of a month or a year, or their time bounds put each time at the end of its period, it shows why and asks whether to shift every model time back a day. It asks before it shows the matchups, so that the files and dates shown with them are those matched up. Shifted back a day, a day’s mean is on its own day and a month’s on the month’s last day.

To decide this in your matchup script, so that you are not asked, use time_shift:

oceanval.matchup(..., time_shift=-1, ...)

time_shift=0 leaves the times as they are, without checking. With ask=False, OceanVal only says what it found and leaves the times as they are. The report says when the model’s times were shifted, and matchups made with a different shift are made again, even with overwrite=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.