Prescribed-track method
========================

Purpose
-------

The prescribed-track tracker (``tracking_method: "prescribed_track"``) uses an external NetCDF track file to locate, at each time step, the model grid point closest to the cyclone position provided in the track. The output is a time series of grid indices ``(cy, cx)`` defined on the set of timestamps common to both the model dataset and the track file.

This method is intended for reproducible diagnostics when a reliable cyclone trajectory is already available (e.g., produced by a prior workflow or an operational tracking).

Core assumptions
----------------

This method relies on strong assumptions:

- The prescribed track file has been built from the *same simulation outputs* as those provided to FrameIt (same time step, same calendar, same experiment).
- Common timestamps between the model dataset and the prescribed track are assumed to match **exactly** (no temporal tolerance is applied).
- The track file provides, at minimum, time, latitude and longitude time series.

Input and output
----------------

Input dataset
~~~~~~~~~~~~~

The tracker is applied to a flattened dataset created by the tracking pipeline (internally, FrameIt provides a "flat" dataset containing at least spatial coordinates and a time coordinate). The model dataset must include:

- a time coordinate named ``time``,
- latitude and longitude coordinates accessible through configuration keys (default names: ``latitude``, ``longitude``).

Prescribed track file
~~~~~~~~~~~~~~~~~~~~~

The external NetCDF file must contain:

- a coordinate for time (default name: ``time``),
- a latitude variable (default name: ``latitude``),
- a longitude variable (default name: ``longitude``).


Configuration keys
------------------

To activate this tracker fill the following variables in the configuration file:

``tracking_method:``
   Tracking method : ``"prescribed_track"``

``prescribed_track_file``
   Path to the external NetCDF file containing the prescribed cyclone trajectory.

.. code-block:: yaml

   tracking_method: "prescribed_track"
   prescribed_track_file: "/path/to/prescribed_track.nc"


Practical considerations and limitations
----------------------------------------

- **Exact time matching**: no time tolerance is implemented. If the track timestamps and model timestamps differ (even by seconds), the intersection may be empty.
- **Distance metric**: the closest-grid search is performed in latitude/longitude space using a squared Euclidean metric. This is adequate for small domains but is not a true geodesic distance.
- **Longitude convention**: the track file and the model dataset must use a consistent longitude convention (e.g., both in ``[-180, 180]`` or both in ``[0, 360]``). Otherwise, the closest-point selection may be incorrect.
- **NaNs**: the tracker uses ``nanargmin`` for robust selection when NaNs exist in the coordinate arrays. If all candidate distances are NaN, ``nanargmin`` will raise.