data_sources package

Individual data source readers for each AMOC observing array and dataset.

Package Overview

Each module provides a read function for accessing its specific data source with consistent interfaces and error handling.

Module naming convention: - Arrays include latitude: rapid26n, move16n, osnap55n, samba34s - Special locations: wh41n (Willis & Hobbs), noac47n (North Atlantic Ocean Current) - Datasets by author/year: fw2015, calafat2025, zheng2024 - Overflow locations: dso (Denmark Strait), fbc (Faroe Bank Channel)

Available Functions

amocatlas.data_sources.read_rapid(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset] | tuple[list[Dataset], list[list[str]]][source]

Load the RAPID transport dataset from a URL or local file path into an xarray.Dataset.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the RAPID data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. If None, will attempt to list files in the source directory.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, return tuple of (datasets, list_of_metadata_changes_per_dataset). If False, return only datasets. Default is False.

Returns:

If track_added_attrs=False: List of loaded datasets with metadata. If track_added_attrs=True: Tuple of (datasets, list of metadata changes per dataset).

Return type:

list[xr.Dataset] or tuple[list[xr.Dataset], list[dict]]

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If no valid NetCDF files are found in the provided file list.

amocatlas.data_sources.read_move(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the MOVE transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the MOVE data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to MOVE_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added by AMOCatlas processing. Returns tuple (datasets, added_attrs_per_dataset) when enabled.

Returns:

If track_added_attrs=False: List of loaded xarray datasets. If track_added_attrs=True: Tuple of (datasets, added_attrs_per_dataset) where added_attrs_per_dataset is a list of dictionaries containing ‘added’ and ‘modified’ attribute tracking information.

Return type:

list of xr.Dataset or tuple

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_osnap(source: str = None, file_list: str | list[str] = None, transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, version: str = '2025', track_added_attrs: bool = False) → list[Dataset][source]

Load the OSNAP transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults depend on version: OSNAP_2025_DEFAULT_FILES for “2025”, OSNAP_DEFAULT_FILES for “2020”.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • version (str, optional) – Dataset version to use (“2025” for 2014-2022 data, “2020” for 2014-2020 data). Defaults to “2025” (latest version).

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If an invalid version is specified.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_osnap_2025(source: str = None, file_list: str | list[str] = None, transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False) → list[Dataset][source]

Load the OSNAP 2025 datasets (2014-2022 coverage) from a URL or local file path.

This is a convenience function that calls read_osnap with version=”2025”.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to OSNAP_2025_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

amocatlas.data_sources.read_samba(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the SAMBA transport datasets from remote URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the dataset directory. If None, will use predefined URLs per file.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to SAMBA_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_fw2015(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the FW2015 transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to FW2015_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_mocha(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the MOCHA transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the MOCHA data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to MOCHA_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_arcticgateway(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the ARCTIC Gateway transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the ARCTIC data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to ARCTIC_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_dso(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the Denmark Strait Overflow (DSO) datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to DSO_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

——- list of xr.Dataset

Notes

The original DSO_transport_hourly_1996_2021.nc file contains a corrupted DEPTH coordinate value (9.97e+36). This function automatically detects and corrects this by setting the DEPTH to NaN and documenting the correction in the dataset’s history attribute.

Raises:

  • ValueError –

  • If no source is provided for a file and no default URL mapping is found. –

  • FileNotFoundError If the file cannot be downloaded or does not exist locally. –

amocatlas.data_sources.read_fbc(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the FBC (Faroe Banks Channel) transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to FBC_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_calafat2025(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the CALAFAT2025 transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the CALAFAT2025 data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to CALAFAT2025_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_zheng2024(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the ZHENG2024 transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • ----------

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to ZHENG2024_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ------ –

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_41n(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the 41N transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to 41N_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_47n(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the 47N transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to 47N_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError –

  • If the file cannot be downloaded or does not exist locally. –

amocatlas.data_sources.read_nac(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the NAC (North Atlantic Current) transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to NAC_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata. And if track_added_attrs is True, also returns a list of dictionaries with the attributes that were added to each dataset during metadata enrichment.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_sf2021(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the SF2021 transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to SF2021_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_lebras35n(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the LEBRAS35N datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to LEBRAS35N_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_axmoc22s(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the AXMOC22S datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to AXMOC22S_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.read_axmoc34s(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the AXMOC34S datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to AXMOC34S_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

Submodules

rapid26n

RAPID array data reader for AMOCatlas.

This module provides functions to read and process data from the RAPID (Rapid Climate Change) observing array located at 26°N in the Atlantic.

amocatlas.data_sources.rapid26n.read_rapid(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset] | tuple[list[Dataset], list[list[str]]][source]

Load the RAPID transport dataset from a URL or local file path into an xarray.Dataset.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the RAPID data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. If None, will attempt to list files in the source directory.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, return tuple of (datasets, list_of_metadata_changes_per_dataset). If False, return only datasets. Default is False.

Returns:

If track_added_attrs=False: List of loaded datasets with metadata. If track_added_attrs=True: Tuple of (datasets, list of metadata changes per dataset).

Return type:

list[xr.Dataset] or tuple[list[xr.Dataset], list[dict]]

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If no valid NetCDF files are found in the provided file list.

move16n

MOVE array data reader for AMOCatlas.

This module provides functions to read and process data from the MOVE (Meridional Overturning Variability Experiment) observing array located at 16°N in the Atlantic.

amocatlas.data_sources.move16n.read_move(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the MOVE transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the MOVE data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to MOVE_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added by AMOCatlas processing. Returns tuple (datasets, added_attrs_per_dataset) when enabled.

Returns:

If track_added_attrs=False: List of loaded xarray datasets. If track_added_attrs=True: Tuple of (datasets, added_attrs_per_dataset) where added_attrs_per_dataset is a list of dictionaries containing ‘added’ and ‘modified’ attribute tracking information.

Return type:

list of xr.Dataset or tuple

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

osnap55n

OSNAP array data reader for AMOCatlas.

This module provides functions to read and process data from the OSNAP (Overturning in the Subpolar North Atlantic Program) observing array.

amocatlas.data_sources.osnap55n.read_osnap(source: str = None, file_list: str | list[str] = None, transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, version: str = '2025', track_added_attrs: bool = False) → list[Dataset][source]

Load the OSNAP transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults depend on version: OSNAP_2025_DEFAULT_FILES for “2025”, OSNAP_DEFAULT_FILES for “2020”.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • version (str, optional) – Dataset version to use (“2025” for 2014-2022 data, “2020” for 2014-2020 data). Defaults to “2025” (latest version).

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If an invalid version is specified.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

amocatlas.data_sources.osnap55n.read_osnap_2025(source: str = None, file_list: str | list[str] = None, transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False) → list[Dataset][source]

Load the OSNAP 2025 datasets (2014-2022 coverage) from a URL or local file path.

This is a convenience function that calls read_osnap with version=”2025”.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to OSNAP_2025_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

samba34s

SAMBA array data reader for AMOCatlas.

This module provides functions to read and process data from the SAMBA (South Atlantic Meridional Overturning Circulation) observing array located at 34.5°S.

amocatlas.data_sources.samba34s.read_samba(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the SAMBA transport datasets from remote URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the dataset directory. If None, will use predefined URLs per file.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to SAMBA_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

arcticgateway

Arctic Gateway transport data reader for AMOCatlas.

This module provides functions to read and process data from the Arctic Gateway transport dataset, which includes measurements from key Arctic Ocean gateways: Fram Strait, Davis Strait, Bering Strait, and Barents Sea Opening.

The data is provided as a zip archive containing multiple NetCDF files for each gateway, with full-depth velocity adjustments applied.

Key functions:

  • read_arcticgateway(): Main data loading interface for Arctic Gateway transport data

Data source: Pan-Arctic Gateway transports since 2004 Project: Norwegian Polar Institute Arctic gateway transport monitoring

Note

The original NetCDF metadata incorrectly uses creator_name and publisher_name for institutional names (“Norwegian Polar Institute (NPI)”) instead of individual researcher names, so institutions can appear in contributor fields. This should be corrected in the source dataset metadata.

amocatlas.data_sources.arcticgateway.read_arcticgateway(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the ARCTIC Gateway transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the ARCTIC data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to ARCTIC_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

fw2015

Frajka-Williams 2015 dataset reader for AMOCatlas.

This module provides functions to read and process data from the Frajka-Williams et al. (2015) AMOC proxy dataset. This dataset provides a reconstruction of AMOC variability based on sea surface height and wind stress observations, extending the observational record beyond direct mooring observations.

amocatlas.data_sources.fw2015.read_fw2015(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the FW2015 transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to FW2015_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

mocha26n

MOCHA dataset reader for AMOCatlas.

This module provides functions to read and process data from the MOCHA (Meridional Overturning Circulation and Heat Transport Array) dataset. MOCHA provides observations of meridional heat transport in the North Atlantic.

amocatlas.data_sources.mocha26n.read_mocha(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the MOCHA transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the MOCHA data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to MOCHA_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

wh41n

41°N array data reader for AMOCatlas.

This module provides functions to read and process data from the 41°N observing array in the North Atlantic. This array monitors the Atlantic Meridional Overturning Circulation and associated heat transport at the northern boundary of the subtropical gyre.

amocatlas.data_sources.wh41n.read_41n(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the 41N transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to 41N_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

dso

DSO (Denmark Strait Overflow) data reader for AMOCatlas.

This module provides functions to read and process data from the Denmark Strait Overflow observing array. DSO monitors the transport of dense water flowing southward through Denmark Strait, which is a key component of the Atlantic Meridional Overturning Circulation.

amocatlas.data_sources.dso.read_dso(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the Denmark Strait Overflow (DSO) datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to DSO_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

——- list of xr.Dataset

Notes

The original DSO_transport_hourly_1996_2021.nc file contains a corrupted DEPTH coordinate value (9.97e+36). This function automatically detects and corrects this by setting the DEPTH to NaN and documenting the correction in the dataset’s history attribute.

Raises:

  • ValueError –

  • If no source is provided for a file and no default URL mapping is found. –

  • FileNotFoundError If the file cannot be downloaded or does not exist locally. –

noac47n

NOAC 47°N array data reader for AMOCatlas.

This module provides functions to read and process data from the North Atlantic Ocean Current (NOAC) observing array located at 47°N. The array provides transport estimates from temperature and salinity profile data in the North Atlantic.

Key functions: - read_47n(): Main data loading interface for NOAC 47°N array data

Data source: Ocean current measurements at 47°N latitude

amocatlas.data_sources.noac47n.read_47n(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the 47N transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to 47N_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError –

  • If the file cannot be downloaded or does not exist locally. –

fbc

Faroe Bank Channel (FBC) overflow data reader for AMOCatlas.

This module provides functions to read and process data from the Faroe Bank Channel overflow monitoring system. The FBC is a critical pathway for dense water overflow from the Nordic Seas into the North Atlantic, representing an important component of the Atlantic Meridional Overturning Circulation.

The dataset includes overflow transport estimates and hydrographic measurements from moored instruments in the channel.

Key functions: - read_fbc(): Main data loading interface for Faroe Bank Channel overflow data

Data source: Faroe Bank Channel overflow monitoring program Location: Deep channel between Faroe Islands and Faroe Bank

amocatlas.data_sources.fbc.read_fbc(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the FBC (Faroe Banks Channel) transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to FBC_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

calafat2025

Calafat et al. 2025 MHT data reader for AMOCatlas.

This module provides functions to read and process Atlantic Meridional Heat Transport (MHT) data from Calafat et al. (2025). This dataset provides observations and estimates of meridional heat transport across multiple latitudes in the Atlantic Ocean.

amocatlas.data_sources.calafat2025.read_calafat2025(source: str, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the CALAFAT2025 transport dataset from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – URL or local path to the NetCDF file(s). Defaults to the CALAFAT2025 data repository URL.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to CALAFAT2025_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If the source is neither a valid URL nor a directory path.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

zheng2024

Zheng et al. 2024 freshwater transport data reader for AMOCatlas.

This module provides functions to read and process freshwater transport data from Zheng et al. (2024). This dataset provides observations and estimates of freshwater transport across key sections in the Atlantic Ocean, which is closely related to AMOC variability and climate change.

amocatlas.data_sources.zheng2024.read_zheng2024(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the ZHENG2024 transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • ----------

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to ZHENG2024_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ------ –

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

nac

North Atlantic Current (NAC) data reader for AMOCatlas.

This module provides functions to read and process the North Atlantic current time series from satellite and float observations. The NAC is a key component of the Atlantic Meridional Overturning Circulation, transporting warm, saline water from the tropics to the high northern latitudes.

The dataset includes NAC transport estimates from satellite and float observations and an NAC estimation from satellite altimetry alone.

Key functions: - read_nac(): Main data loading interface for North Atlantic Current data

Data source: Satellite and float observations Location: Between tip of Greenland and northern Spain

amocatlas.data_sources.nac.read_nac(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the NAC (North Atlantic Current) transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to NAC_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata. And if track_added_attrs is True, also returns a list of dictionaries with the attributes that were added to each dataset during metadata enrichment.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

sf2021

Sanchez-Franks Satellite proxy for the AMOC at 26N data reader for AMOCatlas.

This module provides functions to read and process satellite proxy transport data for 26N from Sanchez-Franks et al. (2021). This dataset provides a satellite reconstruction of the AMOC transport at 26N based on satellite altimetry. It also includes the upper-mid-ocean and gulf stream components. The components are derived through a dynamically based method.

amocatlas.data_sources.sf2021.read_sf2021(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the SF2021 transport datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to SF2021_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

lebras35n

AMOC at 35°N transport data reader for AMOCatlas.

This module provides functions to read and process AMOC transport data at 35°N from deep moorings, floats and satellite altimetry.

Dataset one includes the AMOC transport in depth and in density space, the integrated across-basin streamfunction in depth space and the Ekman transport time series derived from CCMP. Dataset two includes the geostrophic velocities through the section, the potential density anomaly referenced to 2000m, the depth of the sea floor along the section and the area of each grid point.

Key functions: - read_lebras35n(): Main data loading interface for AMOC transport data at 35°N which includes both datasets

Data source: AMOC transport monitoring program including deep moorings, floats and satellite altimetry Location: North Atlantic at 35°N

amocatlas.data_sources.lebras35n.read_lebras35n(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the LEBRAS35N datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to LEBRAS35N_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

axmoc22s

AMOC at 22.5°S transport data reader for AMOCatlas.

This module provides functions to read and process AMOC and meridional heat transport data at 22.5°S based on sustained in situ observations.

Dataset includes estimates of AMOC and heat transport at 22.5°S. Both also have the Ekman and geostrophic component available.

Key functions: - read_axmoc22s(): Main data loading interface for AMOC and meridional heat transport data at 22.5°S

Data source: AXMOC: Estimate of AMOC, heat and freshwater transports at 22.5 and 34.5S based on sustained in situ observations Location: South Atlantic at 22.5°S

amocatlas.data_sources.axmoc22s.read_axmoc22s(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the AXMOC22S datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to AXMOC22S_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

axmoc34s

AMOC at 34.5°S transport data reader for AMOCatlas.

This module provides functions to read and process AMOC, meridional heat and freshwater transport data at 34.5°S based on sustained in situ observations.

Dataset includes estimates of AMOC, heat and freshwater transport at 34.5°S. All three also have the Ekman and geostrophic component available.

Key functions: - read_axmoc34s(): Main data loading interface for AMOC, meridional heat and freshwater transport data at 34.5°S

Data source: AXMOC: Estimate of AMOC, heat and freshwater transports at 22.5 and 34.5S based on sustained in situ observations Location: South Atlantic at 34.5°S

amocatlas.data_sources.axmoc34s.read_axmoc34s(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the AXMOC34S datasets from a URL or local file path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to AXMOC34S_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List of loaded xarray datasets with basic inline and file-specific metadata.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

ovide

OVIDE MOC-intensity reader for AMOCatlas.

Reads the monthly MOC-intensity time series across the Greenland-Portugal A25 OVIDE line (Mercier et al., SEANOE 10.17882/46445). The file carries two indices on different time bases: MOC_index_ISAS (2002-2015; altimetry surface combined with the time-varying Argo/ISAS interior) and MOC_index_AVISO (1993-2015; altimetry combined with a fixed 2002-2015 mean ISAS interior – an altimetry proxy), plus err_index_ISAS (the ISAS ensemble standard deviation). The two monthly timestamp grids coincide exactly, so all three are served on a single 1993-2015 TIME axis, with the ISAS series NaN before 2002.

amocatlas.data_sources.ovide.read_ovide(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the OVIDE MOC-intensity dataset from a URL or local path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path to the data directory (remote source is handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to OVIDE_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List with the single OVIDE dataset, metadata attached and both indices on one TIME axis.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.

scotia

SCOTIA overturning reader for AMOCatlas.

Reads the monthly overturning diagnostics of the Scotland-Canada overturning array (SCOTIA; Fox et al. 2026), computed in neutral-density (gamma-n) space across the subpolar North Atlantic. The upstream product has two files on a SAMS THREDDS server: a small diagnostics time series (served here) and a large gridded T/S/velocity field (~2 GB, not downloaded). Only the diagnostics file is read by default.

The diagnostics carry the overturning streamfunction psi and the transport-by-class transport on a neutral-density coordinate gamma_n_bin, the streamfunction maximum moc and the density gamma_moc at which it occurs, plus northward heat (hf), freshwater (ff) and density (df) fluxes. Raw variable names are kept so the metadata variable_mapping can rename them downstream.

amocatlas.data_sources.scotia.read_scotia(source: str | Path | None, file_list: str | list[str], transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False, track_added_attrs: bool = False) → list[Dataset][source]

Load the SCOTIA overturning diagnostics from a URL or local path into xarray Datasets.

Parameters:

  • source (str, optional) – Local path or base URL to the data directory (remote source handled per-file).

  • file_list (str or list of str, optional) – Filename or list of filenames to process. Defaults to SCOTIA_DEFAULT_FILES.

  • transport_only (bool, optional) – If True, restrict to transport (diagnostics) files only.

  • data_dir (str, Path or None, optional) – Optional local data directory.

  • redownload (bool, optional) – If True, force redownload of the data.

  • track_added_attrs (bool, optional) – If True, track which attributes were added during metadata enrichment.

Returns:

List with the single SCOTIA diagnostics dataset, metadata attached.

Return type:

list of xr.Dataset

Raises:

  • ValueError – If no source is provided for a file and no default URL mapping is found.

  • FileNotFoundError – If the file cannot be downloaded or does not exist locally.