API reference

Figure and MultiFigure

Figure	This class implements a general figure object.
MultiFigure	This class implements the "canvas" on which multiple plots are displayed.

SmartFigure	This class implements a figure object for plotting Plottable elements.
SmartFigureWCS	This class implements a figure object for plotting Plottable elements with a astropy.wcs.WCS projection.
SmartTwinAxis	This class implements a twin axis for the SmartFigure and SmartFigureWCS classes.

Plottables

Arrow	This class implements an arrow object.
Circle	This class implements a Circle object with a given center and radius.
Contour	This class implements contour plots.
Curve	This class implements a general continuous curve.
Ellipse	This class implements an Ellipse object with a given center, two radii and an optional rotation angle.
FitFromExponential	Create a curve fit (continuous Curve) from an existing Curve object using an exponential fit.
FitFromFOTF	Create a curve fit (continuous Curve) from an existing Curve object using a first order transfer function (FOTF) fit.
FitFromFunction	Create a curve fit (continuous Curve) from a Curve object using an arbitrary function passed as an argument.
FitFromGaussian	Create a curve fit (continuous Curve) from an existing Curve object using a gaussian fit.
FitFromLog	Create a curve fit (continuous Curve) from an existing Curve object using a logarithmic fit.
FitFromPolynomial	Creates a curve fit (continuous Curve) from an existing curve object using a polynomial fit.
FitFromSine	Create a curve fit (continuous Curve) from an existing Curve object using a sinusoidal fit.
FitFromSquareRoot	Create a curve fit (continuous Curve) from an existing Curve object using a square root fit.
Heatmap	The class implements heatmaps.
Histogram	This class implements a general histogram.
Hlines	This class implements simple horizontal lines.
Line	This class implements a line object.
PlottableAxMethod	This experimental class allows to call any matplotlib Axes method as a plottable element in a SmartFigure.
Point	This class implements a point object.
Polygon	This class implements a Polygon object.
Rectangle	This class implements a Rectangle object with a given bottom left corner, width and height.
Scatter	This class implements a general scatter plot.
Stream	This class implements stream plots.
Table	This class allows to plot a table inside a Figure or MultiFigure.
Text	This class allows text to be plotted.
VectorField	This class implements vector fields.
Vlines	This class implements simple vertical lines.

Legend elements

LegendLine	This class implements a legend line wrapping the Line2D object for creating custom legend entries with the set_custom_legend() method.
LegendMarker	This class implements a legend marker wrapping the Line2D object with a marker style set for creating custom legend entries with the set_custom_legend() method.
LegendPatch	This class implements a legend patch wrapping the Patch object for creating custom legend entries with the set_custom_legend() method.

Utility functions

get_color	Returns a color from the specified style (user created, GL, or Matplotlib style).
get_colors	Returns a list of colors from the specified style (user created, GL, or Matplotlib style).
get_default_style	Returns the default style.
get_styles	Returns a list or dict of available styles.
set_default_style	Sets the default style.

Tools

MathematicalObject

This class implements the __r* (reverse) and __i* (inplace) methods for adding, subtracting, multiplying, dividing and raising to a power an object that implements the direct methods.

Errors

Every exception GraphingLib raises derives from GraphingLibError (also available under its alias GraphingException), so except graphinglib.GraphingException catches anything the library raises. Most also derive from the matching built-in exception (ValueError, TypeError, …), so existing except ValueError / except TypeError code keeps working too.

exception graphinglib.GraphingLibError

Base class for every exception raised by GraphingLib.

Catch this to handle any GraphingLib-specific failure. It is rarely raised directly; prefer one of the specific subclasses below so the failure mode is explicit.

exception graphinglib.InvalidParameterError

A public argument has the right type but an unacceptable value.

Use for out-of-range numbers, unrecognised option strings, malformed tuples, and similar (e.g. a negative radius, an unknown line style). Also a ValueError.

exception graphinglib.InvalidParameterTypeError

A public argument has the wrong type.

Use when the value is not an instance of any accepted type (e.g. num_rows given a string, an unsupported operand in curve + other). Also a TypeError.

A wrong value of the correct type (e.g. num_rows given 0) is an InvalidParameterError, not this.

exception graphinglib.IncompatibleArgumentsError

Several arguments are individually valid but conflict with one another.

Use for mutually exclusive options set together, co-required options where only one is given, or length mismatches between related sequences (e.g. tick positions and tick labels of different lengths). Also a ValueError.

exception graphinglib.InvalidOperationError

The operation is not allowed for the object’s current state or configuration.

Use when the arguments are fine but the object cannot honour the call as it stands (e.g. plotting a figure with no elements, adding a twin axis that already exists). Also a RuntimeError.

exception graphinglib.LayoutError

A SmartFigure grid/geometry constraint is violated.

A specialised InvalidOperationError for layout problems: overlapping spans, children that do not fit the target grid, indexing a leaf as if it were a layout, etc.

exception graphinglib.StyleNotFoundError

A named style (or similar resource) could not be found.

Use when a requested figure_style does not exist among the built-in or user styles. Also a LookupError.

exception graphinglib.StyleFileError

A style file could not be read, parsed, or automatically updated.

An integrity error about GraphingLib’s own configuration data rather than user input; this is the one place where directing the user to report the problem is appropriate.

exception graphinglib.MissingOptionalDependencyError

A feature requires an optional dependency that is not installed.

Use when a feature gated behind a graphinglib[extra] is invoked without the extra. The message should name the extra and how to install it. Also an ImportError.

exception graphinglib.UnsupportedFeatureError

A requested capability is deliberately not available.

Use for things GraphingLib knowingly does not support (e.g. a 3D projection, or a WCS-only feature used on a non-WCS figure). Also a NotImplementedError.

exception graphinglib.PlottingError

A matplotlib, scipy, or numpy call failed while building or rendering an element.

Use to wrap a lower-level exception raised deep inside a dependency (a failed plot call, a fit that did not converge, an interpolation error, …) so the user sees GraphingLib context instead of a bare backend error. Always chain the original with raise PlottingError(...) from exc. Also a RuntimeError.