aspecd.plotting module

Plotting: Graphical representations of data extracted from datasets.

Plotting relies on matplotlib, and mainly its object-oriented interface should be used for the actual plotting. Each plotter contains references to the respective figure and axes created usually by a call similar to:

fig, ax = matplotlib.pyplot.subplots()

For convenience, short hands for the figure and axes properties of a plotter are available, named fig and ax, respectively.

Generally, two types of plotters can be distinguished:

In the first case, the plot is usually handled using the plot() method of the respective aspecd.dataset.Dataset object. Additionally, those plotters always only operate on the data of a single dataset, and the plot can easily be attached as a representation to the respective dataset. Plotters handling single datasets should always inherit from the aspecd.plotting.SinglePlotter class.

In the second case, the plot is handled using the plot() method of the aspecd.plotting.Plotter object, and the datasets are stored as a list within the plotter. As these plots span several datasets, there is no easy connection between a single dataset and such a plot in sense of representations stored in datasets. Plotters handling multiple datasets should always inherit from the aspecd.plotting.MultiPlotter class.

Regardless of the type of plotter, saving plots is always done using objects of the aspecd.plotting.Saver class. The actual task of saving a plot is as easy as calling the save() method of a plotter with a saver object as its argument.

exception aspecd.plotting.Error

Bases: Exception

Base class for exceptions in this module.

exception aspecd.plotting.MissingDatasetError(message='')

Bases: aspecd.plotting.Error

Exception raised when no dataset exists to act on

message

explanation of the error

Type

str

exception aspecd.plotting.PlotNotApplicableToDatasetError(message='')

Bases: aspecd.plotting.Error

Exception raised when processing step is not applicable to dataset

message

explanation of the error

Type

str

exception aspecd.plotting.MissingSaverError(message='')

Bases: aspecd.plotting.Error

Exception raised when no saver is provided.

message

explanation of the error

Type

str

exception aspecd.plotting.MissingFilenameError(message='')

Bases: aspecd.plotting.Error

Exception raised when no filename was provided

message

explanation of the error

Type

str

exception aspecd.plotting.MissingPlotError(message='')

Bases: aspecd.plotting.Error

Exception raised when no plot exists to save.

message

explanation of the error

Type

str

exception aspecd.plotting.MissingPlotterError(message='')

Bases: aspecd.plotting.Error

Exception raised when no plotter is provided.

message

explanation of the error

Type

str

exception aspecd.plotting.MissingFigureError(message='')

Bases: aspecd.plotting.Error

Exception raised when no figure is provided.

message

explanation of the error

Type

str

exception aspecd.plotting.MissingAxisError(message='')

Bases: aspecd.plotting.Error

Exception raised when no axis is provided.

message

explanation of the error

Type

str

exception aspecd.plotting.MissingLegendError(message='')

Bases: aspecd.plotting.Error

Exception raised when no legend is provided.

message

explanation of the error

Type

str

exception aspecd.plotting.MissingDrawingError(message='')

Bases: aspecd.plotting.Error

Exception raised when no drawing (line, …) is provided.

message

explanation of the error

Type

str

class aspecd.plotting.Plotter

Bases: object

Base class for plots.

Each class actually plotting data should inherit from this class. Furthermore, all parameters, implicit and explicit, necessary to perform the plot, should eventually be stored in the property parameters (currently a dictionary).

Further things that need to be changed upon inheriting from this class are the string stored in description, being basically a one-liner.

The actual implementation of the plotting is done in the private method _create_plot() that in turn gets called by plot().

name

Name of the plotter.

Defaults always to the full class name, don’t change!

Type

str

parameters

All parameters necessary for the plot, implicit and explicit

Type

dict

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.PlotProperties

description

Short description, to be set in class definition

Type

str

figure

Reference to figure object

Type

matplotlib.figure.Figure

axes

Reference to axes object used for actual plotting

Type

matplotlib.axes.Axes

filename

Name of file to save the plot to

Actual saving is done using an aspecd.plotting.Saver object.

Type

str

caption

User-supplied information for the figure line_properties.

Type

aspecd.plotting.Caption

Raises

aspecd.plotting.MissingSaverError – Raised when no saver is provided when trying to save

fig

Short hand for figure.

ax

Short hand for axes.

plot()

Perform the actual plotting.

The actual plotting should be implemented within the private method _create_plot().

static applicable(dataset)

Check whether plot is applicable to the given dataset.

Returns True by default and needs to be implemented in classes inheriting from Plotter according to their needs.

A typical example would be a 2D plot applied to a 1D dataset that will most probably not be possible/sensible.

Returns

applicableTrue if successful, False otherwise.

Return type

bool

save(saver=None)

Save the plot to a file.

The actual saving is postponed to an object of class aspecd.plotting.Saver that is submitted as parameter.

Parameters

saver (aspecd.plotting.Saver) – Saver handling the actual saving of the plot

Returns

saver – Saver used to save the plot

Return type

aspecd.plotting.Saver

Raises

aspecd.plotting.MissingSaverError – Raised if no Saver is provided as parameter.

class aspecd.plotting.SinglePlotter

Bases: aspecd.plotting.Plotter

Base class for plots of single datasets.

Each class actually plotting data of a dataset should inherit from this class. Furthermore, all parameters, implicit and explicit, necessary to perform the plot, should eventually be stored in the property parameters (currently a dictionary).

There are two concrete classes available for conveniently performing plots of single datasets:

To perform the plot, call the plot() method of the dataset the plot should be performed for, and provide a reference to the actual plotter object to it.

Further things that need to be changed upon inheriting from this class are the string stored in description, being basically a one-liner.

The actual implementation of the plotting is done in the private method _create_plot() that in turn gets called by plot() which is called by the aspecd.dataset.Dataset.plot() method of the dataset object.

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.SinglePlotProperties

dataset

Dataset the plotting should be done for

Type

aspecd.dataset.Dataset

drawing

Actual graphical representation of the data

Type

matplotlib.artist.Artist

Raises
plot(dataset=None, from_dataset=False)

Perform the actual plotting on the given dataset.

If no dataset is set as property in the object, the method will raise a respective exception. The Dataset object plot() method always assigns its dataset as the respective dataset attribute of the plotter class.

The actual plotting should be implemented within the non-public method _create_plot(). Besides that, the applicability of the plotting to the given dataset will be checked automatically. These checks should be implemented in the method applicable().

Note that the axis labels are added automatically. If you ever need to change the handling or appearance of your axis labels, you may want to override the corresponding methods _set_axes_labels() and _create_axis_label_string(), respectively.

Parameters
  • dataset (aspecd.dataset.Dataset) – dataset to perform plot for

  • from_dataset (boolean) –

    whether we are called from within a dataset

    Defaults to “False” and shall never be set manually.

Returns

dataset – dataset plot has been performed for

Return type

aspecd.dataset.Dataset

Raises
create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.plot() method of the aspecd.dataset.Dataset class and ensures the history of each plotting step to get written properly.

Returns

history_record – history record for plotting step

Return type

aspecd.plotting.PlotHistoryRecord

class aspecd.plotting.SinglePlotter1D

Bases: aspecd.plotting.SinglePlotter

1D plots of single datasets.

Convenience class taking care of 1D plots of single datasets. The type of plot can be set in its aspecd.plotting.SinglePlotter1D.type attribute. Allowed types are stored in the aspecd.plotting.SinglePlotter1D.allowed_types attribute.

Quite a number of properties for figure, axes, and line can be set using the aspecd.plotting.SinglePlotter1D.properties attribute. For details, see the documentation of its respective class, aspecd.plotting.SinglePlot1DProperties.

To perform the plot, call the plot() method of the dataset the plot should be performed for, and provide a reference to the actual plotter object to it.

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.SinglePlot1DProperties

Raises

TypeError – Raised when wrong plot type is set

allowed_types

Return the allowed plot types.

Returns

allowed_types – List of strings

Return type

list

type

Get or set the plot type.

Types need to be methods of the matplotlib.axes.Axes class.

Allowed plot types are stored in the aspecd.plotting.SinglePlotter1D.allowed_types attribute.

Default: ‘plot’

Raises

aspecd.plotting.TypeError – Raised in case of wrong type

static applicable(dataset)

Check whether plot is applicable to the given dataset.

Checks for the dimension of the data of the dataset, i.e. the aspecd.dataset.Data.data attribute. Returns True if data are one-dimensional, and False otherwise.

Returns

applicableTrue if successful, False otherwise.

Return type

bool

class aspecd.plotting.SinglePlotter2D

Bases: aspecd.plotting.SinglePlotter

2D plots of single datasets.

Convenience class taking care of 2D plots of single datasets. The type of plot can be set in its aspecd.plotting.SinglePlotter2D.type attribute. Allowed types are stored in the aspecd.plotting.SinglePlotter2D.allowed_types attribute.

Quite a number of properties for figure, axes, and line can be set using the aspecd.plotting.SinglePlotter.properties attribute. For details, see the documentation of its respective class, aspecd.plotting.SinglePlotProperties.

To perform the plot, call the plot() method of the dataset the plot should be performed for, and provide a reference to the actual plotter object to it.

Raises

TypeError – Raised when wrong plot type is set

allowed_types

Return the allowed plot types.

Returns

allowed_types – List of strings

Return type

list

type

Get or set the plot type.

Types need to be methods of the matplotlib.axes.Axes class.

Allowed plot types are stored in the aspecd.plotting.SinglePlotter2D.allowed_types attribute.

Default: ‘plot’

Raises

aspecd.plotting.TypeError – Raised in case of wrong type

class aspecd.plotting.MultiPlotter

Bases: aspecd.plotting.Plotter

Base class for plots of multiple datasets.

Each class actually plotting data of multiple dataset should inherit from this class. Furthermore, all parameters, implicit and explicit, necessary to perform the plot, should eventually be stored in the property parameters (currently a dictionary).

To perform the plot, call the plot() method of the plotter directly.

Further things that need to be changed upon inheriting from this class are the string stored in description, being basically a one-liner.

The actual implementation of the plotting is done in the private method _create_plot() that in turn gets called by plot() that needs to be called directly (not from a dataset).

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.MultiPlotProperties

datasets

List of dataset the plotting should be done for

Type

list

Raises
plot()

Perform the actual plotting on the given list of datasets.

If no dataset is added to the list of datasets of the object, the method will raise a respective exception.

The actual plotting should be implemented within the non-public method _create_plot(). Besides that, the applicability of the plotting to the given list of datasets will be checked automatically. These checks should be implemented in the method applicable().

Note

There is two ways of setting axes labels: The user may provide the information required in the “axes” key of the aspecd.plotting.Plotter.parameters property containing a list of aspecd.dataset.Axis objects. Alternatively, if no such information is provided, the axes of each dataset are checked for consistency, and if they are found to be identical, this information is used.

Raises
class aspecd.plotting.Saver(filename=None)

Bases: object

Base class for saving plots.

For basic saving of plots, no subclassing is necessary, as the save() method uses matplotlib.figure.Figure.savefig() and can cope with all possible parameters via the parameters property.

filename

Name of the file the plot should get saved to

Type

str

parameters

Key-value store of parameters for saving.

See matplotlib.figure.Figure.savefig() for details and available options.

Type

dict

plotter

Plotter whose plot should be saved.

Type

aspecd.plotting.Plotter

Raises
save(plotter=None)

Save the plot to a file.

If no plotter is provided at method call, but is set as property in the Saver object, the aspecd.plotting.Plotter.save() method of the plotter will be called.

If no plotter is provided at method call nor as property of the object, the method will raise a respective exception.

The actual saving is implemented within the private method _save_plot().

Parameters

plotter (aspecd.plotting.Plotter) – plot to be saved

Raises
class aspecd.plotting.PlotRecord(plotter=None)

Bases: object

Base class for records storing information about a plot.

For reproducibility of plots performed on either a single dataset or multiple datasets, information for each plot needs to be collected that suffices to reproduce the plot. This is what a PlotRecord is good for.

All information will usually be obtained from a plotter object, either by instantiating a PlotRecord object providing a plotter object, or by calling from_plotter() on a PlotRecord object.

Subclasses for aspecd.plotting.SinglePlotter and aspecd.plotting.MultiPlotter objects are available, namely aspecd.plotting.SinglePlotRecord and aspecd.plotting.MultiPlotRecord.

name

Name of the plotter.

Defaults to the plotter class name and shall never be set manually.

Type

str

description

Short description of the plot

Type

str

parameters

All parameters necessary for the plot, implicit and explicit

Type

dict

filename

Name of the file the plot has been/should be saved to

Type

str

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

from_plotter(plotter=None)

Obtain information from plotter.

Parameters
Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

class aspecd.plotting.SinglePlotRecord(plotter=None)

Bases: aspecd.plotting.PlotRecord

Record for SinglePlotter objects.

When plotting data of a single dataset, classes derived from aspecd.plotting.SinglePlotter will be used. The information obtained from these plotters will be stored in a SinglePlotRecord object.

preprocessing

List of processing steps

The actual processing steps are objects of the class aspecd.processing.ProcessingStepRecord.

Type

list

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

class aspecd.plotting.MultiPlotRecord(plotter=None)

Bases: aspecd.plotting.PlotRecord

Record for MultiPlotter objects.

When plotting data of multiple datasets, classes derived from aspecd.plotting.MultiPlotter will be used. The information obtained from these plotters will be stored in a MultiPlotRecord object.

datasets

List of datasets whose data appear in the plot.

Type

list

Parameters

plotter (aspecd.plotting.Plotter) – Plotter object to obtain information from

class aspecd.plotting.PlotHistoryRecord(package='')

Bases: aspecd.dataset.HistoryRecord

History record for plots of datasets.

plot

Plot the history is saved for

Type

aspecd.plotting.SinglePlotRecord

package

Name of package the hstory record gets recorded for

Prerequisite for reproducibility, gets stored in the aspecd.dataset.HistoryRecord.sysinfo attribute. Will usually be provided automatically by the dataset.

Type

str

class aspecd.plotting.Caption

Bases: aspecd.utils.Properties

Caption for figures.

title

usually one sentence describing the intent of the figure

Often plotted bold-face in a figure caption.

Type

str

text

additional text directly following the title

Contains more information about the plot. Ideally, a figure caption is self-contained such that it explains the figure sufficiently to understand its intent and content without needing to read all the surrounding text.

Type

str

parameters

names of parameters that should be included in the figure caption

Usually, these parameters get included at the very end of a figure line_properties.

Type

list

class aspecd.plotting.PlotProperties

Bases: aspecd.utils.Properties

Properties of a plot, defining its appearance.

figure

Properties of the figure as such

Type

aspecd.plotting.FigureProperties

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

apply(plotter=None)

Apply properties to plot.

In this generic class having only figure properties, only these properties are set. Classes derived from aspecd.plotting.PlotProperties need to take care of setting all available properties.

Parameters

plotter (aspecd.plotting.Plotter) – Plotter the properties should be applied to.

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

class aspecd.plotting.SinglePlotProperties

Bases: aspecd.plotting.PlotProperties

Properties of a single plot, defining its appearance.

axes

Properties of the axes.

Type

aspecd.plotting.AxisProperties

drawing

Properties of the line within a plot

Type

aspecd.plotting.DrawingProperties

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

apply(plotter=None)

Apply properties to plot.

Parameters

plotter (aspecd.plotting.SinglePlotter) – Plotter the properties should be applied to.

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

class aspecd.plotting.SinglePlot1DProperties

Bases: aspecd.plotting.SinglePlotProperties

Properties of a 1D single plot, defining its appearance.

drawing

Properties of the line within a plot

Type

aspecd.plotting.LineProperties

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

class aspecd.plotting.MultiPlotProperties

Bases: aspecd.plotting.PlotProperties

Properties of a multiplot, defining its appearance.

axes

Properties of the axes.

Type

aspecd.plotting.AxisProperties

legend

Properties of the legend.

Type

aspecd.plotting.LegendProperties

drawings

Properties of the lines within a plot.

Each element is a aspecd.plotting.LineProperties object

Type

list

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

apply(plotter=None)

Apply properties to plot.

Parameters

plotter (aspecd.plotting.MultiPlotter) – Plotter the properties should be applied to.

Raises

aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.

class aspecd.plotting.FigureProperties

Bases: aspecd.utils.Properties

Properties of a figure of a plot, i.e., the most general aspects.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.figure.Figure objects.

figsize

Figure dimension (width, height) in inches.

2-tuple of floats

Type

tuple

dpi

Dots per inch.

Type

float

Raises

aspecd.plotting.MissingFigureError – Raised if no figure is provided.

apply(figure=None)

Apply properties to figure.

Parameters

figure (matplotlib.figure.Figure) – Plotter the properties should be applied to.

Raises

aspecd.plotting.MissingFigureError – Raised if no figure is provided.

class aspecd.plotting.AxisProperties

Bases: aspecd.utils.Properties

Properties of an axis of a plot.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.axes.Axes objects.

Todo

How to deal with at least two axes per figure, i.e. x and y axis, whereas matplotlib handles the overall axes as one object?

How about multiple separate axes within a figure window?

aspect

aspect of the axis scaling, i.e. the ratio of y-unit to x-unit

Type

{‘auto’, ‘equal’} or num

facecolor

facecolor of the Axes

Type

color

xlabel

label for the x-axis

Type

str

xlim

x-axis view limits, two floats

Type

list

xscale

x-axis scale

possible values: “linear”, “log”, “symlog”, “logit”

Type

str

xticklabels

x-tick labels: list of string labels

Type

list

xticks

y ticks with list of ticks

ylabel

label for the y-axis

Type

str

ylim

y-axis view limits, two floats

Type

list

yscale

y-axis scale

possible values: “linear”, “log”, “symlog”, “logit”

Type

str

yticklabels

y-tick labels: list of string labels

Type

list

yticks

y ticks with list of ticks

Raises

aspecd.plotting.MissingAxisError – Raised if no axis is provided.

apply(axis=None)

Apply settable properties to axis.

Only properties that are not None or empty will be set, in order to prevent problems. The underlying method used to set the axis properties is matplotlib.axes.Axes.update().

Parameters

axis (matplotlib.axes.Axes) – axis to set properties for

Raises

aspecd.plotting.MissingAxisError – Raised if no axis is provided.

class aspecd.plotting.LegendProperties

Bases: aspecd.utils.Properties

Properties of a legend of a plot, i.e., the most general aspects.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.legend.Legend objects.

loc

Location of the legend

For possible values, see matplotlib.legend.Legend

Type

str

Raises

aspecd.plotting.MissingLegendError – Raised if no legend is provided.

apply(legend=None)

Apply properties to legend.

Parameters

legend (matplotlib.legend.Legend) – Plotter the properties should be applied to.

Raises

aspecd.plotting.MissingFigureError – Raised if no figure is provided.

class aspecd.plotting.DrawingProperties

Bases: aspecd.utils.Properties

Properties of a drawing within a plot.

A drawing is the most abstract object representing data within axes, such as a line, contour, etcetera.

label

label of a line that gets used within a legend, default: ‘’

Type

str

Raises

aspecd.plotting.MissingDrawingError – Raised if no drawing is provided.

apply(drawing=None)

Apply properties to drawing.

For each property, the corresponding “set_<property>” method of the line will be called.

Parameters

drawing (matplotlib.axes.Axes) – axis to set properties for

Raises

aspecd.plotting.MissingDrawingError – Raised if no line is provided.

class aspecd.plotting.LineProperties

Bases: aspecd.plotting.DrawingProperties

Properties of a line within a plot.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.lines.Line2D objects.

color

color of the line

For details see matplotlib.colors

Type

color

drawstyle

drawing style of the line, default: ‘default’

For details see matplotlib.lines.Line2D.set_drawstyle()

Type

str

linestyle

style of the line, default: ‘solid’

For details see matplotlib.lines.Line2D.set_linestyle()

Type

str

linewidth

width of the line, float value in points, default: 1.5

Type

float

marker

marker used for the line, default: ‘’

For details see matplotlib.markers

Type

str

Raises

aspecd.plotting.MissingDrawingError – Raised if no line is provided.