trajan.animation.Animation

class trajan.animation.Animation(ds)

Builder for trajectory animations.

Obtain via ds.traj.animate, configure with method chaining, then call show() or save() to render.

Examples

Simple:

>>> ds.traj.animate().show()  

Chained:

>>> (ds.traj.animate()  
...     .color_by('speed', cmap='RdYlBu_r')
...     .show_trajectories(alpha=0.2)
...     .save('barents.mp4'))

With background field:

>>> (ds.traj.animate()  
...     .overlay_variable(current_speed_da, cmap='Blues', label='speed [m/s]')
...     .show())

__init__(ds)

Methods

__init__(ds)
build([blit])	Build the matplotlib.animation.FuncAnimation.
color_by(variable[, cmap, vmin, vmax, ...])	Color particles by a variable or a fixed matplotlib colour.
overlay_variable(data[, cmap, alpha, vmin, ...])	Overlay an animated gridded variable as a background field.
save(filename[, fps])	Save the animation to a file.
set_fps(fps)	Set the playback speed.
set_markersize(size)	Set the particle marker size.
set_title(title)	Control the axes title.
show()	Display the animation.
show_trajectories([alpha])	Draw full trajectory lines as a static background.

Attributes

DEFAULT_LINE_COLOR
gcrs
ds

DEFAULT_LINE_COLOR = 'gray'

_repr_html_()

Embed the animation inline in a Jupyter notebook.

build(blit=True)

Build the matplotlib.animation.FuncAnimation.

The result is cached (for blit=True only); call set_fps() to invalidate the cache and rebuild on the next call.

Parameters:

blit (bool, optional) – Use blitting for faster rendering (default True). Pass False when the output will be embedded as jshtml (Jupyter) to avoid artefacts caused by the blit background-capture path.

Returns:

matplotlib.animation.FuncAnimation

color_by(variable, cmap=None, vmin=None, vmax=None, label=None, colorbar=True)

Color particles by a variable or a fixed matplotlib colour.

Parameters:

• variable (str or xarray.DataArray) – A DataArray with dims (trajectory, time), a dataset variable name (e.g. 'speed'), or a fixed matplotlib colour string (e.g. 'red').

• cmap (str or Colormap, optional) – Colormap (default: 'jet').

• vmin, vmax (float, optional) – Colour scale limits.

• label (str, optional) – Colorbar label.

• colorbar (bool, optional) – Whether to draw a colorbar (default: True).

Returns:

self

ds

gcrs = None

overlay_variable(data, cmap='viridis', alpha=0.5, vmin=None, vmax=None, label=None)

Overlay an animated gridded variable as a background field.

Parameters:

• data (xarray.DataArray) – Must have a time dimension and lat/lon (or latitude/longitude) coordinates.

• cmap (str or Colormap, optional)

• alpha (float, optional)

• vmin, vmax (float, optional)

• label (str, optional) – Colorbar label.

Returns:

self

save(filename, fps=None)

Save the animation to a file.

Parameters:

• filename (str or Path) – Output file. Supported formats: .gif, .mp4.

• fps (int, optional) – Frames per second; overrides any prior set_fps() call and triggers a rebuild.

Returns:

self

set_fps(fps)

Set the playback speed.

Parameters:

fps (int)

Returns:

self

set_markersize(size)

Set the particle marker size.

Parameters:

size (float)

Returns:

self

set_title(title)

Control the axes title.

Parameters:

title (str or None) – 'auto' (default) shows the current time stamp per frame inside the axes. None suppresses the timestamp entirely. Any other string is used as a fixed axes title (timestamp still shown inside).

Returns:

self

show()

Display the animation.

In a Jupyter notebook the animation is embedded as HTML; in a script matplotlib.pyplot.show() is called.

Returns:

self

show_trajectories(alpha=0.1)

Draw full trajectory lines as a static background.

Parameters:

alpha (float, optional) – Transparency (default: 0.1).

Returns:

self