sisl.viz.Figure

class sisl.viz.Figure(plot_actions, *args, **kwargs)

Bases: object

Base figure class that all backends should inherit from.

It contains all the plotting actions that should be supported by a figure.

A subclass for a specific backend should implement as many methods as possible from the ones where Figure returns NotImplementedError. Other methods are optional because Figure contains a default implementation using other methods, which should work for most backends.

To create a new backend, one might take the PlotlyFigure as a template.

Methods

clear()	Clears the figure so that we can draw again.
draw_area_line(x, y[, name, line, text, ...])	Same as draw line, but to draw a line with an area.
draw_arrows(x, y, dxy[, arrowhead_scale, ...])	Draws multiple arrows using the generic draw_line method.
draw_arrows_3D(x, y, z, dxyz[, ...])	Draws multiple 3D arrows using the generic draw_line_3D method.
draw_balls_3D(x, y, z[, name, markers, row, col])	Draws points as 3D spheres.
draw_heatmap(values[, x, y, name, zsmooth, ...])	Draws a heatmap following the specifications.
draw_line(x, y[, name, line, marker, text, ...])	Draws a line satisfying the specifications
draw_line_3D(x, y, z[, name, line, marker, ...])	Draws a 3D line satisfying the specifications.
draw_mesh_3D(vertices, faces[, color, ...])	Draws a 3D mesh following the specifications.
draw_multicolor_area_line(x, y[, name, ...])	Draw a line with an area with multiple colours.
draw_multicolor_balls_3D(x, y, z[, name, ...])	Draws points as 3D spheres with different colours.
draw_multicolor_line(*args[, line, row, col])	By default, multicoloured lines are drawn simply by drawing scatter points.
draw_multicolor_line_3D(*args, **kwargs)	Draws a multicoloured 3D line.
draw_multicolor_scatter(*args, **kwargs)	Draws a multicoloured scatter.
draw_multicolor_scatter_3D(*args, **kwargs)	Draws a multicoloured 3D scatter.
draw_multisize_area_line(x, y[, name, line, ...])	Draw a line with an area with multiple colours.
draw_multisize_balls_3D(x, y, z[, name, ...])	Draws points as 3D spheres with different sizes.
draw_multisize_line(*args[, line, row, col])	By default, multisized lines are drawn simple by drawing scatter points.
draw_multisize_line_3D(*args, **kwargs)	Draws a multisized 3D line.
draw_multisize_scatter(*args, **kwargs)	Draws a multisized scatter.
draw_multisize_scatter_3D(*args, **kwargs)	Draws a multisized 3D scatter.
draw_scatter(x, y[, name, marker, text, ...])	Draws a scatter satisfying the specifications
draw_scatter_3D(x, y, z[, name, marker, ...])	Draws a 3D scatter satisfying the specifications
fig_has_attr(key)	Whether the figure that this class generates has a given attribute.
init_3D()	Called if functions that draw in 3D are going to be called.
init_coloraxis(name[, cmin, cmax, cmid, ...])	Initializes a color axis to be used by the drawing functions
init_figure([composite_method, ...])
set_axes_equal()	Sets the axes equal.
set_axis(**kwargs)	Sets the axis parameters.
show()

Attributes

plot_actions

clear()

Clears the figure so that we can draw again.

draw_area_line(x, y, name=None, line={}, text=None, dependent_axis=None, row=None, col=None, **kwargs)

Same as draw line, but to draw a line with an area. This is for example used to draw fatbands.

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• name (str, optional) – the name of the scatter

• line (dict, optional) – specifications for the line style, following plotly standards. The backend should at least be able to implement line[“color”] and line[“width”], but it is very advisable that it supports also line[“opacity”].

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• dependent_axis (str, optional) – The axis that contains the dependent variable. This is important because the area is drawn in parallel to that axis.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the scatter. This will of course be framework specific

draw_arrows(x, y, dxy, arrowhead_scale=0.2, arrowhead_angle=20, scale: float = 1, annotate: bool = False, row=None, col=None, **kwargs)

Draws multiple arrows using the generic draw_line method.

Parameters:

• xy (np.ndarray of shape (n_arrows, 2)) – the positions where the atoms start.

• dxy (np.ndarray of shape (n_arrows, 2)) – the arrow vector.

• arrow_head_scale (float, optional) – how big is the arrow head in comparison to the arrow vector.

• arrowhead_angle (angle) – the angle that the arrow head forms with the direction of the arrow (in degrees).

• scale (float, optional) – multiplying factor to display the arrows. It does not affect the underlying data, therefore if the data is somehow displayed it should be without the scale factor.

• annotate – whether to annotate the arrows with the vector they represent.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

draw_arrows_3D(x, y, z, dxyz, arrowhead_scale=0.3, arrowhead_angle=15, scale: float = 1, row=None, col=None, **kwargs)

Draws multiple 3D arrows using the generic draw_line_3D method.

Parameters:

• x (np.ndarray of shape (n_arrows, )) – the X coordinates of the arrow’s origin.

• y (np.ndarray of shape (n_arrows, )) – the Y coordinates of the arrow’s origin.

• z (np.ndarray of shape (n_arrows, )) – the Z coordinates of the arrow’s origin.

• dxyz (np.ndarray of shape (n_arrows, 2)) – the arrow vector.

• arrow_head_scale (float, optional) – how big is the arrow head in comparison to the arrow vector.

• arrowhead_angle (angle) – the angle that the arrow head forms with the direction of the arrow (in degrees).

• scale (float, optional) – multiplying factor to display the arrows. It does not affect the underlying data, therefore if the data is somehow displayed it should be without the scale factor.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

draw_balls_3D(x, y, z, name=None, markers={}, row=None, col=None, **kwargs)

Draws points as 3D spheres.

draw_heatmap(values, x=None, y=None, name=None, zsmooth=False, coloraxis=None, opacity=None, textformat=None, textfont={}, row=None, col=None, **kwargs)

Draws a heatmap following the specifications.

draw_line(x, y, name=None, line={}, marker={}, text=None, row=None, col=None, **kwargs)

Draws a line satisfying the specifications

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• name (str, optional) – the name of the line

• line (dict, optional) – specifications for the line style, following plotly standards. The backend should at least be able to implement line[“color”] and line[“width”]

• marker (dict, optional) – specifications for the markers style, following plotly standards. The backend should at least be able to implement marker[“color”] and marker[“size”]

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the line. This will of course be framework specific

draw_line_3D(x, y, z, name=None, line={}, marker={}, text=None, row=None, col=None, **kwargs)

Draws a 3D line satisfying the specifications.

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• z (array-like) – the coordinates of the points along the Z axis.

• name (str, optional) – the name of the line

• line (dict, optional) – specifications for the line style, following plotly standards. The backend should at least be able to implement line[“color”] and line[“width”]

• marker (dict, optional) – specifications for the markers style, following plotly standards. The backend should at least be able to implement marker[“color”] and marker[“size”]

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the line. This will of course be framework specific

draw_mesh_3D(vertices, faces, color=None, opacity=None, name=None, row=None, col=None, **kwargs)

Draws a 3D mesh following the specifications.

draw_multicolor_area_line(x, y, name=None, line={}, text=None, dependent_axis=None, row=None, col=None, **kwargs)

Draw a line with an area with multiple colours.

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• name (str, optional) – the name of the scatter

• line (dict, optional) – specifications for the line style, following plotly standards. The backend should at least be able to implement line[“color”] and line[“width”], but it is very advisable that it supports also line[“opacity”].

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• dependent_axis (str, optional) – The axis that contains the dependent variable. This is important because the area is drawn in parallel to that axis.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the scatter. This will of course be framework specific

draw_multicolor_balls_3D(x, y, z, name=None, marker={}, row=None, col=None, **kwargs)

Draws points as 3D spheres with different colours.

If marker_color is an array of numbers, a coloraxis is created and values are converted to rgb.

draw_multicolor_line(*args, line={}, row=None, col=None, **kwargs)

By default, multicoloured lines are drawn simply by drawing scatter points.

draw_multicolor_line_3D(*args, **kwargs)

Draws a multicoloured 3D line.

draw_multicolor_scatter(*args, **kwargs)

Draws a multicoloured scatter.

Usually the normal scatter can already support this.

draw_multicolor_scatter_3D(*args, **kwargs)

Draws a multicoloured 3D scatter.

Usually the normal 3D scatter can already support this.

draw_multisize_area_line(x, y, name=None, line={}, text=None, dependent_axis=None, row=None, col=None, **kwargs)

Draw a line with an area with multiple colours.

This is already usually supported by the normal draw_area_line.

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• name (str, optional) – the name of the scatter

• line (dict, optional) – specifications for the line style, following plotly standards. The backend should at least be able to implement line[“color”] and line[“width”], but it is very advisable that it supports also line[“opacity”].

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• dependent_axis (str, optional) – The axis that contains the dependent variable. This is important because the area is drawn in parallel to that axis.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the scatter. This will of course be framework specific

draw_multisize_balls_3D(x, y, z, name=None, marker={}, row=None, col=None, **kwargs)

Draws points as 3D spheres with different sizes.

Usually supported by the normal draw_balls_3D

draw_multisize_line(*args, line={}, row=None, col=None, **kwargs)

By default, multisized lines are drawn simple by drawing scatter points.

draw_multisize_line_3D(*args, **kwargs)

Draws a multisized 3D line.

draw_multisize_scatter(*args, **kwargs)

Draws a multisized scatter.

Usually the normal scatter can already support this.

draw_multisize_scatter_3D(*args, **kwargs)

Draws a multisized 3D scatter.

Usually the normal 3D scatter can already support this.

draw_scatter(x, y, name=None, marker={}, text=None, row=None, col=None, **kwargs)

Draws a scatter satisfying the specifications

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• name (str, optional) – the name of the scatter

• marker (dict, optional) – specifications for the markers style, following plotly standards. The backend should at least be able to implement marker[“color”] and marker[“size”], but it is very advisable that it supports also marker[“opacity”] and marker[“colorscale”]

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the scatter. This will of course be framework specific

draw_scatter_3D(x, y, z, name=None, marker={}, text=None, row=None, col=None, **kwargs)

Draws a 3D scatter satisfying the specifications

Parameters:

• x (array-like) – the coordinates of the points along the X axis.

• y (array-like) – the coordinates of the points along the Y axis.

• z (array-like) – the coordinates of the points along the Z axis.

• name (str, optional) – the name of the scatter

• marker (dict, optional) – specifications for the markers style, following plotly standards. The backend should at least be able to implement marker[“color”] and marker[“size”]

• text (str, optional) – contains the text asigned to each marker. On plotly this is seen on hover, other options could be annotating. However, it is not necessary that this argument is supported.

• row (int, optional) – If the figure contains subplots, the row where to draw.

• col (int, optional) – If the figure contains subplots, the column where to draw.

• **kwargs – should allow other keyword arguments to be passed directly to the creation of the scatter. This will of course be framework specific

classmethod fig_has_attr(key: str) → bool

Whether the figure that this class generates has a given attribute.

Parameters:

key – the attribute to check for.

init_3D()

Called if functions that draw in 3D are going to be called.

init_coloraxis(name, cmin=None, cmax=None, cmid=None, colorscale=None, showscale=True, **kwargs)

Initializes a color axis to be used by the drawing functions

init_figure(composite_method: Literal[None, 'same_axes', 'multiple', 'multiple_x', 'multiple_y', 'subplots', 'animation'] = None, plot_actions=(), init_kwargs: dict[str, Any] = {})

set_axes_equal()

Sets the axes equal.

set_axis(**kwargs)

Sets the axis parameters.

The specification for the axes is exactly the plotly one. This is to have a good reference for consistency. Other frameworks should translate the calls to their functionality.

show()

to(key: str)

Converts the figure to another backend.

Parameters:

key (str) – the backend to convert to.

plot_actions: list = []