Metadata-Version: 2.4
Name: AMOCatlas
Version: 0.2.0
Summary: Python project to read data from arrays measuring the Atlantic meridional overturning circulation
Maintainer-email: Eleanor Frajka-Williams <eleanorfrajka@gmail.com>
License: MIT License
        
        Copyright (c) 2024-2025 Eleanor Frajka-Williams, Isabelle Schmitz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: documentation, https://github.com/AMOCcommunity/AMOCatlas
Project-URL: homepage, https://github.com/AMOCcommunity/AMOCatlas
Project-URL: repository, https://github.com/AMOCcommunity/AMOCatlas
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=2.0
Requires-Dist: xarray>=2023.12.0
Requires-Dist: netcdf4>=1.6
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Dynamic: license-file

# AMOCatlas


[![PyPI version](https://badge.fury.io/py/AMOCatlas.svg)](https://badge.fury.io/py/AMOCatlas)
[![Python](https://img.shields.io/pypi/pyversions/AMOCatlas.svg)](https://pypi.org/project/AMOCatlas/)
[![License](https://img.shields.io/github/license/AMOCcommunity/amocatlas.svg)](LICENSE)

**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](#features)
- [Supported Arrays](#supported-arrays)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Development](#development)
- [Funding & Support](#funding--support)
- [Acknowledgements](#acknowledgements)
- [Contributing](#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 |
| **CALAFAT2025** | Atlantic | Bayesian estimates of Atlantic meridional heat transport |
| **ZHENG2024** | Atlantic | Observation-based Atlantic meridional freshwater transport |

## Installation

### From PyPI (Recommended)
```bash
pip install AMOCatlas
```

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

### For Development
```bash
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
```python
from amocatlas import readers

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

### Load Full Datasets
```python
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](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
├── read_calafat2025.py      # Calafat 2025 heat transport reader
├── read_zheng2024.py        # Zheng 2024 freshwater transport 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:
```bash
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
```bash
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

<div align="center">
  <img src="docs/source/_static/epoc-logo.jpg" alt="EPOC Logo" width="300"/>
</div>

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()
- [x] Optional global logging helpers (disable_logging(), enable_logging())
- [ ] Extend load_sample_dataset() to support all arrays
- [x] 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](https://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](https://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](https://github.com/AMOCcommunity/amocatlas).

## Contributing

All contributions are welcome! See [CONTRIBUTING.md](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](https://www.pygmt.org/latest/install.html) 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:**
<img src="docs/source/_static/paperfigs/amoc_multi_array.png" alt="Atlantic Meridional Overturning Circulation time series from four major observing arrays: OSNAP at subpolar latitudes (green), RAPID at 26°N (red), MOVE at 16°N (magenta), and SAMBA at 34.5°S (blue anomaly). Data spans 2000-2025 showing AMOC transport in Sverdrups and variability across different latitudes." width="600"/>

**Multi-array AMOC comparison (filtered):**
<img src="docs/source/_static/paperfigs/amoc_multi_array_filtered.png" alt="Low-pass filtered Atlantic Meridional Overturning Circulation time series using Tukey window filtering to highlight long-term trends. Shows OSNAP, RAPID, MOVE, and SAMBA MOC transport data with reduced high-frequency variability, revealing decadal-scale changes in ocean circulation strength from 2000-2025." width="600"/>

**Multi-array AMOC overlaid:**
<img src="docs/source/_static/paperfigs/amoc_multi_array_overlaid.png" alt="Overlaid Atlantic Meridional Overturning Circulation time series from multiple observing arrays plotted on the same coordinate system. OSNAP (green), RAPID 26°N (red), and MOVE 16°N (magenta) show MOC transport in Sverdrups, while SAMBA 34.5°S (blue) displays anomaly values, enabling direct comparison of AMOC variability across Atlantic latitudes." width="600"/>

**Historical AMOC (Bryden 2005):**
<img src="docs/source/_static/paperfigs/bryden2005_amoc.png" alt="Historical Atlantic Meridional Overturning Circulation estimates from Bryden et al. 2005 showing AMOC decline from 1957 to 2004. Red line and diamond markers indicate MOC transport measurements at 26°N, demonstrating significant weakening of Atlantic overturning circulation over five decades from 23 to 15 Sverdrups." width="400"/>

---

*For questions or support, please open an [issue](https://github.com/AMOCcommunity/amocatlas/issues) or check our [documentation](https://amoccommunity.github.io/amocatlas/).*
