copernicus module

Copernicus module

Interface utilities for interacting with the Copernicus Marine Service (CMEMS).

This module provides high-level tools to define, execute, and process data requests to the Copernicus Marine Data Store using the copernicusmarine Python client. It streamlines the creation of spatial, temporal, and vertical subset requests, handles caching, and enables easy post-processing through xarray.

Main features include:

  • Construction of structured CMEMS subset requests through the CopernicusRequest class,

  • Execution of download requests with automatic output management (CopernicusRequest.fetch),

  • Loading of downloaded datasets directly into xarray (get_copdataset),

  • Plotting utilities for ocean surface and subsurface currents (plot_currents),

  • Additional helpers to support CMEMS velocity variable detection and dataset inspection.

This module centralizes CMEMS-related operations to ensure consistent, transparent, and reproducible oceanographic workflows within VisuSat.

class visusat.copernicus.CopernicusRequest(dataset_id, variables, minimum_longitude, maximum_longitude, minimum_latitude, maximum_latitude, start_datetime, end_datetime, minimum_depth=None, maximum_depth=None, output_filename='copernicus_output.nc')

Bases: object

Build and manage a data extraction request to the Copernicus Marine Data Store.

This class defines a complete subset request (spatial, temporal, vertical, and variable selection) and provides a convenient interface to download the corresponding dataset using copernicusmarine.subset.

The request can be executed via the fetch() method, which downloads the data to the configured output path, unless the file already exists (this can be overridden with force=True).

Parameters:

  • dataset_id (str) – Identifier of the CMEMS dataset (e.g. "cmems_obs-sl_glo_phy-ssh_nrt_allsat-l4-duacs-0.125deg_P1D").

  • variables (list of str) – List of variable names to extract from the dataset.

  • start_datetime (str) – Start date-time in ISO8601 format (e.g. "2025-01-01T00:00:00").

  • end_datetime (str) – End date-time in the same format.

  • minimum_latitude (float) – Minimum latitude of the requested spatial domain.

  • maximum_latitude (float) – Maximum latitude of the requested spatial domain.

  • minimum_longitude (float) – Minimum longitude of the requested domain.

  • maximum_longitude (float) – Maximum longitude.

  • minimum_depth (float, optional) – Minimum depth for the request (if applicable). Defaults to None.

  • maximum_depth (float, optional) – Maximum depth. Defaults to None.

  • output_filename (str, optional) – Name of the output NetCDF file. Defaults to "output.nc".

  • output_dir (str, optional) – Directory where the output file will be saved. If None, a dataset-specific directory under the project data folder is created automatically.

  • extra_params (dict, optional) – Additional keyword arguments passed directly to copernicusmarine.subset.

output_path

Full path to the resulting NetCDF file.

Type:

str

Examples

Create a request and download DUACS SLA:

>>> from visusat.copernicus import CopernicusRequest
>>> req = CopernicusRequest(
...     dataset_id="cmems_obs-sl_glo_phy-ssh_nrt_allsat-l4-duacs-0.125deg_P1D",
...     variables=["sla", "err_sla"],
...     minimum_longitude=1,
...     maximum_longitude=359,
...     minimum_latitude=-70,
...     maximum_latitude=80,
...     start_datetime="2025-10-22T00:00:00",
...     end_datetime="2025-10-22T00:00:00",
...     minimum_depth=None,
...     maximum_depth=None,
...     output_filename="duacs_sla.nc",
... )
>>> req.fetch()
dataset_id: str
end_datetime: str
fetch(force=False)

Download the requested dataset from the Copernicus Marine Data Store.

Parameters:

force (bool, optional) – If True, overwrite the file even if it already exists. Defaults to False.

Returns:

Path to the downloaded NetCDF file.

Return type:

str

maximum_depth: Optional[float] = None
maximum_latitude: float
maximum_longitude: float
minimum_depth: Optional[float] = None
minimum_latitude: float
minimum_longitude: float
output_filename: Optional[str] = 'copernicus_output.nc'
start_datetime: str
variables: List[str]
visusat.copernicus.load_dataset(request, force=False)

Download and open a Copernicus Marine dataset as an xarray.Dataset.

This function triggers the download associated with a CopernicusRequest object and returns the resulting NetCDF file as an opened xarray.Dataset. If the file already exists, the download is skipped unless force=True is provided.

Parameters:

  • request (CopernicusRequest) – A configured request describing the dataset subset to download.

  • force (bool, optional) – If True, force redownload even if the file already exists. Defaults to False.

Returns:

The dataset opened from the downloaded NetCDF file.

Return type:

xarray.Dataset

visusat.copernicus.plot_currents(request, ds, domain=None, vectors=False)

Plot ocean currents from a Copernicus Marine dataset and save one figure per time–depth combination.

This function reads a velocity field (u, v) from a CMEMS dataset, computes the current magnitude, and produces a figure for each time step and each depth level. The output figures are automatically saved into a dataset- specific directory. Optional vector arrows can be added to visualise flow direction.

Parameters:

  • request (CopernicusRequest) – Request object used to download the dataset. Its dataset_id is used to determine the output directory for the generated figures.

  • ds (xarray.Dataset) – The dataset containing velocity components. The function automatically detects the velocity variable names via utils.detect_velocity_vars. Expected dimensions: time, depth, latitude, longitude.

  • domain (list of float, optional) – Geographic subdomain specified as [lon_min, lon_max, lat_min, lat_max]. If provided, plots are zoomed to this region. Defaults to None.

  • vectors (bool, optional) – If True, overlay quiver arrows (u, v) to show current direction. Defaults to False.

Returns:

The function generates and saves figures but does not return an object.

Return type:

None

Notes

  • A separate PNG file is produced for each combination of time and depth.

  • Velocity components are automatically identified using utils.detect_velocity_vars().

  • Depth and time values are embedded into the output filename.

visusat.copernicus.plot_fields(request, ds)

Plot each variable of a Copernicus Marine dataset retrieved via copernicusmarine.

Parameters:

  • request (CopernicusRequest) – The request used to download the dataset.

  • ds (xarray.Dataset) – Dataset containing the requested variables.

Notes

All heavy imports (cartopy, matplotlib, numpy) are performed inside the function to ensure ReadTheDocs compatibility.