Trajectory Analysis (TrajAn)#

TrajAn is a Python package with functionality to handle trajectory datasets following the CF-conventions on trajectories.

Trajectory datasets contain position time series from e.g. drifting buoys, or output from lagrangian models.

The source code is available on GitHub: OpenDrift/trajan

Installation#

Install from internet package sources (recommended for users)

$ conda install -c conda-forge trajan

or

$ pip install trajan

Install from source (recommended if you want to modify TrajAn code)

$ git clone git@github.com:OpenDrift/trajan.git
$ cd trajan
$ pip install -e .

Remember to re-install each time you have done an edit during the development process.

Usage#

TrajAn is an Xarry extension. On drifter (or trajectory) datasets you can use the .traj accessor on xarray.Dataset. In order to register the accessor, trajan needs to be imported:

import matplotlib.pyplot as plt
import xarray as xr
import trajan as _

ds = xr.open_dataset('drifter_dataset.nc')

ds.traj.plot()
plt.show()

speed = ds.traj.speed()
print(f'Max speed {speed.max().values} m/s')

Trajectory datasets from different models and observations tend to have many small differences. TrajAn expects the dataset to be CF-compliant. However, the standard does leave some room for interpretation.

TrajAn supports two types of data layout:

  1. Ragged: trajectories sampled at different times (unstructured or irregular grid), almost every dataset from real observations. Time is a 2D array with dimensions for trajectory and observation/time.

  2. Orthogonal: trajectories sampled at uniform (or regular) grid, typical the output from a model. Time is a 1D array common for all trajectories.

TrajAn will detect which type of dataset you have and you will have access to the appropriate methods for the type data layout. Contiguous ragged and nc_particles format are internally converted to Ragged format.

While the Ragged format is more general it often limits analysis that require trajectories to be sampled at the same points. A Ragged dataset can therefore be converted to Orthogonal by using ds.traj.gridtime.

Methods applicable to both types of datasets can be found in the traj accessor

Methods for Orthogonal datasets: trajan.traj.orthogonal.Orthogonal

Methods for Ragged datasets: trajan.traj.ragged.Ragged.

All methods are forwarded to the accessor, so you call the methods on ds.traj:

ds = ds.traj.gridtime('1h')   # grid dataset to every hour
ds.traj.plot()                # plot dataset

Generic plotting is available in the standard Xarray way, and strives to stay as close to matplotlib as possible:

ds.traj.plot()

TrajAn also contains an animation builder mechanism:

ds.traj.animate()

Contents#

Indices and tables#

Last Updated on 2026-07-21 at 14:58