OceanVal v…
Home / API

API reference

All of OceanVal's public functions are available directly from the top-level oceanval namespace. Every signature below shows the complete call with default arguments — expand "Parameters" on any function for the full description of each one.

Configuration and matching
oceanval.add_point_comparison(name=None, source=None, model_variable=None, obs_path=None, source_info=None, short_name=None, long_name=None, short_title=None, vertical=False, start=-1000, end=3000, obs_multiplier=1, obs_adder=0, binning=None)

Register an in-situ (point) observational dataset for validation, e.g. cruise or mooring data supplied as CSV.

Parameters

Required:

  • 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. Not currently enforced by the function but should always be supplied.

  • 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.

Optional:

  • source_info

    Additional information about the source, e.g. publication details.

  • short_name

    A short name for the observational variable, e.g. "temp".

  • long_name

    A long name for the variable, e.g. "sea surface temperature".

  • short_title

    A short title for plots, e.g. "Nitrate Concentration".

  • vertical

    Whether to carry out vertical validation. Default False (surface only).

  • start / end

    First / last year of observations to use. Default to all available years.

  • obs_multiplier

    Multiplier applied to observational data, e.g. for unit conversion. Default 1.

  • obs_adder

    Value added to observational data, e.g. 273.15 to convert Kelvin to Celsius. Default 0.

  • binning

    Spatially bin data to a [lon_bin_size, lat_bin_size] resolution in degrees. Off by default.

oceanval.add_gridded_comparison(name=None, source=None, model_variable=None, obs_path=None, climatology=None, obs_variable=None, source_info=None, short_name=None, long_name=None, short_title=None, vertical=False, start=-1000, end=3000, obs_multiplier=1, obs_adder=0, recipe=None, thredds=False, file_check=True)

Register a gridded observational dataset (NetCDF), either your own files or a built-in recipe.

Parameters

Required:

  • 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.

  • climatologyrequired

    Whether the observational data is a climatology.

Optional:

  • obs_variable

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

  • source_info

    Additional information about the source, e.g. publication details.

  • short_name

    A short name for the observational variable, e.g. "temp".

  • long_name

    A long name for the variable, e.g. "sea surface temperature".

  • short_title

    A short title for plots, e.g. "Nitrate Concentration".

  • vertical

    Whether to carry out vertical validation. Default False (surface only).

  • start / end

    First / last year of observations to use. Default to all available years.

  • obs_multiplier

    Multiplier applied to observational data, e.g. for unit conversion. Default 1.

  • obs_adder

    Value added to observational data, e.g. 273.15 to convert Kelvin to Celsius. Default 0.

  • recipe

    A built-in recipe dict, e.g. {"temperature": "woa23"}, providing standard metadata and file locations automatically.

  • thredds

    Whether obs_path is a remote OPeNDAP/THREDDS URL rather than a local file or directory. Default False.

  • file_check

    Whether to check that obs_path exists and its variables are valid. Default True.

oceanval.matchup(sim_dir=None, start=None, end=None, thickness=None, cores=6, lon_lim=None, lat_lim=None, n_dirs_down=2, overwrite=True, ask=True, cache=False, exclude=[], require=None, out_dir="", point_time_res=["year", "month", "day"], n_check=None, as_missing=None, strict_names=True)

Pair registered observations with model output.

Parameters

Required:

  • sim_dirrequired

    Path to the directory containing the model simulation output files.

  • start / endrequired

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

  • thicknessvertical only

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

Optional:

  • cores

    Number of CPU cores to use for parallel processing. Default 6.

  • lon_lim / lat_lim

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

  • n_dirs_down

    Directory levels to search down for output files. Default 2, assuming a YYYY/MM/ structure.

  • overwrite / ask

    Whether to overwrite existing matchup files, and whether to confirm first. ask defaults to True.

  • cache

    Whether to cache intermediate results. Default False.

  • exclude

    Strings that should not appear in any simulation file paths.

  • require

    Strings that must appear in a simulation file path for it to be included — useful when multiple simulations share a directory.

  • out_dir

    Directory to save matchup files in. Defaults to the execution directory.

  • point_time_res

    Time resolution for point matchups. Default ["year", "month", "day"]; set to ["month", "day"] to compare climatological output with observations.

  • n_check

    Number of files checked when identifying the file naming convention.

  • as_missing

    A float or [min, max] range of values to treat as missing in the model output.

  • strict_names

    Whether to strictly enforce variable naming conventions. Default True.

oceanval.create_recipes(simdir=None, ndown=None, out=None, domain=None, start=None, end=None)

Scan a simulation directory and write out a ready-to-run matchup script. Every built-in recipe is included: the ones OceanVal could identify a model variable for are live, with that variable filled in, and the rest are commented out for you to complete by hand. The model variables are identified from the long_name attributes in the netCDF files, so they need not be named after the observational dataset.

Parameters
  • simdir

    Directory holding the model output. Required.

  • ndown

    How many directories below simdir the output files sit, the same idea as n_dirs_down on matchup. Required.

  • out

    Path of the Python file to write. Required.

  • domain

    Either "global" or "nwes". Where a variable has a recipe in both regions (e.g. temperature), the one for this domain is left live and the other is commented out as an alternative; a variable with a recipe only outside this domain still gets that one. Required.

  • start / end

    First / last year of the simulation to validate. Passed straight through to the generated script's matchup() call, and used to pick the WOA23 decadal period for the temperature and salinity recipes. Required.

Reports and maintenance
oceanval.validate(lon_lim=None, lat_lim=None, concise=True, fixed_scale=False, subregions=None, data_dir=".", out_dir=".", pdf=False, word=False, zip=False)

Compute validation statistics from matched data and build the HTML report. Run from the same directory used for matchup.

Parameters
  • lon_lim / lat_lim

    Longitude / latitude limits for the validation region.

  • subregions

    The sub-regions used for the regional summaries: "global", "nwes" (Northwest European Shelf), or a path to your own regions netCDF (.nc) file. The file needs one variable per region, with 1 for grid cells in the region and missing values elsewhere. Any 0 is set to missing and ignored in regional summaries. See Using your own regions.

  • concise

    Whether to generate a concise HTML summary page. Default True.

  • fixed_scale

    Whether to use a fixed colour scale for the seasonal plots, capping min/max to the 2nd/98th percentile. Default False.

  • data_dir / out_dir

    Where matchup data is read from / the report is written to. Default to the current directory.

  • pdf

    Whether to also generate PDF downloads of the report (a per-page PDF and a combined PDF of the whole report). Default False — generating them is slow, and most users only need the HTML report.

  • word

    Whether to also generate Word versions of the report — one per page, plus a combined oceanval_report.docx — with figures, tables and editable Word equations. Default False. Requires pandoc.

  • zip

    Whether to also bundle the report into a zip archive (oceanval_report.zip) in the output directory, containing just the files needed to view the complete report — the HTML pages, plus the PDFs and Word file if those were generated. Default False.

  • region

    Deprecated. Use subregions instead.

oceanval.reset()

Reset the matchup definitions to their default state — clears any datasets previously registered with add_point_comparison / add_gridded_comparison. Use this between validating different simulations in the same script.

oceanval.compare(model_dict=None, view=True, ask=True, pdf=False, word=False)

Compare the validation output from multiple already-validated simulations, writing a shared comparison report. Output: oceanval_comparison/compare/_build/html/notebooks/comparison_seasonal.html.

Parameters
  • model_dictrequired

    Dictionary mapping a short model name to the path of its validation output.

  • view

    Open the comparison report in a browser once built. Default True.

  • ask

    Ask for confirmation before replacing an existing comparison directory. Default True.

  • pdf

    Whether to also generate PDF downloads of the comparison report. Default False.

  • word

    Whether to also generate Word versions of the comparison report — one per page, plus a combined oceanval_report.docx. Default False. Requires pandoc.

oceanval.rebuild(data_dir=".", pdf=False)

Rebuild the validation report after modifying its Jupyter notebooks by hand.

Parameters
  • data_dir

    Directory containing oceanval_report. Defaults to the current directory.

  • pdf

    Whether to also generate PDF downloads of the report. Default False.

oceanval.deep_clean()

Remove all temporary files ever created by OceanVal, across the current and previous sessions — useful if a crash left files behind.

Model support
oceanval.fvcom_preprocess(variables=None, paths=None, lon_lim=None, lat_lim=None, res=0.05, out_dir=None, model_res=None, missing=None)

Preprocess unstructured FVCOM output onto a regular grid so it can be used with the rest of OceanVal.

Parameters

Required:

  • out_dirrequired

    Output directory for the processed data — an error is raised if not supplied.

Optional:

  • variables

    List of NetCDF variable names to process.

  • paths

    List of file paths to the FVCOM data files.

  • lon_lim / lat_lim

    Minimum and maximum longitude / latitude for regridding.

  • res

    Regridding resolution in degrees. Default 0.05, suitable for point matchups.

  • model_res

    Native resolution of the FVCOM model grid, in degrees.

  • missing

    Value used to represent missing data in the FVCOM output.