Canvas

class cand.Canvas(size_x, size_y, unit='inches')

Bases: object

Canvas is a convenient way of arranging and organizing axes and other elements on a figure.

Create a Canvas by specifying its x and y size in inches (size_x and size_y). Optionally, specify the font size in points (fontsize) and the font name as a valid postscript font (font).

A Canvas makes it easy to add create attractive composite layouts in matplotlib. When a figure consists of just a single axis, it is not difficult to create an attractive layout. However, when many axes are combined (e.g. into subpanels), it becomes more difficult to standardize the components such as font size and style. Additionally, for non-grid layouts, it is difficult to correctly compute the position of the axes, align text and arrows, and other layout-related tasks. Canvas provides a set of features to make layouts and fonts trivial.

add_arrow(frm, to, arrowstyle='->,head_width=3,head_length=4', lw=2, linestyle='solid', **kwargs)

Draw an arrow.

Draw an arrow from Point frm to Point to. All other keyword arguments are passed directly to matplotlib.patches.FancyArrowPatch. Reasonable default arguments are given, but these can be overridden.

add_axis(name, pos_ll, pos_ur)

Create a new axis on the Canvas.

Create a new matplotlib axis named name, with the lower left corner at point pos_ll and the upper right corner at pos_ur. Note that the axis labels, title, and other elements may fall outside of this bounding box. The axis of a Canvas object “c” with name “axname” can be accessed by:

ax = c.ax(“axname”)

Then, ax can be used like a normal matplotlib axis.

This also creates two new coordinate systems: one is given by the axis’ name, which uses the coordinates of the data in the axis, and “axis_” prepended to the axis’ name, which is (0,0) at the lower left corner and (1,1) at the upper right corner

add_box(pos_ll, pos_ur, unitname=None, **kwargs)

Draw a bounding box.

The lower left corner is the Point pos_ll and the upper right corner is the Point pos_ur. All other keyword arguments are passed directly to matplotlib.patches.FancyBboxPatch.

Note that this differs from add_rect because it uses the FancyBboxPatch rather than matplotlib.patches.Polygon. Thus, this function can be used for, e.g., boxes with round corners

add_colorbar(name, pos_ll, pos_ur, bounds, **kwargs)

Add a colorbar.

Name the colorbar name, which will be an axis just like any other Canvas axis. The lower left corner is at pos_ll and the upper right corner is at pos_ur. bounds should be a tuple of numbers, representing the lower and upper bounds of the colorbar, respectively. All other arguments are passed directly to matplotlib.colorbar.ColorbarBase. Of particular note is the argument cmap, defining the colormap.

Return the ColorbarBase object.

add_ellipse(pos_ll, pos_ur, **kwargs)

Draw an ellipse.

The lower left corner is the Point pos_ll and the upper right corner is the Point pos_ur. Note that rotation is not currently possible because it is not clear in which coordinate system the rotation would be applied. All other keyword arguments are passed directly to matplotlib.patches.Ellipse.

add_figure_labels(labs, size=12)

Add letter labels to axes.

labs should be a list of tuples of length 2 or 3. The first element of each tuple is a string of the label text, most commonly a single lowercase letter. The second element of the tuple is the name of an axis on the canvas. The optional final element may be either a point (to specify manual positioning) or a vector (to specify an offset from the default position).

add_grid(names, nrows, pos_ll, pos_ur, spacing_x=None, spacing_y=None, spacing=None, size_x=None, size_y=None, size=None, unitname=None)

Create a grid of axes.

Axes are specified by the names argument, a (one-dimensional) list of strings specifying the names of the axes to be created on the grid. Optionally an element may be None, indicating that no axis should be created at this location on the grid. Names start on the top line and go left to right and then line by line, just like words on a page.

The argument nrows specifies how many rows should be created; the number of columns is implied by the number of rows and the length of names.

The lower left corner of the grid is located as Point pos_ll and the upper right corner is at Point pos_ur.

There are two ways to specify spacing of axes. One method is to specify the size of the axes by the Vector size, or component-wise by the Width size_x and Height size_y. Axes will be automatically spaced to maintain the given size The other method is to specify the spacing of the axes with the Vector spacing or component-wise with the Width spacing_x and Height spacing_y. The axes will be automatically sized to give the desired spacing. Finally, it is possible to mix these styles by specifying spacing_x and size_y or vice versa.

Optionally, unitname may specify a name for relative units based on the grid as a whole, i.e. where the origin is located at the bottom left corner of the bottom left figure in the grid, and (1,1) is located at the upper right corner of the upper right grid.

add_image(filename, pos, unitname=None, height=None, width=None, horizontalalignment=None, verticalalignment=None, ha=None, va=None)

Add a png or pdf image to the Canvas.

Insert a .png or .pdf file overlaid on the Canvas. The string filename is the filename of the image, the Point pos is the location of the image, aligned according to horizontalalignment (may be “left”, “center”, or “right”) and verticalalignment (may be “top”, “center”, or “bottom”). For compatibility, ha and va may be used instead. Either a Height height or a Width width must be specified. The image will be scaled in the unspecified direction to maintain the aspect ratio. If both height and width are specified, then the image’s aspect ratio will be ignored.

Note: As the conversion processes for png and pdf export use different libraries, there may be slight differences in output depending on output format.

Optionally, unitname may specify a unit for the image, i.e. the origin is located at the bototm left corner of the image, and (1,1) is located at the upper right corner of the image.

add_legend(pos_tl, els, fontsize=None, line_spacing=Vector(0, 2.2, 'Msize'), sym_width=Vector(2.3, 0, 'Msize'), padding_sep=Vector(1.2, 0, 'Msize'))

Add a legend without using the matplotlib API.

The top-left corner of the legend should be located at the Point pos_tl. The els argument should be a list of tuples representing the elements to include in the legend. The first element of each tuple should be the name of the legend item, the second element should be a dictionary of line properties to be passed to the add_line and add_marker functions, with an optional dictionary element in the dictionary, text_params passed to add_text. To withhold drawing a line and only draw markers, set ‘linestyle’ to the string ‘None’.

Additional parameters control formatting. line_spacing determines spacing between each line of descriptive text in the legend. sym_width is the width of the symbols (lines and markers). padding_sep is the separation between the symbols and the descriptive text.

add_line(frm, to, **kwargs)

Draw a line.

Draw a line from Point frm to Point to. All other keyword arguments are passed directly to matplotlib.lines.Line2D.

add_marker(pos, **kwargs)

Draw a matplotlib marker.

Plot a marker at Point pos. All other keyword arguments are passed directly to matplotlib.lines.Line2D.

add_poly(points, **kwargs)

Draw a polygon with given vertices.

Vertices are passed as a list of Point objects via the points argument. All other keyword arguments are passed directly to matplotlib.patches.Polygon.

add_rect(pos_ll, pos_ur, unitname=None, **kwargs)

Draw a rectangle.

The lower left corner is the Point pos_ll and the upper right corner is the Point pos_ur. All other keyword arguments are passed directly to matplotlib.patches.Polygon.

add_text(text, pos, font=None, size=None, weight=None, style=None, stretch=None, foundry=None, special=None, opticalsize=None, monospace=None, **kwargs)

Add text at a given point.

Draw the text text at Point pos. The argument weight specifies the font weight, which varies depending on the weights of the font, but potential options may be “light”, “roma”, “bold”, “heavy”, “black”. The size is given by size in points, which defaults to the Canvas’ default. The width is given by “stretch”, which can be “consensed”, “normal”, or “wide”, depending on the font. All other keyword arguments are identical to those of matplotlib.pyplot.text. Notably, the horizontalalignment and verticalalignment arguments are often useful. (ha and va are also accepted as aliases for matplotlib compatibility). The rotation keyword may also be useful for rotated text.

add_unit(name, scale, origin=Point(0, 0, 'absolute'))

Create a new unit of measure.

A unit is defined by an affine transformation. It has an origin and a scale in the x and y dimensions. The name of the unit is given by name, the scale in the x and y directions is given by scale, and the origin of the coordinate system is optionally specified by origin.

ax(name)

Return the axis of name name.

convert_to_absolute_coord(point)

Convert the coordinate system of the Point or Vector point to be “figure”.

We can convert any coordinate system to the “figure” coordinate system for a given Point or Vector. This is useful for comparing Points and Vectors, and also used internally as a universal coordinate system. It also collapses Binop objects into Points or Vectors.

convert_to_absolute_length(vector)

Convert the coordinate system of the Vector vector to be “figure”.

We can convert any coordinate system to the “figure” coordinate system for a given Vector. This is useful for comparing vectors, and also used internally as a universal coordinate system. It also collapses BinopVectors into Vectors.

convert_to_figure_coord(point)

Converts units in a Point or Vector to “figure”.

convert_to_figure_length(vec)

Converts units in a Vector to “figure”.

debug_grid(spacing, origin=Point(0, 0, 'absolute'), **kwargs)

Create a grid to help you design a layout.

This function is intended to help in the process of designing a layout, rather than as a feature of a finished figure. It draws a grid over the top of the canvas at spacing defined by the Vector spacing. Optionally, it begins this grid at the Point origin.

fix_fonts()

Convert all text to the desired font.

This function will fix all font objects within the figure. This must be called before displaying or saving the Canvas. Usually this is called automatically, but can be called manually as well.

is_unit(name)

Whether the value is a in use as a unit of measure.

name is a name to test. Returns True if it is in use or False if it is not.

is_valid_identifier(name)

Whether the value can be used as an axis or unit name.

name is a name to test. Returns True if it can be used or False if it cannot (e.g. it is a reserved keyword).

save(filename, dpi=600, *args, **kwargs)

Save the Canvas to a png or pdf file.

The filename is specified by the string filename. Optionally, the dpi argument may specify the dots per inch (dpi) of the output .png file, where larger numbers indicate a higher resolution and larger file size. This is most relevant to .png output, but is also used when individual axes are rasterized through ax.set_rasterized(). Any additional arguments or keyword arguments are passed to the “savefig” function in matplotlib.

set_default_unit(name)

Changes the default unit for the Canvas.

When a unit is not specified for a Point or a Vector, it uses the default unit of the Canvas. The default is initially set to figure coordinates.

show(**kwargs)

Display the Canvas in a new window (non-blocking) or in Jupyter.

Keyword arguments are the same as they are for Canvas.save, with the exception of “filename”, which is of course not available here.

use_latex(preamble=None, engine='pdflatex')

Use latex to render all text.

engine is the latex engine (“texsystem” in matplotlib lingo) used to render the text. It can be “pdflatex”, “lualatex”, or “xelatex”.

Note that this will break math font compatibility. Because latex is being used to render the fonts, you must import a package that allows latex to render in the desired font. For example, if engine is “pdflatex”, to get Helvetica, set preamble=r”usepackage[scaled]{helvet}usepackage[helvet]{sfmath}”.