API Documentation#

A Matplotlib-like interface for generating Tikz and Pgfplots figures

class pykz.Axis(xlabel: str | None = None, ylabel: str | None = None, view: View | None = None, width: str | None = None, height: str | None = None, scale_only_axis: bool = False, axis_x_line: str | None = None, axis_y_line: str | None = None, axis_z_line: str | None = None, xmode: AxisMode | None = None, ymode: AxisMode | None = None, zmode: AxisMode | None = None, x_dir: AxisDir | None = None, y_dir: AxisDir | None = None, z_dir: AxisDir | None = None, axis_equal: bool = False, axis_equal_image: bool = False, xmin: float | None = None, xmax: float | None = None, ymin: float | None = None, ymax: float | None = None, zmin: float | None = None, zmax: float | None = None, grid: Grid | None = None, xminorgrids: bool | None = None, yminorgrids: bool | None = None, zminorgrids: bool | None = None, xmajorgrids: bool | None = None, ymajorgrids: bool | None = None, zmajorgrids: bool | None = None, xtick: str | None = None, ytick: str | None = None, ztick: str | None = None, **extra)[source]#

Bases: Environment

__init__(xlabel: str | None = None, ylabel: str | None = None, view: View | None = None, width: str | None = None, height: str | None = None, scale_only_axis: bool = False, axis_x_line: str | None = None, axis_y_line: str | None = None, axis_z_line: str | None = None, xmode: AxisMode | None = None, ymode: AxisMode | None = None, zmode: AxisMode | None = None, x_dir: AxisDir | None = None, y_dir: AxisDir | None = None, z_dir: AxisDir | None = None, axis_equal: bool = False, axis_equal_image: bool = False, xmin: float | None = None, xmax: float | None = None, ymin: float | None = None, ymax: float | None = None, zmin: float | None = None, zmax: float | None = None, grid: Grid | None = None, xminorgrids: bool | None = None, yminorgrids: bool | None = None, zminorgrids: bool | None = None, xmajorgrids: bool | None = None, ymajorgrids: bool | None = None, zmajorgrids: bool | None = None, xtick: str | None = None, ytick: str | None = None, ztick: str | None = None, **extra)[source]#
boxed()[source]#
center()[source]#

Center the axis lines

enlarge_limits(amount: float = 0.05, direction: str | None = None)[source]#

Enlarge the range of axes (only x or y if direction is provided).

Adds the enlarge x limits option.

Parameters:

  • amount (-) – fraction by which to increase the size of the axes. The final range will be (1 + amount) * original_length

  • direction (-) – “x” | “y”. If provided, only apply to the corresponding axis.

get_ylims() → tuple[source]#
set_axis_label_position(axis: str, position: str)[source]#

Set label position of the given axis relative to the arrowhead. As a side-effect, it also centers the axes.

Parameters:

  • [str] (- positions) – “x”, “y” or “z”

  • [str] – “left”, “right”, “above”, “below”

set_xlabel(label: str)[source]#
set_xlims(lims: tuple[float])[source]#
set_xmax(v)[source]#
set_xmin(v)[source]#
set_xticks(values: tuple[float], labels: tuple[str] | None = None)[source]#
set_ylabel(label: str)[source]#
set_ylims(lims: tuple[float])[source]#
set_ymax(v)[source]#
set_ymin(v)[source]#
set_yticks(values: tuple[float], labels: tuple[str] | None = None)[source]#
set_zlabel(label: str)[source]#
set_zlims(lims: tuple[float])[source]#
set_zmax(v)[source]#
set_zmin(v)[source]#
set_zticks(values: tuple[float], labels: tuple[str] | None = None)[source]#
class pykz.AxisDir(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

normal = 'normal'#
reverse = 'reverse'#
class pykz.AxisMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

linear = 'linear'#
log = 'log'#
normal = 'normal'#
class pykz.Grid(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

both = 'both'#
major = 'major'#
minor = 'minor'#
none = 'none'#
class pykz.View(azimuth: 'int', elevation: 'int')[source]#

Bases: object

__init__(azimuth: int, elevation: int) → None#
azimuth: int#
elevation: int#
pykz.arrow(points: list[ndarray | str | Node], forward: bool = True, backward: bool = False, arrowhead: str | None = None, **options) → Draw[source]#

Draw an arrow through a list of points.

Parameters:

  • points (list[Point]) – List of points to connect

  • forward (bool, optional) – Whether to draw forward arrow, by default True

  • backward (bool, optional) – Whether to draw backward arrow, by default False

  • arrowhead (str, optional) – Style of arrowhead

  • **options – Additional drawing options

Returns:

The drawing command

Return type:

Draw

pykz.ax(**options) → Axis[source]#

Create a new Axis object and add it to the current figure.

Parameters:

**options – Options to pass to the Axis constructor

Returns:

The newly created axis

Return type:

Axis

pykz.axhline(y: float, ax: Axis | None = None, **options) → list[Addplot][source]#

Plot a horizontal line at the provided y value.

Parameters:

  • y (float) – y-coordinate of the line

  • ax (Axis, optional) – Axis to add the line to. If None, uses current axis.

  • **options – Additional plotting options

Returns:

List of plot commands created

Return type:

list[Addplot]

pykz.axvline(x: float, ax: Axis | None = None, **options) → list[Addplot][source]#

Plot a vertical line at the provided x value.

Parameters:

  • x (float) – x-coordinate of the line

  • ax (Axis, optional) – Axis to add the line to. If None, uses current axis.

  • **options – Additional plotting options

Returns:

List of plot commands created

Return type:

list[Addplot]

pykz.circle(center: ndarray | str | Node, radius: float, **options) → Circle[source]#

Draw a circle with given center and radius.

Parameters:

  • center (Point) – Center point of the circle

  • radius (float) – Radius of the circle

  • **options – Additional drawing options

Returns:

The circle drawing command

Return type:

Circle

pykz.define_style(name: str, fig: TikzPicture | None = None, **options)[source]#

Define a new style for the figure.

Parameters:

  • name (str) – Name of the style to define

  • fig (TikzPicture, optional) – Figure to define the style for. If None, uses current figure.

  • **options – Style options to set

pykz.dumps(fig: TikzPicture | None = None) → str[source]#

Dump the tex-code of the current figure to a string.

If no figure is given, the active figure is selected, and the contents of this figure are returned.

Parameters:

fig – Figure to generate the code for. If None is given, then the current figure is used.

Returns:

The tex code.

Return type:

str

pykz.figure(standalone: bool = True, **options) → TikzPicture[source]#

Create a new TikzPicture and set it as the current figure.

Parameters:

  • standalone (bool, optional) – Whether the figure should be a standalone document, by default True

  • **options – Additional options to pass to the TikzPicture

Returns:

The newly created figure

Return type:

TikzPicture

pykz.fill_between(x: ndarray, y1: ndarray, y2: ndarray, *, draw_options=None, fill_options=None) → FillBetween[source]#

Fill the area between two curves.

Parameters:

  • x (np.ndarray) – x-coordinates

  • y1 (np.ndarray) – y-coordinates of first curve

  • y2 (np.ndarray) – y-coordinates of second curve

  • draw_options (dict, optional) – Options for drawing the curves

  • fill_options (dict, optional) – Options for filling the area

Returns:

The fill between plot command

Return type:

FillBetween

pykz.gca() → Axis | None[source]#

Get the currently active axis (representing a pgfplots axis) if there is one.

If you want to create a new axis in case there is none, then use the ax() function.

Returns:

The currently active axis if there is one.

Return type:

Optional[Axis]

pykz.gcf() → TikzPicture | None[source]#

Get the currently active figure in the workspace, which could be None. If you want to create a new one if there is no current figure, then use figure()

Returns:

The currently active Figure if there is one.

Return type:

Optional[TikzPicture]

pykz.line(points: list[ndarray | str | Node], connection: str = '--', **options) → Draw[source]#

Draw a line through a list of points.

Parameters:

  • points (list[Point]) – List of points to connect

  • connection (str, optional) – Type of connection between points, by default “–”

  • **options – Additional drawing options

Returns:

The drawing command

Return type:

Draw

pykz.node(coordinates: ndarray | None = None, label: str | None = None, name: str | None = None, axis_coords: bool | None = None, label_loc: str | None = None, axis: Axis | None = None, fig: TikzPicture | None = None, **options) → Node[source]#

Draw a node at the given coordinates.

Parameters:

  • coordinates (np.ndarray, optional) – Position of the node or name of a previously defined node

  • label (str, optional) – Label text

  • name (str, optional) – Name of the node

  • axis_coords (bool, optional) – Whether to interpret coordinates in axis coordinates

  • label_loc (str, optional) – Label location (None, “above”, “below”, “right”, “left” or combinations)

  • axis (Axis, optional) – Axis to add the node to

  • fig (TikzPicture, optional) – Figure to add the node to

  • **options – Additional styling options

Returns:

The created node object

Return type:

Node

pykz.plot(x, y=None, z=None, ax: Axis | None = None, label: str | tuple[str] | None = None, inline_label: bool = False, **options) → list[Addplot][source]#

Create a plot command.

Parameters:

  • x (array-like) – x-coordinates or data

  • y (array-like, optional) – y-coordinates

  • z (array-like, optional) – z-coordinates for 3D plots

  • ax (Axis, optional) – Axis to add the plot to

  • label (str | tuple[str], optional) – Label or tuple of labels for the plot

  • inline_label (bool, optional) – Whether to place label inline with the plot, by default False

  • **options – Additional plotting options

Returns:

List of plot commands created

Return type:

list[Addplot]

pykz.point(coordinates: ndarray | None = None, label: str = '', name: str | None = None, axis_coords: bool | None = None, label_loc: str = 'above', size: int | str = '1pt', axis: Axis | None = None, fig: TikzPicture | None = None, **options) → Node[source]#

Draw a point at the given coordinates.

It creates a node, but also adds some styling to make it look like a point.

See also: node()

Parameters:

  • coordinates (np.ndarray, optional) – Position of the point

  • label (str, optional) – Label text, by default “”

  • name (str, optional) – Name of the node

  • axis_coords (bool, optional) – Whether to use axis coordinates

  • label_loc (str, optional) – Label location (“above”, “below”, “right”, “left”), by default “above”

  • size (int | str, optional) – Size of the point, by default “1pt”

  • axis (Axis, optional) – Axis to add the point to

  • fig (TikzPicture, optional) – Figure to add the point to

  • **options – Additional styling options

Returns:

The created node object

Return type:

Node

pykz.preview(fig: TikzPicture | None = None)[source]#

Preview the current figure.

The contents of this figure are written to a temporary file, compiled to a pdf and then opened in the default viewer. After the process terminates, these files are removed.

Parameters:

fig (TikzPicture, optional) – The figure to preview. If None is given, the current figure is used.

pykz.rectangle(c1: ndarray | str | Node, c2: ndarray | str | Node, **options) → Draw[source]#

Draw a rectangle between two points.

Parameters:

  • c1 (Point) – First corner point

  • c2 (Point) – Second corner point

  • **options – Additional drawing options

Returns:

The drawing command

Return type:

Draw

pykz.save(filename: str, fig: TikzPicture | None = None, standalone: bool = False)[source]#

Save the generated Tikz code to a file.

Parameters:

  • filename (str) – The path to write the figure to. If the extension .tex or .tikz is not present, .tex is appended.

  • fig (TikzPicture, optional) – The figure to save. If None is given, the current figure is used.

  • standalone (bool, optional) – Whether to save as a standalone document, by default False

pykz.scale(scale: float, fig: TikzPicture | None = None)[source]#

Set the scale of the figure.

Parameters:

  • scale (float) – Scale factor

  • fig (TikzPicture, optional) – Figure to scale. If None, uses current figure.

pykz.scatter(x, y=None, z=None, ax: Axis | None = None, label: str | tuple[str] | None = None, inline_label: bool = False, **options) → list[Addplot][source]#

Create a scatter plot command.

Parameters:

  • x (array-like) – x-coordinates or data

  • y (array-like, optional) – y-coordinates

  • z (array-like, optional) – z-coordinates for 3D plots

  • ax (Axis, optional) – Axis to add the plot to

  • label (str | tuple[str], optional) – Label or tuple of labels for the plot

  • inline_label (bool, optional) – Whether to place label inline with the plot, by default False

  • **options – Additional plotting options

Returns:

List of plot commands created

Return type:

list[Addplot]

pykz.xlabel(lab: str)[source]#

Set the x label of the current axis.

Parameters:

lab (str) – Label text

pykz.xlim(limits: tuple[float])[source]#

Set the x limits of the current axis.

Parameters:

limits (tuple[float]) – Tuple containing (min, max) limits

pykz.xticks(ticks: ndarray, labels: list[str] | None = None, ax: Axis | None = None)[source]#

Set the x ticks and optionally label them.

Parameters:

  • ticks (np.ndarray) – x-coordinates to add ticks at

  • labels (list[str], optional) – Labels of the ticks

  • ax (Axis, optional) – The axis to modify. The current axes is used if None is passed.

pykz.ylabel(lab: str)[source]#

Set the y label of the current axis.

Parameters:

lab (str) – Label text

pykz.ylim(limits: tuple[float])[source]#

Set the y limits of the current axis.

Parameters:

limits (tuple[float]) – Tuple containing (min, max) limits

pykz.yticks(ticks: ndarray, labels: list[str] | None = None, ax: Axis | None = None)[source]#

Set the y ticks and optionally label them.

Parameters:

  • ticks (np.ndarray) – y-coordinates to add ticks at

  • labels (list[str], optional) – Labels of the ticks

  • ax (Axis, optional) – The axis to modify. The current axes is used if None is passed.

pykz.zlabel(lab: str)[source]#

Set the z label of the current axis.

Parameters:

lab (str) – Label text

pykz.zticks(ticks: ndarray, labels: list[str] | None = None, ax: Axis | None = None)[source]#

Set the z ticks and optionally label them.

Parameters:

  • ticks (np.ndarray) – z-coordinates to add ticks at

  • labels (list[str], optional) – Labels of the ticks

  • ax (Axis, optional) – The axis to modify. The current axes is used if None is passed.