artist Package

Artist makes beautiful plots.

Artist is a 2D plotting library for Python. It’s main focus is the output. Artist creates a LaTeX file which can be included in your paper or thesis. The code needs TikZ and PGFPlots to compile and your plots will tightly integrate with your main text. Artist provides an easy-to-use and clean Python interface and can compile your plot on-the-fly as a stand-alone PDF file.

Rationale

Artist enables you to visualize the results of your data analysis. The quality of your plots should reflect the quality of your analysis. With most software, this is hardly possible and the term ‘publication quality’ takes on an entirely new meaning. As a result, many papers and theses suffer from inconsistent and generally poor-quality plots.

Fortunately, some solutions are available. For LaTeX users, one can use PGF/TikZ for generating figures and plots. This ensures a very consistent display throughout your document. PGFPLOTS builds on that to provide a user-friendly interface for many kinds of plots and to allow extensive customization.

For many users, however, it is more convenient to use a programmatic interface from your favorite programming language. For Python, such an interface is available in Artist.

Artist can be used in place of other plotting libraries, but the output is a LaTeX file requiring PGF/TikZ and PGFPLOTS. Previewing the output is possible by means of a simple method which renders the plot as a PDF.

The style of the plots is based on the work of William S. Cleveland.

Contents

The following modules are included:

plot
contains the Plot and PolarPlot classes for creating plots.
multi_plot
contains the MultiPlot class for creating plots comprised of multiple subplots.
simple_smooth
contains a very basic smoothing algorithm.
recursive_smooth
contains a more sophisticated recursive smooth() algorithm.
utils
contains utility functions for e.g. automagic naming of output files based on the name of the function creating the plot.
colormap
contains colormaps for colored 2D histograms.

plot Module

Create a plot.

Contents

BasePlotContainer
Base class for standalone plots.
SubPlot
Plot data in a data rectangle.
Plot
Create a plot containing a single subplot.
PolarPlot
Create a plot containing a single polar subplot.
class artist.plot.BasePlotContainer

Bases: object

Base class for stand-alone plots.

This class provides methods for rendering the plot. To provide methods for plotting and annotating, subclass this base class.

template = None
document_template = None
render(template=None)

Render the plot using a template.

Once the plot is complete, it needs to be rendered. Artist uses the Jinja2 templating engine. The default template results in a LaTeX file which can be included in your document.

Parameters:template (string or None.) – a user-supplied template or None.
Returns:the rendered template as string.

This is a very minimal implementation. Override this method to include variables in the template.render call.

save_assets(dest_path)

Save plot assets alongside dest_path.

Some plots may have assets, like bitmap files, which need to be saved alongside the rendered plot file.

Parameters:dest_path – path of the main output file.
render_as_document()

Render the plot as a stand-alone document.

Returns:the rendered template as string.
save(dest_path)

Save the plot as a includable LaTeX file.

The output file can be included (using input) in your LaTeX document.

Parameters:dest_path – path of the file.
save_as_document(dest_path)

Save the plot as a stand-alone LaTeX file.

Parameters:dest_path – path of the file.
save_as_pdf(dest_path)

Save the plot as a PDF file.

Save and render the plot using LaTeX to create a PDF file.

Parameters:dest_path – path of the file.
class artist.plot.SubPlot

Bases: object

Plot data in a data rectangle.

Provides methods to plot or histogram data, shade regions, add labels, pins and titles. This class is not meant to be used directly. Instead, use the Plot class for single plots, or the MultiPlot class for plots containing multiple subplots.

save_assets(dest_path, suffix='')

Save plot assets alongside dest_path.

Some plots may have assets, like bitmap files, which need to be saved alongside the rendered plot file.

Parameters:
  • dest_path – path of the main output file.
  • suffix – optional suffix to add to asset names.
plot(x, y, xerr=[], yerr=[], mark='o', linestyle='solid', use_steps=False, markstyle=None, legend=None)

Add a data series to the plot.

Parameters:
  • x – array containing x-values.
  • y – array containing y-values.
  • xerr – (optional) array containing errors on the x-values.
  • yerr – (optional) array containing errors on the y-values.
  • mark – the symbol used to mark the data point. May be None, or any plot mark accepted by TikZ (e.g. *, x, +, o, square, triangle).
  • linestyle – the line style used to connect the data points. May be None, or any line style accepted by TikZ (e.g. solid, dashed, dotted, thick, or even combinations like “red,thick,dashed”).
  • use_steps – if True, draw a stepped plot.
  • markstyle – the style of the plot marks (e.g. ‘mark size=.75pt’)

The dimensions of x, y, xerr and yerr should be equal. However, xerr and yerr may be empty lists. Each element in xerr and yerr may be a single value for symmetric error bars, or a tuple of two values for assymetric errors.

histogram(counts, bin_edges, linestyle='solid')

Plot a histogram.

The user needs to supply the histogram. This method only plots the results. You can use NumPy’s histogram function.

Parameters:
  • counts – array containing the count values.
  • bin_edges – array containing the bin edges.
  • linestyle – the line style used to connect the data points. May be None, or any line style accepted by TikZ (e.g. solid, dashed, dotted, thick, or even combinations like “red,thick,dashed”).

Example:

>>> plot = artist.Plot()
>>> x = np.random.normal(size=1000)
>>> n, bins = np.histogram(x)
>>> plot.histogram(n, bins)
histogram2d(counts, x_edges, y_edges, type='bw', style=None, bitmap=False, colormap=None)

Plot a two-dimensional histogram.

The user needs to supply the histogram. This method only plots the results. You can use NumPy’s histogram2d function.

Parameters:
  • counts – array containing the count values.
  • x_edges – array containing the x-axis bin edges.
  • y_edges – array containing the y-axis bin edges.
  • type – the type of histogram. Allowed values are ‘bw’ for filled squares with shades from black (minimum value) to white (maximum value), ‘reverse_bw’ for filled squares with the shades reversed and, ‘color’ for color mapped histogram which uses the ‘coolwarm’ colormap by default, but can be overwritten with the colormap keyword, and ‘area’ for squares where the area of the square is a measure of the count in the bin.
  • style – optional TikZ styles to apply (e.g. ‘red’). Note that many color styles are overridden by the ‘bw’ and ‘reverse_bw’ types.
  • bitmap – Export the histogram as an image for better performance. This does expect all bins along an axis to have equal width. Can not be used in combination with type ‘area’.
  • colormap – A colormap for the ‘color’ type, as expected by the Image.putpalette method.

Example:

>>> x = np.random.uniform(low=1, high=1000, size=2000)
>>> y = np.random.uniform(low=0, high=50, size=2000)
>>> plot = artist.Plot()
>>> n, xbins, ybins = np.histogram2d(x, y)
>>> plot.histogram2d(n, xbins, ybins)

When you desire logarithmic axes and bitmap is set to True special care has to be taken with the binning. This is because the bins along an axis have to be equal size in the final result. So use logarithmic binning for logarithmic axes.

Example:

>>> plot = artist.Plot(axis='semilogx')
>>> xbins = np.logspace(0, 3, 20)
>>> ybins = np.linspace(-5, 10, 10)
>>> n, xbins, ybins = np.histogram2d(x, y, bins=[xbins, ybins])
>>> plot.histogram2d(n, xbins, ybins, bitmap=True)

For each bin where the counts are nan the value will be set to the minimum value (i.e. np.nanmin(counts)).

scatter(x, y, xerr=[], yerr=[], mark='o', markstyle=None)

Plot a series of points.

Plot a series of points (marks) that are not connected by a line. Shortcut for plot with linestyle=None.

Parameters:
  • x – array containing x-values.
  • y – array containing y-values.
  • xerr – array containing errors on the x-values.
  • yerr – array containing errors on the y-values.
  • mark – the symbol used to mark the data points. May be any plot mark accepted by TikZ (e.g. *, x, +, o, square, triangle).
  • markstyle – the style of the plot marks (e.g. ‘mark size=.75pt’)

Example:

>>> plot = artist.Plot()
>>> x = np.random.normal(size=20)
>>> y = np.random.normal(size=20)
>>> plot.scatter(x, y, mark='*')
scatter_table(x, y, c, s, mark='*')

Add a data series to the plot.

Parameters:
  • x – array containing x-values.
  • y – array containing y-values.
  • c – array containing values for the color of the mark.
  • s – array containing values for the size of the mark.
  • mark – the symbol used to mark the data point. May be None, or any plot mark accepted by TikZ (e.g. *, x, +, o, square, triangle).

The dimensions of x, y, c and s should be equal. The c values will be mapped to a colormap.

set_title(text)

Set a title text.

set_label(text, location='upper right', style=None)

Set a label for the plot.

Parameters:
  • text – the label text.
  • location – the location of the label inside the plot. May be one of ‘center’, ‘upper right’, ‘lower right’, ‘upper left’, ‘lower left’.
  • style – any TikZ style to style the text.
add_pin(text, location='left', x=None, use_arrow=False, relative_position=None, style=None)

Add pin to most recent data series.

Parameters:
  • text – the text of the pin label.
  • location (string) – the location of the pin relative to the data point. Any location accepted by TikZ is allowed.
  • x – the x location of the data point (in the most recent data series) at which to place the label. This is interpolated between the actual data points. If None, only the relative_position parameter is used.
  • use_arrow (boolean) – specifies whether to draw an arrow between the data point and the pin label text.
  • relative_position – location of the data point as a relative number between 0 and 1.
  • style – optional TikZ styles to apply (e.g. ‘red’).
add_pin_at_xy(x, y, text, location='above right', relative_position=0.9, use_arrow=True, style=None)

Add pin at x, y location.

Parameters:
  • x – array, list or float, specifying the location of the pin.
  • y – array, list or float, specifying the location of the pin.
  • text – the text of the pin label.
  • location – the location of the pin relative to the data point. Any location accepted by TikZ is allowed.
  • relative_position – location of the data point as a relative number between 0 and 1.
  • use_arrow (boolean) – specifies whether to draw an arrow between the data point and the pin label text.
  • style – optional TikZ styles to apply (e.g. ‘red’).

If x, y are arrays or lists, relative position is used to pick a point from the arrays. A relative position of 0.0 will be the first point from the series, while 1.0 will be the last point.

shade_region(x, lower, upper, color='lightgray')

Shade a region between upper and lower bounds.

Parameters:
  • x – array containing x-values
  • lower – array containing y-values of lower bounds
  • upper – array containing y-values of upper bounds
  • color – TikZ style to color the region
draw_image(image, xmin=0, ymin=0, xmax=None, ymax=None)

Draw an image.

Do not forget to use set_axis_equal() to preserve the aspect ratio of the image, or change the aspect ratio of the plot to the aspect ratio of the image.

Parameters:
  • image – Pillow Image object.
  • xmin,ymin,xmax,ymax – the x, y image bounds.

Example:

>>> from PIL import Image
>>> image = Image.open('background.png')
>>> height_ratio = (.67 * image.size[1]) / image.size[0]
>>> plot = artist.Plot(height=r'%.2f\linewidth' % height_ratio)
>>> plot.draw_image(image)
draw_horizontal_line(yvalue, linestyle=None)

Draw a horizontal line.

Parameters:
  • yvalue – y-value of the line
  • linestyle – TikZ linestyle (e.g. dashed, solid, red)
draw_vertical_line(xvalue, linestyle=None)

Draw a vertical line.

Parameters:
  • xvalue – x-value of the line
  • linestyle – TikZ linestyle (e.g. dashed, solid, red)
set_axis_background(color='white')

Set a fill color for the axis background.

Parameters:color – TikZ style to color the axis background.
set_xlabel(text)

Set a label for the x-axis.

Parameters:text – text of the label.
set_ylabel(text)

Set a label for the y-axis.

Parameters:text – text of the label.
set_xlimits(min=None, max=None)

Set limits for the x-axis.

Parameters:
  • min – minimum value to be displayed. If None, it will be calculated.
  • max – maximum value to be displayed. If None, it will be calculated.
set_ylimits(min=None, max=None)

Set limits for the y-axis.

Parameters:
  • min – minimum value to be displayed. If None, it will be calculated.
  • max – maximum value to be displayed. If None, it will be calculated.
set_xscale(cm)

Set scale of the x-axis.

Parameters:cm – number of units which equals to 1 cm.

You can set the absolute scale of units along the x-axis using this method. If you specify cm=10, then 1 cm along the axis will equal to 10 units. You can use this, for example, to match up graph paper to the axis, and make sure that a ruler can easily be used to read your graph.

set_yscale(cm)

Set scale of the y-axis.

Parameters:cm – number of units which equals to 1 cm.

You can set the absolute scale of units along the y-axis using this method. If you specify cm=10, then 1 cm along the axis will equal to 10 units. You can use this, for example, to match up graph paper to the axis, and make sure that a ruler can easily be used to read your graph.

set_mlimits(min=None, max=None)

Set limits for the point meta (colormap).

Point meta values outside this range will be clipped.

Parameters:
  • min – value corresponding to the start of the colormap. If None, it will be calculated.
  • max – value corresponding to the end of the colormap. If None, it will be calculated.
set_slimits(min, max)

Set limits for the size of points in scatter_table().

If both are None, the size will be the given values.

Parameters:
  • min – point size for the lowest value.
  • max – point size for the highest value.
set_xticks(ticks)

Set ticks for the x-axis.

Parameters:ticks – locations for the ticks along the axis.
set_yticks(ticks)

Set ticks for the y-axis.

Parameters:ticks – locations for the ticks along the axis.
set_logxticks(logticks)

Set ticks for the logarithmic x-axis.

Parameters:logticks – logarithm of the locations for the ticks along the axis.

For example, if you specify [1, 2, 3], ticks will be placed at 10, 100 and 1000.

set_logyticks(logticks)

Set ticks for the logarithmic y-axis.

Parameters:logticks – logarithm of the locations for the ticks along the axis.

For example, if you specify [1, 2, 3], ticks will be placed at 10, 100 and 1000.

set_xtick_labels(labels, style=None)

Set tick labels for the x-axis.

Also set the x-ticks positions to ensure the labels end up on the correct place.

Parameters:labels – list of labels for the ticks along the axis.
set_ytick_labels(labels, style=None)

Set tick labels for the y-axis.

Also set the y-ticks positions to ensure the labels end up on the correct place.

Parameters:labels – list of labels for the ticks along the axis.
set_xtick_suffix(suffix)

Set the suffix for the ticks of the x-axis.

Parameters:suffix – string added after each tick. If the value is degree or precent the corresponding symbols will be added.
set_ytick_suffix(suffix)

Set ticks for the y-axis.

Parameters:suffix – string added after each tick. If the value is degree or precent the corresponding symbols will be added.
set_axis_equal()

Scale the axes so the unit vectors have equal length.

set_scalebar(location='lower right')

Show marker area scale.

Parameters:location – the location of the label inside the plot. May be one of ‘center’, ‘upper right’, ‘lower right’, ‘upper left’, ‘lower left’.
set_colorbar(label='', horizontal=False)

Show the colorbar.

This can be used for both histogram2d and scatter_table. If a custom colomap is used for histogram2d (i.e. not grayscale, coolwarm, or viridis) a matching colormap must be available in PGFPlots or added using set_axis_options.

Parameters:
  • label – axis label for the colorbar.
  • horizontal – boolean, if True the colobar will be horizontal.
set_colormap(name)

Choose a colormap for scatter_table().

Parameters:name – name of the colormap to use. (e.g. hot, cool, blackwhite, greenyellow). If None a coolwarm colormap is used.
set_axis_options(text)

Set additionnal options as plain text.

use_graph_paper()

Draw millimeter graph paper.

class artist.plot.Plot(axis='', width='.67\linewidth', height=None)

Bases: artist.plot.SubPlot, artist.plot.BasePlotContainer

Create a plot containing a single subplot.

This class creates a 2D plot. Its various methods add data, annotations and options which is stored in class variables. Finally, the plot can be rendered using the Jinja2 templating engine resulting in a LaTeX or PDF file.

render(template=None)

Render the plot using a template.

Once the plot is complete, it needs to be rendered. Artist uses the Jinja2 templating engine. The default template results in a LaTeX file which can be included in your document.

Parameters:template (string or None.) – a user-supplied template or None.
Returns:the rendered template as string.
class artist.plot.PolarPlot(*args, **kwargs)

Bases: artist.plot.Plot

Create a plot containing a single polar subplot.

Same as the Plot but uses polar axes. The x values are the phi coordinates in degrees (or radians). The y values are the r coordinates in arbitrary units.

Parameters:use_radians – If this keyword is set to True the units for x (phi) values and x (phi) axis labels are radians.
plot(phi, r, **kwargs)

Add a data series to the plot.

Parameters:
  • phi – array containing phi-values, should be in degrees (or radians).
  • r – array containing r-values.

For further options see the plot function of the super class.

histogram(counts, bin_edges, linestyle='solid')

Plot a polar histogram.

The user needs to supply the histogram. This method only plots the results. You can use NumPy’s histogram function.

Parameters:
  • counts – array containing the count values.
  • bin_edges – array containing the bin edges in degrees (or radians).
  • linestyle – the line style used to connect the data points. May be None, or any line style accepted by TikZ (e.g. solid, dashed, dotted, thick, or even combinations like “red,thick,dashed”).

Example:

>>> plot = artist.PolarPlot()
>>> x = np.random.uniform(0, 360, size=1000)
>>> n, bins = np.histogram(x, bins=np.linspace(0, 360, 37))
>>> plot.histogram(n, bins)
histogram2d(*args)

Do not allow 2D histograms, it produces undesireable results.

set_xlimits(min=None, max=None)

Do not allow setting x limits, it messes with the axes.

multi_plot Module

Create a plot containing multiple subplots.

Contents

MultiPlot
Create a plot containing multiple subplots.
SubPlotContainer
Adds metadata to a SubPlot instance for use in a MultiPlot.
class artist.multi_plot.MultiPlot(rows, columns, axis='', width='.67\linewidth', height=None)

Bases: artist.plot.BasePlotContainer

Create a plot containing multiple subplots.

This class creates a 2D plot containing multiple subplots. The number of rows and columns can be specified and some of the subplot rectangles can remain empty (nothing is drawn, not even an axis rectangle). Its various methods add data, annotations and options which is stored in class variables. Finally, the plot can be rendered using the Jinja2 templating engine resulting in a LaTeX or PDF file.

save_assets(dest_path)

Save plot assets alongside dest_path.

Some plots may have assets, like bitmap files, which need to be saved alongside the rendered plot file.

Parameters:dest_path – path of the main output file.
set_empty(row, column)

Keep one of the subplots completely empty.

Parameters:row,column – specify the subplot.
set_empty_for_all(row_column_list)

Keep all specified subplots completely empty.

Parameters:row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
set_title(row, column, text)

Set a title text.

Parameters:
  • row,column – specify the subplot.
  • text – title text.
set_label(row, column, text, location='upper right', style=None)

Set a label for the subplot.

Parameters:
  • row,column – specify the subplot.
  • text – the label text.
  • location – the location of the label inside the plot. May be one of ‘center’, ‘upper right’, ‘lower right’, ‘upper left’, ‘lower left’.
  • style – any TikZ style to style the text.
show_xticklabels(row, column)

Show the x-axis tick labels for a subplot.

Parameters:row,column – specify the subplot.
show_xticklabels_for_all(row_column_list=None)

Show the x-axis tick labels for all specified subplots.

Parameters:row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
show_yticklabels(row, column)

Show the y-axis tick labels for a subplot.

Parameters:row,column – specify the subplot.
show_yticklabels_for_all(row_column_list=None)

Show the y-axis tick labels for all specified subplots.

Parameters:row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
set_xticklabels_position(row, column, position)

Specify the position of the axis tick labels.

This is generally only useful for multiplots containing only one row. This can be used to e.g. alternatively draw the tick labels on the bottom or the top of the subplot.

Parameters:
  • row,column – specify the subplot.
  • position – ‘top’ or ‘bottom’ to specify the position of the tick labels.
set_yticklabels_position(row, column, position)

Specify the position of the axis tick labels.

This is generally only useful for multiplots containing only one column. This can be used to e.g. alternatively draw the tick labels on the left or the right of the subplot.

Parameters:
  • row,column – specify the subplot.
  • position – ‘left’ or ‘right’ to specify the position of the tick labels.
set_xlimits(row, column, min=None, max=None)

Set x-axis limits of a subplot.

Parameters:
  • row,column – specify the subplot.
  • min – minimal axis value
  • max – maximum axis value
set_xlimits_for_all(row_column_list=None, min=None, max=None)

Set x-axis limits of specified subplots.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • min – minimal axis value
  • max – maximum axis value
set_ylimits(row, column, min=None, max=None)

Set y-axis limits of a subplot.

Parameters:
  • row,column – specify the subplot.
  • min – minimal axis value
  • max – maximum axis value
set_ylimits_for_all(row_column_list=None, min=None, max=None)

Set y-axis limits of specified subplots.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • min – minimal axis value
  • max – maximum axis value
set_mlimits(row, column, min=None, max=None)

Set limits for the point meta (colormap).

Point meta values outside this range will be clipped.

Parameters:
  • min – value for start of the colormap.
  • max – value for end of the colormap.
set_mlimits_for_all(row_column_list=None, min=None, max=None)

Set limits for point meta (colormap) for specified subplots.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • min – value for start of the colormap.
  • max – value for end of the colormap.
set_slimits(row, column, min, max)

Set limits for the point sizes.

Parameters:
  • min – point size for the lowest value.
  • max – point size for the highest value.
set_slimits_for_all(row_column_list=None, min=None, max=None)

Set point size limits of specified subplots.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • min – point size for the lowest value.
  • max – point size for the highest value.
set_xticks(row, column, ticks)

Manually specify the x-axis tick values.

Parameters:
  • row,column – specify the subplot.
  • ticks – list of tick values.
set_xticks_for_all(row_column_list=None, ticks=None)

Manually specify the x-axis tick values.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • ticks – list of tick values.
set_logxticks(row, column, logticks)

Manually specify the x-axis log tick values.

Parameters:
  • row,column – specify the subplot.
  • logticks – logarithm of the locations for the ticks along the axis.

For example, if you specify [1, 2, 3], ticks will be placed at 10, 100 and 1000.

set_logxticks_for_all(row_column_list=None, logticks=None)

Manually specify the x-axis log tick values.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • logticks – logarithm of the locations for the ticks along the axis.

For example, if you specify [1, 2, 3], ticks will be placed at 10, 100 and 1000.

set_yticks(row, column, ticks)

Manually specify the y-axis tick values.

Parameters:
  • row,column – specify the subplot.
  • ticks – list of tick values.
set_yticks_for_all(row_column_list=None, ticks=None)

Manually specify the y-axis tick values.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • ticks – list of tick values.
set_logyticks(row, column, logticks)

Manually specify the y-axis log tick values.

Parameters:
  • row,column – specify the subplot.
  • logticks – logarithm of the locations for the ticks along the axis.

For example, if you specify [1, 2, 3], ticks will be placed at 10, 100 and 1000.

set_logyticks_for_all(row_column_list=None, logticks=None)

Manually specify the y-axis log tick values.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • logticks – logarithm of the locations for the ticks along the axis.

For example, if you specify [1, 2, 3], ticks will be placed at 10, 100 and 1000.

set_xtick_labels(row, column, labels)

Manually specify the x-axis tick labels.

Parameters:
  • row,column – specify the subplot.
  • labels – list of tick labels.
set_xtick_labels_for_all(row_column_list=None, labels=None)

Manually specify the x-axis tick labels.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • labels – list of tick labels.
set_ytick_labels(row, column, labels)

Manually specify the y-axis tick labels.

Parameters:
  • row,column – specify the subplot.
  • labels – list of tick labels.
set_ytick_labels_for_all(row_column_list=None, labels=None)

Manually specify the x-axis tick labels.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • labels – list of tick labels.
get_subplot_at(row, column)

Return the subplot at row, column position.

Parameters:row,column – specify the subplot.
render(template=None)

Render the plot using a template.

Once the plot is complete, it needs to be rendered. Artist uses the Jinja2 templating engine. The default template results in a LaTeX file which can be included in your document.

Parameters:template (string or None.) – a user-supplied template or None.
Returns:the rendered template as string.
set_xlabel(text)

Set a label for the x-axis.

Parameters:text – text of the label.
set_ylabel(text)

Set a label for the y-axis.

Parameters:text – text of the label.
set_subplot_xlabel(row, column, text)

Set a label for the x-axis of a subplot.

Parameters:
  • row,column – specify the subplot.
  • text – text of the label.
set_subplot_ylabel(row, column, text)

Set a label for the y-axis of a subplot.

Parameters:
  • row,column – specify the subplot.
  • text – text of the label.
set_scalebar_for_all(row_column_list=None, location='lower right')

Show marker area scale for subplots.

Parameters:
  • row_column_list – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • location – the location of the label inside the plot. May be one of ‘center’, ‘upper right’, ‘lower right’, ‘upper left’, ‘lower left’.
set_colorbar(label='', horizontal=False)

Show the colorbar, it will be attached to the last plot.

Not for the histogram2d, only for the scatter_table. Global mlimits should be set for this to properly reflect the colormap of each subplot.

Parameters:
  • label – axis label for the colorbar.
  • horizontal – boolean, if True the colobar will be horizontal.
set_colormap(name)

Choose a colormap for all subplots.

Parameters:name – name of the colormap to use. (e.g. hot, cool, blackwhite, greenyellow). If None a coolwarm colormap is used.
set_axis_options(row, column, text)

Set additionnal options as plain text.

set_axis_options_for_all(row_column_list=None, text='')

Set point size limits of specified subplots.

Parameters:
  • row_column_list (list or None) – a list containing (row, column) tuples to specify the subplots, or None to indicate all subplots.
  • text – axis options for the given subplots or the overall plot.
class artist.multi_plot.SubPlotContainer(row, column, xmode, ymode)

Bases: artist.plot.SubPlot

Add metadata to a SubPlot, for inclusion in MultiPlots.

This class adds some metadata to a subplot, including the mode of the plot and whether to show tick labels. For use in MultiPlots, the row and column position are attributes.

set_empty()

Set the plot to be completely empty.

show_xticklabels()

Show the x-axis tick labels for this subplot.

show_yticklabels()

Show the y-axis tick labels for this subplot.

set_xticklabels_position(position)

Specify the position of the axis tick labels.

This is generally only useful for multiplots containing only one row. This can be used to e.g. alternatively draw the tick labels on the bottom or the top of the subplot.

Parameters:position – ‘top’ or ‘bottom’ to specify the position of the tick labels.
set_yticklabels_position(position)

Specify the position of the axis tick labels.

This is generally only useful for multiplots containing only one column. This can be used to e.g. alternatively draw the tick labels on the left or the right of the subplot.

Parameters:position – ‘left’ or ‘right’ to specify the position of the tick labels.

simple_smooth Module

Simple averaging smoother.

artist.simple_smooth.smooth(x, y, degree=3)

Smooth y-values and return new x, y pair.

artist.simple_smooth.isodd(x)

Determine if number is odd.

Returns:boolean

recursive_smooth Module

Recursive linear interpolation smoother.

artist.recursive_smooth.smooth(x, y, degree=1, logx=False, logy=False)

Smooth y-values and return new x, y pair.

Parameters:
  • x,y – data values
  • degree – degree of smoothing

Smooth data by using a recursive linear interpolation technique. For degree = 0, return the original values. For degree = 1, generate a evenly spaced sequence of x-values, with the length equal to the original length. The y-values are linearly interpolated for these x-values. For degree >= 2, calls itself with degree - 1, then calculates new x-values by taking the averages of the returned x-values, and calculates new y-values by linear interpolation. The return values are thus reduced in length by one sample.

utils Module

Utility functions.

artist.utils.set_prefix(prefix)

Set global prefix for all graph names.

Parameters:prefix (string) – prefix for all plot names
artist.utils.set_suffix(suffix)

Set global suffix for all graph names.

Parameters:prefix (string) – suffix for all plot names
artist.utils.get_callers_name(level=2)

Return name of caller.

Return the name of the caller, optionally nested multiple levels deep.

Parameters:level – level of recursion. level=0 is this method, level=1 is the caller, and level=2 is the caller’s parent.
artist.utils.create_graph_name(suffix='', dirname=None)

Create a graph name using the name of the caller.

Parameters:
  • suffix – optional suffix to add to name
  • dirname – optional directory name
Returns:

path for the named graph
Return type:

string
artist.utils.save_graph(graph, suffix='', dirname=None, pdf=False)

Save a graph using caller’s name.

Parameters:
  • suffix – optional suffix to add to name
  • dirname – optional directory name
  • pdf – if True, the saved graph is additionally rendered and saved as a pdf, alongside the LaTeX file.
artist.utils.save_data(data, suffix='', dirname=None)

Save a dataset using caller’s name.

Parameters:
  • data – a list or numpy array containing the data
  • suffix – optional suffix to add to name
  • dirname – optional directory name

colormap Module

Colormaps for use in bitmap 2D histograms

The values are grouped by 3, RGB, and must be a total of 768 values. Greyscale values will be mapped to these color values.