API reference

Required:

• name required

  A name for the dataset, e.g. "temperature" — used internally to keep track of things. Letters and numbers only.

• source required

  The source of the observational data, e.g. "NOAA".

• model_variable required

  The name of the model variable to compare against the observations. Not currently enforced by the function but should always be supplied.

• obs_path required

  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.

• recipe

  A built-in point recipe to use instead of obs_path, e.g. {"temperature": "ices"}. The observations are downloaded during matchup for the years and lon_lim/lat_lim area being matched (or the model's own extent), and name, source and the labels default to the recipe's.

Required:

• name required

  A name for the dataset, e.g. "temperature".

• source required

  The source of the observational data, e.g. "CMEMS".

• model_variable required

  The name of the model variable to compare against the observations.

• obs_path required

  Path to the directory containing the observational data files.

• climatology required

  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.

Required:

• sim_dir required

  Path to the directory containing the model simulation output files.

• start / end required

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

• thickness vertical only

  "z_level" or the exact name of the variable holding the cell thickness, e.g. "e3t" (a variable that only has it in its name, such as O3_c_e3t, is not used) — required for vertical validation. The thickness can have a time dimension or not (a static thickness such as e3t_0), and its vertical coordinate needs a positive attribute ("down" for NEMO). A thickness file must hold only the thickness variable. With "z_level", the model’s levels must be depths (positive down); output on heights (positive up) needs the cell thickness instead.

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.

• fvcom

  Set to True if sim_dir contains raw FVCOM output. Each file is regridded with fvcom_preprocess before matching: surface values for comparisons with vertical=False, and 0–150 m every 5 m for vertical=True. Point comparisons use a 0.05° grid; gridded comparisons use twice the resolution of the observations. thickness is not needed, lon_lim / lat_lim default to the mesh extent, and the regridded files are deleted afterwards. Default False.

• live_validation jupyter-book 2

  Build an interim validation report, HTML only, as the matchups are made: each matchup’s page is added as soon as the matchup is made, and the summary is run again, so the results can be read long before the last matchup is made. True builds it with validate’s defaults; a dict gives validate’s report options — out_dir, lon_lim, lat_lim, subregions, fixed_scale, concise, transect, depth_bins and variables (pdf, word and zip are for the full report). Matchups variables leaves out are still made, but have no page in it. It is built in oceanval_interim_report in out_dir, starting at oceanval_report/_build/html/notebooks/summary.html, and matchup waits for it to be finished before returning. Build the full report with validate afterwards, as usual. Needs jupyter-book 2 or later. Default None.

• time_shift

  Number of days to shift every model time by before matching up, e.g. -1 for output that dates each time mean at the end of the period it covers (00:00 on 1 February for a January mean): shifted back a day, each mean falls in the period it covers. By default (None) matchup checks whether the times of time means look like the ends of their periods and, if so, asks whether to shift them back a day; with ask=False it only says so, and leaves them as they are. 0 leaves the times as they are, without checking.

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

• ask

  Whether to ask you to confirm output that looks like FVCOM, and for the model variable of anything that could not be identified (press Enter to skip). Only asks when run from an interactive terminal. With gui=True, the model variables are filled in in the window instead. Default True.

• fvcom

  Whether simdir holds raw FVCOM output. If True, the variables are read with xarray, as CDO cannot read FVCOM's, and the script calls matchup with fvcom=True. Default None: the files are checked for FVCOM's unstructured mesh and, if they have one, you are asked to confirm — or, when OceanVal cannot ask, they are assumed to be FVCOM output and it says so.

• gui

  Whether to choose the recipes in a page in your web browser before the script is written. Each observational variable gets a row with the model variable identified for it, which you can change (a pop-out under the box lists every variable in the model output with its long_name; search it, and tick several to sum them as var1+var2+var3), and tick-boxes for the gridded and point datasets available for it, ticked where the script would otherwise use them. Every ticked dataset is written out live, so a variable can be validated against several. A ticked dataset can be given years of its own and, if its observations are resolved in depth (WOA23, NSBC and ICES), be set to Vertical to validate the full water column. Cancelling, in the page or with Ctrl+C, writes nothing and returns None. create_recipes waits for the page, so pass gui=False where no one can answer it, e.g. in a batch job. Default True.

• validate

  Whether the script builds the validation report, with validate, once matchup has run. With validate=False the call is still written, commented out, to run once the matchups are made. Default True.

• exclude / require

  A string or list of strings: leave out output files whose names contain any of exclude, and use only those whose names contain each of require, as matchup does. Only file names are checked, not directories. Both are passed straight through to the script's matchup() call. Default None.

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

• transect

  A transect to validate the gridded matchups along, as a dict of its start and end, each [lon, lat]: {"start": [-30, 0], "end": [-30, 65]}. It must run north–south (the same longitude at both ends) or east–west (the same latitude at both ends). Each gridded matchup’s page then maps the transect, shows the monthly climatology of the surface values along it, and, for matchups made through the water column (vertical=True), a section of the annual mean along it, interpolated onto 30 evenly spaced depths from the shallowest to the deepest. Needs nctoolkit 1.3.6 or later. Default None. See Validating along a transect.

• depth_bins

  The depth ranges, in metres, that point matchups made through the water column (vertical=True) are summarised in, as a list of [min, max] pairs: [[0, 20], [20, 200], [200, None]]. A depth is in a bin if it is deeper than its min and no deeper than its max (the shallowest bin also takes its min). The deepest bin can have a max of None, for everything below its min. Bins can leave gaps, whose observations are left out, but cannot overlap. The same bins are used for every point dataset, and in the summary. Default None: 0–10, 10–30, 30–60, 60–100, 100–150, 150–300, 300–600, 600–1000 and >1000 m. See Choosing the depth bins.

• variables

  The matchups to validate, if not all of them. Each entry is a variable, for all its sources, or "variable/source", for one: ["temperature", "nitrate/WOA23"]. They are as named in the matchups (oceanval_matchups), not case sensitive, and each must match at least one matchup. The summary covers only the matchups validated. Default None: every matchup.

• region

  Deprecated. Use subregions instead.

• model_dict required

  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.

• data_dir

  Directory containing oceanval_report. Defaults to the current directory.

• pdf

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

Required:

• out_dir required

  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

  Approximate native resolution of the FVCOM mesh in degrees, used to build the land/sea mask by binning node positions. If None (default), the mask is built from the mesh triangles instead: a grid cell is sea if its centre lies inside the mesh.

• missing

  Value used to represent missing data in the FVCOM output.

• z_level

  If True, variables on sigma layers are interpolated onto fixed depth levels below the free surface before regridding. Depths above the top layer centre take the top layer value, depths between the bottom layer centre and the seabed take the bottom layer value, and depths below the seabed are missing. Default False (surface only).

• levels

  Depth levels in metres (positive down) to interpolate to. Supplying levels implies z_level=True. Defaults to the WOA23 standard depths, down to the maximum model depth.