oceanbench package

Subpackages

• oceanbench.datasets package
  • Submodules
  • oceanbench.datasets.challenger module
    • glo12()
    • glo36v1()
    • glonet()
    • wenhai()
    • xihe()
  • oceanbench.datasets.input module
    • glo12_nowcasts()
    • ifs_forcings()
  • oceanbench.datasets.reference module
    • glo12_analysis()
    • glorys_reanalysis()
  • Module contents

Submodules

oceanbench.cli module

class oceanbench.cli.EvaluationResult(challenger: str, error: str | None = None)

Bases: object

challenger: str

error: str | None = None

property success: bool

oceanbench.cli.main()

oceanbench.metrics module

This module exposes the functions to compute metrics.

oceanbench.metrics.deviation_of_lagrangian_trajectories_compared_to_glo12_analysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the deviation of Lagrangian trajectories compared to GLO12 analysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.deviation_of_lagrangian_trajectories_compared_to_glorys_reanalysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the deviation of Lagrangian trajectories compared to GLORYS reanalysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_geostrophic_currents_compared_to_glo12_analysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of geostrophic currents compared to GLO12 analysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_geostrophic_currents_compared_to_glorys_reanalysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of geostrophic currents compared to GLORYS reanalysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_mixed_layer_depth_compared_to_glo12_analysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of Mixed Layer Depth (MLD) compared to GLO12 analysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_mixed_layer_depth_compared_to_glorys_reanalysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of Mixed Layer Depth (MLD) compared to GLORYS reanalysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_variables_compared_to_glo12_analysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of variables compared to GLO12 analysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_variables_compared_to_glorys_reanalysis(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of variables compared to GLORYS reanalysis.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.metrics.rmsd_of_variables_compared_to_observations(challenger_dataset: Dataset, region: str | RegionSpec | None = 'global') → DataFrame

Compute the Root Mean Square Deviation (RMSD) of variables compared to observations.

Parameters

challenger_datasetxarray.Dataset

The challenger dataset.

regionstr, optional

The OceanBench region to evaluate on.

Returns

DataFrame

The DataFrame containing the scores.

oceanbench.regions module

This module exposes the OceanBench region API.

class oceanbench.regions.RegionSpec(id: str, display_name: str, bounds: oceanbench.core.regions.BoundingBox | None)

Bases: object

bounds: BoundingBox | None

display_name: str

id: str

property official: bool

oceanbench.regions.available_regions() → list[str]

Return the official OceanBench region identifiers accepted by the CLI --region option.

oceanbench.regions.custom(identifier: str, display_name: str, minimum_latitude: float, maximum_latitude: float, minimum_longitude: float, maximum_longitude: float) → RegionSpec

Create a custom bounded region for programmatic evaluation.

oceanbench.regions.load_region_file(path: str | Path) → RegionSpec

Load a custom region definition from a JSON file.

oceanbench.regions.subset(dataset: Dataset, region: str | RegionSpec | None) → Dataset

Return a dataset restricted to the selected OceanBench region.

Module contents

This module exposes the package python API to evaluate a challenger.

oceanbench.evaluate_challenger(challenger_python_code_uri_or_local_path: str | None = None, output_bucket: str | None = None, output_prefix: str | None = None, runtime_configuration: RuntimeConfiguration | None = None, region: str | RegionSpec | None = None)

Compute all the benchmark scores for the given challenger dataset, by calling all functions of the metrics module. It generates and executes a notebook based on the python code that opens the challenger dataset as challenger_dataset: xarray.Dataset.

This function is used for official evaluation.

The output notebook file name is automatically derived from the challenger file name: glonet.py becomes glonet.global.report.ipynb.

Parameters

challenger_python_code_uri_or_local_pathstr, optional

The python content that opens the challenger dataset. Required. Can be a remote file (URL), a DataURI or the path to a local file. Can also be configured with environment variable OCEANBENCH_CHALLENGER_PYTHON_CODE_URI_OR_LOCAL_PATH.

output_bucketstr, optional

The destination S3 bucket of the executed notebook. If not provided, the notebook is written on the local filesystem. If provided, uses AWS S3 environment variables. Can also be configured with environment variable OCEANBENCH_OUTPUT_BUCKET.

output_prefixstr, optional

The destination S3 prefix of the executed notebook. If output_bucket is not provided, this option is ignored. If provided, uses AWS S3 environment variables. Can also be configured with environment variable OCEANBENCH_OUTPUT_PREFIX.

runtime_configurationRuntimeConfiguration, optional

Runtime settings applied inside the generated notebook execution, including staging and remote retry behavior.

regionstr, RegionSpec, or None, optional

The OceanBench region to evaluate on. This can be an official region id such as global or ibi, or a custom oceanbench.regions.RegionSpec value.