sisl.viz.Figure
- class sisl.viz.Figure(plot_actions, *args, **kwargs)[source]
Bases:
objectBase 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, ...])Sets the axes equal.
set_axis(**kwargs)Sets the axis parameters.
show()to(key)Converts the figure to another backend.
- Parameters:
plot_actions (list)
- draw_area_line(x, y, name=None, line={}, text=None, dependent_axis=None, row=None, col=None, **kwargs)[source]
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)[source]
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 (bool) – 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)[source]
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)[source]
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)[source]
Draws a heatmap following the specifications.
- draw_line(x, y, name=None, line={}, marker={}, text=None, row=None, col=None, **kwargs)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
By default, multicoloured lines are drawn simply by drawing scatter points.
- draw_multicolor_scatter(*args, **kwargs)[source]
Draws a multicoloured scatter.
Usually the normal scatter can already support this.
- draw_multicolor_scatter_3D(*args, **kwargs)[source]
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)[source]
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)[source]
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)[source]
By default, multisized lines are drawn simple by drawing scatter points.
- draw_multisize_scatter(*args, **kwargs)[source]
Draws a multisized scatter.
Usually the normal scatter can already support this.
- draw_multisize_scatter_3D(*args, **kwargs)[source]
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)[source]
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)[source]
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[source]
Whether the figure that this class generates has a given attribute.
- init_coloraxis(name, cmin=None, cmax=None, cmid=None, colorscale=None, showscale=True, **kwargs)[source]
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] = {})[source]