API reference

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.

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.

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.

• lon_lim / lat_lim

  Longitude / latitude limits for the validation region.

• region

  "global" or "nwes" (Northwest European Shelf).

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

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

• data_dir

  Directory containing oceanval_report. Defaults to the current directory.

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.