Metadata-Version: 2.4
Name: oceantaco
Version: 0.1.0
Summary: Reproducible native-coordinate ocean retrieval and sampling
Keywords: climate,assimilation,earth-observation,altimetry,dataset,ocean,machine-learning
Author: Nils Lehmann
Author-email: Nils Lehmann <n.lehmann@tum.de>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=1.26,<3
Requires-Dist: pandas>=2.2
Requires-Dist: torch>=2.2
Requires-Dist: tqdm>=4.66
Requires-Dist: xarray>=2025.11.0
Requires-Dist: pyarrow>=16
Requires-Dist: h5netcdf>=1.3
Requires-Dist: h5py>=3.11
Requires-Dist: cartopy>=0.23.0
Requires-Dist: matplotlib>=3.10
Requires-Dist: tacoreader>=2.4.20
Requires-Dist: scipy>=1.12
Requires-Dist: shapely>=2.0
Requires-Dist: omegaconf>=2.3
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: huggingface-hub>=0.24
Requires-Dist: zarr>=2.18 ; extra == 'benchmarks'
Requires-Dist: sphinx>=7.4 ; extra == 'docs'
Requires-Dist: sphinx-book-theme>=1.1 ; extra == 'docs'
Requires-Dist: myst-nb>=1.1 ; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5 ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2.0 ; extra == 'docs'
Requires-Dist: argopy ; extra == 'generate'
Requires-Dist: copernicusmarine>=2.2.1 ; extra == 'generate'
Requires-Dist: tacotoolbox>=0.26.1 ; extra == 'generate'
Requires-Dist: dask[array]>=2024.10 ; extra == 'materialize'
Requires-Dist: pytest>=8.0 ; extra == 'tests'
Requires-Dist: ruff>=0.9 ; extra == 'tests'
Requires-Dist: jupyterlab>=4.0 ; extra == 'tutorials'
Requires-Dist: nbclient>=0.10 ; extra == 'tutorials'
Requires-Dist: nbformat>=5.10 ; extra == 'tutorials'
Requires-Dist: matplotlib>=3.10 ; extra == 'viz'
Requires-Dist: cartopy>=0.23.0 ; extra == 'viz'
Maintainer: Nils Lehmann
Maintainer-email: Nils Lehmann <n.lehmann@tum.de>
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/nilsleh/oceanTACO
Project-URL: Documentation, https://oceantaco.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/nilsleh/oceanTACO
Project-URL: Issues, https://github.com/nilsleh/oceanTACO/issues
Provides-Extra: benchmarks
Provides-Extra: docs
Provides-Extra: generate
Provides-Extra: materialize
Provides-Extra: tests
Provides-Extra: tutorials
Provides-Extra: viz
Description-Content-Type: text/markdown

# OceanTACO

[![docs](https://app.readthedocs.org/projects/oceantaco/badge/?version=latest)](https://oceantaco.readthedocs.io/en/latest/)
[![pypi](https://badge.fury.io/py/oceantaco.svg)](https://pypi.org/project/oceantaco/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Language: Python](https://img.shields.io/badge/language-Python%203.12%2B-green?logo=python&logoColor=green)](https://www.python.org)


OceanTACO is a multi-source sea surface variable dataset for Earth-system analysis workflows and also provides dataloaders for machine learning workflows.

Documentation page: https://oceantaco.readthedocs.io/en/latest/

Current dataset coverage includes:

- Sea surface height (SSH): L4, L3, SWOT L3
- Sea surface temperature (SST): L4, L3, GLORYS
- Sea surface salinity (SSS): L4, L3 SMOS
- Argo float profile observations (point-source)
- Additional co-located sources including wind and GLORYS currents

The Core dataset spans 2023-03-29 until 2025-08-02 and includes the SWOT data. It is available on [Hugging Face](https://huggingface.co/datasets/nilsleh/OceanTACO). The extended dataset spans 2015-01-01 until 2023-03-29 but precedes the SWOT era and is available on [Hugging Face](https://huggingface.co/datasets/nilsleh/oceanTACO_extended); see [Extended dataset](https://oceantaco.readthedocs.io/en/latest/dataset_description.html#extended-dataset) for how to download and use it.

### SWOT mission phases (read this before comparing SWOT across dates)

The Core dataset spans two different SWOT orbits, and `l3_swot` behaves very
differently in each. Both regimes are routinely mistaken for broken or duplicated
data, so check which phase your dates fall in before filing a bug.

| Phase | Dates | Repeat cycle | What a fixed bounding box looks like |
|---|---|---|---|
| Calibration ("fast-sampling") | `2023-03-29` – `2023-07-10` | 1 day | The swath sits in the **same place every day**, so a daily animation or mosaic looks *identical* |
| Orbit change | `2023-07-11` – `2023-07-25` | — | **No `l3_swot.nc` is published** on these dates |
| Science | `2023-07-26` – `2025-08-02` | 21 days | The swath **moves every day**, so a small box is **empty (all-NaN) on most days** |

Two consequences worth stating explicitly:

- **During calibration, an unchanging picture does not mean unchanging data.** The
  swath *footprint* repeats, but the values inside it do not: consecutive days
  differ by roughly 0.02–0.05 m on average over a 10°x10° box, with coherent
  mesoscale structure. Difference the days to see it.
- **During science, most days over a small box are legitimately empty.** Revisits
  land at lags of 0, 11 and 21/22 days (the 21-day cycle plus its ascending /
  descending sub-cycle). All-NaN days are pixel-identical to one another, which is
  a second, unrelated way a mosaic can appear "the same".

SWOT is gridded at ~2 km with `processing = bin_mean_no_smoothing`: there is **no
gap-filling**, so `NaN` always means "not observed here on this day", never zero.

Beyond the orbit-change window, 33 dates in total publish no `l3_swot.nc` in any
region (SWOT-wide outages): `2023-05-20/21`, `2023-07-11`–`2023-07-25`,
`2023-09-22`–`2023-09-26`, `2023-12-23`–`2023-12-27`, `2024-05-11/12`,
`2024-10-28`, `2025-01-11/12`, `2025-04-26/27`. Other modalities are unaffected on
those dates.

<img src="https://raw.githubusercontent.com/nilsleh/oceanTACO/main/docs/images/swot_revisit_coverage.png" alt="SWOT coverage over a fixed box across both mission phases" width="900" />

See [Dataset Description](https://oceantaco.readthedocs.io/en/latest/dataset_description.html)
for the per-phase figures. To regenerate them:

```sh
python scripts/dev/swot_phase_figures.py --out docs/images
```

<img src="https://raw.githubusercontent.com/nilsleh/oceanTACO/main/docs/images/oceantaco.svg" alt="OceanTACO Figure" width="760" />

Generated directly from OceanTACO sources (GLORYS SST, SSH L4, SSH SWOT, SST L4, SSS L4, Argo).

## Documentation and Notebooks

If you are new to OceanTACO, start with the hosted documentation and tutorials:

- Documentation home: https://oceantaco.readthedocs.io/en/latest/
- Getting started guide: https://oceantaco.readthedocs.io/en/latest/getting_started.html
- Retrieval and QuerySet selection: https://oceantaco.readthedocs.io/en/latest/tutorials/data_retrieval_workflows.html
- ML loader entry point: https://oceantaco.readthedocs.io/en/latest/tutorials/ml_dataset.html
- Tutorial notebooks index: https://oceantaco.readthedocs.io/en/latest/tutorials/index.html
- API reference: https://oceantaco.readthedocs.io/en/latest/api/index.html

OceanTACO includes several tutorial notebooks in the docs, with rendered outputs and downloadable `.ipynb` files, so you can get started quickly before writing your own workflows.

## Installation

Most users should install directly from PyPI:

```sh
pip install oceantaco
```

If you want the latest development version from GitHub:

```sh
pip install "oceantaco @ git+https://github.com/nilsleh/oceanTACO.git@main"
```

If you have cloned this repository and want a local editable install, run the following from the repository root:

```sh
# Dataset loading + queries + visualization (default profile)
pip install -e .

# Add dataset-generation dependencies (download/format/build pipeline)
pip install -e ".[generate]"

# Full development profile
pip install -e ".[generate,tests]"
```

## Repository Structure

Everything under `ocean_taco/` is installed, and nothing else is:

- `ocean_taco/retrieve.py`: native-coordinate catalog retrieval.
- `ocean_taco/catalog.py`, `ocean_taco/geobox.py`, `ocean_taco/temporal.py`: catalog configuration and the spatial/temporal primitives.
- `ocean_taco/queryset.py`, `ocean_taco/filter.py`, `ocean_taco/sampling/`: `QuerySet` construction, filtering, and reproducible draws.
- `ocean_taco/render/`: renderers that turn a query into arrays, such as `Resample`.
- `ocean_taco/torch/`: the shipped `OceanTACODataset`, collators, and Core loader.
- `ocean_taco/access/`: source adapters for the underlying assets.
- `ocean_taco/figures/`: the Hurricane Milton figure modules the tutorial notebooks import, and the QuerySet diagnostic maps.

Repository-only, not part of the installed package:

- `tools/ocean_taco_generate/`: data acquisition and dataset build pipeline. See the [dataset generation guide](https://oceantaco.readthedocs.io/en/latest/dataset_generation.html).
- `tools/ocean_taco_benchmarks/`: the ClimateBenchPress comparison pipeline.
- `tools/ocean_taco_figures_wip/`: paper-figure code that no longer runs against the current API, kept for possible revival.
- `scripts/`: QuerySet production pipeline and release checks.
- `docs/tutorials/`: the tutorial notebooks, also rendered in the hosted docs.

ML sampling starts with a published `QuerySet`, then records an exact draw:

```python
from ocean_taco import CatalogConfig, QuerySet, draw_queryset
from ocean_taco.render import Resample
from ocean_taco.torch import OceanTACODataset

queryset = QuerySet.from_hub(256, "eval")
draw = draw_queryset(queryset, requested_row_count=32, seed=7, record_path="run.json")
dataset = OceanTACODataset(
    queries=draw,
    sources={"l4_sst": Resample((64, 64), support_threshold=0.5)},
    catalog_config=CatalogConfig(),
)
sample = dataset[0]
```

## Patch Size from Resolution

Use this rule of thumb when choosing patch extents:

- `patch_deg ≈ pixels * resolution_deg`
- Example: for ~`0.1°` data and `64 x 64` patches, choose about `6.4°` patch size.

`PatchSize(unit="km")` is also supported; conversion to degrees is latitude-dependent for longitude.

## Hugging Face Dataset Access

OceanTACO is available at:

- https://huggingface.co/datasets/nilsleh/OceanTACO

### Stream OceanTACO

TACO is cloud-native. Therefore, the dataset can be accessed remotely without downloading it to local disk, both for data analysis and machine learning workflows.

Streaming is the default: a bare `CatalogConfig()` reads the published catalog on
Hugging Face and fetches only the granules a query touches, caching them under
`HF_HOME`. Nothing needs to be downloaded up front.

```python
from ocean_taco import CatalogConfig, GeoBox
from ocean_taco.retrieve import load_bbox_nc, load_hf_dataset

config = CatalogConfig()            # remote by default
catalog = load_hf_dataset(config)

sst = load_bbox_nc(
    catalog,
    "2024-06-01",
    GeoBox(-80.0, -30.0, 25.0, 50.0),
    "l4_sst",
    config=config,
)
```

The same applies to the ML path: pass `catalog_config=CatalogConfig()` to
`OceanTACODataset`, as in the quickstart above, and batches stream from the Hub.
To read a local copy instead, point at the `OceanTACO` directory itself with
`CatalogConfig(taco_path="/path/to/OceanTACO")`.


### Download snapshot locally (huggingface_hub)

```python
from huggingface_hub import snapshot_download

local_dir = snapshot_download(repo_id="nilsleh/OceanTACO", repo_type="dataset")
print(local_dir)
```

## More Detailed Guide

For full examples (query save/load, train/eval dataloaders, patch-size recipes, and troubleshooting), see:

- [Tutorial notebooks](https://oceantaco.readthedocs.io/en/latest/tutorials/index.html)
- [API reference](https://oceantaco.readthedocs.io/en/latest/api/index.html)

## CODE LICENSE

The Code is licensed under Apache - 2.0.

## DATASET LICENSE

OceanTACO is released under Creative Commons Attribution 4.0 International (CC BY 4.0). However, please see the [OceanTACO Dataset Card](https://huggingface.co/datasets/nilsleh/OceanTACO) for full license information, and required attribution, acknowledgements and citations.

## Citation

OceanTACO has been accepted for publication in Earth System Science Data. Until the final version
appears, please cite the preprint:

```bibtex
@article{lehmann2026oceantaco,
  author  = {Lehmann, Nils and Aybar, Cesar and Shah, Ando and Passaro, Marcello and Bamber, Jonathan L. and Zhu, Xiao Xiang},
  title   = {{OceanTACO}: A Multi-Sensor Global Ocean Sea Surface State Dataset},
  journal = {Earth System Science Data Discussions},
  year    = {2026},
  doi     = {10.5194/essd-2026-232},
  url     = {https://essd.copernicus.org/preprints/essd-2026-232/},
  note    = {Accepted for publication in Earth System Science Data}
}
```

Preprint: https://essd.copernicus.org/preprints/essd-2026-232/
