toad.plotting¶

Functions

get_projection(projection)

Get a cartopy projection object from a string name or return the projection.

Classes

`MapStyle`([resolution, coastline_linewidth, ...])	Configuration for map styling parameters.
`Plotter`(td)	Plotting utilities for TOAD objects.

class toad.plotting.MapStyle(resolution='110m', coastline_linewidth=0.5, border_linewidth=0.25, grid_labels=False, grid_lines=True, grid_style='--', grid_width=0.5, grid_color='gray', grid_alpha=0.5, borders=True, projection=None, extent=None, map_frame=True, continent_shading=False, continent_shading_color='lightgray', ocean_shading=False, ocean_shading_color='lightgray', plot_contour=True, plot_fill=True, add_labels=True, contour_linewidth=1.5)¶

Bases: object

Configuration for map styling parameters.

This dataclass contains all the configuration options for styling maps with Plotter, including coastline, grid, and projection settings.

Parameters:

resolution (Literal['110m', '50m', '10m'] | str)
coastline_linewidth (float)
border_linewidth (float)
grid_labels (bool)
grid_lines (bool)
grid_style (str)
grid_width (float)
grid_color (str)
grid_alpha (float)
borders (bool)
projection (str | Projection | None)
extent (Tuple[float, float, float, float] | None)
map_frame (bool)
continent_shading (bool)
continent_shading_color (str)
ocean_shading (bool)
ocean_shading_color (str)
plot_contour (bool)
plot_fill (bool)
add_labels (bool)
contour_linewidth (float)

add_labels: bool = True¶

border_linewidth: float = 0.25¶

borders: bool = True¶

coastline_linewidth: float = 0.5¶

continent_shading: bool = False¶

continent_shading_color: str = 'lightgray'¶

contour_linewidth: float = 1.5¶

extent: Tuple[float, float, float, float] | None = None¶

grid_alpha: float = 0.5¶

grid_color: str = 'gray'¶

grid_labels: bool = False¶

grid_lines: bool = True¶

grid_style: str = '--'¶

grid_width: float = 0.5¶

map_frame: bool = True¶

ocean_shading: bool = False¶

ocean_shading_color: str = 'lightgray'¶

plot_contour: bool = True¶

plot_fill: bool = True¶

projection: str | Projection | None = None¶

resolution: Literal['110m', '50m', '10m'] | str = '110m'¶

class toad.plotting.Plotter(td)¶

Bases: object

Plotting utilities for TOAD objects.

The Plotter class provides methods for creating publication-ready visualizations of TOAD data, including maps, timeseries, and statistical plots.

Parameters:: td – TOAD object containing the data to plot

Plot one or multiple clusters on a map.

Parameters:

var –

Base variable name (e.g. ‘temperature’, will look for
’temperature_cluster’) or custom cluster variable name. If None, TOAD will attempt to infer which variable to use.

A ValueError is raised if the variable cannot be uniquely determined.
cluster_ids – Single cluster ID or list of cluster IDs to plot. Defaults to range(9) (clusters 0-8) if not provided.
map_style – Map style configuration. Can be a MapStyle object, a dict with MapStyle fields, or None (uses defaults). If dict, missing keys use defaults. Controls projection, grid, borders, and cluster visualization options (plot_contour, plot_fill, add_labels, contour_linewidth).
ax – Matplotlib axes to plot on. Creates new figure if None. Cannot be used with subplots=True.
color – Color for cluster visualization. Can be: - A single color (str, hex, RGB tuple) to use for all clusters. - A list of colors to use for each cluster. Overrides cmap.
cmap – Colormap for multiple clusters. Used only if color is None.
map_cmap_other – Colormap for remaining clusters. Can be: - A string (e.g., “jet”, “viridis”) to use a built-in colormap. - A matplotlib colormap object.
include_all_clusters – If True, plot all clusters on the map. If False, only plot selected clusters. Defaults to True.
subplots – If True, plot each cluster on its own subplot. Defaults to False.
figsize – Figure size when subplots=True. Defaults to (12, 3 * nrows).
ncols – Number of columns in subplot grid when subplots=True. Defaults to 3.
**kwargs – Additional arguments passed to xarray.plot methods (e.g., plot, plot.contour).

Returns:

Tuple of (figure, axes). Figure is None if ax was provided. When subplots=True, axes is a numpy array of axes.

Raises:

ValueError – If no clusters found for given variable, or if ax is provided with subplots=True.
TypeError – If cluster_ids is not an int, list, ndarray, range, or None, or if cmap is not a string or ListedColormap.

cluster_overview(**kwargs)¶

Deprecated function: use td.plot.overview() instead.

Parameters:: kwargs (Any)

map(nrows: Literal[1] = 1, ncols: Literal[1] = 1, *, figsize: Tuple[float, float] | None = None, height_ratios: List[float] | None = None, width_ratios: List[float] | None = None, subplot_spec: Any = None, map_style: MapStyle | dict | None = None) → Tuple[Figure, Axes]¶

map(nrows: int, ncols: int = 1, *, figsize: Tuple[float, float] | None = None, height_ratios: List[float] | None = None, width_ratios: List[float] | None = None, subplot_spec: Any = None, map_style: MapStyle | dict | None = None) → Tuple[Figure, ndarray]

Create map plots with standard features.

Parameters:

nrows – Number of rows in subplot grid
ncols – Number of columns in subplot grid
figsize – Figure size (width, height) in inches. If None, not set (matplotlib default).
height_ratios – List of height ratios for subplots
width_ratios – List of width ratios for subplots
subplot_spec – A gridspec subplot spec to place the map in
map_style – Map style configuration. Can be a MapStyle object, a dict with MapStyle fields, or None (uses defaults). If dict, missing keys use defaults. The projection is set via map_style.projection.

Returns:

Tuple of (figure, axes). If nrows=1 and ncols=1, returns a single Axes. Otherwise, returns a numpy array of axes.

overview(var=None, cluster_ids=range(0, 6), map_style=None, mode='timeseries', **kwargs)¶

Create an overview plot with map and timeseries for clusters.

This is a convenience method that creates a combined visualization showing both the spatial distribution of clusters on a map and their corresponding timeseries. It automatically enables subplots and map display.

Parameters:

var (str | None) – Base variable or cluster variable. If None, TOAD will attempt to infer which variable to use. A ValueError is raised if the variable cannot be uniquely determined.
cluster_ids (int | List[int] | ndarray | range | None) – ID or list of IDs of clusters to plot. Defaults to range(6) (clusters 0-5).
map_style (MapStyle | dict | None) – Map style configuration. Can be a MapStyle object, a dict with MapStyle fields, or None (uses defaults). If dict, missing keys use defaults.
mode (Literal['timeseries', 'aggregated']) – Visualization mode. “timeseries” shows individual trajectories, “aggregated” shows statistical summaries (median, range, IQR).
**kwargs (Any) – Additional arguments passed to timeseries() method.

Returns:

Tuple of (figure, dict) with keys ‘map’ and ‘timeseries’. - ‘map’: Axes for the map plot - ‘timeseries’: List of axes for timeseries subplots (one per cluster)

Return type:

Tuple[Figure | None, dict]

shifts_distribution(figsize=None, yscale='log', bins=20)¶

Plot histograms showing the distribution of shifts for each shift variable.

Parameters:

figsize (tuple | None) – Figure size (width, height) in inches. If None, defaults to (12, 2 * number of shift variables).
yscale (str) – Scale for the y-axis. Defaults to “log”.
bins – Number of bins for the histogram. Defaults to 20.

Returns:

Tuple of (figure, axes). Axes is a numpy array of axes (one per shift variable).

timeseries(var=None, cluster_ids=None, *, timeseries_var=None, ax=None, color=None, cmap='tab20b', normalize=None, add_legend=True, plot_trajectories=True, max_trajectories=1000, trajectories_sample_seed=0, trajectories_alpha=0.5, trajectories_linewidth=0.5, full_timeseries=True, highlight_color=None, highlight_alpha=0.5, highlight_linewidth=0.5, plot_dts=False, plot_median=False, plot_mean=False, median_linewidth=3, mean_linewidth=3, plot_trajectory_range=False, plot_trajectory_std=False, trajectory_range_alpha=0.2, trajectory_std_alpha=0.4, plot_shift_indicator=True, shift_indicator_color=None, shift_indicator_alpha=0.25, plot_map=False, map_var=None, map_cmap_other='jet', map_include_all_clusters=True, subplots=False, ncols=1, figsize=None, wspace=0.1, hspace=0.1, show_ylabels=False, vertical=False, width_ratios=(1.0, 1.0), height_ratios=None, map_style=None, **plot_kwargs)¶

Plot time series from clusters or all data.

This function allows flexible plotting of individual trajectories, aggregated statistics (median/mean), shaded regions (full range and IQR), and shift duration indicators. If no clusters are provided, plots all timeseries from the dataset.

Can optionally create separate subplots for each cluster, and optionally include a map showing cluster spatial locations alongside the timeseries.

Parameters:

var (str | None) – Base variable or cluster variable. If None, TOAD will attempt to infer which variable to use. A ValueError is raised if the variable cannot be uniquely determined.
cluster_ids (int | List[int] | ndarray | range | None) – ID or list of IDs of clusters to plot. If None, plots all timeseries from the dataset (no clustering). Cannot be None if plot_map=True.
timeseries_var (str | None) – Variable name to plot (if different from var). Defaults to var.
ax (Axes | None) – Matplotlib axes to plot on. Creates new figure if None. Ignored if subplots=True or plot_map=True.
color (str | None) – Single color to use for all plotted clusters. Overrides cmap.
cmap (str | ListedColormap) – Colormap to use if plotting multiple clusters and color is None.
normalize (Literal['max', 'max_each'] | None | str) – Method to normalize timeseries (‘max’, ‘max_each’). Defaults to None.
add_legend (bool) – If True, add a legend indicating cluster IDs.
plot_trajectories (bool) – If True, plot individual cell trajectories.
max_trajectories (int) – Maximum number of individual trajectories to plot (per cluster if clusters provided, or total if plotting all data).
trajectories_sample_seed – Seed for the random number generator used to sample trajectories. Defaults to 0.
trajectories_alpha (float) – Alpha transparency for individual time series lines. Defaults to 0.5.
trajectories_linewidth (float) – Linewidth for individual time series lines. Defaults to 0.5.
full_timeseries (bool) – If True, plot the full timeseries for each cell. If False, only plot the segment belonging to the cluster.
highlight_color (str | None) – Color to highlight the actual cluster segment when full_timeseries is True.
highlight_alpha (float) – Alpha for the cluster highlight segment.
highlight_linewidth (float) – Line width for the cluster highlight segment.
plot_dts (bool) – If True, plot shifts variable in timeseries instead of base variable.
plot_median (bool) – If True, plot the median timeseries curve.
plot_mean (bool) – If True, plot the mean timeseries curve.
median_linewidth (float) – Linewidth for the median curve.
mean_linewidth (float) – Linewidth for the mean curve.
plot_trajectory_range (bool) – If True, plot the full range (min to max) as a shaded area.
plot_trajectory_std (bool) – If True, plot the 68% interquartile range (16th to 84th percentile) as a shaded area.
trajectory_range_alpha (float) – Alpha transparency for the full range shaded area.
trajectory_std_alpha (float) – Alpha transparency for the IQR shaded area.
plot_shift_indicator (bool) – If True, adds horizontal shading indicating the cluster’s temporal extent (start to end). Only applies when clusters are provided.
shift_indicator_color (str | None) – Color for shift duration shading. Uses cluster color if None.
shift_indicator_alpha (float) – Alpha for the shift duration shading.
plot_map (bool) – If True, include a map showing cluster spatial locations alongside timeseries. Defaults to False.
map_var (str | None) – Variable name whose data to plot in the map. Defaults to var if None. Only used if plot_map=True.
map_cmap_other (str | Colormap | None) – Colormap for remaining clusters on map. Only used if plot_map=True.
map_include_all_clusters (bool) – If True, plot all clusters on the map. If False, only plot selected clusters. Only used if plot_map=True.
subplots (bool) – If True, create one subplot per cluster. Defaults to False. If plot_map=True and multiple clusters, subplots are automatically enabled.
ncols (int) – Number of columns for subplot grid when subplots=True. Defaults to 1.
figsize (Tuple[float, float] | None) – Figure size (width, height) in inches. Used when subplots=True or plot_map=True.
wspace (float) – Width space between timeseries subplots (if ncols > 1).
hspace (float) – Height space between timeseries rows.
show_ylabels (bool) – If True, show y-axis label on the timeseries plots. Only relevant for subplots.
vertical (bool) – If True, arrange map above timeseries plots. Otherwise, map is placed to the left. Only used if plot_map=True.
width_ratios (Tuple[float, float]) – Tuple of relative widths for map vs. timeseries section (used in horizontal layout). Only used if plot_map=True.
height_ratios (Tuple[float, float] | None) – Optional tuple of relative heights for map vs. timeseries section (used in vertical layout). Only used if plot_map=True.
**plot_kwargs (Any) – Additional arguments passed to xarray.plot for each trajectory.
map_style (MapStyle | dict | None)
**plot_kwargs

Returns:

Tuple of (figure, axes). - If plot_map=False and single plot: (figure, Axes) - If plot_map=False and subplots=True: (figure, List[Axes]) - If plot_map=True: (figure, dict) with keys ‘map’ and ‘timeseries’ Figure is None if ax was provided and subplots=False and plot_map=False.

Raises:

ValueError – If no timeseries found for a given cluster ID, if nothing is set to plot, if cluster_ids is None when plot_map=True, or if plotting all data when plot_map=True.

Return type:

Tuple[Figure | None, Axes | List[Axes] | dict | None]