Figure API

API for working with the Figure type.

Import this module like this:

from sympathy.api import figure

Markers

The methods SyAxes.plot() allow the following marker styles:

marker

description

“o”

circle

“x”

x

“*”

star

“,”

pixel

“.”

point

“+”

plus

“D”

diamond

“s”

square

“_”

hline

“|”

vline

“^”

triangle_up

“d”

thin_diamond

“h”

hexagon1

“H”

hexagon2

“1”

tri_down

“2”

tri_up

“3”

tri_left

“4”

tri_right

“8”

octagon

“p”

pentagon

“v”

triangle_down

“<”

triangle_left

“>”

triangle_right

0

tickleft

1

tickright

2

tickup

3

tickdown

4

caretleft

5

caretright

6

caretup

7

caretdown

“”

nothing

” “

nothing

“None”

nothing

None

nothing

Colors

All color parameters accept the standard matplotlib colors formats:

  • color names (see Named colors)

  • RGB(A) colors as integer or float (e.g. (255, 255, 255) or (1., 1., 1., 1.))

  • hex colors (e.g. ‘#eeefff’)

For further information see matplotlibs color api.

Location

Whenever a location parameter is allowed, the following name strings can be used.

Location String

Location Code

‘best’

0 (only for legend)

‘upper right’

1

‘upper left’

2

‘lower left’

3

‘lower right’

4

‘right’

5

‘center left’

6

‘center right’

7

‘lower center’

8

‘upper center’

9

‘center’

10

Class figure.File

class sympathy.typeutils.figure.File(fileobj=None, data=None, filename=None, mode='r', scheme='hdf5', source=None, managed=False, import_links=False)[source]

A Figure.

Any node port with the Figure type will produce an object of this type.

__deepcopy__(memo=None)[source]

Return new TypeAlias object that does not share references with self.

Must be re-implemented by subclasses that introduce additional fields to ensure that the fields are copied to the returned object.

colorbar(artist, orientation='vertical', label=None, fraction=0.05, extend=None)[source]

Add a colorbar to a Figure.

A row/column will be added to the bottom/right of the subplot Gridspec layout depending on the specified orientation (horizontal/vertical).

Parameters
  • artist (matplotlib.artist.Artist) – The artist which the colorbar should be linked to.

  • orientation (unicode, optional) – The orientation of the colorbar. Options: vertical or horizontal. Default: vertical

  • label (unicode or None, optional) – The label added to the long axis of colorbar. Default: None

  • fraction (float, optional) – The faction of the colorbar should take within the whole figure. Default: 0.05 (5%)

first_subplot()[source]

Returns the first axes of the figure or creates one.

get_mpl_figure()[source]

Return the underlying matplotlib Figure object.

Warning

When using this function you will get access to the entire matplotlib API. That API is likely to change slightly over time completely outside of our control. If you want to be sure that the code you are writing continues to work as expected in upcoming versions of Sympathy you should not use this method.

classmethod icon()[source]

Return full path to svg icon.

init()[source]

Perform any initialization, such as, defining local fields.

rotate_xlabels_for_dates()[source]

Rotates labels for all x axes if one is a datetime axis.

save_figure(filename, size=None, dpi=None, size_mm=None)[source]

Save figure to file.

Parameters
  • filename (str) – The full path with filename including the extension.

  • size (array_like, shape (2,)) – Tuple of width and height in pixels.

  • dpi (int) – The dots-per-inch of the figure.

  • size_mm (array_like, shape (2,)) – Tuple of width and height in millimeters.

set_dpi(dpi)[source]

Set the dots-per-inch of the figure.

set_title(title, fontsize=None)[source]

Add a centered title to the figure.

Parameters

fontsize (int or float or str, optional) – Controls the font size of the legend. If given as string, following strings are possible {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size.

source(other, shallow=False)[source]

Copy the contents from other figure.File. Equivalent to update().

subplots(nrows, ncols, sharex=False, sharey=False)[source]

Create subplot axes.

Parameters
  • nrows (int) – Number of rows of subplots.

  • ncols (int) – Number of columns of subplots.

  • sharex (bool or str, optional) – Defines if x-axis are shared amongst subplots, see matplotlib.figure.Figure.subplots for details.

  • sharey (bool or str, optional) – Defines if y-axis are shared amongst subplots, see matplotlib.figure.Figure.subplots for details.

Returns

axes – Returns a list of SyAxes axes.

Return type

list

sync()[source]

Synchronize data fields that are kept in memory to self._data.

Called before data is written to disk and must be re-implemented by subclasses that introduce additional fields to ensure that the fields will be written through self._data.

classmethod viewer()[source]

Return viewer class, which must be a subclass of sympathy.api.typeutil.ViewerBase

Class figure.SyAxes

class sympathy.typeutils.figure.SyAxes(axes)[source]

Wrapper around matplotlib Axes.

__eq__(other)[source]

Return self==value.

__init__(axes)[source]

Initialize self. See help(type(self)) for accurate signature.

__ne__(other)[source]

Return self!=value.

__weakref__

list of weak references to the object (if defined)

axhline(y=0, xmin=0, xmax=1, color=None, linewidth=1.0, linestyle='-')[source]

Add a horizontal line across the axis.

Parameters
  • y (scalar, optional, default: 0) – y position in data coordinates of the horizontal line.

  • xmin (scalar, optional, default: 0) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right of the plot.

  • xmax (scalar, optional, default: 0) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right of the plot.

  • linestyle (str, optional, default: '-') – Any of [‘solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’]

  • linewidth (float, optional) – Float value in points.

  • color (color) – Any matplotlib color. See Colors.

Returns

Line2D wrapped in SyArtist.

Return type

SyArtist

axvline(x=0, ymin=0, ymax=1, color=None, linewidth=1.0, linestyle='-')[source]

Add a vertical line across the axes.

Parameters
  • x (scalar, optional, default: 0) – x position in data coordinates of the vertical line.

  • ymin (scalar, optional, default: 0) – Should be between 0 and 1, 0 being the bottom of the plot, 1 the top of the plot.

  • ymax (scalar, optional, default: 0) – Should be between 0 and 1, 0 being the bottom of the plot, 1 the top of the plot.

  • linestyle (str, optional, default: '-') – Any of [‘solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’]

  • linewidth (float, optional) – Float value in points.

  • color (color) – Any matplotlib color. See Colors.

Returns

Line2D wrapped in SyArtist.

Return type

SyArtist

bar(left, height, width=0.8, bottom=None, color=None)[source]

Make a bar plot.

Make a bar plot with rectangles bounded by:

left, left + width, bottom, bottom + height

(left, right, bottom and top edges)

Parameters
  • left (sequence of scalars) – the x coordinates of the left sides of the bars

  • height (sequence of scalars) – the heights of the bars

  • width (scalar or array-like, optional) – the width(s) of the bars default: 0.8

  • bottom (scalar or array-like, optional) – the y coordinate(s) of the bars default: None

  • color (scalar or array-like, optional) – face color of the bars

Returns

List of SyArtist s.

Return type

list

get_mpl_axes()[source]

Return the underlying matplotlib Axes object.

Warning

When using this function you will get access to the entire matplotlib API. That API is likely to change slightly over time completely outside of our control. If you want to be sure that the code you are writing continues to work as expected in upcoming versions of Sympathy you should not use this method.

grid(b=None, which='major', axis='both', color=None, linestyle=None, linewidth=None)[source]

Turn the axes grids on or off.

Parameters
  • b (bool, optional) – Set the axes grids on or off. None with len(kwargs) toggles the grid state.

  • which (str, optional) – Can be ‘major’ (default), ‘minor’, or ‘both’. Controls whether only major, only minor, or both tick grids are affected.

  • axis (str, optional) – Can be ‘both’ (default), ‘x’, or ‘y’. Controls which set of gridlines are drawn.

  • color (color, optional) – Any matplotlib color. See Colors.

  • linestyle (str) – Any of [‘solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’]

  • linewidth (float, optional) – Float value in points.

heatmap(x, y, c, cmap=None, vmin=None, vmax=None, edgecolor=None, linewidth=None)[source]

Create a heatmap from

Parameters
  • x (array_like, shape (m+1,)) – x is 1D arrays of length nc +1 giving the x boundaries of the cells.

  • y (array_like, shape (n+1,)) – y is 1D arrays of length nr +1 giving the y boundaries of the cells.

  • c (array_like, shape (m, n)) – A 2D array of color values.

  • cmap ({ None | Colormap }) – A matplotlib.colors.Colormap instance. If None, use rc settings.

  • edgecolor ({None | 'None' | 'face' | color | color sequence}) – If None, the rc setting is used by default. If 'None', edges will not be visible. If 'face', edges will have the same color as the faces. An mpl color or sequence of colors will set the edge color

  • linewidth (float, optional) – Float value in points.

Returns

SyArtist of the matplotlib collection.

Return type

SyArtist

hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False, bottom=None, histtype='bar', align='mid', orientation='vertical', rwidth=None, log=False, color=None, label=None, stacked=False)[source]

Plot a histogram.

Compute and draw the histogram of x. The return value is a tuple (n, bins, patches) or ([n0, n1, …], bins, [patches0, patches1,…]) if the input contains multiple data.

Multiple data can be provided via x as a list of datasets of potentially different length ([x0, x1, …]), or as a 2-D ndarray in which each column is a dataset. Note that the ndarray form is transposed relative to the list form.

Masked arrays are not supported at present.

Parameters
  • x ((n,) array or sequence of (n,) arrays) – Input values, this takes either a single array or a sequency of arrays which are not required to be of the same length

  • bins (integer or array_like, optional) –

    If an integer is given, bins + 1 bin edges are returned, consistently with numpy.histogram() for numpy version >= 1.3.

    Unequally spaced bins are supported if bins is a sequence.

    default is 10

  • range (tuple or None, optional) –

    The lower and upper range of the bins. Lower and upper outliers are ignored. If not provided, range is (x.min(), x.max()). Range has no effect if bins is a sequence.

    If bins is a sequence or range is specified, autoscaling is based on the specified bin range instead of the range of x.

    Default is None

  • normed (boolean, optional) –

    If True, the first element of the return tuple will be the counts normalized to form a probability density, i.e., n/(len(x)`dbin), i.e., the integral of the histogram will sum to 1. If stacked is also True, the sum of the histograms is normalized to 1.

    Default is False

  • weights ((n, ) array_like or None, optional) –

    An array of weights, of the same shape as x. Each value in x only contributes its associated weight towards the bin count (instead of 1). If normed is True, the weights are normalized, so that the integral of the density over the range remains 1.

    Default is None

  • cumulative (boolean, optional) –

    If True, then a histogram is computed where each bin gives the counts in that bin plus all bins for smaller values. The last bin gives the total number of datapoints. If normed is also True then the histogram is normalized such that the last bin equals 1. If cumulative evaluates to less than 0 (e.g., -1), the direction of accumulation is reversed. In this case, if normed is also True, then the histogram is normalized such that the first bin equals 1.

    Default is False

  • bottom (array_like, scalar, or None) –

    Location of the bottom baseline of each bin. If a scalar, the base line for each bin is shifted by the same amount. If an array, each bin is shifted independently and the length of bottom must match the number of bins. If None, defaults to 0.

    Default is None

  • histtype ({'bar', 'barstacked', 'step', 'stepfilled'}, optional) –

    The type of histogram to draw.

    • ’bar’ is a traditional bar-type histogram. If multiple data are given the bars are aranged side by side.

    • ’barstacked’ is a bar-type histogram where multiple data are stacked on top of each other.

    • ’step’ generates a lineplot that is by default unfilled.

    • ’stepfilled’ generates a lineplot that is by default filled.

    Default is ‘bar’

  • align ({'left', 'mid', 'right'}, optional) –

    Controls how the histogram is plotted.

    • ’left’: bars are centered on the left bin edges.

    • ’mid’: bars are centered between the bin edges.

    • ’right’: bars are centered on the right bin edges.

    Default is ‘mid’

  • orientation ({'horizontal', 'vertical'}, optional) – If ‘horizontal’, the bottom kwarg will be the left edges.

  • rwidth (scalar or None, optional) –

    The relative width of the bars as a fraction of the bin width. If None, automatically compute the width.

    Ignored if histtype is ‘step’ or ‘stepfilled’.

    Default is None

  • log (boolean, optional) –

    If True, the histogram axis will be set to a log scale. If log is True and x is a 1D array, empty bins will be filtered out and only the non-empty (n, bins, patches) will be returned.

    Default is False

  • color (color or array_like of colors or None, optional) –

    Color spec or sequence of color specs, one per dataset. Default (None) uses the standard line color sequence.

    Default is None

  • label (string or None, optional) –

    String, or sequence of strings to match multiple datasets. Bar charts yield multiple patches per dataset, but only the first gets the label, so that the legend command will work as expected.

    default is None

  • stacked (boolean, optional) –

    If True, multiple data are stacked on top of each other If False multiple data are aranged side by side if histtype is ‘bar’ or on top of each other if histtype is ‘step’

    Default is False

Returns

  • n (array or list of arrays) – The values of the histogram bins. See normed and weights for a description of the possible semantics. If input x is an array, then this is an array of length nbins. If input is a sequence arrays [data1, data2,..], then this is a list of arrays with the values of the histograms for each of the arrays in the same order.

  • bins (array) – The edges of the bins. Length nbins + 1 (nbins left edges and right edge of last bin). Always a single array even when multiple data sets are passed in.

legend(handles=None, labels=None, loc='upper right', ncol=1, fontsize=None, frameon=None, title=None)[source]

Places a legend on the axes.

Parameters
  • handles (array_like, shape (n,)) – List of Artist handles.

  • labels (array_like, shape (n,)) – List of Artist labels.

  • loc (str or int, optional) – The location of the legend. See Location. Default is ‘upper right’.

  • ncol (int, optional) – The number of columns that the legend has. Default is 1.

  • fontsize (int or float or str, optional) – Controls the font size of the legend. If given as string, following strings are possible {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size.

  • frameon (bool or None, optional) – Controls whether a frame should be drawn around the legend. Default is None which will take the value from the legend.frameon rcParam.

  • title (str or None, optional) – The legend’s title. Default is no title (None).

plot(x, y, label=None, color=None, marker=None, markersize=None, markeredgecolor=None, markeredgewidth=None, markerfacecolor=None, linestyle='-', linewidth=1.0, alpha=1.0, drawstyle='default', zorder=None)[source]

Plot lines and/or markers to the axes.

Parameters
  • x (array_like, shape (n,)) – The data for the x axis.

  • y (array_like, shape (n,)) – The data for the y axis.

  • label (unicode, optional) – The label of the line.

  • color (color, optional) – Any matplotlib color. See Colors.

  • marker (str, optional) – Defines the marker style. See Markers for all available markers.

  • markersize (float, optional) – Defines the marker size.s

  • markeredgecolor (color, optional) – Any matplotlib color. See Colors.

  • markeredgewidth (float, optional) – Float value in points.

  • markerfacecolor (color, optional) – Any matplotlib color. See Colors.

  • linestyle (str, optional) – Any of [‘solid’ | ‘dashed’, ‘dashdot’, ‘dotted’ | ‘-‘ | ‘–’ | ‘-.’ | ‘:’ | ‘None’ | ‘ ‘ | ‘’]

  • linewidth (float, optional) – Float value in points.

  • alpha (float, optional) – Defines the transparency. Float value between 0. and 1. Default is 1.

  • drawstyle (str, optional) – Defines the drawstyle of the plot. Accepts: [‘default’, ‘steps’, ‘steps-pre’, ‘steps-mid’, ‘steps-post’]

  • zorder (int, optional) – Define the z-order for this artist.

Returns

artists – Returns a list of SyArtist s.

Return type

list

scatter(x, y, size=20, color=None, marker='o', cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, linestyles=None, edgecolors=None, label=None, zorder=None)[source]

Make a scatter plot of x vs y, where x and y are sequence like objects of the same lengths.

Parameters
  • y (x,) – Input data

  • size (scalar or array_like, shape (n, ), optional, default: 20) – size in points^2.

  • color (color or sequence of color, optional, default : 'b') – color can be a single color format string, or a sequence of color specifications of length N, or a sequence of N numbers to be mapped to colors using the cmap and norm specified via kwargs (see below). Note that color should not be a single numeric RGB or RGBA sequence because that is indistinguishable from an array of values to be colormapped. color can be a 2-D array in which the rows are RGB or RGBA, however, including the case of a single row to specify the same color for all points. See also Colors.

  • marker (marker, optional, default: 'o') – See Markers for more information on the different styles of markers scatter supports. marker can be either an instance of the class or the text shorthand for a particular marker.

  • cmap (~matplotlib.colors.Colormap, optional, default: None) – A ~matplotlib.colors.Colormap instance or registered name. cmap is only used if color is an array of floats.

  • norm (~matplotlib.colors.Normalize, optional, default: None) – A ~matplotlib.colors.Normalize instance is used to scale luminance data to 0, 1. norm is only used if color is an array of floats. If None, use the default normalize().

  • vmax (vmin,) – vmin and vmax are used in conjunction with norm to normalize luminance data. If either are None, the min and max of the color array is used. Note if you pass a norm instance, your settings for vmin and vmax will be ignored.

  • alpha (scalar, optional, default: None) – The alpha blending value, between 0 (transparent) and 1 (opaque)

  • linewidths (scalar or array_like, optional, default: None) –

  • edgecolors (color or sequence of color, optional, default: None) – If ‘face’, the edge color will always be the same as the face color. If it is ‘none’, the patch boundary will not be drawn. For non-filled markers, the edgecolors kwarg is ignored; color is determined by color.

  • label (unicode, optional) – The label of the line.

  • zorder (int, optional) – Define the z-order for this artist.

set_axis(state)[source]

Sets the axes frame/ticks/labels visibility on/off.

set_title(title, fontsize=None)[source]

Set the title of the axes.

Parameters

fontsize (int or float or str, optional) – Controls the font size of the legend. If given as string, following strings are possible {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size.

set_xlabel(label, fontsize=None)[source]

Set the label for the x-axis.

Parameters

fontsize (int or float or str, optional) – Controls the font size of the legend. If given as string, following strings are possible {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size.

set_xlim(left=None, right=None)[source]

Set the data limits for the x-axis.

Examples

>>> set_xlim((left, right))
>>> set_xlim(left, right)
>>> set_xlim(left=1)  # right unchanged
>>> set_xlim(right=1)  # left unchanged
set_xticklabels(labels)[source]

Set the x-tick labels with list of strings labels.

set_ylabel(label, fontsize=None)[source]

Set the label for the y-axis.

Parameters

fontsize (int or float or str, optional) – Controls the font size of the legend. If given as string, following strings are possible {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size.

set_ylim(bottom=None, top=None)[source]

Set the data limits for the y-axis.

Examples

>>> set_ylim((bottom, top))
>>> set_ylim(bottom, top)
>>> set_ylim(bottom=1)  # top unchanged
>>> set_ylim(top=1)  # bottom unchanged
set_yticklabels(labels)[source]

Set the y-tick labels with list of strings labels.

text(x, y, s, color=None, fontsize=None, bold=False, horizontalalignment='left', verticalalignment='top', data_coordinates=True)[source]

Add text to the axes.

Parameters
  • x (scalars) – x data coordinates.

  • y (scalars) – y data coordinates.

  • s (unicode) – The text to be shown.

  • color (color, optional) – Any matplotlib color. See Colors.

  • bold (boolean, optional) – If True, use a bold font. If False (the default), use a normal font.

  • fontsize (int or float or str, optional) – Controls the font size of the legend. If given as string, following strings are possible {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}. If the value is numeric the size will be the absolute font size in points. String values are relative to the current default font size.

  • horizontalalignment ({'center', 'right', 'left'}, optional) –

  • verticalalignment ({'center', 'top', 'bottom', 'baseline'}, optional) –

  • data_coordinates (bool, optional, default True) – If True, x and y are assumed to be in data coordinates. If False, they are assumed to be in axes coordinates.

Returns

The text wrapped in a SyArtist.

Return type

SyArtist

twinx()[source]

Create a twin SyAxes with shared x-axis.

twiny()[source]

Create a twin SyAxes with shared y-axis.

Class figure.SyArtist

class sympathy.typeutils.figure.SyArtist(artist)[source]

Wrapper around matplotlib Artist.

__eq__(other)[source]

Return self==value.

__init__(artist)[source]

Initialize self. See help(type(self)) for accurate signature.

__ne__(other)[source]

Return self!=value.

__weakref__

list of weak references to the object (if defined)

get_mpl_artist()[source]

Returns the underlying matplotlib Artist object.

Warning

When using this function you will get access to the entire matplotlib API. That API is likely to change slightly over time completely outside of our control. If you want to be sure that the code you are writing continues to work as expected in upcoming versions of Sympathy you should not use this method.