Ctrl+K

clouddrift.plotting

Contents

clouddrift.plotting#

This module provides a function to easily and efficiently plot the rows of a ragged array.

Functions

plot_ragged(ax, longitude, latitude, ...[, ...])

Plot individually the rows of a ragged array dataset on a Matplotlib Axes or a Cartopy GeoAxes object ax.
clouddrift.plotting.plot_ragged(ax, longitude: list | ndarray | Series | DataArray, latitude: list | ndarray | Series | DataArray, rowsize: list | ndarray | Series | DataArray, *args, colors: list | ndarray | Series | DataArray | None = None, tolerance: float | int | None = 180, **kwargs)[source]#

Plot individually the rows of a ragged array dataset on a Matplotlib Axes or a Cartopy GeoAxes object ax.

This function wraps Matplotlib’s plot function (plt.plot) and LineCollection (matplotlib.collections) to efficiently plot the rows of a ragged array dataset.

Parameters#

ax: matplotlib.axes.Axes or cartopy.mpl.geoaxes.GeoAxes

Axis to plot on.

longitudearray-like

Longitude sequence. Unidimensional array input.

latitudearray-like

Latitude sequence. Unidimensional array input.

rowsizelist

List of integers specifying the number of data points in each row.

*argstuple

Additional arguments to pass to ax.plot.

colorsarray-like

Values to map on the current colormap. If colors is the shape of rowsize, the data points of each row are uniformly colored according to the color value for the row. If colors is the shape of longitude and latitude, the data points are colored according to the color value for each data point.

tolerancefloat

Longitude tolerance gap between data points (in degrees) for segmenting rows. For periodic domains, the tolerance parameter should be set to the maximum allowed gap between data points. Defaults to 180.

**kwargsdict

Additional keyword arguments to pass to ax.plot.

Returns#

list of matplotlib.lines.Line2D or matplotlib.collections.LineCollection

The plotted lines or line collection. Can be used to set a colorbar after plotting or extract information from the lines.

Examples#

Load 100 trajectories from the gdp1h dataset for the examples.

>>> from clouddrift import datasets
>>> from clouddrift.ragged import subset
>>> from clouddrift.plotting import plot_ragged
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from mpl_toolkits.axes_grid1 import make_axes_locatable
>>> ds = datasets.gdp1h()
>>> ds = subset(ds, {"id": ds.id[:100].values}).load()

Plot the trajectories, assigning a different color to each trajectory:

>>> fig = plt.figure()
>>> ax = fig.add_subplot(1, 1, 1)
>>> l = plot_ragged(
>>>     ax,
>>>     ds.lon,
>>>     ds.lat,
>>>     ds.rowsize,
>>>     colors=np.arange(len(ds.rowsize))
>>> )
>>> divider = make_axes_locatable(ax)
>>> cax = divider.append_axes('right', size='3%', pad=0.05)
>>> fig.colorbar(l, cax=cax)

To plot the same trajectories, but assigning a different color to each data point based on a transformation of the time variable mapped onto the inferno colormap:

>>> fig = plt.figure()
>>> ax = fig.add_subplot(1, 1, 1)
>>> time = [v.astype(np.int64) / 86400 / 1e9 for v in ds.time.values]
>>> l = plot_ragged(
>>>     ax,
>>>     ds.lon,
>>>     ds.lat,
>>>     ds.rowsize,
>>>     colors=np.floor(time),
>>>     cmap="inferno"
>>> )
>>> divider = make_axes_locatable(ax)
>>> cax = divider.append_axes('right', size="3%", pad=0.05)
>>> fig.colorbar(l, cax=cax)

Finally, to plot the same trajectories, but using a cartopy projection:

>>> import cartopy.crs as ccrs
>>> fig = plt.figure()
>>> ax = fig.add_subplot(1, 1, 1, projection=ccrs.Mollweide())
>>> l = plot_ragged(
>>>     ax,
>>>     ds.lon,
>>>     ds.lat,
>>>     ds.rowsize,
>>>     colors=np.arange(len(ds.rowsize)),
>>>     transform=ccrs.PlateCarree(),
>>>     cmap="Blues",
>>> )
>>> ax.set_extent([-180, 180, -90, 90])
>>> ax.coastlines()
>>> ax.gridlines(draw_labels=True)
>>> divider = make_axes_locatable(ax)
>>> cax = divider.append_axes('right', size="3%", pad=0.25, axes_class=plt.Axes)
>>> fig.colorbar(l, cax=cax)

Raises#

ValueError

If longitude and latitude arrays do not have the same shape. If colors do not have the same shape as longitude and latitude arrays or rowsize. If ax is not a matplotlib Axes or GeoAxes object. If ax is a GeoAxes object and the transform keyword argument is not provided.

ImportError

If matplotlib is not installed. If the axis is a GeoAxes object and cartopy is not installed.

Contents