AMOCatlas

Standardized, modular loading of AMOC observing array datasets, with optional structured logging and metadata enrichment.

AMOCatlas provides a unified system to access and process data from major Atlantic Meridional Overturning Circulation (AMOC) observing arrays. The Atlantic Meridional Overturning Circulation is a critical component of Earth's climate system, transporting heat northward in the Atlantic Ocean. This project enables researchers to easily access, analyze, and visualize data from key monitoring stations.

This is a work in progress, all contributions welcome!

Table of Contents

• Features
• Supported Arrays
• Installation
• Quick Start
• Documentation
• Development
• Funding & Support
• Acknowledgements
• Contributing

Features

• 🌊 Unified Data Access: Single interface for multiple AMOC observing arrays
• 📊 Automatic Data Download: Intelligent caching system prevents redundant downloads
• 📝 Structured Logging: Per-dataset logging for reproducible workflows
• 🔍 Metadata Enrichment: Enhanced datasets with processing timestamps and source information
• 📈 Visualization Tools: Built-in plotting functions with consistent styling
• 🧪 Sample Datasets: Quick access to example data for testing and development

Available Data Sources

For more detail on the AMOC and observing arrays, see:

• UCAR overview: https://climatedataguide.ucar.edu/climate-data/observations-atlantic-meridional-overturning-circulation-amoc
• AtlantOS/OceanSITES: https://www.ocean-ops.org/oceansites/tma/index.html

Installation

From PyPI (Recommended)

pip install AMOCatlas

Requirements: Python ≥3.9, with numpy, pandas, xarray, and matplotlib.

For Development

git clone https://github.com/AMOCcommunity/amocatlas.git
cd amocatlas
pip install -r requirements-dev.txt
pip install -e .

This installs amocatlas locally. The -e ensures that any edits you make in the files will be picked up by scripts that import functions from amocatlas.

Quick Start

Load Sample Data

from amocatlas import read

# Load RAPID sample dataset (new API - recommended)
ds = read.rapid()
print(ds)

# Or use the legacy API
from amocatlas import readers
ds = readers.load_sample_dataset("rapid")

Load Full Datasets

from amocatlas import read

# Load complete dataset (downloads and caches data) - new API
ds = read.osnap()                          # Single standardized dataset
all_files = read.osnap(all_files=True)     # Get all files for array

# Or use the legacy API
from amocatlas import readers
datasets = readers.load_dataset("osnap")  # Returns list of raw datasets

A *.log file will be written to logs/ by default.

Data will be cached in ~/.amocatlas_data/ unless you specify a custom location.

API Features (v0.2.0+)

AMOCatlas provides standardized, analysis-ready data by default with the new read API:

Key Benefits:

• 🧹 Standardized Data: Consistent variable names, metadata, and units
• 🚀 Easy to Use: Single function calls instead of complex workflows
• 🔄 Flexible: Get raw data when needed with raw=True
• 📊 Smart Defaults: Automatically handles array-specific parameters

from amocatlas import read

# Standard workflow - recommended for most users
rapid_data = read.rapid()              # Single standardized dataset
osnap_data = read.osnap()              # Automatically uses latest version
arctic_data = read.arcticgateway()     # Consistent across all arrays

# Advanced usage
all_rapid = read.rapid(all_files=True) # Get all files for an array
raw_data = read.rapid(raw=True)        # Original format for special cases

Legacy API (still supported):

from amocatlas import readers
datasets = readers.load_dataset("rapid")  # Returns raw data as before

Documentation

Documentation is available at https://amoccommunity.github.io/AMOCatlas.

Check out the demo notebook notebooks/demo.ipynb for example functionality.

Project Structure

amocatlas/
│
├── read.py                  # 🆕 Modern API namespace (read.rapid(), read.osnap(), etc.)
├── readers.py               # Legacy orchestrator for loading datasets
├── reader_utils.py          # Shared utilities for all data source readers
│
├── data_sources/            # 🆕 Organized data source readers
│   ├── rapid26n.py          # RAPID array (26°N)
│   ├── move16n.py           # MOVE array (16°N)
│   ├── osnap55n.py          # OSNAP array (Subpolar North Atlantic)
│   ├── samba34s.py          # SAMBA array (34.5°S)
│   ├── mocha26n.py          # MOCHA dataset (26°N)
│   ├── wh41n.py             # 41°N array
│   ├── dso.py               # DSO overflow
│   ├── fbc.py               # Faroe Bank Channel
│   ├── fw2015.py            # Frajka-Williams 2015 dataset
│   ├── arcticgateway.py     # Arctic Gateway transports
│   ├── calafat2025.py       # Calafat 2025 heat transport
│   ├── zheng2024.py         # Zheng 2024 freshwater transport
│   └── noac47n.py           # NOAC 47°N monitoring
│
├── metadata/                # 🆕 YAML metadata files for standardization
├── utilities.py             # Core utilities (downloads, parsing, validation)
├── logger.py                # Structured logging system
├── standardise.py           # Data standardization functions
├── plotters.py              # Visualization and plotting functions
├── tools.py                 # Analysis and calculation functions
├── writers.py               # Data export functionality
│
└── tests/                   # Comprehensive unit tests

Development

Running Tests

All new functions should include tests. You can run tests locally and generate a coverage report with:

pytest --cov=amocatlas --cov-report term-missing tests/

Try to ensure that all the lines of your contribution are covered in the tests.

Generating Dataset Reports

AMOCatlas includes automated report generation for comprehensive dataset documentation:

# Generate reports for all supported arrays
python generate_report

# Generate report for a specific dataset
python generate_report --data_source rapid

# Generate reports with custom output directory
python generate_report --output_dir custom_reports/

Reports are generated as structured RST files in docs/source/reports/ with:

• Dataset visualization plots
• Variable mapping tables (original → standardized names)
• Comprehensive metadata documentation
• Temporal coverage analysis
• Statistical summaries

Code Quality

black amocatlas/ tests/          # Format code
ruff check amocatlas/ tests/     # Lint code
pre-commit run --all-files       # Run all hooks

Working with Notebooks

You can run the example jupyter notebook by launching jupyterlab with jupyter-lab and navigating to the notebooks directory, or in VS Code or another python GUI.

Documentation

To build the documentation locally you need to install a few extra requirements:

• Install make for your computer, e.g. on ubuntu with sudo apt install make
• Install the additional python requirements. Activate the environment you use for working with amocatlas, navigate to the top directory of this repo, then run pip install -r requirements-dev.txt

Once you have the extras installed, you can build the docs locally by navigating to the docs/ directory and running make clean html. This command will create a directory called build/ which contains the html files of the documentation. Open the file docs/build/html/index.html in your browser, and you will see the docs with your changes applied.

Funding & Support

This project is supported by the Horizon Europe project EPOC - Explaining and Predicting the Ocean Conveyor (Grant Agreement No. 101081012).

Funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them.

Current Roadmap

• Improve test coverage for data sources with <40% coverage
• Add more comprehensive visualization function tests
• Expand plotting capabilities with additional array-specific visualizations
• Create summary table of variable names, standard_names, long_names and units across all datasets
• Create summary table of default units and formatting conventions used for standardization
• Document deviations from OceanSITES-1.5 standard and rationale for changes
• Enrich metadata with ORCID identifiers for contributors
• Enrich metadata with https://edmo.seadatanet.org identifiers for contributing institutions
• Create sample 3D plots for Arctic Gateway and Calafat2025 datasets

Acknowledgements

The observing arrays and datasets accessed through AMOCatlas are supported by:

• RAPID data: Data from the RAPID-MOCHA-WBTS observing project are funded by the Natural Environment Research Council, the National Science Foundation (NSF), with support from NOAA. They are freely available from www.rapid.ac.uk/.

• MOVE data: The MOVE project is made possible with funding from the NOAA Climate Program Office under award NA15OAR4320071 and carried out by principal investigators Uwe Send and Matthias Lankhorst. Initial funding came from the German Bundesministerium fuer Bildung und Forschung. MOVE data are made freely available through the international OceanSITES program.

• OSNAP data: OSNAP data were collected and made freely available by the OSNAP (Overturning in the Subpolar North Atlantic Program) project and all the national programs that contribute to it (www.o-snap.org).

• SAMBA data: SAMBA data were collected and made freely available by the SAMOC international project and contributing national programs

• 41°N data: These data were collected and made freely available by the International Argo Program and the national programs that contribute to it. The Argo Program is part of the Global Ocean Observing System

• DSO data: Generated by Institution of Oceanography Hamburg and Marine and Freshwater Research Institute (Reykjavik, Iceland). Supported through funding from NACLIM (EU-FP7, grant 308299), RACE II, RACE-Synthese (German BMBF), Nordic WOCE, VEINS, MOEN, ASOF-W, NAClim, THOR, AtlantOS, and Blue Action

• FBC data: Funding for the in situ Faroe Bank Channel measurements is from the Environmental Research Programme of the Nordic Council of Ministers (NMR) 1993–1998, from national Nordic research councils, from the Danish DANCEA programme, and from the European Framework Programs, lately under grant agreement no. GA212643 (THOR) and under grant agreement no. 308299 (NACLIM).

• Arctic Gateway data: This work is funded by the European Union as part of the EPOC project (Explaining and Predicting the Ocean Conveyor; grant number: 101059547). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them.

• CALAFAT2025 data: This work has been carried out within the framework of the EPOC project funded by the European Union's Horizon Europe programme (grant agreement No 101059547), under call HORIZON-CL6-2021-CLIMATE01. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them.

• FW2015 data: Based on Frajka-Williams, E. (2015), "Estimating the Atlantic overturning at 26°N using satellite altimetry and cable measurements"

Dataset access and processing via AMOCatlas.

Contributing

All contributions are welcome! See CONTRIBUTING.md for more details.

PyGMT add-on

AMOCatlas includes support for creating publication-quality figures using PyGMT. The demo notebook notebooks/amoc_paperfigs.ipynb demonstrates how to generate figures similar to those in Frajka-Williams et al. (2019, 2023) papers, including filtered time series, component breakdowns, and multi-array comparisons.

Note: PyGMT can be challenging to install due to its dependency on GMT. See the PyGMT installation guide for platform-specific instructions. PyGMT is an optional dependency - all other AMOCatlas functionality works without it.

Example figures generated by the notebook:

Multi-array AMOC comparison:

Multi-array AMOC comparison (filtered):

Multi-array AMOC overlaid:

Historical AMOC (Bryden 2005):

For questions or support, please open an issue or check our documentation.