[CLEANUP] Repo hygiene: pyproject-only dependencies, no environment.yml, coverage floor

.github/CONTRIBUTING.md

@@ -12,10 +12,9 @@ Please follow these steps to get started:
 2. **Create a new branch** for your work.
 3. **Set up the development environment:**
    - Create a virtual environment
-   - Install dependencies:
+   - Install the package with its development extras:
      ```bash
-     pip install -r requirements.txt
-     pip install -r requirements-dev.txt
+     pip install -e ".[dev]"
      ```
 4. **Make your changes** — remember to write clear commits!
 5. **Run tests and quality checks:**

.github/workflows/docs.yml

@@ -20,25 +20,19 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v3
+      - uses: actions/setup-python@v7
         with:
-          environment-file: environment.yml
-          init-shell: bash
-          condarc: |
-            channels:
-              - conda-forge
-            channel_priority: strict
-          cache-environment: true
+          python-version: "3.12"
 
-      - name: Install package (editable)
-        shell: bash -l {0}
+      - name: Install pandoc
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Install package with docs extras
         run: |
-          micromamba run -n amocatlas python -m pip install --upgrade pip
-          micromamba run -n amocatlas python -m pip install -e . --no-deps --force-reinstall
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
 
       - name: Build documentation
-        shell: bash -l {0}
         run: |
           set -e
           # Copy notebooks without executing. They read live data from remote array
@@ -47,5 +41,5 @@ jobs:
           cp notebooks/demo.ipynb docs/source/demo-output.ipynb
           cp notebooks/amoc_paperfigs.ipynb docs/source/amoc_paperfigs-output.ipynb
           pushd docs
-          micromamba run -n amocatlas make clean html
+          make clean html
           popd

.github/workflows/docs_deploy.yml

@@ -19,25 +19,19 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v3
+      - uses: actions/setup-python@v7
         with:
-          environment-file: environment.yml
-          init-shell: bash
-          condarc: |
-            channels:
-              - conda-forge
-            channel_priority: strict
-          cache-environment: true
-
-      - name: Install package (editable)
-        shell: bash -l {0}
+          python-version: "3.12"
+
+      - name: Install pandoc
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Install package with docs extras
         run: |
-          micromamba run -n amocatlas python -m pip install --upgrade pip
-          micromamba run -n amocatlas python -m pip install -e . --no-deps --force-reinstall
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
 
       - name: Build documentation
-        shell: bash -l {0}
         run: |
           set -e
           # Copy notebooks without executing. They read live data from remote array
@@ -46,7 +40,7 @@ jobs:
           cp notebooks/demo.ipynb docs/source/demo-output.ipynb
           cp notebooks/amoc_paperfigs.ipynb docs/source/amoc_paperfigs-output.ipynb
           pushd docs
-          micromamba run -n amocatlas make clean html
+          make clean html
           popd
 
       - name: Deploy to GitHub Pages

.github/workflows/tests.yml

@@ -6,19 +6,34 @@ on:
       - main
     paths:
       - '**.py'
-      - 'requirements*.txt'
       - 'pyproject.toml'
-      - 'setup.cfg'
-      - '.github/workflows/tests.yml'
+      - '.github/workflows/**'
 
 jobs:
   job_mytests:
     runs-on: ${{ matrix.os }}
+    # 3.13 runs as an experimental cell (see the matrix): continue-on-error so a
+    # 3.13-only breakage fails softly rather than failing the whole check. 3.13 CI
+    # is green as of this PR; drop the experimental flag to make it a required cell.
+    continue-on-error: ${{ matrix.experimental == true }}
     strategy:
+      # Do not cancel the other cells when one fails — a red 3.13 (or a platform
+      # cell) should not hide results from the rest of the matrix.
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.12"]
-      fail-fast: true
+        # Ubuntu covers the full Python range; macOS and Windows run one version
+        # only (they catch platform issues, not version issues). Coverage is gated
+        # on the ubuntu-latest / 3.12 cell.
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.13"
+            experimental: true
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
 
     defaults:
       run:
@@ -33,28 +48,16 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
+      - name: Install amocatlas with test extras
         run: |
           python -m pip install --upgrade pip
-          if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
-
-      - name: Install amocatlas package
-        run: |
-          python -m pip install -e . --no-deps --force-reinstall
+          python -m pip install -e ".[test]"
 
       - name: Test with pytest
+        # Coverage is measured on a single matrix cell (ubuntu / 3.12) so the
+        # --cov-fail-under floor is compared against one platform's number, not
+        # a mix; every other cell runs --no-cov. Raise the floor as coverage
+        # grows; never lower it.
         run: |
-          pytest -m "not slow"
-
-      # Optional future: use Micromamba after publishing to Conda-forge
-      # - name: Setup Micromamba Python ${{ matrix.python-version }}
-      #   uses: mamba-org/setup-micromamba@v2
-      #   with:
-      #     environment-name: TEST
-      #     init-shell: bash
-      #     create-args: >-
-      #       python=${{ matrix.python-version }} --file requirements-dev.txt --channel conda-forge
-      #
-      # - name: Full Tests
-      #   run: |
-      #     python -m pytest --cov=amocatlas --cov-report term-missing tests/
+          pytest -m "not slow" \
+          ${{ (matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12') && '--cov=amocatlas --cov-report=term-missing --cov-fail-under=55' || '--no-cov' }}

.mailmap

@@ -0,0 +1,4 @@
+# Canonicalise contributor identities so `git shortlog`/`git log` counts are correct.
+# Format: Proper Name <canonical-email> Commit Name <commit-email>
+Isabelle Schmitz <isabelle.sh@gmx.de> Isabelle1299 <isabelle.sh@gmx.de>
+Isabelle Schmitz <isabelle.sh@gmx.de> Isabelle <isabelle.sh@gmx.de>

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- New reader for the OVIDE section (`read.ovide()`) (#183)
+- New reader for the SCOTIA overturning array (`read.scotia()`) — the first array served in neutral-density (GAMMA) space (#184)
+- `amocvocab`, a controlled variable vocabulary under `amocatlas/vocabulary/` (short name → `standard_name`-or-null → units → P02/P01 URI → definition), with a JSON schema and a validator (`validate_amocvocab.py`) that checks every CF `standard_name` against the live CF standard-name table and every unit under UDUNITS; a repo-tracked staging draft (`amocvocab_draft.yml`) is included but not shipped in the wheel (#181)
+- New optional metadata field `report_plot_variable` to select the headline variable a per-array report plots (#184)
+
+### Changed
+- README rewritten for a first-time scientific reader (#179)
+- Standardised output now follows the `amocvocab` + OceanSITES convention (see Breaking changes) (#181)
+- Per-array reports regenerated with corrected variable names, and the two report generators consolidated into `scripts/generate_reports.py` (#182)
+- Linting is now ruff-only: `ruff format` replaces black, and the pre-commit/codespell configuration was removed (#182)
+- Documentation autodoc deduplicated (`amocatlas.rst` reduced to an index; docs build warnings cut from ~140 to 4); the legacy `readers` string API was dropped from the API docs, though the code remains (still deprecated) (#182)
+- Dependencies are declared in `pyproject.toml` (`[project] dependencies`, extras `test`/`docs`/`dev`); `requirements.txt`, `requirements-dev.txt` and `environment.yml` removed; install with `pip install -e ".[dev]"`. Docs CI no longer uses conda. A coverage floor of 55% is enforced in CI
+
+### Fixed
+- Every CF `standard_name` used in array metadata verified against the live CF standard-name table; three fabricated names removed; the transport unit canonicalised to lowercase `sverdrup` (#180)
+- Zenodo concept DOI added to the CITATION file and as a README badge (#178)
+
+### Removed
+- `writers.save_AC1_dataset()` and its tests, and the AC1 format reference pages (`docs/source/reference/AC1_*.rst`) (#182)
+
+### Breaking changes
+
+- **#182 — AC1 writer and format docs removed.** `writers.save_AC1_dataset()` no longer exists; the only public writer is `writers.save_dataset(ds, output_file)`. Code that imported or called `save_AC1_dataset` must switch to `save_dataset`. The AC1 format reference pages were deleted.
+- **#181 — standardised output moved to the `amocvocab` + OceanSITES convention.** A script written against 0.4.0 output must update on two fronts:
+  - **Variable names.** OSNAP streamfunctions `STREAMFUNCTION_SIGMA0` / `STREAMFUNCTION_SIGMA0_WEST` / `STREAMFUNCTION_SIGMA0_EAST` are now `PSI_SIGMA0` / `PSI_SIGMA0_WEST` / `PSI_SIGMA0_EAST`; streamfunctions generally standardise to `PSI_Z` / `PSI_SIGMA0` / `PSI_SIGMA2`. SAMBA is reworked to anomalies: `UPPER_TRANSPORT` / `ABYSSAL_TRANSPORT` became `TRANS_UPPER` / `TRANS_ABYSSAL`, and the MOC decomposition is now `MOC_ANOM`, `TRANS_RELATIVE`, `TRANS_REFERENCE`, `TRANS_EKMAN` (with `_WEST` / `_EAST` constituents).
+  - **Attributes.** `long_name` values were rewritten to descriptive lowercase and the original provider label is preserved under a new `source_long_name` attribute; `cell_methods` was added where a variable is a max/mean over a coordinate; and `standard_name` was dropped from derived or anomaly quantities that have no exact CF name (vocabulary "Case C"). A 0.4.0 script that keys on an old variable name, on `source_long_name` being absent, or on every variable carrying a `standard_name`, must be updated.
+
 ## [0.4.0] - 2026-08-13
 
 ### Added

CONTRIBUTING.md

@@ -190,7 +190,8 @@ Our [documentation](https://amoccommunity.github.io/AMOCatlas/) is built from th
 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 amocatlas, navigate to the top directory of this repo, then run `pip install -r requirements-dev.txt`
+- Install `pandoc` (nbsphinx renders the notebooks through it), e.g. on ubuntu with `sudo apt install pandoc`, or from conda-forge
+- Install the documentation extras. Activate the environment you use for amocatlas, navigate to the top directory of this repo, then run `pip install -e ".[docs]"`
 
 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. After making more changes, just run make clean html again to rebuild the docs.
 

README.md

@@ -93,8 +93,7 @@ pip install AMOCatlas
 ```bash
 git clone https://github.com/AMOCcommunity/amocatlas.git
 cd amocatlas
-pip install -r requirements-dev.txt
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 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.
@@ -106,34 +105,35 @@ The `read` namespace returns a single standardised `xarray` dataset per array, d
 ```python
 from amocatlas import read
 
-ds = read.rapid()              # RAPID transport at 26°N
+ds = read.rapid()  # RAPID transport at 26°N
 print(ds)
 
-osnap = read.osnap()           # OSNAP; uses the latest version by default
+osnap = read.osnap()  # OSNAP; uses the latest version by default
 ```
 
 Common options:
 
 ```python
-read.osnap(version="2025")     # select a version where multiple exist
-read.rapid(all_files=True)     # list of all files for an array, not just the standard one
-read.rapid(raw=True)           # original upstream format, without standardisation
+read.osnap(version="2025")  # select a version where multiple exist
+read.rapid(all_files=True)  # list of all files for an array, not just the standard one
+read.rapid(raw=True)  # original upstream format, without standardisation
 ```
 
 The legacy string-based API and small bundled samples remain available:
 
 ```python
 from amocatlas import readers
 
-ds = readers.load_sample_dataset("rapid")   # small bundled sample, no download
-datasets = readers.load_dataset("rapid")    # returns a list of datasets
+ds = readers.load_sample_dataset("rapid")  # small bundled sample, no download
+datasets = readers.load_dataset("rapid")  # returns a list of datasets
 ```
 
 **Data location and logs.** Downloads are cached in `~/.amocatlas_data/` and a per-run `*.log` is written to `logs/`. Override the cache per call with `data_dir="/path/to/data"`, or set a default:
 
 ```python
 import amocatlas
-amocatlas.set_data_dir("~/my_data")    # custom location
+
+amocatlas.set_data_dir("~/my_data")  # custom location
 print(amocatlas.get_data_dir())
 ```
 
@@ -249,7 +249,8 @@ You can run the example jupyter notebook by launching jupyterlab with `jupyter-l
 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`
+- Install `pandoc` (nbsphinx renders the notebooks through it), e.g. on ubuntu with `sudo apt install pandoc`, or from conda-forge
+- Install the documentation extras. Activate the environment you use for working with amocatlas, navigate to the top directory of this repo, then run `pip install -e ".[docs]"`
 
 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.
 

amocatlas/data_sources/wh41n.py

@@ -227,19 +227,21 @@ def read_41n(
             # Time handling
             try:
                 df = df.apply(
-                    lambda col: col.astype(str)
-                    .str.replace(",", "", regex=False)
-                    .astype(float)
+                    lambda col: (
+                        col.astype(str).str.replace(",", "", regex=False).astype(float)
+                    )
                 )
                 # df['Decimal year'] = df['Decimal year'].astype(str).str.replace(',', '',regex=False).astype(float)
                 df["TIME"] = df["Decimal year"].apply(
-                    lambda x: datetime.datetime(int(x), 1, 1)
-                    + datetime.timedelta(
-                        days=(x - int(x))
-                        * (
-                            datetime.datetime(int(x) + 1, 1, 1)
-                            - datetime.datetime(int(x), 1, 1)
-                        ).days
+                    lambda x: (
+                        datetime.datetime(int(x), 1, 1)
+                        + datetime.timedelta(
+                            days=(x - int(x))
+                            * (
+                                datetime.datetime(int(x) + 1, 1, 1)
+                                - datetime.datetime(int(x), 1, 1)
+                            ).days
+                        )
                     )
                 )
                 df = df.drop(columns=["Decimal year"])

docs/source/about.rst

@@ -74,10 +74,9 @@ To install a local, development version for contributing, clone the repository a
 
     git clone https://github.com/AMOCcommunity/amocatlas.git
     cd amocatlas
-    pip install -r requirements-dev.txt
-    pip install -e .
+    pip install -e ".[dev]"
 
-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``. The ``requirements-dev.txt`` includes additional Python packages needed for development, including building documentation, running tests, and code linting.
+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``. The ``[dev]`` extra pulls in the additional Python packages needed for development, including building documentation, running tests, and code linting.
 
 You can run the example Jupyter notebook by launching JupyterLab with ``jupyter-lab`` and navigating to the ``notebooks`` directory, or in VS Code or other Python GUI.
 

docs/source/archive/developer_guide_original.md

@@ -338,6 +338,7 @@ You can toggle logging dynamically:
 
 ```python
 from amocatlas import logger
+
 logger.enable_logging()
 logger.disable_logging()
 ```

docs/source/developers/actions.md

@@ -15,7 +15,7 @@ The basic behaviour is explained in the template repository that this project wa
 
 The way that this project ([http://github.com/AMOCcommunity/amocatlas](http://github.com/AMOCcommunity/amocatlas)) is set up:
 
-- the `docs.yml` attempts to build the documentation which is contained in `docs/source/` and built to `docs/build/`.  It sets up the environment based on `requirements-dev.txt`, installs the project with `pip install`, and builds the documentation including running the `notebooks/demo.ipynb`.
+- the `docs.yml` attempts to build the documentation which is contained in `docs/source/` and built to `docs/build/`.  It installs the project with its `docs` extra (`pip install -e ".[docs]"`, plus the `pandoc` binary), and builds the documentation including copying in the `notebooks/demo.ipynb`.
 
 - the `tests.yml` uses `pytest` to run the tests contained within the `tests/` directory, and it does this on several platforms (windows, mac and linux) and with a couple versions of python.
 
@@ -36,16 +36,16 @@ Before making a PR, you can try to run `demo.ipynb` on your fork/branch to see w
 
 ### Check tests
 
-You can run the tests locally if your environment is built from `requirements-dev.txt`.  Here we've also required e.g., `pytest`.
+You can run the tests locally if your environment has the `test` extra installed (which includes `pytest`).
 
-To run the tests, in the command line on your computer, activate the environment, make sure requirements from `requirements-dev.txt` are installed, and then run `pytest`.
+To run the tests, in the command line on your computer, activate the environment, make sure the `test` (or `dev`) extra is installed, and then run `pytest`.
 
 For me, this looks like
 ```bash
 cd github/amocatlas
 virtualenv venv
 source venv/bin/activate
-pip install -r requirements-dev.txt
+pip install -e ".[dev]"
 pytest
 ```