You're reading the documentation for a development version. For the latest released version, please have a look at v0.11.

aspecd.plotting module

Plotting: Graphical representations of data extracted from datasets.

Contents

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. For details on handling (own) figure and axes objects, see below.

Overview

As there are a lot of different plotters available, each for different purposes, Fig. 43 gives a first overview of the different Plotter classes.

Fig. 43 First overview of the different Plotter classes available in the plotting module. The three classes marked as abstract (with the “A”, i.e. Plotter, SinglePlotter, and MultiPlotter) are not true abstract classes, but nevertheless base classes that shall not used directly for plotting purposes.

For each Plotter class, there exists a dedicated PlotProperties class, besides further properties classes for those plot elements independent of a concrete plotter. For a first overview, see Fig. 44.

Fig. 44 First overview of the different PlotProperties classes available in the plotting module. For each Plotter, there is a separate PlotProperties class. Furthermore, there are additional classes for properties of elements of plots, such as FigureProperties and DrawingProperties. Note that SinglePlot2DStackedProperties inherits from MultiPlot1DProperties. This is due to the very similar behaviour of the two plotters, with respect to the resulting plots.

For more explanation and details on the individual classes and how to best make use of them, continue reading.

Types of abstract plotters

Abstract plotters are the base classes for all plotters actually used to graphically display data. If you are mire interested in actually plotting data rather than the overall concepts, have a look at the concrete plotters.

Generally, two types of plotters can be distinguished:

• Plotters for handling single datasets

  Shall be derived from aspecd.plotting.SinglePlotter.

• Plotters for handling multiple datasets

  Shall be derived from aspecd.plotting.MultiPlotter.

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.

In a certain sense, there is a third type of plotters:

• Plotters consisting of more than one axes

  Shall be derived from aspecd.plotting.CompositePlotter.

However, practically mostly these composite plotters will behave like plotters handling either single or multiple datasets. Generally, these composite plotters will use other types of plotters to perform the actual plot tasks. This modular approach allows for great flexibility.

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.

A note on array dimensions and axes

Something often quite confusing is the apparent inconsistency between the order of array dimensions and the order of axes. While we are used to assigning axes in the order x, y, z, and assuming x to be horizontal, y vertical (and z sticking out of the paper plane), arrays are usually (at least in the C world as compared to the FORTRAN world) indexed row-first, column-second. That means, however, that if you simply plot a 2D array in axes, your first dimension is along the y axis, the second dimension along the x axis.

Therefore, as the axes of your datasets will always correspond to the array dimensions of your data, in case of 2D plots you will need to either use the information contained in the second axis object for your x axis label, and the information from the first axis object for your y axis label, or to transpose the data array.

Another aspect to have in mind is the position of the origin. Usually, in a Cartesian coordinate system, convention is to have the origin (0, 0) in the lower left of the axes (for the positive quadrant). However, for images, convention is to have the corresponding (0, 0) pixel located in the upper left edge of your image. Therefore, those plotting methods dealing with images will usually revert the direction of your y axis. Most probably, eventually you will have to check with real data and ensure the plotters to plot data and axes in a consistent fashion.

Types of concrete plotters

The ASpecD framework comes with a series of concrete plotters included ready to be used. As stated above, plotters can generally be divided into two types: plotters operating on single datasets and plotters combining the data of multiple datasets into a single figure.

Additionally, plotters can be categorised with regard to creating figures consisting of a single or multiple axes. The latter are plotters inheriting from the aspecd.plotting.CompositePlotter class. The latter can be thought of as templates for the other plotters to operate on, i.e. they provide the axes for other plotters to display their results.

Concrete plotters for single datasets

• aspecd.plotting.SinglePlotter1D

  Basic line plots for single datasets, allowing to plot a series of line-type plots, including (semi)log plots

• aspecd.plotting.SinglePlotter2D

  Basic 2D plots for single datasets, allowing to plot a series of 2D plots, including contour plots and image-type display

• aspecd.plotting.SinglePlotter2DStacked

  Stacked plots of 2D data, converting a 2D display into a series of 1D line plots stacked on top of each other.

• aspecd.plotting.SingleCompositePlotter

  Composite plotter for single datasets, allowing to plot different views of one and the same datasets by using existing plotters for single datasets.

• aspecd.plotting.MultiDeviceDataPlotter1D

  Basic line plots for multiple device data of a single dataset, allowing to plot a series of line-type plots, including (semi)log plots

Concrete plotters for multiple datasets

• aspecd.plotting.MultiPlotter1D

  Basic line plots for multiple datasets, allowing to plot a series of line-type plots, including (semi)log plots

• aspecd.plotting.MultiPlotter1DStacked

  Stacked line plots for multiple datasets, allowing to plot a series of line-type plots, including (semi)log plots

Properties of plot(ter)s

Plots can be controlled extensively regarding their appearance. While Matplotlib provides both, sensible defaults and an extensive list of customisation options for the plot appearance, the ASpecD framework tries to homogenise these settings and currently provides only a subset of the possibilities the underlying Matplotlib library would allow.

The properties of plots and their individual components are reflected in a hierarchy of objects. Each plotter has a corresponding properties attribute that contains an object of the respective aspecd.plotting.PlotProperties class.

To give you an idea of the hierarchy of classes handling the plot properties, below is a (hopefully complete) list:

• aspecd.plotting.PlotProperties

  • aspecd.plotting.SinglePlotProperties

    • aspecd.plotting.SinglePlot1DProperties

    • aspecd.plotting.SinglePlot2DProperties

  • aspecd.plotting.MultiPlotProperties

    • aspecd.plotting.MultiPlot1DProperties

      • aspecd.plotting.SinglePlot2DStackedProperties

  • aspecd.plotting.CompositePlotProperties

• aspecd.plotting.FigureProperties

• aspecd.plotting.AxesProperties

• aspecd.plotting.LegendProperties

• aspecd.plotting.DrawingProperties

  • aspecd.plotting.LineProperties

  • aspecd.plotting.SurfaceProperties

  • aspecd.plotting.TextProperties

• aspecd.plotting.GridProperties

• aspecd.plotting.ColorbarProperties

• aspecd.plotting.SubplotGridSpecs

Each of the plot properties classes, i.e. all subclasses of aspecd.plotting.PlotProperties, contain other properties classes as attributes.

Getting and setting plot properties is somewhat complicated by the fact that Matplotlib usually allows setting properties only when instantiating objects, or sometimes with explicit setter methods. Similarly, there may or may not be getter methods for the relevant attributes.

In any case, while you can set and get properties of plots programmatically within the ASpecD framework, using recipe-driven data analysis is highly recommended.

General tips and tricks

Plotting can become horribly complicated, simply due to the complexity of the matter involved and the parameters one can (and often want to) control. For the convenience of the user, a few more general cases are discussed below and example recipes provided for each case. For details on recipe-driven data analysis, see either the introduction or the documentation of the aspecd.tasks module.

Overall figure properties

On the figure level, i.e. the level of the overall graphical representation, only a few properties can be set, namely size (in inches), resolution (in dots per inch), and title:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      figure:
        size: [8, 5]
        resolution: 600
        title: My fancy figure
    filename: output.pdf

Important

If you have a second axis on top of the axes, setting the figure title will result in the figure title clashing with the upper axis. Hence, in such case, try setting the axis title.

Overall axes properties

Axes properties can be set for SinglePlotter and MultiPlotter, but for obvious reasons not for CompositePlotter. In case of the latter, the properties of the axes are set for the individual plotters that are used to plot in the different axes.

Below is a demonstration of just a subset of the properties that can be set. For further details, see the AxesProperties class. Note in particular that all the settings shown here for the x axis can be applied to the y axis analogously.

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      axes:
        title: My fancy plot
        aspect: equal
        facecolor: darkgreen
        xlabel: $foo$ / bar
        xlim: [-5, 5]
        xticklabelangle: 45
        invert: x
    filename: output.pdf

Important

If you have a second axis on top of the axes, setting the figure title will result in the figure title clashing with the upper axis. Hence, in such case, try setting the axis title.

Removing axes labels

Generally, axes labels are set according to the settings in the dataset plotted. However, sometimes you would like to remove a label entirely. To do so, set the label to None. The equivalent in YAML, hence in recipes, is null. Hence, removing the y axis label in a plot translates to:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      axes:
        ylabel: null

Of course, you can do the same with the x axis label and with all kinds of plotters.

Added in version 0.9.3.

Type of plot for 1D plotters

When plotting one-dimensional (1D) data, there is of course more than the usual line plot. For the actual types of plots that you can use, see the SinglePlotter1D.allowed_types and MultiPlotter1D.allowed_types attributes.

To make a semilogy plot (i.e., with logarithmic y axis), invoke the plotter as follows:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    type: semilogy
    filename: output.pdf

And analogous for the MultiPlot1D plotter:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    type: semilogy
    filename: output.pdf

Important

As the logarithm of negative values is not defined, usually having a logarithmic axis with negative values will lead to unexpected results. Matplotlib defaults to clipping the invalid values. To help you with debugging the unexpected results, a warning will be logged (and printed to the terminal when serving a recipe) in case a logarithmic axis is affected by negative values. In such case, the easiest is to add an offset to your data, using aspecd.processing.ScalarAlgebra.

Appearance of individual drawings

The individual drawings within the axes of a plot can be controlled in quite some detail. Depending on the overall type, be it a line or a surface, there are different classes responsible for setting the properties: LineProperties and SurfaceProperties. The general class is DrawingProperties.

Below is a (real-world) example of a multiplotter containing two lines, and in this particular case with standard settings.

- kind: multiplot
  type: MultiPlotter1D
  properties:
    properties:
      drawings:
      - label: Substance 1
        color: '#1f77b4'
        drawstyle: default
        linestyle: '-'
        linewidth: 1.5
        marker: None
      - label: Substance 2
        color: '#ff7f0e'
        drawstyle: default
        linestyle: '-'
        linewidth: 1.5
        marker: None

Controlling the appearance of zero lines

While a grid is not shown by default, zero lines are, as long as the zero value is present in either or both axes ranges. While it is a sensible default to display zero lines, and switching them off is a matter of setting the parameter show_zero_lines to False, controlling the appearance of these lines is often useful. Below is a (real-world) example of the available settings for the zero lines (with default values).

- kind: multiplot
  type: MultiPlotter1D
  properties:
    parameters:
      show_zero_lines: true
    properties:
      zero_lines:
        label: ''
        color: '#cccccc'
        drawstyle: default
        linestyle: solid
        linewidth: 1.0
        marker: ''

While it rarely makes sense to set line markers for these lines, the line properties are simply all properties that can be set using the LineProperties class. Besides controlling the appearance of zero lines, you can display a grid and control the appearance of these lines. See below for more details.

Adding a grid

Particularly when comparing plots or when you want to extract values from a plot, a grid can come in quite handy. As a grid is already quite complicated – for which axis (x, y, or both) to set the grid, for which ticks (minor, major, or both) – and as you may even want to control the appearance of the grid lines, all these properties are handled by the GridProperties class. You can add a grid to both, SinglePlotter and MultiPlotter instances.

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      grid:
        show: True
        ticks: major
        axis: both

If you now even want to control the appearance of the grid lines (you can not, however, control individual grid lines, only all grid lines at once), things get even more complex:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      grid:
        show: True
        ticks: major
        axis: both
        lines:
          color: #123456
          linestyle: dashed
          linewidth: 3
          marker: triangle_up

Note that the values for the lines are not necessarily sensible for grid lines. For a full list of possible properties, see the LineProperties class. The same as shown here for a SinglePlotter can be done for a MultiPlotter accordingly.

Adding a legend

As soon as there is more than one line in a plot, adding a legend comes in quite handy. Again, a legend can be controlled in quite some detail. An example showing some of the properties that can be set is given below:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    parameters:
      show_legend: True
    properties:
      legend:
        location: upper right
        frameon: False
        labelspacing: 0.75
        fontsize: small
        ncol: 2
        title: some explanation

Important here is to note that you need to set the show_legend parameter on a higher level of the overall plotter properties to True in order to have a legend be shown. Of course, you need not set all (or even any) of the properties explicitly. For details, see the LegendProperties class.

Removing a line from the legend

Sometimes, you may want to have certain lines in your plot not showing up in the legend. By default, all lines (“drawings”) will enter the legend, either by the explicit label you provide or by the label of the corresponding dataset. To have a line not showing up in the legend, set its label to either the empty string or to null (the YAML equivalent of None). A minimal example is given below:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    parameters:
      show_legend: True
    properties:
      drawings:
      - label: "one line"
      - label: ""
      - label: "another line"

Here, there should be three lines in the plot, and the second would not appear in the legend, as its label is set to the empty string.

Annotating plots

Annotations of plots are something that cannot be automated. However, they can be quite important for the analysis and hence for providing new scientific insight. Typical simple examples of plot annotations are horizontal or vertical lines to compare peak positions or intensities. You may as well think of highlighted areas or symbols pointing to distinct characteristics.

When annotating plots, for obvious reasons you need to have both, a plot task and a plotannotation task. It does not really matter which task you define first, the plot or the plot annotation. There are only marginal differences, and both ways are shown below.

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: plot1Dstacked.pdf
  result: plot1Dstacked

- kind: plotannotation
  type: VerticalLine
  properties:
    parameters:
      positions: [35, 42]
    properties:
      color: green
      linewidth: 1
      linestyle: dotted
  plotter: plot1Dstacked

In this case, the plotter is defined first, and the annotation second. To refer to the plotter from within the plotannotation task, you need to set the result attribute in the plotting task and refer to it within the plotter attribute of the plotannotation task. Although defining the plotter before the annotation, the user still expects the annotation to be included in the file containing the actual plot, despite the fact that the figure has been saved (for the first time) before the annotation has been added.

Sometimes, it might be convenient to go the other way round and first define an annotation and afterwards add it to a plot(ter). This can be done as well:

- kind: plotannotation
  type: VerticalLine
  properties:
    parameters:
      positions:
        - 21
        - 42
    properties:
      color: green
      linewidth: 1
      linestyle: dotted
  result: vlines

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: plot1Dstacked.pdf
  annotations:
    - vlines

In this way, you can add the same annotation to several plots, and be sure that each annotation is handled as a separate object.

Suppose you have more than one plotter you want to apply an annotation to. In this case, the plotter property of the plotannotation task is a list rather than a string:

- kind: multiplot
  type: MultiPlotter1DStacked
  result: plot1

- kind: multiplot
  type: MultiPlotter1DStacked
  result: plot2

- kind: plotannotation
  type: VerticalLine
  properties:
    parameters:
      positions: [35, 42]
  plotter:
    - plot1
    - plot2

In this case, the annotation will be applied to both plots independently. Note that the example has been reduced to the key aspects. In a real situation, the two plotters will differ much more.

Adding a colorbar

For two-dimensional (2D) plots, adding a colorbar that provides some information on the intensity values encoded in different colors is usually a good idea. The properties of the colorbar can be set via the ColorbarProperties class.

- kind: singleplot
  type: SinglePlotter2D
  properties:
    parameters:
      show_colorbar: True
    properties:
      colorbar:
        location: top
        fraction: 0.1
        aspect: 30
        pad: 0.2
        format: "%4.2e"
        label:
          text: $intensity$ / a.u.
          location: right

Again, you need not to set any of the properties explicitly, besides setting the parameter show_colorbar to True. If none of the properties are set explicitly, the defaults provided by Matplotlib will be used.

Plotting device data rather than primary data

Datasets may contain additional data as device data in aspecd.dataset.Dataset.device_data. For details, see the section on device data in the dataset module. To conveniently plot those device data instead of the primary data of the dataset, provide the key(s) to the device(s) the data should be plotted for:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    parameters:
      device_data: timestamp
    filename: output.pdf

Basically, all plotters understand device data and will plot the device data rather than the primary data of the dataset accordingly.

Plotting to existing axes

Figure and axes properties of a plotter object will only be populated upon calling the method aspecd.plotting.Plotter.plot(), therefore by using the plot() method of the respective plotter class.

Furthermore, figure and axes properties will only be populated if both are not existing already. Therefore, if you like to use a plotter to plot to an existing axis, set its figure and axes properties before calling the aspecd.plotting.Plotter.plot() method.

Important

If you do so, make sure to set both, figure and axes properties, as failing to set a valid figure property will cause matplotlib to throw exceptions.

A simple example may look like this:

import matplotlib.pyplot as plt
fig, ax = plt.subplots()
plotter = aspecd.plotting.SinglePlotter1D()
plotter.figure = fig
plotter.axes = ax
plotter.plot()

In this case, the plotter will plot to the axis specified before calling its plot() method. Thus, it should be straight-forward to write plotter classes that create complex plots consisting of several subplots by reusing available plotter classes. This is what the aspecd.plotting.CompositePlotter class is for, and how it basically works.

For developers

A bit of conceptual documentation for both, developers of the ASpecD framework and derived packages, including general hints how to implement plotters.

When and how to subclass plotters

ASpecD comes with a list and hierarchy of plotters. For details, see the section on types of concrete plotters. The question therefore arises: when and how to subclass plotters, particularly in derived packages?

Generally, you nearly always want to subclass directly one of the concrete plotters, such as SinglePlotter1D or MultiPlotter1D, but rarely if ever parent classes such as SinglePlotter or even Plotter. The reason is simply that only the concrete plotters can be used directly.

Reasons for subclassing plotters in derived packages are:

• Adding new kinds of (specific) plotters,

• Adding functionality to otherwise generic plotters,

• Change certain functionality to otherwise generic plotters.

A typical use case for the last case would be to revert the x axis by default, perhaps depending on the axis unit. For this, you would probably want to subclass all relevant concrete ASpecD plotter, i.e. SinglePlotter1D, SinglePlotter2D, SinglePlotter2DStacked, MultiPlotter1D, and MultiPlotter1DStacked. For each of these, there would only be a few relevant lines of code, and as this would look fairly similar for each of the plotters, the following stripped-down example shows just the case for the SinglePlotter1D:

class SinglePlotter1D(aspecd.plotting.SinglePlotter1D):

    def _create_plot(self):
        super()._create_plot()
        if self.data.axes[0].unit == "<Some Unit>":
            self.properties.axes.invert = ["x"]

Here, the unit of the x axis is checked and if it is set to a certain value (replace the placeholder <Some Unit> with a reasonable value in your code), the x axis is inverted. This is all functional code necessary to achieve the requested behaviour. In a real class, you would need to add a proper class docstring including examples how to use the class. Get inspiration from either the ASpecD framework itself or one of the derived packages.

Access to data for plotting

Datasets may contain additional data as device data in aspecd.dataset.Dataset.device_data. For details, see the section on device data in the dataset module. When implementing a plotter, you should not need to care about whether device data or data should be plotted. For this to work, do not access aspecd.dataset.Dataset.data directly in your plotter, but use instead aspecd.plotting.SinglePlotter.data or aspecd.plotting.MultiPlotter.data, respectively.

Important

Support for device data has been added in ASpecD v0.9. Developers of packages based on the ASpecD framework should update their code accordingly.

In a simplistic scenario, your plotter (here, a class derived from SinglePlotter) may contain the following code:

def _create_plot(self):
    self.drawing, = self.axes.plot(
        self.data.axes[0].values,
        self.data.data,
        label=self.properties.drawing.label
    )

A few comments on this code snippet:

• All actual plotting is implemented in the private method _create_plot().

• The actual object returned by the plot function is stored in self.drawing.

• The actual plot function gets the data to be plotted by accessing self.data (and not self.dataset.data).

Of course, usually there is more that is handled in a plotter. For details, have a look at the actual source code of different ASpecD plotters.

Module API documentation

class aspecd.plotting.Plotter

Bases: ToDictMixin

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().

Note

Usually, you will never implement an instance of this class for actual plotting tasks, but rather one of the child classes.

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

The following keys exist:

show_legendbool

Whether to show a legend in the plot

Default: False

show_zero_linesbool

Whether to show zero lines in the plot

Regardless of whether you set this to true, zero lines will only be added to the final plot if the zero value is within the current axes limits.

Zero line properties can be set via the aspecd.plotting.Plotter.properties attribute.

Default: True

tight_layoutbool

Whether to adjust the plot to fit into the figure area

For details see matplotlib.figure.Figure.tight_layout().

Use with care, as this will automatically adjust the padding around the axes and might lead to unexpected results.

Default: False

device_datastr or list

Name(s) of the device(s) the data should be plotted for.

Datasets may contain additional data as device data in aspecd.dataset.Dataset.device_data. For details, see aspecd.dataset.DeviceData. To conveniently plot those device data instead of the primary data of the dataset, provide the key(s) to the device(s) the data should be plotted for.

Will be a string (i.e. data of a single device) in all cases except of specific plotters for plotting data of multiple devices.

Default: ‘’

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

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.

Type:

aspecd.plotting.Caption

legend

Legend object

Type:

matplotlib.legend.Legend

label

Label used to reference figure, e.g. in context of a report

Type:

str

style

plotting style to use

You can use all plotting styles understood by matplotlib. See matplotlib.style for details.

Note that the style will only be applied for the current plot and reset to the values before the plot, at least as long as applying the style (only) affects the rcParams of matplotlib.

Type:

str

comment

User-supplied comment describing intent, purpose, reason, …

Type:

str

annotations

List of annotations added to the plotter.

Each annotation is an object of class aspecd.annotation.PlotAnnotation.

Type:

list

Raises:

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

Changed in version 0.6: New attribute label

Changed in version 0.6.2: New parameter tight_layout

Changed in version 0.6.4: New attribute comment

Changed in version 0.9: New parameter ‘’device_data’’

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

plot()

Perform the actual plotting.

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

static applicable(data)

Check whether plot is applicable to the 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:

applicable – True if successful, False otherwise.

Return type:

bool

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlotter

Bases: 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:

• aspecd.plotting.SinglePlotter1D

  1D plots, such as line, scatter, log, semilog

• aspecd.plotting.SinglePlotter2D

  2D plots, such as contour, image

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

data

Actual data that should be plotted

Defaults to the primary data of a dataset, but can be the device data. See the key device_data of Plotter.parameters for details.

Type:

aspecd.dataset.Data

drawing

Actual graphical representation of the data

Type:

matplotlib.artist.Artist

Raises:

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotter is not applicable to dataset

Changed in version 0.9: New attribute ‘’data’’

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.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.history.PlotHistoryRecord

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

static applicable(data)

Check whether plot is applicable to the 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:

applicable – True if successful, False otherwise.

Return type:

bool

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlotter1D

Bases: 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

For the properties that can be set this way, see the documentation of the aspecd.plotting.SinglePlot1DProperties class.

Type:

aspecd.plotting.SinglePlot1DProperties

parameters

All parameters necessary for the plot, implicit and explicit

The following keys exist, in addition to those of the superclass:

tight: str

Whether to set the axes limits tight to the data

Possible values: ‘x’, ‘y’, ‘both’

Default: ‘’

switch_axesbool

Whether to switch x and y axes

Normally, the first axis is used as x axis, and the second as y axis. Sometimes, switching this assignment is necessary or convenient.

Default: False

Type:

dict

Raises:

TypeError – Raised when wrong plot type is set

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    filename: output.pdf

Of course, line plots are not the only plot type available. Check the SinglePlotter1D.allowed_types attribute for further details. To make a semilogy plot (i.e., with logarithmic y axis), invoke the plotter as follows:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    type: semilogy
    filename: output.pdf

Important

As the logarithm of negative values is not defined, usually having a logarithmic axis with negative values will lead to unexpected results. Matplotlib defaults to clipping the invalid values. To help you with debugging the unexpected results, a warning will be logged (and printed to the terminal when serving a recipe) in case a logarithmic axis is affected by negative values. In such case, the easiest is to add an offset to your data, using aspecd.processing.ScalarAlgebra.

Sometimes it is convenient to switch the x and y axes, e.g. in context of 2D datasets where slices along both dimensions should be displayed together with the 2D data and next to the respective axes. To achieve this, set the switch_axes parameter accordingly:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    parameters:
      switch_axes: true
    filename: output.pdf

If the dataset contains additional device data, and you want to plot data of a single device rather than the primary data of the dataset ( and the device data are 1D), provide the name of the device (i.e., the key the device data are stored in the dataset). Assuming the device data are stored as timestamp in the dataset:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    parameters:
      device_data: timestamp
    filename: output.pdf

Changed in version 0.7: New parameter switch_axes

Changed in version 0.9: Issue warning with log plotters and negative values

property allowed_types

Return the allowed plot types.

Currently, the allowed types are: plot, scatter, step, loglog, semilogx, semilogy, stemplot.

Returns:

allowed_types – List of strings

Return type:

list

property 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:

TypeError – Raised in case of wrong type

static applicable(data)

Check whether plot is applicable to the 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:

applicable – True if successful, False otherwise.

Return type:

bool

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.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.history.PlotHistoryRecord

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlotter2D

Bases: 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 surface can be set using the aspecd.plotting.SinglePlotter2D.properties attribute. For details, see the documentation of its respective class, aspecd.plotting.SinglePlot2DProperties.

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.

Important

Due to the difference between axes conventions in plots, with axes being labelled x, y, z accordingly, and the convention of indexing arrays (first index refers to the row, converting to the y axis, the second index to the column, i.e. the x axis), the x axis in the plot will be the second axis, the y axis the first axis of your dataset. If you need to change this, you can set the switch_axes parameter to True.

While usually, it is only a matter of convention how to display your 2D data, it is often confusing, as we intuitively think in x, y, z axes, not in row-column indices.

parameters

All parameters necessary for the plot, implicit and explicit

The following keys exist, in addition to those of the superclasses:

switch_axesbool

Whether to switch x and y axes

Normally, the first axis is used as x axis, and the second as y axis. Sometimes, switching this assignment is necessary or convenient.

Default: False

levelsint

Number of levels of a contour plot

If None, the number of levels will be determined automatically.

Default: None

thresholdfloat

Threshold for determining the levels of a contour plot.

Sometimes, you want to control explicitly the lowest level of a contour plot. This can be done setting a threshold value here.

Internally, a matplotlib.ticker.MaxNLocator will be used to determine the levels.

Added in version 0.12.

show_contour_linesbool

Whether to show contour lines in case of contourf plot

show_colorbarbool

Whether to show a colorbar

Added in version 0.9.

Type:

dict

propertiesaspecd.plotting.SinglePlot2DProperties

Properties of the plot, defining its appearance

For the properties that can be set this way, see the documentation of the aspecd.plotting.SinglePlot2DProperties class.

Raises:

TypeError – Raised when wrong plot type is set

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf

To change the axes (flip x and y axis):

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    parameters:
      switch_axes: True

To use another type (here: contour):

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    type: contour

To set the number of levels of a contour plot to 10:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    type: contour
    parameters:
      levels: 10

To change the colormap (cmap) used:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    filename: output.pdf
    properties:
      drawing:
        cmap: RdGy

To plot both, filled contours and contour lines, setting the appearance of the contour lines as well:

- kind: singleplot
  type: SinglePlotter2D
  properties:
    type: contourf
    filename: output.pdf
    parameters:
      show_contour_lines: True
    properties:
      drawing:
        cmap: RdGy
        linewidths: 0.5
        linestyles: '-'
        colors: k

In this particular case, the contour lines are thin black solid lines.

Make sure to check the documentation for further parameters that can be set.

property allowed_types

Return the allowed plot types.

Currently allowed types are: contour, contourf, imshow

Returns:

allowed_types – List of strings

Return type:

list

property 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: ‘imshow’

Raises:

TypeError – Raised in case of wrong type

static applicable(data)

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 two-dimensional, and False otherwise.

Returns:

applicable – True if successful, False otherwise.

Return type:

bool

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.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.history.PlotHistoryRecord

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlotter2DStacked

Bases: SinglePlotter

Stacked plots of 2D data

A stackplot creates a series of lines stacked on top of each other from a 2D dataset.

dataset

Dataset the plotting should be done for

Type:

aspecd.dataset.Dataset

drawing

Actual graphical representation of the data.

List of , one for each of the actual lines of the plot

Type:

list

parameters

All parameters necessary for the plot, implicit and explicit

The following keys exist, in addition to the keys inherited from the superclass:

show_legendbool

Whether to show a legend in the plot

Default: False

show_zero_linesbool

Whether to show zero lines in the plot

Regardless of whether you set this to true, zero lines will only be added to the final plot if the zero value is within the current axes limits.

Zero line properties can be set via the aspecd.plotting.Plotter.properties attribute.

Default: False

stacking_dimensionint

dimension of data along which to stack the plot

Default: 1

offsetfloat

offset between lines

If not explicitly set, the plotter will try its best to determine a sensible value, by using self.dataset.data.data.max() * 1.05.

Default: 0

yticklabelformatstring

format for tick labels on the y axis

Useful in case of too many decimals displayed on the y axis. Uses (currently) the “old-style” formatting syntax familiar from the C programming language, e.g. “%.2f” would format your labels with two decimals (including rounding).

If “None”, no explicit formatting will be performed and the defaults of Matplotlib applied.

Default: None

ytickcountint

number of tick labels on the y axis

Useful in case of too many ticks displayed on the y axis.

If “None”, as many ticks as plotted lines will be displayed.

If the number is larger than the number of plotted lines, only one tick per line will be shown, not more.

Default: None

tight: str

Whether to set the axes limits tight to the data

Possible values: ‘x’, ‘y’, ‘both’

Default: ‘’

Type:

dict

properties

Properties of the plot, defining its appearance

For the properties that can be set this way, see the documentation of the aspecd.plotting.SinglePlot2DStackedProperties class.

Type:

aspecd.plotting.SinglePlot2DStackedProperties

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: singleplot
  type: SinglePlotter2DStacked
  properties:
    filename: output.pdf

If you need to more precisely control the formatting of the y tick labels, particularly the number of decimals shown, you can set the formatting accordingly:

- kind: singleplot
  type: SinglePlotter2DStacked
  properties:
    filename: output.pdf
    parameters:
      yticklabelformat: '%.2f'

In this particular case, the y tick labels will appear with only two decimals. Note that currently, the “old style” formatting specifications are used due to their widespread use in other programming languages and hence the familiarity of many users with this particular notation.

Sometimes you want to have horizontal “zero lines” appear for each individual trace of the stacked plot. This can be achieved explicitly setting the “show_zero_lines” parameter to “True” that is set to “False” by default:

- kind: singleplot
  type: SinglePlotter2DStacked
  properties:
    filename: output.pdf
    parameters:
      show_zero_lines: True

As always, you can set the appearance of the plot in quite some detail. If you would like to style the individual lines, i.e. drawings, provide a list of properties for each individual drawing and make sure to provide as many items in the list as there are lines in the plot:

- kind: singleplot
  type: SinglePlotter2DStacked
  properties:
    properties:
      drawings:
        - color: '#FF0000'
          label: foo
        - color: '#00FF00'
          label: bar
        - color: '#0000FF'
          label: foobar

Important

If you set colours using the hexadecimal RGB triple prefixed by #, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.

Suppose you want to set identical properties for all lines. This is possible as well, by not providing the drawings key (plural) but the drawing key (singular) - and of course, this time not a list:

- kind: singleplot
  type: SinglePlotter2DStacked
  properties:
    properties:
      drawing:
        color: '#FF0000'

Changed in version 0.6: ylabel is set to third axis if offset = 0; new parameter “tight”

Changed in version 0.6.2: New parameter ytickcount

Changed in version 0.10: Properties changed to SinglePlot2DStackedProperties

property drawings

Actual graphical representation of the data.

List of matplotlib.artist.Artist objects, one for each of the actual lines of the plot

This is identical to drawing and has been added to work conveniently with SinglePlot2DStackedProperties.

Returns:

drawings – Actual graphical representation of the data.

Return type:

list

Added in version 0.10.

static applicable(data)

Check whether plot is applicable to the dataset.

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

Returns:

applicable – True if successful, False otherwise.

Return type:

bool

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.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.history.PlotHistoryRecord

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.MultiDeviceDataPlotter1D

Bases: SinglePlotter1D

1D plots of multiple device data of a single dataset.

Convenience class taking care of 1D plots of multiple device data of a single dataset. The type of plot can be set in its SinglePlotter1D.type attribute. Allowed types are stored in the SinglePlotter1D.allowed_types attribute.

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

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.

dataset

Dataset the plotting should be done for

Type:

aspecd.dataset.Dataset

data

Actual data that should be plotted.

List of aspecd.dataset.DeviceData objects corresponding to the device data selected using the parameter device_data.

Type:

list

drawing

List of matplotlib.artist.Artist objects, one for each of the actual lines of the plot

Type:

list

properties

Properties of the plot, defining its appearance

For the properties that can be set this way, see the documentation of the aspecd.plotting.MultiPlot1DProperties class.

Type:

aspecd.plotting.MultiPlot1DProperties

parameters

All parameters necessary for the plot, implicit and explicit

The following keys exist, in addition to those of the superclass:

axeslist

List of objects of class aspecd.dataset.Axis

There is two ways of setting axes labels: The user may provide the information required here. 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.

tight: str

Whether to set the axes limits tight to the data

Possible values: ‘x’, ‘y’, ‘both’

Default: ‘’

switch_axesbool

Whether to switch x and y axes

Normally, the first axis is used as x axis, and the second as y axis. Sometimes, switching this assignment is necessary or convenient.

Default: False

Type:

dict

Raises:

TypeError – Raised when wrong plot type is set

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values. Note, however, that in any case, you need to provide a list of devices whose data should be plotted:

- kind: singleplot
  type: MultiDeviceDataPlotter1D
  properties:
    parameters:
      device_data:
        - device_1
        - device_2
    filename: output.pdf

Often, it is convenient to have a legend to know for which devices the data are plotted:

- kind: singleplot
  type: MultiDeviceDataPlotter1D
  properties:
    parameters:
      device_data:
        - device_1
        - device_2
      show_legend: True
    filename: output.pdf

Here, it is interesting to note what labels will be used: Usually, the data for each device will have the attribute aspecd.metadata.Device.label set, and if so, this label will be used as label in the legend. If this attribute is not set, and you do not provide an alternative label in the MultiPlot1DProperties.drawing attribute, the key the device data are known within the dataset will be used in the legend.

To explicitly set (or override) the labels of your device data:

- kind: singleplot
  type: MultiDeviceDataPlotter1D
  properties:
    parameters:
      device_data:
        - device_1
        - device_2
      show_legend: True
    properties:
      drawings:
        - label: first device
        - label: second device
    filename: output.pdf

As axes are only labelled in case the axes of all devices are compatible, there may be situations where you want to set the axes properties explicitly:

- kind: singleplot
  type: MultiDeviceDataPlotter1D
  properties:
    parameters:
      device_data:
        - device_1
        - device_2
      axes:
        - quantity: time
          unit: s
        - quantity: intensity
          unit: a.u.
    filename: output.pdf

Added in version 0.9.

property drawings

Alias for drawing property.

As the plotter uses MultiPlot1DProperties as properties, this alias is necessary to apply the drawings settings.

static applicable(data)

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:

applicable – True if successful, False otherwise.

Return type:

bool

property allowed_types

Return the allowed plot types.

Currently, the allowed types are: plot, scatter, step, loglog, semilogx, semilogy, stemplot.

Returns:

allowed_types – List of strings

Return type:

list

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.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.history.PlotHistoryRecord

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

property 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:

TypeError – Raised in case of wrong type

class aspecd.plotting.SingleBarPlotter

Bases: SinglePlotter

Bar plots of single datasets.

Bar plots can be used for both, 1D and 2D datasets. In case of a 1D dataset, bars will be created whose height corresponds to the individual data points. For a 2D dataset, groups of bars will be created, with one bar per column in each bar group.

dataset

Dataset the plotting should be done for

Type:

aspecd.dataset.Dataset

drawing

Actual graphical representation of the data.

List of matplotlib.container.BarContainer objects, one for each column of the dataset. The actual matplotlib.artist.Artist objects are the children of the matplotlib.container.BarContainer objects.

Type:

list

properties

Properties of the plot, defining its appearance

For the properties that can be set this way, see the documentation of the aspecd.plotting.BarPlotProperties class.

Type:

aspecd.plotting.BarPlotProperties

parameters

All parameters necessary for the plot, implicit and explicit

The following keys exist, in addition to those of the superclass:

show_zero_linesbool

Whether to show zero lines in the plot

Regardless of whether you set this to true, zero lines will only be added to the final plot if the zero value is within the current axes limits.

Zero line properties can be set via the aspecd.plotting.Plotter.properties attribute.

Default: False

widthfloat

Total width of one group of bars.

In case of a 1D dataset, this is identical to the width of a single bar. For 2D datasets, this is identical to the width of each group of bars, i.e. a single bar will be width/columns wide.

As (groups of) bars are equally spaced, with a difference of two ticks of 1, width should be in the interval [0, 1]. Setting the width to 1 will leave no space between bars. While a width > 1 is technically possible, this would lead to overlapping bars.

Default: 0.8

labelslist

Labels used for the individual columns of the dataset.

In case of a 2D dataset, each column is treated similarly to an individual dataset, hence a label for the legend seems sensible. If the dataset does not provide the necessary information, you can set the label here.

Default: []

Type:

dict

Raises:

aspecd.exceptions.NotApplicableToDatasetError – Raised if the dataset data are >2D

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: singleplot
  type: SingleBarPlotter
  properties:
    filename: output.pdf

Added in version 0.12.

property drawings

Actual graphical representation of the data.

List of matplotlib.container.BarContainer objects, one for each column of the dataset. The actual matplotlib.artist.Artist objects are the children of the matplotlib.container.BarContainer objects.

This is identical to drawing and has been added to work conveniently with BarPlotProperties.

Returns:

drawings – Actual graphical representation of the data.

Return type:

list

static applicable(data)

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- or two-dimensional, and False otherwise.

Returns:

applicable – True if successful, False otherwise.

Return type:

bool

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

create_history_record()

Create history record to be added to the dataset.

Usually, this method gets called from within the aspecd.dataset.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.history.PlotHistoryRecord

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.MultiPlotter

Bases: Plotter

Base class for plots of multiple datasets.

Each class actually plotting data of multiple datasets 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

data

List of actual data that should be plotted

Each element is of type aspecd.dataset.Data.

Defaults to the primary data of a dataset, but can be the device data. See the key device_data of Plotter.parameters for details.

Type:

list

parameters

All parameters necessary for the plot, implicit and explicit

The following keys exist, in addition to the keys inherited from the superclass:

axeslist

List of objects of class aspecd.dataset.Axis

There is two ways of setting axes labels: The user may provide the information required here. 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.

Type:

dict

Raises:

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

• aspecd.exceptions.NotApplicableToDatasetError – Raised when processing step is not applicable to dataset

Changed in version 0.9: New attribute ‘’data’’

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to at least one of the datasets listed in datasets

• aspecd.exceptions.MissingDatasetError – Raised when no datasets exist to act on

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

static applicable(data)

Check whether plot is applicable to the 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:

applicable – True if successful, False otherwise.

Return type:

bool

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.MultiPlotter1D

Bases: MultiPlotter

1D plots of multiple datasets.

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

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

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

drawings

Actual graphical representations of the data of the datasets

Type:

list

properties

Properties of the plot, defining its appearance

For the properties that can be set this way, see the documentation of the aspecd.plotting.MultiPlotProperties class.

Type:

aspecd.plotting.MultiPlot1DProperties

parameters

All parameters necessary for this step.

Additionally, to those from aspecd.plotting.MultiPlotter, the following parameters are allowed:

switch_axesbool

Whether to switch x and y axes

Normally, the first axis is used as x axis, and the second as y axis. Sometimes, switching this assignment is necessary or convenient.

Default: False

tight: str

Whether to set the axes limits tight to the data

Possible values: ‘x’, ‘y’, ‘both’

Default: ‘’

Type:

dict

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    filename: output.pdf

To change the settings of each individual line (here the colour and label), supposing you have three lines, you need to specify the properties in a list for each of the drawings:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    filename: output.pdf
    properties:
      drawings:
        - color: '#FF0000'
          label: foo
        - color: '#00FF00'
          label: bar
        - color: '#0000FF'
          label: foobar

Important

If you set colours using the hexadecimal RGB triple prefixed by #, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.

Suppose you want to set identical properties for all lines. This is possible as well, by not providing the drawings key (plural) but the drawing key (singular) - and of course, this time not a list:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    properties:
      drawing:
        color: '#FF0000'

Of course, line plots are not the only plot type available. Check the MultiPlotter1D.allowed_types attribute for further details. To make a semilogy plot (i.e., with logarithmic y axis), invoke the plotter as follows:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    type: semilogy
    filename: output.pdf

Important

As the logarithm of negative values is not defined, usually having a logarithmic axis with negative values will lead to unexpected results. Matplotlib defaults to clipping the invalid values. To help you with debugging the unexpected results, a warning will be logged (and printed to the terminal when serving a recipe) in case a logarithmic axis is affected by negative values. In such case, the easiest is to add an offset to your data, using aspecd.processing.ScalarAlgebra.

Sometimes it is convenient to switch the x and y axes, e.g. in context of 2D datasets where slices along both dimensions should be displayed together with the 2D data and next to the respective axes. To achieve this, set the switch_axes parameter accordingly:

- kind: multiplot
  type: MultiPlotter1D
  properties:
    parameters:
      switch_axes: true
    filename: output.pdf

Changed in version 0.7: New parameters switch_axes and tight

Changed in version 0.9: Issue warning with log plotters and negative values

property allowed_types

Return the allowed plot types.

Currently, the allowed types are: plot, step, loglog, semilogx, semilogy.

Returns:

allowed_types – List of strings

Return type:

list

property 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:

TypeError – Raised in case of wrong type

static applicable(data)

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:

applicable – True if successful, False otherwise.

Return type:

bool

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to at least one of the datasets listed in datasets

• aspecd.exceptions.MissingDatasetError – Raised when no datasets exist to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.MultiPlotter1DStacked

Bases: MultiPlotter1D

Stacked 1D plots of multiple datasets.

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

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

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

parameters

All parameters necessary for this step.

offsetfloat

The offset used for stacking the individual lines of the plot.

If not provided, automatically a best fit will be calculated.

Default: None

show_zero_linesbool

Whether to show zero lines in the plot

Regardless of whether you set this to true, zero lines will only be added to the final plot if the zero value is within the current axes limits.

Zero line properties can be set via the aspecd.plotting.Plotter.properties attribute.

Default: False

Type:

dict

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.

In the simplest case, just invoke the plotter with default values:

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: output.pdf

To change the settings of each individual line (here the colour and label), supposing you have three lines, you need to specify the properties in a list for each of the drawings:

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: output.pdf
    properties:
      drawings:
        - color: '#FF0000'
          label: foo
        - color: '#00FF00'
          label: bar
        - color: '#0000FF'
          label: foobar

Important

If you set colours using the hexadecimal RGB triple prefixed by #, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.

Sometimes you want to have horizontal “zero lines” appear for each individual trace of the stacked plot. This can be achieved explicitly setting the “show_zero_lines” parameter to “True” that is set to “False” by default. The offset is automatically set that spectra don’t overlap but can also be chosen freely (in units of the intensity):

- kind: multiplot
  type: MultiPlotter1DStacked
  properties:
    filename: output.pdf
    parameters:
      show_zero_lines: True
      offset: 0.3

property allowed_types

Return the allowed plot types.

Currently, the allowed types are: plot, step, loglog, semilogx, semilogy.

Returns:

allowed_types – List of strings

Return type:

list

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

static applicable(data)

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:

applicable – True if successful, False otherwise.

Return type:

bool

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Reference to axes object used for actual plotting.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to at least one of the datasets listed in datasets

• aspecd.exceptions.MissingDatasetError – Raised when no datasets exist to act on

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

property 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:

TypeError – Raised in case of wrong type

class aspecd.plotting.CompositePlotter

Bases: Plotter

Base class for plots consisting of multiple axes.

The underlying idea of composite plotters is to use a dedicated existing plotter for each axis and assign this plotter to the list of plotters of the CompositePlotter object. Thus the actual plotting task is left to the individual plotter and the CompositePlotter only takes care of the specifics of plots consisting of more than one axis.

In the framework of the CompositePlotter you can define the grid within which the axes are arranged. First, you define the grid dimension as a two-element vector, and second you define the subplot locations as list of four-element vectors. For details, see the documentation of the attributes grid_dimensions and subplot_locations below.

For each of the subplots, define a plotter and add the object to the list of plotters, the attribute plotter. Make sure to equip each of these plotters with the necessary information. To actually plot, use the plot() method of the CompositePlotter object.

If you would like to display a single dataset in several ways within one and the same figure window, have a look at the SingleCompositePlotter class. This class pretty much behaves like an ordinary SinglePlotter, where you can (and should) use the aspecd.dataset.Dataset.plot() method to plot.

Note

When writing classes based on this class, do not override the _create_plot() method. Generally, providing a list of plotters for each of the axes should be sufficient, and the CompositePlotter will call the plot() property of each of these plotters automatically for you.

Examples

A quick example how a recipe part using a composite plotter may look like. Both plotters raw-data and processed-data are previously defined figures using different datasets. Therefore, it is important to give results of a processing task a unique identifier if it is used in such a composite plotter.

- kind: compositeplot
  type: CompositePlotter
  properties:
    plotter:
    - raw-data
    - processed-data
    filename: comparison.pdf
    grid_dimensions: [1, 2]
    subplot_locations:
    - [0, 0, 1, 1]
    - [0, 1, 1, 1]

Suppose you have a more complex plot with three axes, and you want to share the x axes only for those axes in the same column(s).

- kind: compositeplot
  type: CompositePlotter
  properties:
    properties:
      grid_spec:
        hspace: 0
    plotter:
    - plotter1
    - plotter2
    - plotter3
    filename: comparison.pdf
    grid_dimensions: [2, 2]
    subplot_locations:
    - [0, 0, 1, 1]
    - [1, 0, 1, 1]
    - [0, 1, 2, 1]
    sharex: True

In this case, only the two axes in the left column will share their x axes, and as you have defined the top axes first, the axes below will share their x axis with the top axes. Further note that hspace, i.e. the vertical space between the axes, has been set to zero (the property starts with a “h” for height).

You could do the same for three axes where you would like to have the y axes of those plots in the same row shared:

- kind: compositeplot
  type: CompositePlotter
  properties:
    properties:
      grid_spec:
        wspace: 0
    plotter:
    - plotter1
    - plotter2
    - plotter3
    filename: comparison.pdf
    grid_dimensions: [2, 2]
    subplot_locations:
    - [0, 0, 1, 1]
    - [1, 1, 1, 1]
    - [1, 0, 1, 2]
    sharey: True

In this case, only the two axes in the top row will share their y axes, and as you have defined the left axes first, the axes to the right will share their y axis with the left axes. Further note that wspace, i.e. the horizontal space between the axes, has been set to zero (the property starts with a “w” for width).

grid_dimensions

Dimensions of the grid used to layout the figure

two elements: number of rows, number of columns

Default: [1, 1]

Type:

list

grid_spec

Grid layout used to place the subplots within the figure.

The properties of the grid layout can be controlled using the CompositePlotProperties.grid_spec attribute that is part of properties attribute.

Type:

matplotlib.gridspec.GridSpec

subplot_locations

List of subplot locations

Each subplot location is a list with four numeric elements: [start_row, start_column, row_span, column_span]

Default: [[0, 0, 1, 1]]

Type:

list

axes_positions

List of axes positions for fine-adjustment

Each axes position is a list with four numeric elements: [left_scale, bottom_scale, width_scale, height_scale] that are applied in the following way to the position of the individual axes:

[left, bottom, width, height] = ax[idx].get_position().bounds
new_position = [
    left + left_scale * width, bottom + bottom_scale * height,
    width * width_scale, height * height_scale
]
ax[idx].set_position(new_position)

Values can be both, positive and negative floats. Note, however, that negative values for the width and height parameter will mirror the axes accordingly.

Default: []

Type:

list

plotter

List of plotters

Plotters are objects of type aspecd.plotting.Plotter.

Upon calling aspecd.plotting.Plotter.plot(), for each axes in the list of axes, the corresponding plotter will be accessed and its aspecd.plotting.Plotter.plot() method called.

Note

When the plotters are operating on the same dataset which got processed in between, both will use and display the dataset after processing. To prevent this, assign the result of the processing step a unique name.

Type:

list

sharex

Whether to share the x axes of all subplots.

If set to True or all, all x axes are shared, starting with the first defined axes.

If set to one of ["col", "columns", "column-wise"], the x axes in each column are shared, starting with the first defined axes in each column.

In both cases, only the outer x axes will be shown.

Typically, you will want to set the hspace property in CompositePlotProperties.grid_spec to a small value.

Added in version 0.10.

Type:

bool | str

sharey

Whether to share the y axes of all subplots.

If set to True or all, all y axes are shared, starting with the first defined axes.

If set to one of ["row", "rows", "row-wise"], the y axes in each row are shared, starting with the first defined axes in each row.

In both cases, only the outer y axes will be shown.

Typically, you will want to set the wspace property in CompositePlotProperties.grid_spec to a small value.

Added in version 0.10.

Type:

bool | str

properties

Properties of the plot, defining its appearance

These properties are used for the CompositePlot as such, and if set will override those properties of the individual plotters used to fill the axes of the CompositePlot. For details, see the documentation of the aspecd.plotting.CompositePlotProperties class.

Type:

aspecd.plotting.CompositePlotProperties

Raises:

aspecd.exceptions.MissingPlotterError – Raised if the number of plotters does not match the number of axes Note that for each axes you need a corresponding plotter.

property axes

Axes of the composite plotter.

Will eventually be objects of subtypes of matplotlib.axes.Axes and populated upon calling aspecd.plotting.Plotter.plot().

Returns:

axes – List of axes

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

For some reason, matplotlib.gridspec.GridSpec leads to an infinite recursion, hence the attribute is emptied before creating the dict, and afterwards readded.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

static applicable(data)

Check whether plot is applicable to the 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:

applicable – True if successful, False otherwise.

Return type:

bool

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

plot()

Perform the actual plotting.

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

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

class aspecd.plotting.SingleCompositePlotter

Bases: CompositePlotter

Composite plotter for single datasets

This composite plotter is used for different representations of one and the same dataset in multiple axes contained in one figure. In this respect, it works like all the other ordinary single plotters derived from SinglePlotter, i.e. it usually gets called by using the dataset’s aspecd.dataset.Dataset.plot() method.

As with the generic CompositePlotter, specify both the axes grid and locations as well as the plotters to use for each individual plot. Calling plot() by means of aspecd.dataset.Dataset.plot() will assign the dataset to each of the individual plotters and make them plot the data contained in the dataset.

dataset

Dataset the plotting should be done for

Type:

aspecd.dataset.Dataset

Raises:

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

• aspecd.exceptions.NotApplicableToDatasetError – Raised when processing step is not applicable to dataset

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().

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:

• aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset

• aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on

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.history.PlotHistoryRecord

annotate(annotation=None)

Add annotation to dataset.

Parameters:

annotation (aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter

Returns:

annotation – Annotation added to the plot(ter)

Return type:

aspecd.annotation.PlotAnnotation

static applicable(data)

Check whether plot is applicable to the 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:

applicable – True if successful, False otherwise.

Return type:

bool

property ax

Shorthand for axes.

Returns:

axes – Reference to axes object used for actual plotting

Return type:

matplotlib.axes.Axes

property axes

Axes of the composite plotter.

Will eventually be objects of subtypes of matplotlib.axes.Axes and populated upon calling aspecd.plotting.Plotter.plot().

Returns:

axes – List of axes

Return type:

list

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters:

index (int) – Number of analysis in analyses to delete

property fig

Shorthand for figure.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

property figure

Reference to figure object.

Returns:

figure – Reference to figure object

Return type:

matplotlib.figure.Figure

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.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

For some reason, matplotlib.gridspec.GridSpec leads to an infinite recursion, hence the attribute is emptied before creating the dict, and afterwards readded.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

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:

• aspecd.exceptions.MissingFilenameError – Raised if no filename is provided for saver.

• aspecd.exceptions.MissingPlotError – Raised if no plot is provided to act upon.

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:

• aspecd.exceptions.MissingFilenameError – Raised if no filename is provided for saver.

• aspecd.exceptions.MissingPlotError – Raised if no plot is provided to act upon.

class aspecd.plotting.Caption

Bases: 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 caption.

Type:

list

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.PlotProperties

Bases: Properties

Properties of a plot, defining its appearance.

figure

Properties of the figure as such

For the properties that can be set this way, see the documentation of the aspecd.plotting.FigureProperties class.

Type:

aspecd.plotting.FigureProperties

axes

Properties of the axes.

For the properties that can be set this way, see the documentation of the aspecd.plotting.AxesProperties class.

Type:

aspecd.plotting.AxesProperties

legend

Properties of the legend.

For the properties that can be set this way, see the documentation of the aspecd.plotting.LegendProperties class.

Type:

aspecd.plotting.LegendProperties

zero_lines

Properties of the zero lines.

For the properties that can be set this way, see the documentation of the aspecd.plotting.LineProperties class.

Default values for the zero lines are:

• color: #cccccc

Type:

aspecd.plotting.LineProperties

Raises:

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

Changed in version 0.12: Moved axes up to this class from subclasses.

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.exceptions.MissingPlotterError – Raised if no plotter is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlotProperties

Bases: PlotProperties

Properties of a single plot, defining its appearance.

figure

Properties of the figure as such

For the properties that can be set this way, see the documentation of the aspecd.plotting.FigureProperties class.

Type:

aspecd.plotting.FigureProperties

axes

Properties of the axes.

For the properties that can be set this way, see the documentation of the aspecd.plotting.AxesProperties class.

Type:

aspecd.plotting.AxesProperties

grid

Properties of the grid.

For the properties that can be set this way, see the documentation of the aspecd.plotting.GridProperties class.

Type:

aspecd.plotting.GridProperties

drawing

Properties of the line within a plot

For the properties that can be set this way, see the documentation of the aspecd.plotting.DrawingProperties class.

Type:

aspecd.plotting.DrawingProperties

Raises:

aspecd.exceptions.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.exceptions.MissingPlotterError – Raised if no plotter is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlot1DProperties

Bases: SinglePlotProperties

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

drawing

Properties of the line within a plot

For the properties that can be set this way, see the documentation of the aspecd.plotting.LineProperties class.

Type:

aspecd.plotting.LineProperties

Raises:

aspecd.exceptions.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.exceptions.MissingPlotterError – Raised if no plotter is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlot2DProperties

Bases: SinglePlotProperties

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

drawing

Properties of the surface within a plot

For the properties that can be set this way, see the documentation of the aspecd.plotting.SurfaceProperties class.

Type:

aspecd.plotting.SurfaceProperties

colorbar

Properties of the colorbar (optionally) added to a plot

For the properties that can be set this way, see the documentation of the aspecd.plotting.ColorbarProperties class.

Added in version 0.9.

Type:

aspecd.plotting.ColorbarProperties

Raises:

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

property colormap

Name of the colormap to use for colouring the surface.

If not given, the default colormap set via the property cmap in aspecd.plotting.SurfaceProperties will be used. Querying this property will only return a non-empty string if the property itself was set, not the default value set via the property cmap in aspecd.plotting.SurfaceProperties. However, setting a value will be propagated to the property cmap in aspecd.plotting.SurfaceProperties. This behaviour is necessary to allow for setting a default colormap in a recipe and having it propagated by default to 2D surface plots as well.

For a full list of colormaps available with Matplotlib, see https://matplotlib.org/stable/gallery/color/colormap_reference.html.

Note that appending _r to the name of a colormap will reverse it.

Added in version 0.8.2.

apply(plotter=None)

Apply properties to plot.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.MultiPlotProperties

Bases: PlotProperties

Properties of a multiplot, defining its appearance.

figure

Properties of the figure as such

For the properties that can be set this way, see the documentation of the aspecd.plotting.FigureProperties class.

Type:

aspecd.plotting.FigureProperties

axes

Properties of the axes.

For the properties that can be set this way, see the documentation of the aspecd.plotting.AxesProperties class.

Type:

aspecd.plotting.AxesProperties

grid

Properties of the grid.

For the properties that can be set this way, see the documentation of the aspecd.plotting.GridProperties class.

Type:

aspecd.plotting.GridProperties

drawings

Properties of the lines within a plot.

Each element is a aspecd.plotting.DrawingProperties object

For the properties that can be set this way, see the documentation of the aspecd.plotting.DrawingProperties class.

Type:

list

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

The key drawings is handled in a special way: First of all, aspecd.plotting.MultiPlotProperties.drawings is a list, hence we need to iterate over the entries of the list. Furthermore, a new element of the list is appended only if it does not exist already.

As different MultiPlotter objects will use different properties classes for their drawing, adding a new drawing is handled by a separate method, aspecd.plotting.MultiPlotProperties.add_drawing(). Additionally, each MultiPlotter class can use this method as well, to add drawing properties for each plotted item.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.exceptions.MissingDictError – Raised if no dict is provided.

add_drawing()

Add a aspecd.plotting.DrawingProperties object to the list.

As different MultiPlotter objects will use different properties classes for their drawing, adding a new drawing is handled by this method. Additionally, each MultiPlotter class can use this method as well, to add drawing properties for each plotted item.

Note

A note for developers: Concrete MultiPlotter classes will use classes derived from aspecd.plotting.MultiPlotProperties for their properties property. These properties classes should override this method to ensure the correct type of aspecd.plotting.DrawingProperties is instantiated. Furthermore, make sure to set default values according to the current cycler.

apply(plotter=None)

Apply properties to plot.

Parameters:

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

Raises:

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

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.MultiPlot1DProperties

Bases: MultiPlotProperties

Properties of a 1D multiplot, defining its appearance.

drawings

Properties of the lines within a plot.

Each element is a aspecd.plotting.LineProperties object

For the properties that can be set this way, see the documentation of the aspecd.plotting.LineProperties class.

Type:

list

colormap

Name of the colormap to use for colouring the individual drawings.

For a full list of colormaps available with Matplotlib, see https://matplotlib.org/stable/gallery/color/colormap_reference.html.

Note that appending _r to the name of a colormap will reverse it.

If set to None, the default colormap from your Matplotlib settings will be used.

Default: None

Type:

str

number_of_colors

Number of colors taken from the colormap.

This setting is useful if you provide a colormap (probably globally in a recipe) and would like to have always the same colour succession in your figures, regardless of the number of actual drawings within one figure.

If there are more drawings than colors, the colors will be cycled, i.e., several drawings will have the same color.

Has only an effect if a colormap is provided.

Type:

int

first_color

First color of a chosen colormap to use.

Particularly with colormaps starting with white or fairly light colors, setting an offset within the colormap is often necessary.

Default: 0

Type:

int

Raises:

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

Changed in version 0.8: Added attribute colormap

Changed in version 0.12: Added attributes number_of_colors and first_color

from_dict(dict_=None)

Set attributes from dictionary.

The key drawing (singular!) is handled in a special way: If it exists in the dictionary, it gets used to set all drawings to this one set of properties.

Otherwise, the behaviour is identical to that of the superclass method: see MultiPlotProperties.from_dict() for details.

Parameters:

dict (dict) – Dictionary containing information of a task.

Added in version 0.10.

add_drawing()

Add a aspecd.plotting.LineProperties object to the list.

The default properties are set as well, as obtained from matplotlib.pyplot.rcParams. These contain at least colour, width, marker, and style of a line.

Note

If you provide a key “drawing” (singular!) in the dictionary with the properties, instead of setting default properties the properties of this dict will be set to all drawings. Thus, you can conveniently set identical settings for all lines.

Changed in version 0.10: Handling of the drawing key.

apply(plotter=None)

Apply properties to plot.

The main difference to the parent class: if you set a colormap property, the lines will be coloured according to the colormap. Note that this needs to be done on this level, as we need to know how many drawings (i.e. lines) there are to colour.

Parameters:

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

Raises:

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

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SinglePlot2DStackedProperties

Bases: MultiPlot1DProperties

Properties of a 2D stacked singleplot, defining its appearance.

drawings

Properties of the lines within a plot.

Each element is a aspecd.plotting.LineProperties object

For the properties that can be set this way, see the documentation of the aspecd.plotting.LineProperties class.

Type:

list

colormap

Name of the colormap to use for colouring the individual drawings

For a full list of colormaps available with Matplotlib, see https://matplotlib.org/stable/gallery/color/colormap_reference.html.

Note that appending _r to the name of a colormap will reverse it.

Type:

str

Raises:

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

Added in version 0.10.

property drawing

Properties of the lines within a plot.

Each element is a aspecd.plotting.LineProperties object

For the properties that can be set this way, see the documentation of the aspecd.plotting.LineProperties class.

This is identical to drawings and has been added to work conveniently with SinglePlotter2DStacked.

Returns:

drawing – Properties of the lines within a plot.

Return type:

list

Added in version 0.10.

add_drawing()

Add a aspecd.plotting.LineProperties object to the list.

The default properties are set as well, as obtained from matplotlib.pyplot.rcParams. These contain at least colour, width, marker, and style of a line.

Note

If you provide a key “drawing” (singular!) in the dictionary with the properties, instead of setting default properties the properties of this dict will be set to all drawings. Thus, you can conveniently set identical settings for all lines.

Changed in version 0.10: Handling of the drawing key.

apply(plotter=None)

Apply properties to plot.

The main difference to the parent class: if you set a colormap property, the lines will be coloured according to the colormap. Note that this needs to be done on this level, as we need to know how many drawings (i.e. lines) there are to colour.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

The key drawing (singular!) is handled in a special way: If it exists in the dictionary, it gets used to set all drawings to this one set of properties.

Otherwise, the behaviour is identical to that of the superclass method: see MultiPlotProperties.from_dict() for details.

Parameters:

dict (dict) – Dictionary containing information of a task.

Added in version 0.10.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.BarPlotProperties

Bases: MultiPlot1DProperties

Properties of a bar plot, defining its appearance.

drawings

Properties of the bars within a plot.

Each element is a aspecd.plotting.PatchProperties object

For the properties that can be set this way, see the documentation of the aspecd.plotting.PatchProperties class.

Type:

list

colormap

Name of the colormap to use for colouring the individual drawings

For a full list of colormaps available with Matplotlib, see https://matplotlib.org/stable/gallery/color/colormap_reference.html.

Note that appending _r to the name of a colormap will reverse it.

Type:

str

Raises:

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

Added in version 0.12.

property drawing

Properties of the bars within a plot.

Each element is a aspecd.plotting.PatchProperties object

For the properties that can be set this way, see the documentation of the aspecd.plotting.PatchProperties class.

This is identical to drawings and has been added to work conveniently with SingleBarPlotter.

Returns:

drawing – Properties of the bars within a plot.

Return type:

list

add_drawing()

Add a aspecd.plotting.PatchProperties object to the list.

Note

If you provide a key “drawing” (singular!) in the dictionary with the properties, instead of setting default properties the properties of this dict will be set to all drawings. Thus, you can conveniently set identical settings for all patches.

apply(plotter=None)

Apply properties to plot.

The main difference to the parent class: if you set a colormap property, the lines will be coloured according to the colormap. Note that this needs to be done on this level, as we need to know how many drawings (i.e. lines) there are to colour.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

The key drawing (singular!) is handled in a special way: If it exists in the dictionary, it gets used to set all drawings to this one set of properties.

Otherwise, the behaviour is identical to that of the superclass method: see MultiPlotProperties.from_dict() for details.

Parameters:

dict (dict) – Dictionary containing information of a task.

Added in version 0.10.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.CompositePlotProperties

Bases: PlotProperties

Properties of a composite plot, defining its appearance.

For the plotter class, see CompositePlotter.

figure

Properties of the figure as such

For the properties that can be set this way, see the documentation of the aspecd.plotting.FigureProperties class.

Type:

aspecd.plotting.FigureProperties

axes

Properties for all axes of the CompositePlotter.

This property is used to set properties for all axes of a CompositePlotter at once. This will override the settings of the individual plotters.

For the properties that can be set this way, see the documentation of the AxesProperties class.

Type:

AxesProperties

grid_spec

Properties for the subplot grid specs.

This property is used to set properties for the subplot grid.

For the properties that can be set this way, see the documentation of the SubplotGridSpecs class.

Added in version 0.10.

Type:

SubplotGridSpecs

Raises:

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

Changed in version 0.10: Property grid_spec added.

apply(plotter=None)

Apply properties to plot.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.FigureProperties

Bases: 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.

size

Figure dimension (width, height) in inches.

2-tuple of floats

In order to not prevent users from setting the default figure size in their matplotlibrc file, the default is None.

Default: None

Type:

tuple

dpi

Figure resolution in dots per inch.

Default: 100

Type:

float

title

Title for the figure as a whole

Important

If you have a second axis on top of the axes, setting the figure title will result in the figure title clashing with the upper axis. Hence, in such case, try setting the axis title.

Type:

str

Raises:

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

Changed in version 0.6: Default figure size set to (6., 4.)

Changed in version 0.11: Default figure size set to None to allow setting from matplotlibrc file.

apply(figure=None)

Apply properties to figure.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.AxesProperties

Bases: Properties

Properties of an axis of a plot.

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

aspect

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

Default: ‘’

Type:

{‘auto’, ‘equal’} or num

facecolor

facecolor of the axes

Default: None

Type:

color

position

position of the axes: left, bottom, width, height

four numbers in the interval [0..1]

Default: []

Type:

list

title

title for the axis

Note that this is a per-axis title, unlike the figure title set for the whole figure.

Important

If you have a second axis on top of the axes, setting the figure title will result in the figure title clashing with the upper axis. Hence, in such case, try setting the axis title.

Default: ‘’

Type:

str

xlabel

label for the x-axis

To remove the xlabel entirely, set it to None (or null in YAML).

Default: ‘’

Type:

str

xlabelposition

Position of the label for the x-axis.

Possible values are: “left”, “center”, “right”.

Default: “center”

Added in version 0.11.

Type:

str

xlim

x-axis view limits, two floats

Default: []

Type:

list

xscale

x-axis scale

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

Default: ‘’

Type:

str

xticks

y ticks with list of ticks

Default: None

xticklabels

x-tick labels: list of string labels

Default: None

Type:

list

xticklabelangle

Angle of the x-tick labels

Default: None

Added in version 0.6.

Type:

float

ylabel

label for the y-axis

To remove the xlabel entirely, set it to None (or null in YAML).

Default: ‘’

Type:

str

ylabelposition

Position of the label for the y-axis.

Possible values are: “left”, “center”, “right”, “bottom”, “top”, where “left”/”bottom” and “right”/”top” are equivalent.

Default: “center”

Added in version 0.11.

Type:

str

ylim

y-axis view limits, two floats

Default: []

Type:

list

yscale

y-axis scale

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

Default: ‘’

Type:

str

yticks

y ticks with list of ticks

Default: None

yticklabels

y-tick labels: list of string labels

Default: None

Type:

list

yticklabelangle

Angle of the y-tick labels

Default: None

Added in version 0.6.

Type:

float

label_fontsize

Font size of the axes labels.

If numeric the size will be the absolute font size in points. String values are relative to the current default font size. Valid string values are: xx-small, x-small, small, medium, large, x-large, xx-large

Default: plt.rcParams['font.size']

Added in version 0.9.

Type:

int or str

invert

Axes to invert

Sometimes, inverted axes are the default, e.g. the wavenumber axis in FTIR spectroscopy. While dedicated packages for such method based on the ASpecD framework will take care of these specialties, this option allows for full flexibility.

Can either be a single value, such as ‘x’ or ‘y’, or a list, such as [‘x’] or even [‘x’, ‘y’].

Note

An alternative option to invert an axis is to provide descending values for axis limits. However, this may be inconvenient if you don’t want to explicitly provide axis limits.

Added in version 0.9.

Type:

list or str

frame_on

Whether to draw the “frame” (aka “spines”) around the axes.

Note that setting this attribute to False will remove the entire frame, hence it is usually not what you intended.

Default: True

Added in version 0.11.

Type:

bool

spines

Settings for axes spines.

Axes spines are basically the four lines in the four edges of an axes, where the tick marks are attached.

See class Spines and SpineProperties for details.

Added in version 0.11.

Type:

Spines

Raises:

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

Changed in version 0.6: New properties xticklabelangle and yticklabelangle

Changed in version 0.9: New property invert

Changed in version 0.9: New property label_fontsize

Changed in version 0.9.3: Properties xlabel and ylabel can be removed by setting to Null

Changed in version 0.11: New properties frame_on, spines, xlabelposition, and ylabelposition

apply(axes=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:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.LegendProperties

Bases: 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

frameon

Whether to plot a box around the legend

Default: True

Type:

bool

labelspacing

Vertical space between the legend entries, in font-size units.

Default: 0.5

Type:

float

fontsize

Font size of the legend.

If numeric the size will be the absolute font size in points. String values are relative to the current default font size. Valid string values are: xx-small, x-small, small, medium, large, x-large, xx-large

Default: plt.rcParams['font.size']

Type:

int or str

ncol

Number of columns of the legend

Default: 1

Type:

int

title

Title of the legend

Default: empty

Type:

str

Raises:

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

Changed in version 0.7: Added attributes labelspacing and fontsize

Changed in version 0.8: Added attribute ncol

Changed in version 0.9: Added attribute title

property location

Alias for aspecd.plotting.LegendProperties.loc

apply(legend=None)

Apply properties to legend.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.DrawingProperties

Bases: 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.

While a base class for more specific kinds of drawings, such as lines, surfaces, or even text, drawing properties come with two essential attributes: a label and the zorder.

The latter means that you can control the z stacking of the different parts of a plot. Artists with lower zorder are drawn first.

For specific kinds of drawings and their respective properties, see LineProperties, SurfaceProperties, and TextProperties.

label

Label of a drawing that gets used within a legend.

Default: ‘’

Type:

str

alpha

Alpha value used for blending

Must be within the 0-1 range, inclusive, or None.

Added in version 0.11.

Type:

float

zorder

Zorder for the artist.

Artists with lower zorder are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Added in version 0.10.

Type:

float

Raises:

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

Examples

Drawing properties are always set in context of concrete plotters, and furthermore, the individual main elements of a plot are always referred to as drawing or drawings within their respective PlotProperties.

An example for setting the drawing properties of a SinglePlotter1D are given below:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      drawings:
        label: Substance 1
        zorder: 3

In context of a plotter with a legend, the label would appear in this legend, and in this particular case, the zorder is set to 3, i.e. the line in the plotter would appear behind other elements.

Changed in version 0.10: New property zorder

Changed in version 0.11: New property alpha

apply(drawing=None)

Apply properties to drawing.

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

Parameters:

drawing (matplotlib.artist.Artist) – Artist to set properties for

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.LineProperties

Bases: 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

zorder

Zorder for the artist.

Artists with lower zorder are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Added in version 0.10.

Type:

float

Raises:

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

Examples

Drawing properties are always set in context of concrete plotters, and furthermore, the individual main elements of a plot are always referred to as drawing or drawings within their respective PlotProperties.

An example for setting the line properties of a SinglePlotter1D are given below:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      drawings:
        label: Substance 1
        zorder: 3
        color: '#1f77b4'
        drawstyle: default
        linestyle: '-'
        linewidth: 1.5
        marker: None

Here, all currently possible properties are shown.

settable_properties()

Return properties that are not empty or None.

Returns:

properties – Dictionary containing all settable properties, i.e. properties that are neither empty nor None.

Return type:

dict

apply(drawing=None)

Apply properties to drawing.

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

Parameters:

drawing (matplotlib.artist.Artist) – Artist to set properties for

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SurfaceProperties

Bases: DrawingProperties

Properties of a surface within a plot.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.contour.ContourSet and matplotlib.image.AxesImage objects.

cmap

Name of the colormap to use

For details see matplotlib.colors.Colormap

Type:

str

clim

Norm limits for image scaling: (vmin, vmax)

The corresponding parameters of the matplotlib.axes.Axes.contour() method are vmin and vmax. If you would like to set only one of them, set the other to None.

Added in version 0.12.

Type:

tuple

linewidths

Width of the contour lines (if present)

Type:

float

linestyles

Style of the contour lines (if present)

Type:

str

colors

Colour of the contour lines (if present)

Type:

str

norm

The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1.

For a list of available scales, call matplotlib.scale.get_scale_names(). Besides these names, you can use the names of all subclasses of matplotlib.colors.Normalize. If the resulting object needs any additional parameter or if you want to change the defaults, set the norm_parameters attribute accordingly.

Added in version 0.12.

Type:

str

norm_parameters

Additional parameters for the norm set using the attribute norm.

For details which parameters can be set, see the Matplotlib documentation of the respective subclass of matplotlib.colors.Normalize.

Added in version 0.12.

Type:

dict

zorder

Zorder for the artist.

Artists with lower zorder are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Added in version 0.10.

Type:

float

apply(drawing=None)

Apply properties to drawing.

Parameters:

drawing – matplotlib object to set properties for

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.GridProperties

Bases: Properties

Properties of the grid of a plot.

show

whether to show grids

Type:

bool

ticks

ticks to set grid lines for: {‘major’, ‘minor’, ‘both’}

For details see the which parameter of matplotlib.axes.Axes.grid()

Type:

str

axis

axis to set grid lines for: {‘both’, ‘x’, ‘y’}

For details see matplotlib.axes.Axes.grid()

Type:

str

lines

line properties of the grid

Type:

aspecd.plotting.LineProperties

Raises:

TypeError – Raised if no axes is provided.

apply(axes=None)

Apply properties to axes.

If show is false, no grid will be displayed. Otherwise, the properties will be set, including the line properties.

Parameters:

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

Raises:

TypeError – Raised if called without axes object

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.ColorbarProperties

Bases: Properties

Properties of the colorbar of a plot.

Basically, a subset of what matplotlib.figure.Figure.colorbar() defines for a colorbar.

Note that Matplotlib does not usually have an interface that easily allows to both, set and query properties. For colorbars in particular, many parameters can only be set when instantiating the colorbar object.

location

Location of the colorbar.

Valid parameters: None or {‘left’, ‘right’, ‘top’, ‘bottom’}

Type:

str

fraction

Fraction of original axes to use for colorbar.

Default: 0.15

Type:

float

aspect

Ratio of long to short dimensions.

Default: 20.

Type:

float

pad

Fraction of original axes between colorbar and new image axes.

Default: 0.05 if vertical, 0.15 if horizontal

Type:

float

format

Format of the tick labels

Type:

str

label

The label on the colorbar’s long axis and its properties.

The following keys exist:

textstr

The label text

locationstr

The location of the label

Valid values depend on the orientation of the colorbar.

• For horizontal orientation one of {‘left’, ‘center’, ‘right’}

• For vertical orientation one of {‘bottom’, ‘center’, ‘top’}

Type:

dict

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class.

Generally, the ColorbarProperties are set within the properties of the respective plotter.

- kind: singleplot
  type: SinglePlotter2D
  properties:
    properties:
      colorbar:
        location: top
        fraction: 0.1
        pad: 0.1
        format: "%4.2e"
        label:
          text: $foo$ / bar
          location: left

Added in version 0.9.

property kwargs

Properties that can/need to be set during colorbar object creation.

Many parameters can only be set when instantiating the colorbar object. For convenience, this property returns a dict with the subset of properties that can (and need to) be set this way.

Those properties of the class that cannot be set this way are listed in the private attribute _exclude_from_kwargs. Actually setting the properties to a colorbar looks like:

fig.colorbar(drawing, ax=ax, **kwargs)

Here, **kwargs is the expansion of the returned dictionary.

Returns:

kwargs – dict with kwargs that can be set when instantiating the colorbar.

Return type:

dict

apply(colorbar=None)

Apply properties to colorbar.

Parameters:

colorbar (matplotlib.colorbar.Colorbar) – Colorbar the properties should be applied to.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.TextProperties

Bases: DrawingProperties

Properties of text within a plot.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.text.Text objects.

alpha

Alpha value used for blending

Must be within the 0-1 range, inclusive, or None.

Type:

float

backgroundcolor

Color used as background for the text

If set to None, no background will be set (and the bbox removed from the Matplotlib artist)

Type:

str

color

Color used for the text

Type:

str

fontfamily

Font family or font name

Font family can be one of: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, ‘monospace’

Type:

str

fontsize

Size of the font

Either a numeric value or one of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’

Type:

float or str

fontstretch

Stretch of the font

A numeric value in range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultra-expanded’

Type:

int or str

fontstyle

Style of the font

One of: ‘normal’, ‘italic’, ‘oblique’

Type:

str

fontvariant

Variant of the font

One of: ‘normal’, ‘small-caps’

Type:

:class:``

fontweight

Weight of the font

A numeric value in range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

Type:

int or str

horizontalalignment

Horizontal alignment of the text

One of: ‘left’, ‘center’, ‘right’

Type:

str

in_layout

Set if artist is to be included in layout calculations.

Type:

bool

linespacing

Line spacing of the text

The value is interpreted as multiple of the font size

Type:

float

math_fontfamily

Font family or fontname used for math fonts

Type:

str

multialignment

Text alignment for multiline texts

One of: ‘left’, ‘right’, ‘center’

Type:

str

parse_math

Set mathtext parsing for text

If False, no mathtext will be used. If True, mathtext will be used if there is an even number of unescaped dollar signs.

Type:

bool

rotation

Rotation of the text

Either a scalar number or one of: ‘vertical’, ‘horizontal’

Type:

float or str

rotation_mode

Rotation mode of the text

One of: ‘default’, ‘anchor’

If “default”, the text will be first rotated, then aligned according to their horizontal and vertical alignments. If “anchor”, then alignment occurs before rotation.

Type:

str

usetex

Whether to render using TeX

None means to use rcParams["text.usetex"] (default: False).

Type:

bool or None

verticalalignment

Vertical alignment of the text

One of: ‘baseline’, ‘bottom’, ‘center’, ‘center_baseline’, ‘top’

Type:

str

wrap

Set whether the text can be wrapped.

Wrapping makes sure the text is confined to the (sub)figure box. It does not take into account any other artists.

Type:

bool

zorder

Zorder for the artist.

Artists with lower zorder values are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Type:

float

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no text is provided.

Added in version 0.10.

apply(drawing=None)

Apply properties to text.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SubplotGridSpecs

Bases: Properties

Properties for the subplot grid specs.

This class is used to set properties for the subplot grid of the CompositePlotter class. As such, it is part of the CompositePlotProperties class. For further details, see the matplotlib.gridspec.GridSpec documentation.

left

Left extent of the subplots as a fraction of figure width.

Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.

Type:

float

bottom

Bottom extent of the subplots as a fraction of figure height.

Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.

Type:

float

right

Right extent of the subplots as a fraction of figure width.

Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.

Type:

float

top

Top extent of the subplots as a fraction of figure height.

Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.

Type:

float

wspace

The amount of width reserved for space between subplots.

Expressed as a fraction of the average axis width. If not given, the values will be inferred from a figure or rcParams when necessary.

Type:

float

hspace

The amount of height reserved for space between subplots.

Expressed as a fraction of the average axis height. If not given, the values will be inferred from a figure or rcParams when necessary.

Type:

float

width_ratios

Relative width of the columns.

Each column gets a relative width of width_ratios[i] / sum(width_ratios). If not given, all columns will have the same width.

Type:

list

height_ratios

Relative height of the rows.

Each row gets a relative height of height_ratios[i] / sum(height_ratios). If not given, all rows will have the same height.

Type:

list

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class.

Subplot grid spec properties are always set in context of a concrete CompositePlotter.

An example for setting the subplot grid specs of a CompositePlotter are given below:

- kind: compositeplot
  type: CompositePlotter
  properties:
    properties:
      grid_spec:
        wspace: 0
        hspace: 0
    plotter:
    - raw-data
    - processed-data
    filename: comparison.pdf
    grid_dimensions: [1, 2]
    subplot_locations:
    - [0, 0, 1, 1]
    - [0, 1, 1, 1]

Added in version 0.10.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.PatchProperties

Bases: DrawingProperties

Properties of a patch within a plot.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.patches.Patch objects.

alpha

Transparency value – not supported on all backends.

Valid range: [0, 1]

Type:

float | None

color

color of the patch

For details see matplotlib.colors

Type:

color

edgecolor

edge color of the patch

For details see matplotlib.colors

Type:

color

facecolor

face color of the patch

For details see matplotlib.colors

Type:

color

fill

Whether to fill the patch

Type:

bool

hatch

hatching pattern.

hatch can be one of:

/   - diagonal hatching
\   - back diagonal
|   - vertical
-   - horizontal
+   - crossed
x   - crossed diagonal
o   - small circle
O   - large circle
.   - dots
*   - stars

Letters can be combined, in which case all the specified hatchings are done. If same letter repeats, it increases the density of hatching of that pattern.

Type:

str | None

in_layout

Set if artist is to be included in layout calculations.

Type:

bool

joinstyle

Connection between two line segments.

Default: ‘miter’

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.0

Type:

float

rasterized

Whether to force rasterized drawing for vector graphics output.

Type:

bool

snap

Snapping behavior.

Possible values:

• True: Snap vertices to the nearest pixel center.

• False: Do not modify vertex positions.

• None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center.

Type:

bool

zorder

Zorder for the artist.

Artists with lower zorder are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Type:

float

Examples

A typical use case for patches are horizontal or vertical spans as used for plot annotations. For details, see the aspecd.annotation.VerticalSpan class.

Added in version 0.11.

apply(drawing=None)

Apply properties to drawing.

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

Parameters:

drawing (matplotlib.artist.Artist) – Artist to set properties for

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.AnnotationTextProperties

Bases: DrawingProperties

Properties of text of an annotation.

Basically, the attributes are a subset of what matplotlib defines for matplotlib.text.Text objects. However, the alignment properties are missing that are present in TextProperties, as they would interfere with the functionality of the aspecd.annotate.TextWithLine class.

alpha

Alpha value used for blending

Must be within the 0-1 range, inclusive, or None.

Type:

float

backgroundcolor

Color used as background for the text

If set to None, no background will be set (and the bbox removed from the Matplotlib artist)

Type:

str

color

Color used for the text

Type:

str

fontfamily

Font family or font name

Font family can be one of: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, ‘monospace’

Type:

str

fontsize

Size of the font

Either a numeric value or one of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’

Type:

float or str

fontstretch

Stretch of the font

A numeric value in range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultra-expanded’

Type:

int or str

fontstyle

Style of the font

One of: ‘normal’, ‘italic’, ‘oblique’

Type:

str

fontvariant

Variant of the font

One of: ‘normal’, ‘small-caps’

Type:

:class:``

fontweight

Weight of the font

A numeric value in range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.

Type:

int or str

in_layout

Set if artist is to be included in layout calculations.

Type:

bool

linespacing

Line spacing of the text

The value is interpreted as multiple of the font size

Type:

float

math_fontfamily

Font family or fontname used for math fonts

Type:

str

parse_math

Set mathtext parsing for text

If False, no mathtext will be used. If True, mathtext will be used if there is an even number of unescaped dollar signs.

Type:

bool

rotation

Rotation of the text

Either a scalar number or one of: ‘vertical’, ‘horizontal’

Type:

float or str

rotation_mode

Rotation mode of the text

One of: ‘default’, ‘anchor’

If “default”, the text will be first rotated, then aligned according to their horizontal and vertical alignments. If “anchor”, then alignment occurs before rotation.

Type:

str

usetex

Whether to render using TeX

None means to use rcParams["text.usetex"] (default: False).

Type:

bool or None

wrap

Set whether the text can be wrapped.

Wrapping makes sure the text is confined to the (sub)figure box. It does not take into account any other artists.

Type:

bool

zorder

Zorder for the artist.

Artists with lower zorder values are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Type:

float

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no text is provided.

Added in version 0.11.

apply(drawing=None)

Apply properties to text.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.AnnotationProperties

Bases: Properties

Properties for the text and line of annotations.

This class is used to set properties for the aspecd.annotation.TextWithLine class.

text

Properties of the text part of the annotation

Type:

AnnotationTextProperties

line

Properties of the line part of the annotation

Type:

PatchProperties

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no text is provided.

Added in version 0.11.

apply(drawing=None)

Apply properties to drawing.

Properties will be set independently for the text and line parts of the annotation, and the underlying AnnotationTextProperties.apply() and PatchProperties.apply() method be called.

Parameters:

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

Raises:

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

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.Spines

Bases: Properties

Properties proxy for spines of an axes.

Axes spines are basically the four lines in the four edges of an axes, where the tick marks are attached.

This class serves as a “container” for the four individual spines.

left

Properties of the left axes spine

Type:

SpineProperties

bottom

Properties of the bottom axes spine

Type:

SpineProperties

right

Properties of the right axes spine

Type:

SpineProperties

top

Properties of the top axes spine

Type:

SpineProperties

Raises:

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

Examples

For detailed examples on how to set the spine properties in a plot, see the documentation of the SpineProperties class.

Added in version 0.11.

apply(axes=None)

Apply properties to spine.

For each spine, the corresponding SpineProperties.apply() method will be called.

Parameters:

axes (matplotlib.axes.Axes) – Axis to set spine properties for

Raises:

aspecd.exceptions.MissingAxisError – Raised if no axes is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

class aspecd.plotting.SpineProperties(edge='left')

Bases: DrawingProperties

Properties proxy for spines of an axes.

Axes spines are basically the four lines in the four edges of an axes, where the tick marks are attached.

For details, see the documentation of the matplotlib.spines.Spine class.

visible

Whether to show the spine.

To remove a spine, set its visibility to False.

Type:

bool

position

Type and value of the positioning of a spine.

The position type is one of outward, axes, data:

outward

Place the spine out from the data area by the specified number of points. (Negative values place the spine inwards.)

axes

Place the spine at the specified Axes coordinate (0 to 1).

data

Place the spine at the specified data coordinate.

Two shorthand notations exist, where position is only a string, no longer a tuple (or list):

center

Sets spline at the centre of the axis.

Same as ('axes', 0.5)

zero

Sets spline to the zero value of the data.

Same as ('data', 0.0)

Type:

tuple

boundstuple

Lower and higher spine bound in axes coordinates.

arrowbool

Whether to draw arrows at the tip of the spine

Particularly with only two spines shown and perhaps with spines positioned at zero (the origin of the Cartesian coordinate system), adding arrow heads at the tips of the spines makes sense.

Note that this is not a default property of the underlying matplotlib.spines.Spine, but adds the arrow heads as additional plots.

This functionality is inspired by an example in the Matplotlib documentation: https://matplotlib.org/stable/gallery/spines/centered_spines_with_arrows.html

Parameters:

edge (str) –

Position the spline belongs to in an axis: left, bottom, right, top.

This information is relevant for adding arrow heads.

Raises:

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

Examples

For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see aspecd.tasks) is given below for how to make use of this class.

Spines are set within the axes properties, hence in the axes block. Note that there are four spines: left, bottom, right, and top, for whom you can (and need to) set the properties separately.

To get rid of the top and right spine (a typical use case), just set the visibility of those two to False:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      axes:
        spines:
          right:
            visible: False
          top:
            visible: False

If you want to detach the spines, you could explicitly set both, bounds and positions:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      axes:
        spines:
          left:
            bounds: [0, 1]
            position: ["outward", 5]
          bottom:
            bounds: [-10, 10]
            position: ["outward", 5]
          right:
            visible: False
          top:
            visible: False

Suppose you want to draw what the Matplotlib documentation calls a “math textbook style plot”, where the spines are centred at zero (in the origin of the Cartesian coordinate system) and have arrows at their ends:

- kind: singleplot
  type: SinglePlotter1D
  properties:
    properties:
      axes:
        xlabel: Null
        ylabel: Null
        invert:
          - x
          - y
        spines:
          left:
            position: zero
            arrow: True
          bottom:
            position: zero
            arrow: True
          right:
            visible: False
          top:
            visible: False

Added in version 0.11.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.

apply(drawing=None)

Apply properties to spine.

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

Parameters:

drawing (matplotlib.spines.Spine) – Spine of an axis to set properties for

Raises:

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

class aspecd.plotting.MarkerProperties

Bases: DrawingProperties

Properties for marker.

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

alpha

Transparency value – not supported on all backends.

Valid range: [0, 1]

Type:

float | None

edgecolor

edge color of the marker

For details see matplotlib.colors

To remove the color, set it to None (or Null in YAML)

Default: “#000000”

Type:

color

edgewidth

Width of the marker edge

Type:

float

facecolor

face color of the marker

For details see matplotlib.colors

To remove the color, set it to None (or Null in YAML)

Default: “#000000”

Type:

color

facecoloralt

Alternative face color of the marker

This color gets interesting depending on the fill style.

For details see matplotlib.colors

To remove the color, set it to None (or Null in YAML)

Default: “none”

Type:

color

fillstyle

Style to use to fill the marker.

Allowed values are: “full”, “left”, “right”, “bottom”, “top”, “none”

Type:

str

size

Size of the marker.

Type:

float

zorder

Zorder for the artist.

Artists with lower zorder are drawn first.

For a summary of the default zorder values, see the Matplotlib documentation

Type:

float

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no marker is provided.

Examples

Markers are typically used for plot annotations. For details, see the aspecd.annotation.Marker class.

Added in version 0.11.

apply(drawing=None)

Apply properties to drawing.

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

Parameters:

drawing (matplotlib.artist.Artist) – Artist to set properties for

Raises:

aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.

from_dict(dict_=None)

Set attributes from dictionary.

Parameters:

dict (dict) – Dictionary containing information of a task.

Raises:

aspecd.plotting.MissingDictError – Raised if no dict is provided.

get_properties()

Return (public) properties, i.e. attributes that are not methods.

Returns:

properties – public properties

Return type:

list

to_dict(remove_empty=False)

Create dictionary containing public attributes of an object.

Parameters:

remove_empty (bool) –

Whether to remove keys with empty values

Default: False

Returns:

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type:

collections.OrderedDict

Changed in version 0.6: New parameter remove_empty

Changed in version 0.9: Settings for properties to exclude and include are not traversed

Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables __dict__ and __0dict__ are modified, what may result in strange behaviour.

Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.