graph

py4vasp.graph.Contour

(

  • data: array,
  • lattice: Plane,
  • label: str,
  • colorbar_label: str = None,
  • isolevels: bool = False,
  • show_contour_values: bool = None,
  • color_scheme: str = ‘auto’,
  • color_limits: tuple = None,
  • traces_as_periodic: bool = False,
  • supercell: array = (1, 1),
  • show_cell: bool = True,
  • max_number_arrows: int = None,
  • scale_arrows: float = None

)

Represents data on a 2d slice through the unit cell.

This class creates a visualization of the data within the unit cell based on its configuration. Currently it supports the creation of heatmaps and quiver plots. For heatmaps each data point corresponds to one point on the grid. For quiver plots each data point should be a 2d vector within the plane.

color_limits

: tuple = None

Is a tuple that sets the minimum and maximum of the color scale. Can be:

  • None | (None, None): No limits are imposed.
  • (float, None): Sets the minimum of the color scale.
  • (None, float): Sets the maximum of the color scale.
  • (float, float): Sets minimum and maximum of the color scale.

color_scheme

: str = ‘auto’

The color_scheme argument informs the chosen color map and parameters for the contours plot. It should be chosen according to the nature of the data to be plotted, as one of the following:

  • “auto” (Default): py4vasp will try to infer the color scheme on its own.
  • “monochrome” OR “stm”: Standard colorscheme for STM.
  • “sequential”: Use a sequential color scheme.
  • “positive”: Values are only positive. Use a Reds color scheme. Consider setting color_limits=(0, None).
  • “diverging”: Use a diverging color scheme.
  • “negative”: Values are only negative. Use a reverse Blues color scheme. Consider setting color_limits=(None, 0).
  • “cyclical”: Use a cyclical color scheme.

colorbar_label

: str = None
Label to show at the colorbar.

data

: array
2d or 3d grid data in the plane spanned by the lattice vectors. If the data is the dimensions should be the ones of the grid, if the data is 3d the first dimension should be a 2 for a vector in the plane of the grid and the other two dimensions should be the grid.

isolevels

: bool = False
Defines whether isolevels should be added or a heatmap is used.

label

: str
Assign a label to the visualization that may be used to identify one among multiple plots.

lattice

: Plane
Lattice plane in which the data is represented spanned by 2 vectors. Each vector should have two components, so remove any element normal to the plane. Can be generated with the ‘plane’ function in py4vasp._util.slicing.

max_number_arrows

: int = None
Subsample the data until the number of arrows falls below this limit.

scale_arrows

: float = None
Scale arrows by this factor when converting their length to Å. None means autoscale them so that the arrows do not overlap.

show_cell

: bool = True
Show the unit cell in the resulting visualization.

show_contour_values

: bool = None
Defines whether contour values should be shown along contour plot lines.

supercell

: array = (1, 1)
Multiple of each lattice vector to be drawn.

to_plotly

()
Use yield to generate one or more plotly traces. Each returned element should be a tuple (trace, dict) where the trace can be used as data for plotly and the options modify the generation of the figure.

traces_as_periodic

: bool = False

If True, traces (contour and quiver) are shifted so that quiver and heatmap ‘cell’ centers align with the positions they were computed at. Periodic images will be drawn so that the supercell still appears completely covered on all sides.

If False, traces (contour and quiver) are shifted so that the heatmap cells visually align with the supercell instead. No periodic images are required, but the visual presentation might be misleading.

py4vasp.graph.Graph

(

  • series: Trace,
  • xlabel: str = None,
  • xrange: tuple = None,
  • xticks: dict = None,
  • xsize: int = 720,
  • ylabel: str = None,
  • yrange: tuple = None,
  • y2label: str = None,
  • ysize: int = 540,
  • title: str = None

)

Wraps the functionality to generate graphs of series.

From a single or multiple series a graph is generated based on the optional parameters set in this class.

count

(value) → integer -- return number of occurrences of value

index

(value) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

label

(new_label: str)

Apply a new label to all series within.

If there is only a single series, the label will replace the current one. If there are more than one, the new label will be prefixed to the existing ones.

Parameters

new_label: str
The new label added to the series.

series

: Trace
One or more series shown in the graph.

show

()
Show the graph with the default look.

title

: str = None
Title of the graph.

to_csv

(filename: str | Path)

Export graph to a csv file.

Starting from the dataframe generated from to_frame, use the to_csv method implemented in pandas to write out a csv file with a given filename

Parameters

filename: str | Path
Name of the exported csv file

to_frame

() → Dataframe

Convert graph to a pandas dataframe.

Every series will have at least two columns, named after the series name with the suffix x and y. Additionally, if weights are provided, they will also be written out as another column. If a series does not have a name, a name will be generated based on a uuid.

Returns

Dataframe
A pandas dataframe with columns for each series in the graph

to_plotly

()
Convert the graph to a plotly figure.

xlabel

: str = None
Label for the x axis.

xrange

: tuple = None
Reduce the x axis to this interval.

xsize

: int = 720
Width of the resulting figure.

xticks

: dict = None
A dictionary specifying positions and labels where ticks are placed on the x axis.

y2label

: str = None
Label for the secondary y axis.

ylabel

: str = None
Label for the y axis.

yrange

: tuple = None
Reduce the y axis to this interval.

ysize

: int = 540
Height of the resulting figure.

py4vasp.graph.Series

(

  • x: ndarray,
  • y: ndarray,
  • label: str = None,
  • weight: ndarray = None,
  • weight_mode: str = ‘size’,
  • annotations: dict = None,
  • y2: bool = False,
  • subplot: int = None,
  • color: str = None,
  • marker: str = None

)

Represents a single series in a graph.

Typically this corresponds to a single line of x-y data with an optional label used in the legend of the figure. The look of the series is modified by some of the other optional arguments.

annotations

: dict = None
If present, stores the metadata for this line or each point of the plot. Note that each element of the dictionary must have either size 1 or the same size as the x coordinates.

color

: str = None
The color used for this series.

label

: str = None
A label for the series used in the legend.

marker

: str = None
Which marker is used for the series, None defaults to line mode.

subplot

: int = None
Split series into different axes

to_plotly

()
Use yield to generate one or more plotly traces. Each returned element should be a tuple (trace, dict) where the trace can be used as data for plotly and the options modify the generation of the figure.

weight

: ndarray = None
When a weight is set, the series will modify the plot according to weight_mode.

weight_mode

: str = ‘size’
If weight_mode is ‘size’, the size of the plot is adjusted according to the weight. If weight_mode is ‘color’, the color of the plot is adjusted according to the weight.

x

: ndarray
The x coordinates of the series.

y

: ndarray
The y coordinates of the series. If the data is 2-dimensional multiple lines are generated with a common entry in the legend.

y2

: bool = False
Use a secondary y axis to show this series.