OceanTACO

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. The extended dataset spans 2015-01-01 until 2023-03-29 but precedes the SWOT era and is available on Hugging Face; see 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.

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.

See Dataset Description for the per-phase figures. To regenerate them:

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

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:

pip install oceantaco

If you want the latest development version from GitHub:

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:

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

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.

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)

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
• API reference

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 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:

@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/