MARIS-Forecast

A multi-region AIS dataset with temporally aligned maritime context
for vessel trajectory forecasting

This repository holds the code and documentation that accompany the Scientific Data Data Descriptor for MARIS-Forecast, a forecasting-ready Automatic Identification System (AIS) trajectory dataset built from four public maritime sources — Denmark (DMA), the United States (NOAA/MarineCadastre), Greece (Piraeus / Saronic Gulf) and Norway (Kystverket). A single shared pipeline processes all four regions identically and pairs every trajectory window with aligned environmental, social and meteorological context.

The data itself is archived on Zenodo (frozen, DOI-citable) and mirrored on the Hugging Face Hub. This repository provides the loaders, metrics, quality-control / construction scripts and the figure-regeneration code — everything needed to use the dataset and to reproduce the paper's figures and technical-validation numbers.

---

Contents

Path	What it is
maris_forecast/	Installable Python package: dataset loader, ADE/FDE/minADE metrics, on-disk schema, unified ship-class taxonomy.
examples/	Runnable quickstart.py: load a leaf, run a dead-reckoning baseline, inspect aligned context.
figures/	Scripts that regenerate the paper's data-driven figures (composition, geographic coverage, cross-domain transfer, environmental & social context) from the released data.
pipeline/	Reference construction & quality-control scripts (Stage-17 OSM-temporal-consistency, historical-OSM rebuild, unified taxonomy, meteo features, artefact verification).
docs/	Per-sample schema, data card, changelog.

---

Dataset access

The dataset is not stored in this repository. Download it from either mirror:

Zenodo (recommended, frozen & DOI-citable) — https://doi.org/10.5281/zenodo.21224009 Nine MD5-checksummed tar archives, 49.1 GB total:

Archive	Size	Contents
docs_scripts_checkpoints.tar	60 MB	docs, scripts, baseline checkpoints
track_a_dma_track_v1.tar	12.8 GB	Track A · Denmark
track_a_noaa_track_v1.tar	4.6 GB	Track A · United States
track_a_piraeus_track_v1.tar	13.3 GB	Track A · Greece
track_a_norway_track_v1.tar	8.8 GB	Track A · Norway
track_b_dma.tar	4.8 GB	Track B · Denmark
track_b_noaa.tar	4.0 GB	Track B · United States
track_b_piraeus.tar	257 MB	Track B · Greece
track_b_norway.tar	506 MB	Track B · Norway

Hugging Face (browsable directory tree) — https://huggingface.co/datasets/mark000071/envship_v2_datasets

# Hugging Face (partial download of a single leaf is possible):
huggingface-cli download mark000071/envship_v2_datasets --repo-type dataset --local-dir ./maris

# Zenodo (whole archives, then extract):
#   download the .tar files from the record, then:  tar xf track_a_dma_track_v1.tar -C ./maris

After extraction the release has two track roots:

track_a_short-term_Cross-domain_Datasets/{dma,noaa,piraeus,norway}_track_v1/
track_b_medium-term_Cross-domain_Datasets/{dma,noaa,piraeus,norway}/standard_track_v1/

Each leaf contains official train/ val/ test/ splits (part-000.csv.gz), a context_v1/ package (environmental rasters, signed-distance fields, vector shorelines, scene descriptors, social records), osm_temporal_consistency/ side-cars, sample_ids/, reports/, a README.md and a summary.json. Piraeus additionally ships a context_v1_2019osm/ historical-OSM package. See docs/SCHEMA.md for the full per-sample schema.

---

Installation

git clone https://github.com/mark000071/MARIS-Forecast.git
cd MARIS-Forecast
pip install -e .            # installs the maris_forecast package (numpy, pandas)

Optional extras: pip install -e ".[figures]" adds matplotlib and scipy for the figure scripts.

---

Quickstart

from maris_forecast import loader, metrics
import numpy as np

# point `root` at your downloaded release
leaf = loader.leaf_dir("/data/maris", track="A", region="dma")

# recommended default view = OSM-temporally consistent samples only
df = loader.load_split(leaf, "test", consistent_only=True)
hist, fut = loader.stack_trajectories(df)          # (N,30,2), (N,30,2), metres

# constant-velocity dead-reckoning baseline
v = hist[:, -1] - hist[:, -2]
pred = hist[:, -1:] + np.arange(1, 31)[None, :, None] * v[:, None]
print("ADE", metrics.ade(pred, fut), "FDE", metrics.fde(pred, fut))

# aligned context tensors, reordered to match `df`
env = loader.load_environment(leaf, "test", align_to=df)   # masks (N,6,128,128), SDFs (N,128,128)
soc = loader.load_social(leaf, "test")                     # CPA/TCPA neighbour records

Or run the bundled example end-to-end:

python examples/quickstart.py --root /data/maris --track A --region dma

The loader reads the four Stage-17 flags inline (the release layout) or, if they are stored separately, from the osm_temporal_consistency/ side-car — so consistent_only=True works on both the released and freshly-built layouts.

---

Reproducing the paper figures

The scripts in figures/ regenerate the data-driven figures of the Data Descriptor directly from the released data (Arial-metric Arimo typography bundled under figures/fonts/):

pip install -e ".[figures]"
# edit the DATA path at the top of each script to your download, then:
python figures/plot_composition_geographic_transfer.py   # composition, geographic coverage, transfer heatmap
python figures/plot_environment.py                       # paired environmental representations
python figures/plot_social.py                            # social context + interaction statistics

See figures/README.md for the mapping from script to figure.

---

Construction & quality control (reference)

The pipeline/ directory contains the scripts used to build and audit the release, including stage_17_osm_temporal_consistency.py (the per-sample OSM-temporal-consistency check), pbf_to_tile_cache.py (historical-OSM rebuild), apply_unified_taxonomy.py, build_meteo_features.py and verify_v2_artifacts.py. These are provided as reference: several carry environment-specific absolute paths from the original build machine and are meant to be read and adapted, not run unmodified. See pipeline/README.md.

---

Citation

If you use MARIS-Forecast, please cite the Data Descriptor and the Zenodo dataset record (see CITATION.cff), and attribute the upstream AIS providers and OpenStreetMap (see NOTICE.md).

@article{ma2026maris,
  title   = {A multi-region AIS dataset with temporally aligned maritime context
             for vessel trajectory forecasting},
  author  = {Ma, Kun and Han, Qilong and Han, Xiao and Yao, Jingzheng and
             Song, Chengjing and Gao, Tianyu and Na, Chunrui and Zhou, Ziqi and
             Wang, Hao and Sun, Jiaying and Wu, Changmao},
  journal = {Scientific Data},
  year    = {2026}
}

@dataset{ma2026maris_data,
  author    = {Ma, Kun and Han, Qilong and Han, Xiao and Yao, Jingzheng and
               Song, Chengjing and Gao, Tianyu and Na, Chunrui and Zhou, Ziqi and
               Wang, Hao and Sun, Jiaying and Wu, Changmao},
  title     = {MARIS-Forecast: a multi-region AIS trajectory dataset with
               temporally aligned maritime context for vessel trajectory forecasting},
  year      = {2026},
  publisher = {Zenodo},
  version   = {1.0.0},
  doi       = {10.5281/zenodo.21224009}
}

---

Licensing

• Code in this repository is released under the MIT License.

• Data on Zenodo/Hugging Face uses a composite model — different files and even different columns of one table carry different licences:

  • Denmark (DMA) AIS → Danish PSI Act (act 596/2005; free reuse, no warranty, no re-identification — not Creative Commons);
  • United States (NOAA) AIS → U.S. public domain;
  • Greece (Piraeus) AIS → CC BY 4.0;
  • Norway (Kystverket) AIS → NLOD 2.0;
  • all OpenStreetMap-derived context (rasters, signed-distance fields, vector objects, and the OSM-derived port/fairway/TSS/consistency columns) → ODbL, with share-alike;
  • weather / sea-state columns → ERA5 / ECMWF (Copernicus) via Open-Meteo.

  The authoritative per-file / per-column mapping is in LICENSE-DATA.md; attributions are in NOTICE.md. Map data © OpenStreetMap contributors, ODbL.

Acknowledgements

We thank the Danish Maritime Authority, NOAA/MarineCadastre, the authors of the Piraeus AIS open release (Tritsarolis et al., 2022, Zenodo 6323416), and Kystverket / Kystdatahuset for their open AIS data; OpenStreetMap contributors and Geofabrik for cartographic data; and ECMWF / Open-Meteo for ERA5 and WAM reanalysis fields.