AMOCatlas

Clean, 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

Supported Arrays

Array	Location	Description
RAPID	26°N	Continuous monitoring since 2004
MOCHA	26°N	Heat transport since 2004
MOVE	16°N	Meridional heat transport
OSNAP	Subpolar North Atlantic	Overturning circulation
SAMBA	34.5°S	South Atlantic MOC
41°N	41°N	North Atlantic section
DSO	Denmark Strait	Overflow monitoring
FW2015	26°N	Frajka-Williams 2015 satellite-cable dataset

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 readers

# Load RAPID sample dataset
ds = readers.load_sample_dataset("rapid")
print(ds)

Load Full Datasets

from amocatlas import readers

# Load complete dataset (downloads and caches data)
datasets = readers.load_dataset("osnap")
for ds in datasets:
    print(ds)

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

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

Documentation

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

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

Project Structure

amocatlas/
│
├── readers.py               # Orchestrator for loading datasets
├── read_move.py             # MOVE reader
├── read_rapid.py            # RAPID reader
├── read_osnap.py            # OSNAP reader
├── read_samba.py            # SAMBA reader
├── read_mocha.py            # MOCHA reader
├── read_41n.py              # 41°N reader
├── read_dso.py              # DSO reader
├── read_fw2015.py           # Frajka-Williams 2015 reader
│
├── utilities.py             # Shared utilities (downloads, parsing, etc.)
├── logger.py                # Structured logging setup
├── plotters.py              # Visualization functions
├── tools.py                 # Analysis and calculation functions
├── standardise.py           # Common formatting and metadata
├── writers.py               # Data export functionality
│
└── tests/                   # 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.

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.

Roadmap

• Add test coverage for utilities and readers
• Add dataset summary output at end of load_dataset()
• Optional global logging helpers (disable_logging(), enable_logging())
• Extend load_sample_dataset() to support all arrays
• Metadata enrichment (source paths, processing dates)
• Clarify separation between added metadata and original metadata

Acknowledgements

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

• RAPID data: The RAPID-MOC monitoring project is funded by the Natural Environment Research Council (UK). Data is freely available from www.rapid.ac.uk

• MOVE data: The MOVE project is funded by the NOAA Climate Program Office under award NA15OAR4320071. Initial funding came from the German Bundesministerium für Bildung und Forschung. Data collection is carried out by Uwe Send and Matthias Lankhorst at Scripps Institution of Oceanography

• 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). Multiple contributing institutions from US, UK, Germany, Netherlands, Canada, France, and China

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

• MOCHA data: Data from the RAPID-MOCHA program are funded by the U.S. National Science Foundation and U.K. Natural Environment Research Council

• 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

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