API

Drawable

Most Ziaplot classes inherit from Drawable, allowing them to be drawn as SVG, saved to file, or converted to other image formats.

class ziaplot.drawable.Drawable

Drawable SVG/XML object. Implements common XML and SVG functions, plus _repr_ for Jupyter

add(series: Drawable) → None

Add a data series to the axis

imagebytes(fmt: Literal['svg', 'eps', 'pdf', 'png'] = 'svg') → bytes

Get byte data for image

Parameters:

ext – File format extension. Will be extracted from fname if not provided.

save(fname: str)

Save image to a file

Parameters:

fname – Filename, with extension.

Notes

SVG format is always supported. EPS, PDF, and PNG formats are available when the cairosvg package is installed

svg() → str

Get SVG string representation

svgxml(border: bool = False) → Element

Generate XML for a standalone SVG

Axes

class ziaplot.axes.BasePlot(title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Base plotting class

Parameters:

  • title – Title to draw above axes

  • xname – Name/label for x axis

  • yname – Name/label for y axis

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

add(series: Drawable) → None

Add a data series to the axis

colorfade(*clrs: str, stops: Sequence[float] | None = None) → None

Define the color cycle evenly fading between multiple colors.

Parameters:

  • colors – List of colors in #FFFFFF format

  • stops – List of stop positions for each color in the gradient, starting with 0 and ending with 1.

datarange() → DataRange

Get range of data only

svgxml(border: bool = False) → Element

XML for standalone SVG

xrange(xmin: float, xmax: float) → BasePlot

Set x-range of data display

xticks(values: Sequence[float], names: Sequence[str] | None = None, minor: Sequence[float] | None = None) → BasePlot

Set x axis tick values and names

yrange(ymin, ymax)

Set y-range of data display

yticks(values: Sequence[float], names: Sequence[str] | None = None, minor: Sequence[float] | None = None) → BasePlot

Set y axis tick values and names

class ziaplot.axes.XyPlot(title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Plot of x-y data

Parameters:

  • title – Title to draw above axes

  • xname – Name/label for x axis

  • yname – Name/label for y axis

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

class ziaplot.axes.XyGraph(centerorigin: bool = True, title: str | None = None, xname: str = 'x', yname: str = 'y', legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

X-Y Graph. Axes are drawn as arrows pointing to infinity with xname and yname labels at the ends of the arrows. Often used to visualize functions (e.g. y = x**2) rather than empirical data.

Parameters:

  • centerorigin – Place the (0, 0) origin in the center of the axis

  • title – Title to draw above axes

  • xname – Name/label for x axis

  • yname – Name/label for y axis

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

datarange() → DataRange

Get range of x-y data. XyGraph datarange must include 0

class ziaplot.axeslog.LogYPlot(title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Plot with Y on a log10 scale

Parameters:

  • title – Title to draw above axes

  • xname – Name/label for x axis

  • yname – Name/label for y axis

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

datarange() → DataRange

Get range of data

class ziaplot.axeslog.LogXPlot(title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Plot with Y on a log10 scale

Parameters:

  • title – Title to draw above axes

  • xname – Name/label for x axis

  • yname – Name/label for y axis

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

datarange() → DataRange

Get range of data

class ziaplot.axeslog.LogXYPlot(title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Plot with X and Y on a log10 scale

Parameters:

  • title – Title to draw above axes

  • xname – Name/label for x axis

  • yname – Name/label for y axis

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

datarange() → DataRange

Get range of data only

class ziaplot.polar.Polar(labeldeg: bool = True, title: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Polar Plot. Use with LinePolar to define series in (radius, angle) format.

Parameters:

  • labeldeg – Draw theta labels in degrees vs. radians

  • title – Title to draw above axes

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

rrange(rmax: float) → None

Sets maximum radius to display

svgxml(border: bool = False) → Element

XML for standalone SVG

yrange(ymin: float, ymax: float) → None

Sets range of y data

class ziaplot.smith.Smith(grid: str = 'coarse', title: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

Smith Chart Axis

Parameters:

  • grid – Smith grid spacing

  • title – Title to draw above axes

  • legend – Location of legend

  • style – Drawing style

style

Drawing style

svgxml(border: bool = False) → Element

XML for standalone SVG

class ziaplot.pie.Pie(title: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', labelmode: str = 'name', style: Style | None = None)

Pie Chart. Total of all wedge values will be normalized to 100%.

Parameters:

  • title – Title of the chart

  • legend – Location for legend

  • labelmode – How to label each wedge - by name, percent, or value.

  • style – Plotting style

colorfade(*clrs: str, stops: Sequence[float] | None = None) → None

Define the color cycle evenly fading between two colors. c1 will always be the color of the first series, and c2 the color of the last series, with an even gradient for series in between.

Parameters:

  • colors – List of colors to fade through

  • stops – Stop positions, starting with 0 and ending with 1

classmethod fromdict(slices: dict[str, float], title: str | None = None, legend: LegendLoc = 'left', labelmode: str = 'name') → Pie

Create Pie from bars dictionary

Parameters:

  • slices – dictionary of name:value pairs

  • title – Title of the chart

  • legend – Location for legend

  • labelmode – How to label each wedge - by name, percent, or value.

  • style – Plotting style

classmethod fromlist(slices: list[float], title: str | None = None, legend: LegendLoc = 'none', labelmode: str = 'name') → Pie

Create Pie from list of values

Parameters:

  • slices – list of values

  • title – Title of the chart

  • legend – Location for legend

  • labelmode – How to label each wedge - by name, percent, or value.

  • style – Plotting style

class ziaplot.pie.PieSlice(value: float = 1)

One slice of a pie.

Parameters:

value – value assigned to this slice. Percent will be calculated using total value of all the slices.

edgecolor(color: str) → Series

Sets the series stroke/linestyle

extrude(extrude: bool) → PieSlice

Extrude the slice

class ziaplot.bar.BarChart(horiz: bool = False, title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'none', style: Style | None = None)

A bar chart with a single data series. Independent variable is qualitative.

Parameters:

  • horiz – Draw as horizontal bars (x values will be drawn along vertical axis)

  • title – Title for chart

  • xname – Name/label for x (independent variable) axis

  • yname – Name/label for y (dependent variable) axis

  • legend – Location for legend

  • style – Plotting style

Note

For a bar graph with quantitative x values, use XyPlot and add Bars instances.

add(bar: Drawable) → None

Add a data series to the axis

class ziaplot.bar.BarSingle(value: float = 1)

A single bar in a BarChart

Parameters:

value – value assigned to this bar.

class ziaplot.bar.BarChartGrouped(groups: Sequence[str], horiz: bool = False, title: str | None = None, xname: str | None = None, yname: str | None = None, legend: Literal['left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright', 'none'] = 'left', style: Style | None = None)

A grouped bar chart, where independent variable is qualitative.

Parameters:

  • groups – list of x value strings

  • horiz – Draw as horizontal bars (x values will be drawn along vertical axis)

  • title – Title for chart

  • xname – Name/label for x (independent variable) axis

  • yname – Name/label for y (dependent variable) axis

  • legend – Location for legend

  • style – Plotting style

Note

For a bar graph with quantitative x values, use XyPlot and add Bars instances.

add(barseries: Drawable) → None

Add a data series to the axis

class ziaplot.bar.BarSeries(*values: float)

A series of bars across all groups

Parameters:

values – values assigned to this bar series.

Data Series

class ziaplot.series.Series

Base class for data series, defining a single line in a plot

color(color: str) → Series

Sets the series color

marker(marker: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None], radius: float | None = None, orient: bool = False) → Series

Sets the series marker

name(name: str) → Series

Sets the series name to include in the legend

stroke(stroke: Literal['-', ':', 'dotted', '--', 'dashed', '-.', '.-', 'dashdot'] | str) → Series

Sets the series stroke/linestyle

strokewidth(width: float) → Series

Sets the series strokewidth

class ziaplot.dataseries.Line(x: Sequence[float], y: Sequence[float])

A line series of x-y data

Parameters:

  • x – X-values to plot

  • y – Y-values to plot

datarange() → DataRange

Get range of data

endmarkers(start: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None] = '<', end: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None] = '>') → Line

Define markers to show at the start and end of the line. Use defaults to show arrowheads pointing outward in the direction of the line.

svgxml(border: bool = False) → Element

Generate XML for standalone SVG

class ziaplot.dataseries.Xy(x: Sequence[float], y: Sequence[float])

An X-Y Scatter series of data

Parameters:

  • x – X-values to plot

  • y – Y-values to plot

class ziaplot.dataseries.Function(func: Callable[[float], float], xmin: float = -5, xmax: float = 5, n: int = 200)

Plot a function

Parameters:

  • func – Callable function (e.g. lambda x: x**2)

  • xmin – Minimum x value

  • xmax – Maximum x value

  • n – Number of datapoints for discrete representation

class ziaplot.dataseries.ErrorBar(x: Sequence[float], y: Sequence[float], yerr: Sequence[float] | None = None, xerr: Sequence[float] | None = None)

An X-Y Line with Error Bars in X and/or Y

Parameters:

  • x – X-values to plot

  • y – Y-values to plot

  • yerr – Y errors

  • xerr – X errors

datarange() → DataRange

Get range of data

xerrmarker(marker: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None] = '|', length: float | None = None, width: float | None = None, stroke: Literal['-', ':', 'dotted', '--', 'dashed', '-.', '.-', 'dashdot'] | str | None = None) → ErrorBar

Set marker and linestyle for x-error bars

Parameters:

  • marker – Shape of the marker

  • length – Length of the marker

  • width – Linewidth of the marker

  • stroke – Stroke/dash style for the errorbar line

yerrmarker(marker: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None] = '-', length: float | None = None, width: float | None = None, stroke: Literal['-', ':', 'dotted', '--', 'dashed', '-.', '.-', 'dashdot'] | str | None = None) → ErrorBar

Set marker and linestyle for y-error bars

Parameters:

  • marker – Shape of the marker

  • length – Length of the marker

  • width – Linewidth of the marker

  • stroke – Stroke/dash style for the errorbar line

class ziaplot.dataseries.LineFill(x: Sequence[float], ymax: Sequence[float], ymin: Sequence[float] | None = None)

A filled line/region

Parameters:

  • x – X-values

  • ymax – Y-values defining upper limit of region

  • ymin – Y-values defining lower limit of region. Defaults to 0.

datarange() → DataRange

Get range of data

fill(color: str, alpha: float | None = None) → LineFill

Set the region fill color and transparency

Parameters:

  • color – Fill color

  • alpha – Transparency (0-1, with 1 being opaque)

svgxml(border: bool = False) → Element

Generate XML for standalone SVG

class ziaplot.dataseries.Text(x: float, y: float, s: str, halign: Literal['left', 'center', 'right'] = 'left', valign: Literal['top', 'center', 'baseline', 'base', 'bottom'] = 'bottom', rotate: float | None = None)

A text element to draw at a specific x-y location

Parameters:

  • x – X-position for text

  • y – Y-position for text

  • s – String to draw

  • halign – Horizontal alignment

  • valign – Vertical alignment

  • rotate – Rotation angle, in degrees

color(color: str) → Text

Sets the text color

datarange() → DataRange

Get x-y datarange

class ziaplot.dataseries.Arrow(xy: Sequence[float], xytail: Sequence[float], s: str = '', strofst: Sequence[float] = (0, 0), marker: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None] = 'arrow', tailmarker: Literal['round', 'o', 'square', 's', 'triangle', '^', 'triangled', 'v', 'larrow', '<', 'arrow', '>', '+', 'x', '-', '|', 'undefined', None] | None = None)

An arrow pointing to an XY location, with optional text annotation

Parameters:

  • xy – XY position to point at

  • xytail – XY-position of arrow tail

  • s – String to draw at tail of arrow

  • strofst – XY offset between text and arrow tail

  • marker – Arrowhead marker shape

  • tailmarker – Arrowhead tail marker

class ziaplot.dataseries.HLine(y: float)

Horizontal line spanning the plot

Parameters:

y – Y-value of the line

datarange() → DataRange

Get x-y datarange

class ziaplot.dataseries.VLine(x: float)

Vertical line spanning the plot

Parameters:

x – X-value of the line

datarange() → DataRange

Get x-y datarange

class ziaplot.dataseries.Bars(x: Sequence[float], y: Sequence[float], y2: Sequence[float] | None = None, width: float | None = None, align: Literal['left', 'center', 'right'] = 'center')

A series of bars to add to an XyPlot (quantitative x values) For qualitative bar chart, use a BarChart instance.

Parameters:

  • x – X-values of each bar

  • y – Y-values of each bar

  • y2 – Minimum y-values of each bar

  • width – Width of all bars

  • align – Bar position in relation to x value

datarange()

Get x-y datarange

svgxml(border: bool = False) → Element

Generate XML for standalone SVG

class ziaplot.dataseries.BarsHoriz(x: Sequence[float], y: Sequence[float], y2: Sequence[float] | None = None, width: float | None = None, align: Literal['left', 'center', 'right'] = 'center')

Horizontal bars

datarange() → DataRange

Get x-y datarange

class ziaplot.dataseries.Histogram(x: Sequence[float], bins: int | None = None, binrange: tuple[float, float, float] | None = None, density: bool = False, weights: Sequence[float] | None = None)

Histogram data series

Parameters:

  • x – Data to show as histogram

  • bins – Number of bins for histogram

  • binrange – Tuple of (start, stop, step) defining bins

  • density – Normalize the histogram

  • weights – Weights to apply to each x value

class ziaplot.polar.LinePolar(radius: Sequence[float], theta: Sequence[float], deg: bool = False)

Define a data Line series using polar coordinates

Parameters:

  • radius – The radius values to plot

  • theta – The theta values to plot, in degres or radians

  • deg – Interpret theta as degrees instead of radians

class ziaplot.smith.SmithConstResistance(resistance: float, xmin: float = -inf, xmax: float = inf)

Smith chart circle of constant Resistance (normalized)

Parameters:

  • resistance – Resistance value (0 to inf)

  • xmin – Minimum reactance intersection value

  • xmax – Maximum reactance intersection value

Notes

Leave xmin and xmax at inf to draw full circle

class ziaplot.smith.SmithConstReactance(reactance: float, rmax: float = inf, rmin: float = 0)

Smith chart arcs of constant Reactance (normalized). Draws both positive and negative (capacitive and inductive) arcs.

Parameters:

  • reactance – Reactance value

  • rmax – maximum resistance intersection value

  • rmin – minimum resistance intersection value

Layouts

class ziaplot.layout.Hlayout(*axes: Drawable, width: float = 600, height: float = 400, sep: float = 10)

Horizontal Plot Layout

Parameters:

  • axes – The axes and/or VLayouts to draw, evenly spaced horizontally

  • width – Width of the figure/layout

  • height – Height of the figure/layout

  • sep – Distance between subplots

Note

height and width are ignored if the layout is added to another layout.

class ziaplot.layout.Vlayout(*axes: Drawable, width: float = 600, height: float = 400, sep: float = 10)

Vertical Plot Layout

Parameters:

  • axes – The axes and/or HLayouts to draw, evenly spaced vertically

  • width – Width of the figure/layout

  • height – Height of the figure/layout

  • sep – Distance between subplots

Note

height and width are ignored if the layout is added to another layout.