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

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

Notes: - The original NetCDF metadata incorrectly uses creator_name and publisher_name

for institutional names (“Norwegian Polar Institute (NPI)”) instead of individual researcher names. This causes institutions to 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.