.. This file is generated by scripts/render_dataset_docs.py. Do not edit by hand.

IBTrACS
=======

Synthetic-backed storm-track adapter aligned to the IBTrACS tropical cyclone archive.

Overview
--------

IBTrACS is the public storm-track adapter used by PyHazards for shared tropical cyclone benchmark runs.

The current implementation is synthetic-backed, but it preserves the track-intensity forecasting surface used by the shared tropical cyclone evaluator.

At a Glance
-----------

.. list-table::
   :widths: 28 72
   :stub-columns: 1

   * - Provider
     - NOAA NCEI International Best Track Archive for Climate Stewardship surfaced through a PyHazards adapter
   * - Hazard Family
     - Tropical Cyclone
   * - Source Role
     - Track Archive
   * - Coverage
     - Benchmark-aligned tropical cyclone track and intensity samples
   * - Geometry
     - Storm-track history sequences
   * - Spatial Resolution
     - Storm-centered best-track sequences
   * - Temporal Resolution
     - Historical track windows with forecast horizons
   * - Update Cadence
     - Generated locally for smoke and benchmark-alignment runs
   * - Period of Record
     - Synthetic-backed benchmark adapter
   * - Formats
     - PyTorch tensors via the dataset registry
   * - Registry Entry
     - ``ibtracs_tracks``

Data Characteristics
--------------------

- Storm-history sequences with future latitude, longitude, and intensity targets.
- Registry-backed benchmark adapter rather than a raw IBTrACS archive loader.
- Supports both basin-specific hurricane models and broader tropical cyclone adapters.

Typical Use Cases
~~~~~~~~~~~~~~~~~

- Hurricast smoke tests.
- Shared tropical cyclone benchmark runs for track and intensity prediction.
- Benchmark-aligned validation for weather-model storm adapters.

Access
------

Use the links below to access the upstream source or its public documentation.

- `IBTrACS product page <https://www.ncei.noaa.gov/products/international-best-track-archive>`_

PyHazards Usage
---------------

Use this adapter when you want the public IBTrACS-aligned storm-track surface exposed by the tropical cyclone benchmark.

Registry Workflow
~~~~~~~~~~~~~~~~~

Primary dataset name: ``ibtracs_tracks``

.. code-block:: python

   from pyhazards.datasets import load_dataset

   data = load_dataset(
       "ibtracs_tracks",
       micro=True,
       history=6,
       horizon=5,
   ).load()

   train = data.get_split("train")
   print(train.inputs.shape, train.targets.shape)

Related Coverage
~~~~~~~~~~~~~~~~

**Benchmarks:** :doc:`Tropical Cyclone Benchmark </benchmarks/tropical_cyclone_benchmark>`, :doc:`IBTrACS </benchmarks/ibtracs>`

**Representative Models:** :doc:`Hurricast </modules/models_hurricast>`, :doc:`GraphCast TC Adapter </modules/models_graphcast_tc>`, :doc:`Pangu TC Adapter </modules/models_pangu_tc>`, :doc:`FourCastNet TC Adapter </modules/models_fourcastnet_tc>`

Inspection Workflow
-------------------

This dataset is currently surfaced as a registry-backed benchmark adapter,
so there is no standalone inspection CLI documented for it.

Notes
-----

- This is a synthetic-backed benchmark adapter rather than a full IBTrACS ingestion pipeline.

Reference
---------

- `IBTrACS <https://www.ncei.noaa.gov/products/international-best-track-archive>`_.