Data Recipes

OceanVal provides built-in recipes for many popular observational datasets. Downloading and storing data can be annoying and tedious, and recipes take care of it for you.

Recipes are available for gridded data. Use the recipe argument with oceanval.add_gridded_comparison() and provide the model variable that should be compared with the observation.

We can illustrate how they work with an example. The following call asks OceanVal to compare the model’s thetao variable with the COBE2 temperature dataset. The recipe dictionary {"temperature": "cobe2"} tells OceanVal to use the COBE2 recipe for the temperature variable.

oceanval.add_gridded_comparison(
    name="temperature",                 # <--- report name
    model_variable="thetao",           # <--- model NetCDF variable
    recipe={"temperature": "cobe2"},    # <--- observation recipe
    climatology=True,                # <--- climatological comparison
)

The parts of the call mean:

• name is the short name OceanVal uses in reports.

• model_variable is the variable name in the model NetCDF output.

• recipe is a dictionary that must contain one variable and source identifier. For example, {"temperature": "woa23"} selects temperature from WOA23.

• climatology is a boolean that sets whether to compare climatological means or all available years. Set climatology=True for a climatological comparison, or climatology=False to compare all available years.

How are recipes processed?

OceanVal will automatically download the observational data when the oceanval.matchup() function is called. In most cases this happens via THREDDS servers, which makes things efficient: OceanVal only downloads what is needed. Once the data is downloaded, the model and observations are regridded to a common spatial grid, and model and observational data are averaged per month and year, where appropriate.

What recipes are available?

Global datasets

Global built-in recipes

Region	Variable	Recipe	Dataset	Water-column	Example
Global	Alkalinity	glodap	GLODAPv2.2016b	No	Full details
Global	Chlorophyll	occci	Ocean Colour CCI	No	Full details
Global	KD490	occci	Ocean Colour CCI	No	Full details
Global	Nitrate	woa23	World Ocean Atlas 2023	Yes	Full details
Global	Oxygen	woa23	World Ocean Atlas 2023	Yes	Full details
Global	pH	glodap	GLODAPv2.2016b	No	Full details
Global	Phosphate	woa23	World Ocean Atlas 2023	Yes	Full details
Global	Salinity	woa23	World Ocean Atlas 2023	Yes	Full details
Global	Silicate	woa23	World Ocean Atlas 2023	Yes	Full details
Global	Temperature	cobe2	COBE-SST 2	No	Full details
Global	Temperature	woa23	World Ocean Atlas 2023	Yes	Full details

The recipe dictionary must contain one variable and source identifier. For example, {"temperature": "woa23"} selects temperature from WOA23.

Northwest European Shelf datasets

The nsbc recipe provides North Sea Biogeochemical Climatology data for chlorophyll, nitrate, phosphate, silicate, oxygen, temperature, and salinity.

Northwest European Shelf built-in recipes

Region	Variable	Recipe	Dataset	Water-column	Example
Northwest European Shelf	Ammonium	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Chlorophyll	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Nitrate	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Oxygen	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Phosphate	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Salinity	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Silicate	nsbc	North Sea Biogeochemical Climatology	Yes	Full details
Northwest European Shelf	Temperature	nsbc	North Sea Biogeochemical Climatology	Yes	Full details

Each Example link opens a separate page containing the corresponding call.

Dataset notes

Always check the dataset units and climatology period before comparing the result with model output. See How to use OceanVal for matching and time-resolution guidance.