graphinglib.SmartFigure

class graphinglib.SmartFigure(num_rows: int = 1, num_cols: int = 1, x_label: str | None = None, y_label: str | None = None, size: tuple[float, float] | Inherit = Inherit, title: str | None = None, x_lim: ListOrItem[tuple[float, float] | None] = None, y_lim: ListOrItem[tuple[float, float] | None] = None, sub_x_labels: Iterable[str] | None = None, sub_y_labels: Iterable[str] | None = None, subtitles: Iterable[str] | None = None, log_scale_x: ListOrItem[bool] = False, log_scale_y: ListOrItem[bool] = False, remove_axes: ListOrItem[bool] = False, aspect_ratio: ListOrItem[float | Literal['auto', 'equal']] = 'auto', box_aspect_ratio: ListOrItem[float | None] = None, remove_x_ticks: ListOrItem[bool] = False, remove_y_ticks: ListOrItem[bool] = False, invert_x_axis: ListOrItem[bool] = False, invert_y_axis: ListOrItem[bool] = False, reference_labels: ListOrItem[bool] = True, global_reference_label: bool = False, reference_labels_loc: ListOrItem[Literal['inside', 'outside'] | tuple[float, float]] = 'outside', width_padding: float = None, height_padding: float = None, width_ratios: ArrayLike = None, height_ratios: ArrayLike = None, share_x: bool = False, share_y: bool = False, projection: ListOrItem[Any | None] = None, general_legend: bool = False, legend_loc: ListOrItem[str | tuple | None] = None, legend_cols: ListOrItem[int] = 1, show_legend: ListOrItem[bool] = True, twin_x_axis: SmartTwinAxis | None = None, twin_y_axis: SmartTwinAxis | None = None, figure_style: str | Inherit = Inherit, elements: Plottable | Iterable[Plottable | SmartFigure | None] | Iterable[Iterable[Plottable | None]] = [], annotations: Iterable[Text] | None = None)

This class implements a figure object for plotting Plottable elements.

It allows for the creation of complex figures recursively, where each SmartFigure can contain other SmartFigure objects. The class supports a variety of customization options as well as the ability to use styles and themes for consistent visual appearance across different figures. A SmartFigure can either be used directly as a single plot containing Plottable objects, or as a layout that arranges child SmartFigure objects on a grid. The idea behind this class is that every SmartFigure contains a single x_label, y_label, title, projection, etc. and that nested SmartFigures can be inserted into the main SmartFigure to create complex figures with more parameters.

Parameters:

num_rows, num_colsint, optional

Number of rows and columns for the base grid. These parameters determine the number of “squares” on which the plots can be placed. Defaults to 1.

x_label, y_labelstr, optional

Labels for the x and y axes of the figure.

sizetuple[float, float], optional

Overall size of the figure. Note that this option is useless if the SmartFigure is nested inside another SmartFigure, as the size is then determined by the parent SmartFigure and the available space. Figure size is in inches; typical width is 4 to 12 and typical height is 3 to 8. Default depends on the figure_style configuration.

titlestr, optional

General title of the figure.

x_lim, y_limtuple[float, float] | list[tuple[float, float]], optional

Limits for the x and y axes of the figure. This can be given as a single value or a list of values to apply to each subplot.

sub_x_labels, sub_y_labelsIterable[str], optional

Labels for the x and y axes of each subfigure, respectively. This is only useful for figures that are not a single subplot and when each subfigure needs its own x and y labels. This prevents the creation of nested SmartFigure objects for each subfigure only to set the x and y labels. This list cannot be longer than the number of subfigures drawn by the SmartFigure and None values can be used to skip specific subfigures.

subtitlesIterable[str], optional

Labels for the subtitles of each subfigure, respectively. Similarly to sub_x_labels and sub_y_labels, this allows to set subtitles for each subfigure without needing to create nested SmartFigure objects. It is only useful for figures that are not a single subplot and when each subfigure needs its own subtitle. This list cannot be longer than the number of subfigures drawn by the SmartFigure and None values can be used to skip specific subfigures.

log_scale_x, log_scale_ybool | list[bool], optional

Whether to use a logarithmic scale for the x and y axes, respectively. This can be given as a single value or a list of values to apply to each subplot. Defaults to False.

remove_axesbool | list[bool], optional

Whether to remove the axes from the figure. This can be given as a single boolean or a list of booleans to apply to each subplot. Defaults to False.

aspect_ratiofloat | Literal[“auto”, “equal”] | list[float | Literal[“auto”, “equal”]], optional

Aspect ratio of the figure. If set to “auto”, the aspect ratio is determined automatically to fill the available space. If set to “equal”, the aspect ratio is set to 1:1. If set to a float, the aspect ratio represents the ratio of the height to the width of the data. This can be given as a single value or a list of values to apply to each subplot. Values are "equal", "auto", or a positive float. Defaults to "auto".

Warning

This parameter must not be confused with the box_aspect_ratio parameter, which is the aspect ratio of the box containing the elements. The aspect_ratio parameter is the aspect ratio of the data itself, which does not change the size of the plot but rather how the data is displayed within the plot.

box_aspect_ratiofloat | list[float], optional

Aspect ratio of the box containing the elements, i.e. the ratio of the height to the width of the plot. This can be given as a single value or a list of values to apply to each subplot.

Warning

This parameter must not be confused with the aspect_ratio parameter, which is the aspect ratio of the data itself. The box_aspect_ratio parameter changes the size of the plot, which does not affect the figure’s axes.

remove_x_ticks, remove_y_ticksbool | list[bool], optional

Whether to remove the x and y ticks from the figure, respectively. This can be given as a single value or a list of values to apply to each subplot. Defaults to False.

invert_x_axis, invert_y_axisbool | list[bool], optional

Whether to invert the x and y axes, respectively. This can be given as a single value or a list of values to apply to each subplot. Defaults to False.

reference_labelsbool | list[bool], optional

Whether or not to add reference labels to the subfigures. If set to True, each subfigure will be labeled alphabetically in the form of “a)”, “b)”, etc. This can be given as a single value or a list of values to apply to each subplot. Defaults to True.

Note

For nested figures, each subfigure controls its own reference labels. This means that if a nested SmartFigure turns off reference labels, the plots in it will not be labeled, even if the parent SmartFigure has reference labels turned on.

global_reference_labelbool, optional

Whether to use a single reference label for the entire figure instead of individual labels for each subfigure. If set to True, the reference label will be placed in the top left corner of the global SmartFigure. This is useful for labeling the entire figure rather than individual subfigures. Defaults to False.

Warning

As the global reference label is placed more left than the reference label, this forces the horizontal shift of the axes, which may lead to overlapping between axes. Consider modifying the size or width_padding parameters to avoid this issue.

reference_labels_locLiteral[“inside”, “outside”] | tuple[float, float] | list, optional

Location of the reference labels of the SubFigures, which can be either "inside", "outside", or a tuple of (x, y) relative coordinates to the top-left corner of each subfigure. This can be given as a single value or a list of values to apply to each subplot. Defaults to "outside".

width_padding, height_paddingfloat, optional

Padding between the subfigures in the x and y directions, respectively. The default value of None results in a default small amount of padding. This may be set to 0 to completely remove the space between subfigures, but note that axes labels may need to be removed to delete additional space.

width_ratios, height_ratiosArrayLike, optional

Ratios of the widths and heights of the subfigures, respectively. These ratios determine how much space each column and row of subfigures will take up in the overall figure. The length of these arrays must match the number of columns and rows, respectively. By default, all subfigures are given equal space.

share_x, share_ybool, optional

Whether to share the x and y axes between subfigures, respectively. This means that all subfigures will have the same x and y limits, and the ticks will be shared as well. This is useful for comparing data across subfigures.

Note

Sharing axes only works for plots drawn directly in the SmartFigure. If you insert an existing nested SmartFigure, that nested figure keeps its own axes sharing settings.

projectionAny | list[Any], optional

Projection type for the subfigures. This can be a string of a matplotlib projection (e.g., “polar”) or an object capable of creating a projection (e.g. astropy.wcs.WCS). This can be given as a single value or a list of values to apply to each subplot.

Note

3D projections are not supported at the moment.

general_legendbool, optional

Whether to create a general legend for the entire figure. If set to True, a single legend will be created to regroup all the legends from the subplots. If set to False, all subplots will have their own legend. If nested SmartFigures set this parameter to False, their legend is added to the parent’s general legend. However, if a nested SmartFigure sets its general legend to True, it will be created separately and will not be added to the parent’s general legend. Defaults to False.

legend_locstr | tuple | list[str | tuple], optional

Location of the legend. This can be a string (e.g., “upper right”) or a tuple of (x, y) relative coordinates. The supported string locations are: {“upper right”, “upper left”, “lower left”, “lower right”, “right”, “center left”, “center right”, “lower center”, “upper center”, “center”, “outside upper center”, “outside center right”, “outside lower center”, “outside center left”}. Additionally, only if general_legend is set to False, the legend location can also be set to “best”. This option can be given as a single value or a list of values to apply to each subplot. Defaults to "best" if general_legend is set to False, otherwise it defaults to "lower center".

Warning

If general_legend is set to True and the legend location is set to a position containing “outside”, the legend may not be displayed correctly in some matplotlib backends. In such cases, it is recommended to use inline figures in a Jupyter notebook or save the figure to a file to ensure proper display of the legend outside the figure.

legend_colsint | list[int], optional

Number of columns to display the labels in the legend. This is only used if the legend is displayed. This can be given as a single value or a list of values to apply to each subplot. Defaults to 1.

show_legendbool | list[bool], optional

Whether to show the legend for the figure. This allows to easily toggle the visibility of the legend. This can be given as a single value or a list of values to apply to each subplot. Defaults to True.

twin_x_axis, twin_y_axisSmartTwinAxis, optional

Twin axes for the x and y axes, respectively. This allows to attach additional axes to the main axes of the SmartFigure, which can be useful for displaying additional information or data on the same plot without cluttering the main axes. The twin axes can be used to plot additional data with different scales or units. See the SmartTwinAxis class for more details on how to use twin axes and the create_twin_axis() method for wrapping the creation of twin axes.

figure_stylestr, optional

The figure style to use for the figure. The default style can be set using gl.set_default_style(). Defaults to "default".

elementsPlottable | Iterable[Plottable | SmartFigure | None] | Iterable[Iterable[Plottable | None]], optional

The elements to plot in the figure. For a standalone SmartFigureSmartFigure, this can be a single Plottable or an iterable of Plottable objects to plot in the figure. For a SmartFigure with multiple cells, passing a single Plottable will add it in the first cell of the figure. If an iterable is provided for a figure with multiple cells, the items are assigned to the cells from left-to-right, top-to-bottom. Each item can be a child SmartFigure, a Plottable, an iterable of Plottable objects, or None. The iterable can be shorter than the total number of cells, in which case the remaining cells are left empty. If a SmartFigure is provided, it occupies exactly one cell in the parent figure. Its num_rows and num_cols only describe its internal layout.

Note

The elements parameter does not use a child SmartFigure’s shape to determine how much space it occupies in the parent. If you want a bare Plottable, an iterable of Plottables, or a child SmartFigure to span multiple subplots in the parent, you should use the __setitem__ method instead. For example, to add an element spanning the complete first row , use fig[0,:] = element.

annotationsIterable[Text], optional

Text annotations to add on the figure. The provided Text elements must have figure-relative coordinates, i.e. in the range [0, 1] for both x and y. This allows to add annotations that are not tied to a specific subplot, for example, to add general notes or labels on the figure.

Methods

__init__([num_rows, num_cols, x_label, ...])
add_elements(*elements)	Adds one or more Plottable objects to the current SmartFigure.
copy()	Returns a deep copy of the SmartFigure object.
copy_with(**kwargs)	Returns a deep copy of the SmartFigure with specified attributes overridden.
create_twin_axis([is_y, label, axis_lim, ...])	Creates a twin axis for the SmartFigure.
save(file_name[, dpi, transparent, split_pdf])	Saves the SmartFigure to a file.
set_custom_legend([elements, reset])	Sets a custom legend for the figure.
set_grid([reset, visible_x, visible_y, ...])	Sets the grid parameters for the figure.
set_rc_params([rc_params_dict, reset])	Customize the visual style of the SmartFigure.
set_reference_labels_params([reset, color, ...])	Sets advanced parameters for the reference labels that can be added to the subplots.
set_text_padding_params([reset, ...])	Sets the padding parameters for the figure's text elements.
set_tick_params([axis, which, reset, ...])	Sets the tick parameters for the figure.
set_ticks([reset, x_ticks, y_ticks, ...])	Sets custom ticks and tick labels.
set_visual_params([reset, ...])	Customize the visual style of the SmartFigure.
show([fullscreen])	Plots and displays the SmartFigure.
__iter__()	Iterates over the immediate contents of the SmartFigure.
__len__()	Gives the number of immediate contents in the SmartFigure.
__getitem__(key)	Gives the child SmartFigure at the specified key in the SmartFigure.
__setitem__(key, element)	Assigns a Plottable, a list of Plottable objects, or a SmartFigure to a specified position in the SmartFigure.
show_grid	Whether to show the grid lines on the figure.
hide_custom_legend_elements	Whether to hide custom legend elements.
hide_default_legend_elements	Whether to hide default legend elements.
is_single_subplot	Whether the SmartFigure currently behaves as a single plot.