You're reading an old version of this documentation. For up-to-date information, please have a look at v0.9.

aspecd.plotting module

Plotting: Graphical representations of data extracted from datasets.

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

fig, ax = matplotlib.pyplot.subplots()

For convenience, short hands for the figure and axes properties of a plotter are available, named fig and ax, respectively. For details on handling (own) figure and axes objects, see below.

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:

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:

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

Concrete plotters for multiple datasets

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:

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

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: singleplot
  type: SinglePlotter1D
  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.

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: aspecd.utils.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

figure

Reference to figure object

Type

matplotlib.figure.Figure

axes

Reference to axes object used for actual plotting

Type

matplotlib.axes.Axes

filename

Name of file to save the plot to

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

Type

str

caption

User-supplied information for the figure.

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 fig

Short hand for figure.

property ax

Short hand for 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

applicableTrue 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

class aspecd.plotting.SinglePlotter

Bases: aspecd.plotting.Plotter

Base class for plots of single datasets.

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

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

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

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

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

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.SinglePlotProperties

dataset

Dataset the plotting should be done for

Type

aspecd.dataset.Dataset

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

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

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters

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

property fig

Short hand for 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

class aspecd.plotting.SinglePlotter1D

Bases: aspecd.plotting.SinglePlotter

1D plots of single datasets.

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

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

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

properties

Properties of the plot, defining its appearance

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

applicableTrue 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

Short hand for 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

Short hand for 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
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

class aspecd.plotting.SinglePlotter2D

Bases: aspecd.plotting.SinglePlotter

2D plots of single datasets.

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

Quite a number of properties for figure, axes, and 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

show_contour_linesbool

Whether to show contour lines in case of contourf plot

show_colorbarbool

Whether to show a colorbar

New 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

applicableTrue 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

Short hand for 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

Short hand for 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
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

class aspecd.plotting.SinglePlotter2DStacked

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

list of matplotlib.artist.Artist objects, 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.SinglePlot1DProperties class.

Type

aspecd.plotting.SinglePlot1DProperties

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

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

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

applicableTrue 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

Short hand for 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

Short hand for 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
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

class aspecd.plotting.MultiDeviceDataPlotter1D

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

New 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

applicableTrue 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

Short hand for 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

Short hand for 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
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

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

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

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

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters

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

property fig

Short hand for 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

class aspecd.plotting.MultiPlotter1D

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

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

applicableTrue 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

Short hand for axes.

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters

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

property fig

Short hand for 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
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

class aspecd.plotting.MultiPlotter1DStacked

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

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

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters

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

property fig

Short hand for 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
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

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: aspecd.plotting.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]
axes

List of axes

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

Type

list

grid_dimensions

Dimensions of the grid used to layout the figure

two elements: number of rows, number of columns

Default: [1, 1]

Type

list

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

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.

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

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters

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

property fig

Short hand for 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.

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

class aspecd.plotting.SingleCompositePlotter

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

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

delete_annotation(index=None)

Remove annotation record from dataset.

Parameters

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

property fig

Short hand for 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

class aspecd.plotting.Saver(filename=None)

Bases: object

Base class for saving plots.

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

filename

Name of the file the plot should get saved to

Type

str

parameters

Key-value store of parameters for saving.

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

Type

dict

plotter

Plotter whose plot should be saved.

Type

aspecd.plotting.Plotter

Raises
save(plotter=None)

Save the plot to a file.

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

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

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

Parameters

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

Raises
class aspecd.plotting.Caption

Bases: aspecd.utils.Properties

Caption for figures.

title

usually one sentence describing the intent of the figure

Often plotted bold-face in a figure caption.

Type

str

text

additional text directly following the title

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

Type

str

parameters

names of parameters that should be included in the figure caption

Usually, these parameters get included at the very end of a figure 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

class aspecd.plotting.PlotProperties

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

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.

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

class aspecd.plotting.SinglePlotProperties

Bases: aspecd.plotting.PlotProperties

Properties of a single plot, defining its appearance.

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

class aspecd.plotting.SinglePlot1DProperties

Bases: aspecd.plotting.SinglePlotProperties

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

drawing

Properties of the line within a plot

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

class aspecd.plotting.SinglePlot2DProperties

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

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

New 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

class aspecd.plotting.MultiPlotProperties

Bases: aspecd.plotting.PlotProperties

Properties of a multiplot, defining its appearance.

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 drawing is handled in a special way: First of all, aspecd.plotting.MultiPlotProperties.drawing 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

class aspecd.plotting.MultiPlot1DProperties

Bases: aspecd.plotting.MultiPlotProperties

Properties of a 1D multiplot, defining its appearance.

drawingslist

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.

colormapstr

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.

Raises

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

Changed in version 0.8: Added attribute colormap

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.

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 is handled in a special way: First of all, aspecd.plotting.MultiPlotProperties.drawing 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.

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

class aspecd.plotting.CompositePlotProperties

Bases: aspecd.plotting.PlotProperties

Properties of a composite plot, defining its appearance.

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 aspecd.plotting.AxesProperties class.

Type

aspecd.plotting.AxesProperties

Raises

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

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

class aspecd.plotting.FigureProperties

Bases: aspecd.utils.Properties

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

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

size

Figure dimension (width, height) in inches.

2-tuple of floats

Default: 6, 4

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

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

class aspecd.plotting.AxesProperties

Bases: aspecd.utils.Properties

Properties of an axis of a plot.

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

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

Default: ‘’

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

Type

float

ylabel

label for the y-axis

Default: ‘’

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

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']

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.

Type

list or str

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

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

class aspecd.plotting.LegendProperties

Bases: aspecd.utils.Properties

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

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

loc

Location of the legend

For possible values, see matplotlib.legend.Legend

Type

str

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

class aspecd.plotting.DrawingProperties

Bases: aspecd.utils.Properties

Properties of a drawing within a plot.

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

label

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

Type

str

Raises

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

apply(drawing=None)

Apply properties to drawing.

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

Parameters

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

Raises

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

class aspecd.plotting.LineProperties

Bases: aspecd.plotting.DrawingProperties

Properties of a line within a plot.

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

color

color of the line

For details see matplotlib.colors

Type

color

drawstyle

drawing style of the line, default: ‘default’

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

Type

str

linestyle

style of the line, default: ‘solid’

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

Type

str

linewidth

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

Type

float

marker

marker used for the line, default: ‘’

For details see matplotlib.markers

Type

str

Raises

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

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 line will 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

class aspecd.plotting.SurfaceProperties

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

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

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

class aspecd.plotting.GridProperties

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

class aspecd.plotting.ColorbarProperties

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

New in version 0.9.

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

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.