canopy.visualization

canopy.visualization.distribution_plot

Distribution plot visualization.

canopy.visualization.distribution_plot.make_distribution_plot(fields: Field | List[Field], output_file: str | None = None, plot_type: str = 'box', layers: List[str] | str | None = None, gridop: str | None = 'av', yaxis_label: str | None = None, field_labels: List[str] | None = None, unit: List[str] | None = None, title: str | None = None, palette: str | None = None, custom_palette: List[str] | None = None, horizontal: bool = False, vertical_xlabels: bool = False, x_label_rotation: float = 0, move_legend: bool = False, dark_mode: bool = False, transparent: bool = False, x_fig: float = 10, y_fig: float = 10, subfig=None, return_fig: bool = False, **kwargs) → Figure | None[source]

Create a comparative plot from a list of input data Fields from, for example, different runs. The functions can generate boxplot, strip or swarm plot, violin plot, boxen plot, point plot, bar plot or count plot based on the plot_type parameter.

Parameters:

fields (cp.Field or List[cp.Field]) – Input data Field to display.
output_file (str, optional) – File path for saving the plot.
plot_type (str, optional) – Type of plot. Either “strip”, “swarm”, “box”, “violin”, “boxen”, “point”, or “bar”
layers (List[str] or str, optional) – List of layer names to display.
gridop (str, optional) – If provided, the grid reduction operation. Either None, ‘sum’ or ‘av’. Default is ‘av’.
yaxis_label (str, optional) – Y-axis label, if not provided canopy will try to retrieve the name of the variable in the metadata.
field_labels (List[str], optional) – Names of each series to display in the legend.
unit (List[str], optional) – Unit of the y-axis variable, if not provided canopy will try to retrieve the unit of the variable in the metadata.
title (str, optional) – Title of the plot.
palette (str, optional) – Seaborn color palette to use for the line colors (https://seaborn.pydata.org/tutorial/color_palettes.html, recommended palette are in https://colorbrewer2.org).
custom_palette (List[str], optional) – Path of custom color palette .txt file to use. Names should match label names.
horizontal (bool, optional) – If True, renders the plot with horizontal orientation (flips the axes).
vertical_xlabels (bool, optional) – If True, rotates the x-axis tick labels vertically (i.e., 90 degrees).
x_label_rotation (float, optional) – Rotation angle in degrees for the x-axis tick labels. Overrides vertical_xlabels when non-zero. Default is 0.
move_legend (bool, optional) – Move the legend outside of plot. Default is False.
dark_mode (bool, optional) – If True, applies dark mode styling to the figure. Default is False.
transparent (bool, optional) – If True, sets the figure background to be transparent when saved. Default is False.
x_fig (float, optional) – Width of the figure in inches. Default is 10.
y_fig (float, optional) – Height of the figure in inches. Default is 10.
subfig (matplotlib.figure.SubFigure, optional) – If provided, the plot will be created in this subfigure instead of creating a new figure. This is used by multiple_figs() to combine multiple plots. User can also provide a plt.figure.subfigure object (https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html)
return_fig (bool, optional) – If True, return a callable wrapper function instead of creating the plot immediately. This wrapper can be used with multiple_figs(). Default is False.
**kwargs – Additional keyword arguments are passed directly to seaborn.catplot. This allows customization of plot features such as aspect, errorbar, height`, etc.

canopy.visualization.map

Map visualization module.

Create a difference map from two fields (field_b - field_a). Same arguments as make_simple_map except the ones below.

Parameters:

field_a (cp.Field) – First and second Field objects for computing the difference (field_b - field_a).
field_b (cp.Field) – First and second Field objects for computing the difference (field_b - field_a).
percentage (bool, optional) – If True, compute proportional difference in %. Default is False.
nonsig (bool, optional) – If True, overlay hatched areas to indicate regions where differences between the two fields are not statistically significant (p-value >= 0.05). These are areas where the observed differences could be explained by interannual variability rather than representing a true difference between the two climate runs. Default is False.

canopy.visualization.map.make_simple_map(field: Field, layer: str, categorical: bool = False, output_file: str | None = None, timeop: str = 'av', cb_label: str | None = None, title: str | None = None, unit: str | None = None, n_classes: int = 4, classification: List[float] | str = 'linear', palette: str | None = None, custom_palette: str | None = None, orientation: str = 'horizontal', cb_label_rotation: float = 0, extend: str = 'neither', proj: str = 'Robinson', force_zero: bool = False, dark_mode: bool = False, transparent: bool = False, stats_annotation: bool = False, x_fig: float = 10, y_fig: float = 10, subfig=None, return_fig: bool = False) → Figure | None[source]

Create a map from a given Field object (apply time reduction) and save it to a file.

Parameters:

field (cp.Field) – Field object.
layer (str) – Layer name to display.
categorical (bool, optional) – Set to True for categorical data mapping. Default False.
output_file (str, optional) – File path for saving the plot.
timeop (str, optional) – The reduction operation. Either ‘sum’ or ‘av’. Default is ‘av’.
cb_label (str, optional) – Label of the colour bar, if not provided canopy will try to retrieve the name of the variable in the metadata.
unit (str, optional) – Unit of the variable, if not provided canopy will try to retrieve the unit of the variable in the metadata.
title (str, optional) – Title of the map.
n_classes (int, optional) – Number of discrete color classes to use. Default is 4.
classification (List[float] | str, optional) – Method to classify the data into different classes. One of ‘linear’, ‘quantile’, ‘jenks’, ‘std’ (https://gisgeography.com/choropleth-maps-data-classification/) or a list, e.g. [0,2,4,8]. Default is ‘linear’.
palette (str, optional) – Seaborn color palette to use for the line colors (https://seaborn.pydata.org/tutorial/color_palettes.html, recommended palette are in https://colorbrewer2.org).
custom_palette (str, optional) – Path of custom color palette .txt file to use.
orientation (str, optional) – Orientation of the legend. Either ‘horizontal’ or ‘vertical’. Default is ‘horizontal’.
cb_label_rotation (float, optional) – Rotation angle in degrees for the colorbar tick labels. Default is 0.
extend (str, optional) – Extend colourbar to maximum and minimum value. One of ‘neither’, ‘min’, ‘max’ or ‘both’. Default is ‘neither’.
proj (str, optional) – Cartopy projection to use for the map (https://scitools.org.uk/cartopy/docs/v0.15/crs/projections.html). Default is ‘Robinson’.
force_zero (bool, optional) – If True, force the first (or the closest in diff_map) bin to zero. Default is False.
dark_mode (bool, optional) – If True, apply dark mode styling. Default is False.
transparent (bool, optional) – If True, make the figure transparent. Default is False.
stats_annotation (bool, optional) – If True, adds a text box annotation on the bottom-left of the map displaying the mean and standard deviation of the raster values over the entire domain. Default is False.
x_fig (float, optional) – Width of the figure in inches. Default is 10.
y_fig (float, optional) – Height of the figure in inches. Default is 10.
subfig (matplotlib.figure.SubFigure, optional) – If provided, the plot will be created in this subfigure instead of creating a new figure. This is used by multiple_figs() to combine multiple plots. User can also provide a plt.figure.subfigure object (https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html)
return_fig (bool, optional) – If True, return a callable wrapper function instead of creating the plot immediately. This wrapper can be used with multiple_figs(). Default is False.

canopy.visualization.plot_functions

canopy.visualization.visualization_helpers.format_value_label(yaxis_label: str | None, unit: str | None) → str[source]: Format y-axis label with unit, or return label alone if no unit.

canopy.visualization.visualization_helpers.get_color_palette(n_classes: int, palette: str | None = None, custom_palette: str | None = None) → Tuple[List[Any], dict | None][source]: Generate a color palette for plotting based on either a ColorBrewer palette or a custom palette file.

canopy.visualization.visualization_helpers.get_field_metadata(field_or_fields, label: str | None = None, unit: str | None = None, layers: Any | None = None) → Tuple[str, str, Any][source]: Retrieve label, unit, and layers from field metadata when not provided.

canopy.visualization.visualization_helpers.handle_figure_output(fig: Figure, output_file: str | None = None, transparent: bool = False, subfig=None) → Figure | None[source]: Figure handler: save or show.

canopy.visualization.visualization_helpers.make_dark_mode(fig: Figure, ax: Any, legend_style: str | None = None, cbar: Any | None = None, gridlines: Any | None = None) → Tuple[Figure, Any][source]: Apply dark mode styling to the given figure and axis.

canopy.visualization.visualization_helpers.save_figure_png(output_file: str, bbox_inches: str | None = None, transparent: bool = False) → None[source]: Save the current matplotlib figure as a PNG file.

canopy.visualization.visualization_helpers.set_axis_style(ax: Any, title: str | None = None, x_label: str | None = None, y_label: str | None = None, tick_labelsize: int = 12) → None[source]: Set axis labels, title, tick size, and despine.

canopy.visualization.multiple_figs

canopy.visualization.multiple_figs.create_wrapper_from_locals(plot_func: Callable[[...], Any], local_vars: dict[str, Any], x_fig_key: str = 'x_fig', y_fig_key: str = 'y_fig') → Callable[[...], Any][source]: Helper function to create a plot wrapper from local variables. Automatically extracts all parameters except excluded ones.

canopy.visualization.multiple_figs.multiple_figs(fig_list: List[Callable[[...], Any] | Figure], output_file: str | None = None, ncols: int = 2, dpi: int = 150, dark_mode: bool = False, add_letters: bool = False, title: str | None = None, title_font_size: int = 24, wspace: float = 0.0, hspace: float = 0.05)[source]

Arrange multiple figures into a single figure using matplotlib subfigures.

Parameters:

fig_list (list of callables) – List of plotting functions created with return_fig=True (e.g., make_static_plot(…, return_fig=True)).
output_file (str, optional) – Path to save the combined figure
ncols (int, optional) – Number of columns in the grid. Default is 2.
dpi (int, optional) – Resolution for the output. Default is 150.
dark_mode (bool, optional) – If True, use dark gray background instead of white. Default is False.
add_letters (bool, optional) – If True, adds letter labels (a, b, c…) to the bottom left corner of each subfigure. Default is False.
title (str, optional) – A common title for all figures.
title_font_size (int, optional) – Font size for the title in points (pt). Default is 24.
wspace (float, optional) – Horizontal space between subfigures as fraction of subfigure width. Default is 0.0.
hspace (float, optional) – Vertical space between subfigures as fraction of subfigure height. Default is 0.05.

Returns:

The combined figure object.

Return type:

matplotlib.Figure

Notes

The entries in fig_list are callables that re-execute the plotting function when the combined figure is built. Any Field objects captured in those closures are used in their current state at that moment, not frozen at wrapper creation time. For example, reusing one Field with reduce_layers(..., inplace=True) between building wrappers can make earlier panels redraw with a mutated field (and may raise errors). Prefer separate Field instances per plot, or avoid in-place reductions on a shared field.

Example

plot1 = cv.make_static_plot(field_a=agpp1, field_b=agpp3, kind=’scatter’, return_fig=True) plot2 = cv.make_time_series(fields=[agpp, agpp_nolc], gridop=”av”, return_fig=True) cv.multiple_figs([plot1, plot2], ncols=2, output_file=”combined.png”)

canopy.visualization.multiple_figs.setup_figure_and_axes(subfig=None, x_fig: float = 10, y_fig: float = 10, projection: type | None = None, constrained_layout: bool = False) → Tuple[Figure, Axes][source]: Set up figure and axes, handling both standalone and subfigure cases.

canopy.visualization.map.projections

canopy.visualization.static_plot

Static plot visualization (scatter, hist, kde).

This function generates a scatter plot with regression lines and r-scores, a histogram or a kde plot, comparing two input fields (which can be reduced spatially, temporally or both).

Parameters:

field_a (cp.Field) – Input data Field to display.
field_b (cp.Field) – Input data Field to display.
kind (str, optional) – Kind of plot to draw. Default is ‘scatter’, which uses seaborn.regplot (supports multiple layers). Option ‘hist’ uses seaborn.histplot (supports multiple layers). Option ‘kde’ uses seaborn.kdeplot (supports multiple layers).
output_file (str, optional) – File path for saving the plot.
layers (List[str] or str, optional) – Layers to plot from the input data.
field_a_label (str, optional) – Labels for the data series, if not provided canopy will try to retrieve the name of the variable in the metadata.
field_b_label (str, optional) – Labels for the data series, if not provided canopy will try to retrieve the name of the variable in the metadata.
unit_a (str, optional) – Units for the data series, if not provided canopy will try to retrieve the unit of the variable in the metadata.
unit_b (str, optional) – Units for the data series, if not provided canopy will try to retrieve the unit of the variable in the metadata.
scatter_size (float, optional) – Marker size for scatter points. Default is 6.
scatter_alpha (float, optional) – Transparency (alpha) for scatter points. Default is 0.5.
title (str, optional) – Title of the plot.
palette (str, optional) – Seaborn color palette to use for the line colors (https://seaborn.pydata.org/tutorial/color_palettes.html, recommended palette are in https://colorbrewer2.org).
custom_palette (str, optional) – Path of custom color palette .txt file to use. Names should match label names.
move_legend (bool, optional) – Location of the legend (‘in’ or ‘out’). Default is False.
dark_mode (bool, optional) – Whether to apply dark mode styling to the plot.
transparent (bool, optional) – If True, makes the background of the figure transparent.
x_label_rotation (float, optional) – Rotation angle in degrees for the x-axis tick labels. Default is 0.
x_fig (float, optional) – Width of the figure in inches. Default is 10.
y_fig (float, optional) – Height of the figure in inches. Default is 10.
subfig (matplotlib.figure.SubFigure, optional) – If provided, the plot will be created in this subfigure instead of creating a new figure. This is used by multiple_figs() to combine multiple plots. User can also provide a plt.figure.subfigure object (https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html)
return_fig (bool, optional) – If True, return a callable wrapper function instead of creating the plot immediately. This wrapper can be used with multiple_figs(). Default is False.
**kwargs – Additional keyword arguments are passed directly to seaborn.regplot (if kind=’scatter’) or seaborn.histplot (if kind=’hist’). This allows customization of plot features.

canopy.visualization.taylor_diagram

Taylor diagram visualization.

canopy.visualization.taylor_diagram.make_taylor_diagram(fields: Field | List[Field], obs: Field, output_file: str | None = None, gridop: str | None = None, title: str | None = None, layers: List[str] | str | None = None, field_labels: List[str] | None = None, palette: str | None = None, custom_palette: str | None = None, dark_mode: bool = False, transparent: bool = False, marker_size: float = 100, marker: str = 'o', fontsize: int = 16, x_fig: float = 12, y_fig: float = 10, subfig=None, return_fig: bool = False, **kwargs) → Figure | None[source]

Create a Taylor diagram (https://pcmdi.llnl.gov/staff/taylor/CV/Taylor_diagram_primer.pdf) comparing model data against observations.

Note: This function requires all input fields and observations to have grid_type=’sites’.

Parameters:

fields (cp.Field or List[cp.Field]) – Model data Field(s) to compare against observations. If a list is provided, multiple fields will be plotted with one point per field.
obs (cp.Field) – Observation/reference data Field (typically the “truth”).
output_file (str, optional) – File path for saving the plot.
gridop (str, optional) – If provided, the grid reduction operation. Either None, ‘sum’ or ‘av’. Default is None.
title (str, optional) – Title of the plot.
layers (List[str] or str, optional) – Layer names to include. Defaults to all layers in the first field.
field_labels (List[str], optional) – Labels for each field when multiple fields are provided. Required when field is a list.
palette (str, optional) – Seaborn color palette to use (https://seaborn.pydata.org/tutorial/color_palettes.html).
custom_palette (str, optional) – Path of custom color palette .txt file to use. Names should match site labels.
dark_mode (bool, optional) – Whether to apply dark mode styling to the plot.
transparent (bool, optional) – If True, makes the background of the figure transparent.
marker_size (float, optional) – Size of the markers. Default is 100.
marker (str, optional) – Marker shape. Default is ‘o’ (circle).
fontsize (int, optional) – Font size for labels. Default is 16.
x_fig (float, optional) – Width of the figure in inches. Default is 12.
y_fig (float, optional) – Height of the figure in inches. Default is 12.
subfig (matplotlib.figure.SubFigure, optional) – If provided, the plot will be created in this subfigure instead of creating a new figure. This is used by multiple_figs() to combine multiple plots. User can also provide a plt.figure.subfigure object (https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html)
return_fig (bool, optional) – If True, return a callable wrapper function instead of creating the plot immediately. This wrapper can be used with multiple_figs(). Default is False.
**kwargs – Additional keyword arguments are passed directly to taylor.add_model_set. This allows customization of plot features such as linestyle, linewidth, etc.

canopy.visualization.line_plot.time_series

canopy.visualization.line_plot.time_series.make_time_series(fields: Field | List[Field], output_file: str | None = None, layers: List[str] | str | None = None, gridop: str | None = None, make_diff: bool = False, yaxis_label: str | None = None, yaxis_lim: List[float] | None = None, field_labels: List[str] | None = None, unit: str | None = None, title: str | None = None, palette: str | None = None, custom_palette: str | None = None, move_legend: bool = False, legend_style: str = 'default', reverse_hue_style: bool = False, max_labels_per_col: int = 15, baseline: bool = False, rolling_size: int | None = None, stacked: bool = False, relative: bool = False, dark_mode: bool = False, transparent: bool = False, x_label_rotation: float = 0, x_fig: float = 10, y_fig: float = 10, subfig=None, return_fig: bool = False, **kwargs) → Figure | None[source]

Create a time-series plot from the given fields.

Parameters:

fields (cp.Field or List[cp.Field]) – Input data Field or list of Fields to display.
output_file (str, optional) – File path for saving the plot.
layers (List[str] or str, optional) – List of layer names to display.
gridop (str, optional) – The reduction operation. Either ‘sum’, ‘av’ or None. Default is None.
make_diff (bool, optional) – Option to make the difference between two time-series. Default is False.
yaxis_label (str, optional) – Y-axis label, if not provided canopy will try to retrieve the name of the variable in the metadata.
yaxis_lim (List[float], optional) – List of y-axis limits.
field_labels (List[str], optional) – List of labels for the time series.
unit (str, optional) – Unit of the y-axis variable, if not provided canopy will try to retrieve the unit of the variable in the metadata.
title (str, optional) – Title of the plot.
palette (str, optional) – Seaborn color palette to use for the line colors (https://seaborn.pydata.org/tutorial/color_palettes.html, recommended palette are in https://colorbrewer2.org).
custom_palette (str, optional) – Path of custom color palette .txt file to use. Names should match label names.
move_legend (bool, optional) – Move the the legend outside of plot. Default is False.
legend_style (str or None, optional) – Style of the legend (‘default’, ‘highlighted’, ‘end-of-line’, ‘hidden’). If ‘hidden’, the legend will not be shown.
reverse_hue_style (bool, optional) – Reverse how seaborn uses hue for different time series and style for different layers. Default is False.
max_labels_per_col (int, optional) – Maximum number of labels per layer in the legend. Default is 15.
baseline (bool, optional) – Option to add a y=0 dotted line. Default is False.
rolling_size (int, optional) – Window of rolling mean. Only available when using a single dimension (multiple layers, multiple fields, or multiple gridcells).
stacked (bool, optional) – Option to create a stacked plot. Default is False.
relative (bool, optional) – Option to plot relative values. Default is False.
dark_mode (bool, optional) – Option to use dark mode. Default is False.
transparent (bool, optional) – Option to use a transparent background. Default is False.
x_label_rotation (float, optional) – Rotation angle in degrees for the x-axis tick labels. Default is 0.
x_fig (float, optional) – Width of the figure in inches. Default is 10.
y_fig (float, optional) – Height of the figure in inches. Default is 10.
subfig (matplotlib.figure.SubFigure, optional) – If provided, the plot will be created in this subfigure instead of creating a new figure. This is used by multiple_figs() to combine multiple plots. User can also provide a plt.figure.subfigure object (https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html)
return_fig (bool, optional) – If True, return a callable wrapper function instead of creating the plot immediately. This wrapper can be used with multiple_figs(). Default is False.
**kwargs – Additional keyword arguments are passed directly to seaborn.lineplot. This allows customization of line aesthetics such as linewidth, linestyle, alpha, etc.

canopy.visualization.line_plot.latitudinal_plot

canopy.visualization.line_plot.latitudinal_plot.make_latitudinal_plot(fields: Field | List[Field], output_file: str | None = None, layers: List[str] | str | None = None, yaxis_label: str | None = None, field_labels: List[str] | None = None, unit: str | None = None, title: str | None = None, palette: str | None = None, custom_palette: str | None = None, move_legend: bool | None = False, legend_style: str = 'default', max_labels_per_col: int = 15, dark_mode: bool = False, transparent: bool = False, x_label_rotation: float = 0, x_fig: float = 10, y_fig: float = 10, subfig=None, return_fig: bool = False, **kwargs) → Figure | None[source]

Create a latitudinal plot showing variable values as a function of latitude. The plot displays mean values averaged over time at each latitude.

Parameters:

fields (cp.Field or List[cp.Field]) – Input data Field or list of Fields to display.
output_file (str, optional) – File path for saving the plot.
layers (List[str] or str, optional) – List of layer names to display. If None, all layers from the first field are used.
yaxis_label (str, optional) – Y-axis label, if not provided canopy will try to retrieve the name of the variable in the metadata.
field_labels (List[str], optional) – List of labels for each field when multiple fields are provided. Required when multiple fields are used.
unit (str, optional) – Unit of the variable, if not provided canopy will try to retrieve the unit of the variable in the metadata.
title (str, optional) – Title of the plot.
palette (str, optional) – Seaborn color palette to use for the line colors (https://seaborn.pydata.org/tutorial/color_palettes.html, recommended palette are in https://colorbrewer2.org).
custom_palette (str, optional) – Path of custom color palette .txt file to use. Names should match label names.
move_legend (bool, optional) – Move the legend outside of plot. Default is False.
legend_style (str, optional) – Style of the legend (‘default’, ‘highlighted’, ‘end-of-line’, ‘hidden’). If ‘hidden’, the legend will not be shown. Default is ‘default’.
max_labels_per_col (int, optional) – Maximum number of labels per column in the legend. Default is 15.
dark_mode (bool, optional) – If True, apply dark mode styling. Default is False.
transparent (bool, optional) – If True, make the figure transparent. Default is False.
x_label_rotation (float, optional) – Rotation angle in degrees for the x-axis tick labels. Default is 0.
x_fig (float, optional) – Width of the figure in inches. Default is 10.
y_fig (float, optional) – Height of the figure in inches. Default is 10.
subfig (matplotlib.figure.SubFigure, optional) – If provided, the plot will be created in this subfigure instead of creating a new figure. This is used by multiple_figs() to combine multiple plots. User can also provide a plt.figure.subfigure object (https://matplotlib.org/stable/gallery/subplots_axes_and_figures/subfigures.html)
return_fig (bool, optional) – If True, return a callable wrapper function instead of creating the plot immediately. This wrapper can be used with multiple_figs(). Default is False.
**kwargs – Additional keyword arguments are passed directly to seaborn.lineplot. This allows customization of line aesthetics such as linewidth, linestyle, alpha, etc.