The `Canvas` Class and Subclasses

class src.matnimation.canvas.canvas.Canvas(figsize: tuple, dpi: int, time_array: ndarray[float])

Bases: object

__init__(figsize: tuple, dpi: int, time_array: ndarray[float])

Initialize Canvas.

Parameters:

figsize (tuple) – Figure size (width, height) in inches
dpi (int) – Dots per inch, resolution of canvas
time_array (np.ndarray) – Array representing time steps in animation

add_legend(axes: Axes, legend_handles: set, **legend_styling)

Add a legend to the canvas.

Parameters:

axes (Axes) – Matplotlib Axes object to add legend to
legend_handles (set) – Set of legend handles
**legend_styling (dict) – Keyword arguments for styling the legend, all kwargs (‘Other Parameters’) of Matplotlib’s Axes.legend() may be passed here.

get_axs_array()

Get the array of Axes objects.

Returns:: self.axs_array – Array of Axes objects
Return type:: np.ndarray

get_figure() → Figure

Get the canvas figure.

Returns:: self.fig – The canvas figure
Return type:: Figure

save_canvas(filename: str)

Save the canvas figure to a file.

Parameters:: filename (str) – Name of the file to save as

set_figure_properties(**figure_styling)

Set styling properties of the canvas figure.

Parameters:: **figure_styling (dict) – Styling keyword arguments for Matplotlib Figure object

set_layout(fig: Figure, axs_array: ndarray[Axes], axes_limits: list[float], axes_labels: list[str])

Set the layout of the canvas.

Parameters:

fig (Figure) – Matplotlib Figure object
axs_array (np.ndarray) – Array of Axes objects
axes_limits (list[float]) – List of axis limits in the form [[xmin, xmax, ymin, ymax], …]
axes_labels (list[str]) – List of axis labels in the form [[xlabel, ylabel], …]

Note

In axes_limits and axes_labels, first sublist corresponds to first Axes object in axs_array. Order is left-right then top-bottom through possible subplots.

update_frame(time_index: int)

Update the canvas for a given time index.

Parameters:: time_index (int) – Index representing time

class src.matnimation.canvas.custom_canvas.CustomCanvas(figsize: tuple, dpi: int, time_array: ndarray[float], mosaic: list, axes_limits: list, axes_labels: list, shared_x=False, shared_y=False, width_ratios=None, height_ratios=None, gridspec_kw=None)

Bases: Canvas

__init__(figsize: tuple, dpi: int, time_array: ndarray[float], mosaic: list, axes_limits: list, axes_labels: list, shared_x=False, shared_y=False, width_ratios=None, height_ratios=None, gridspec_kw=None)

Initialize a CustomCanvas instance.

Parameters:

figsize (tuple) – Figure size (width, height) in inches
dpi (int) – Dots per inch, resolution of canvas
time_array (np.ndarray) – Array representing time steps in animation
mosaic (list) – List specifying the layout of subplots, e.g., [[‘Axes 1’, ‘Axes 1’], [‘Axes 2’, ‘Axes 3’]] Here ‘Axes 1’ spans the entire first row, ‘Axes 2’ (‘Axes 3’) is on second row first (second) column
axes_limits (list) – 2D list with axes limits [[xmin, xmax, ymin, ymax], …] Order of subplots in list is left-to-right then top-to-bottom.
axes_labels (list) – 2D list with axes labels [[‘xlabel’, ‘ylabel’], …] Order of subplots in list is left-to-right then top-to-bottom.
shared_x (bool, optional) – Whether x-axis of subplots is shared, by default False
shared_y (bool, optional) – Whether y-axis of subplots is shared, by default False
width_ratios (list, optional) – Width ratios of subplots, by default None
height_ratios (list, optional) – Height ratios of subplots, by default None
gridspec_kw (dict, optional) – Additional keyword arguments for specifying the layout, by default None

add_artist(artist: BaseArtist, axes_key: str, in_legend=False)

Add an artist to a specific subplot/Axes.

Parameters:

artist (BaseArtist) – Artist object to add
axes_key (str) – Key representing the desired subplot
in_legend (bool, optional) – Whether the artist should be included in the subplot’s legend, by default False

construct_legend(axes_key: str, **legend_styling)

Construct a legend for a specific subplot, if legend handles are available.

Parameters:

axes_key (str) – Key representing the desired subplot/Axes
**legend_styling (dict) – Keyword arguments for styling the legend

get_axis(axis_key: str) → Axes

Get the Axes object corresponding to a specific subplot.

Parameters:: axis_key (str) – Key representing the desired subplot/Axes
Returns:: ax – Matplotlib Axes object corresponding to the specified subplot
Return type:: Axes

set_axis_properties(axis_key: str, **axis_styling)

Set styling properties for a specific subplot.

Parameters:

axis_key (str) – Key representing the desired subplot/Axes
**axis_styling (dict) – Keyword arguments for styling the subplot

class src.matnimation.canvas.grid_canvas.GridCanvas(figsize: tuple, dpi: int, time_array: ndarray[float], nrows: int, ncols: int, spans: list[list], axes_keys: list[str], axes_limits: list, axes_labels: list, width_ratios=None, height_ratios=None)

Bases: Canvas

__init__(figsize: tuple, dpi: int, time_array: ndarray[float], nrows: int, ncols: int, spans: list[list], axes_keys: list[str], axes_limits: list, axes_labels: list, width_ratios=None, height_ratios=None)

Initialize a GridCanvas instance.

Parameters:

figsize (tuple) – Figure size (width, height) in inches
dpi (int) – Dots per inch, resolution of canvas
time_array (np.ndarray) – Array representing time steps in animation
nrows (int) – Number of rows in the grid of subplots
ncols (int) – Number of columns in the grid of subplots
spans (list[list]) –
List indicating the span of each subplot Each sublist [span_row, span_col] defines the span of a subplot, span_row and span_col can be either an int or list of length 2.

Example: Suppose that nrows = 2, ncols = 2 and spans = [[0, [0,1]], [1,0], [1,1]] Here the first subplot spans the entire first row, the second spans row 1, col 0 and the third spans row 1, col 1.
axes_keys (list[str]) – List of keys identifying each subplot, order of subplots is the same as in spans. Lenght must be equal to spans as well.
axes_limits (list) – 2D list with axes limits [[xmin, xmax, ymin, ymax], …], order of subplots is the same as in spans. Lenght must be equal to spans as well.
axes_labels (list) – 2D list with axes labels [[‘xlabel’, ‘ylabel’], …], order of subplots is the same as in spans. Lenght must be equal to spans as well.
width_ratios (list, optional) – Width ratios of subplots, by default None
height_ratios (list, optional) – Height ratios of subplots, by default None

add_artist(artist: BaseArtist, axes_key: str, in_legend=False)

Add an artist to a specific subplot.

Parameters:

artist (BaseArtist) – Artist object to add
axes_key (str) – Key representing the desired subplot
in_legend (bool, optional) – Whether the artist should be included in the subplot’s legend, by default False

construct_legend(axes_key: str, **legend_styling)

Construct a legend for a specific subplot, if legend handles are available.

Parameters:

axes_key (str) – Key representing the desired subplot
**legend_styling (dict) – Keyword arguments for styling the legend

get_axis(axes_key: str)

Get the Axes object corresponding to a specific subplot.

Parameters:: axes_key (str) – Key representing the desired subplot
Returns:: ax – Matplotlib Axes object corresponding to the specified subplot
Return type:: Axes

set_axis_properties(axes_key: str, **axis_styling)

Set styling properties for a specific subplot.

Parameters:

axes_key (str) – Key representing the desired subplot
**axis_styling (dict) – Keyword arguments for styling the subplot

class src.matnimation.canvas.multi_canvas.MultiCanvas(figsize: tuple, dpi: int, time_array: ndarray[float], nrows: int, ncols: int, axes_limits: list, axes_labels: list, shared_x=False, shared_y=False, height_ratios: list | None = None, width_ratios: list | None = None)

Bases: Canvas

A canvas for creating multi-axis plots with a grid layout. This class extends the functionality of the base Canvas class and allows for creating a grid of subplots.

__init__(figsize: tuple, dpi: int, time_array: ndarray[float], nrows: int, ncols: int, axes_limits: list, axes_labels: list, shared_x=False, shared_y=False, height_ratios: list | None = None, width_ratios: list | None = None)

Initialize a MultiCanvas instance.

Parameters:

figsize (tuple) – Figure size (width, height) in inches
dpi (int) – Dots per inch, resolution of canvas
time_array (np.ndarray) – Array representing time steps in animation
nrows (int) – Number of rows in the grid of subplots
ncols (int) – Number of columns in the grid of subplots
axes_limits (list) – 2D list with axes limits [[xmin, xmax, ymin, ymax], …] Order of subplots in list is left-to-right then top-to-bottom.
axes_labels (list) – 2D list with axes labels [[‘xlabel’, ‘ylabel’], …] Order of subplots in list is left-to-right then top-to-bottom.
shared_x (bool, optional) – Whether x-axis of subplots is shared, by default False
shared_y (bool, optional) – Whether y-axis of subplots is shared, by default False
height_ratios (list, optional) – Ratio of heights of different subplots
width_ratios (list, optional) – Ratio of widths of different subplots

add_artist(artist: BaseArtist, row: int, col: int, in_legend=False)

Add an artist to a specific subplot.

Parameters:

artist (BaseArtist) – Artist object to add
row (int) – Row index of the subplot in the grid
col (int) – Column index of the subplot in the grid
in_legend (bool, optional) – Whether the artist should be included in the subplot’s legend, by default False

construct_legend(row: int, col: int, **legend_styling)

Construct a legend for a specific subplot, if legend handles are available.

Parameters:

row (int) – Row index of the subplot in the grid
col (int) – Column index of the subplot in the grid
**legend_styling (dict) – Keyword arguments for styling the legend

get_axis(row: int, col: int) → Axes

Get the Axes object corresponding to a specific subplot.

Parameters:

row (int) – Row index of the subplot in the grid
col (int) – Column index of the subplot in the grid

Returns:

ax – Matplotlib Axes object corresponding to the specified subplot

Return type:

Axes

set_axis_properties(row: int, col: int, **axis_styling)

Set styling properties for a specific subplot.

Parameters:

row (int) – Row index of the subplot in the grid
col (int) – Column index of the subplot in the grid
**axis_styling (dict) – Keyword arguments for styling the subplot

class src.matnimation.canvas.single_canvas.SingleCanvas(figsize: tuple, dpi: int, time_array: ndarray[float], axis_limits: list, axis_labels: list)

Bases: Canvas

__init__(figsize: tuple, dpi: int, time_array: ndarray[float], axis_limits: list, axis_labels: list)

Initialize a SingleCanvas instance.

Parameters:

figsize (tuple) – Figure size (width, height) in inches
dpi (int) – Dots per inch, resolution of canvas
time_array (np.ndarray) – Array representing time steps in animation
axis_limits (list) – 1D list with axis limits [xmin, xmax, ymin, ymax]
axis_labels (list) – 1D list with axis labels [‘xlabel’, ‘ylabel’]

add_artist(artist: BaseArtist, in_legend=False)

Add an artist to the single canvas.

Parameters:

artist (BaseArtist) – Artist object to add
in_legend (bool, optional) – Whether the artist should be included in the canvas’s legend, by default False

construct_legend(**legend_styling)

Construct legend for the single canvas, if legend handles collection is not empty.

Parameters:: **legend_styling (dict) – Keyword arguments for styling the legend

get_axis() → Axes

Get the Axes object for the single canvas.

Returns:: self.ax – Matplotlib Axes object for the canvas
Return type:: Axes

set_axis_properties(**axis_styling)

Set styling properties for the single canvas.

Parameters:: **axis_styling (dict) – Keyword arguments for styling the canvas

The Canvas Class and Subclasses

The `Canvas` Class and Subclasses