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 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 to develop for Trajan)
$ cd trajan # move to the location of the trajan root, containing the pyproject.toml file
$ pip install .
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 s. 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.
- Generally, TrajAn supports two types of data layout:
trajectories sampled at different times (unstructured or irregular grid), almost every dataset from real observations.
trajectories sampled at uniform (or regular) grid, typical the output from a model.
We refer to the first type as _2D_ since time is a function of trajectory and observation, while the second type is _1D_ and time is only a function of observation. __TrajAn__ will detect which type of dataset you have and you will have access to the appropriate methods for the type data layout.
While the first type (_2D_) is more general it often limits analysis that require trajectories to be sampled at the same points, you can therefor convert a _2D_ dataset to _1D_ by using trajan.traj2d.Traj2d.gridtime().
Methods applicable to both types of datasets can be found in: trajan.traj, methods for _1D_ datasets: trajan.traj.traj1d, and _2D_: trajan.traj.traj2d. All methods are forwarded to the accessor, so you call the methods on Dataset.traj:
ds = ds.traj.gridtime('1H') # grid dataset to every hour (a 2D method)
ds.traj.plot() # plot dataset
Generic plotting is available in the standard Xarray way, and strives to stay as close to matplotlib as possible: (trajan.trajectory_accessor.TrajAccessor.plot()) and animation (trajan.trajectory_accessor.TrajAccessor.animate()).