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.

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

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.

Module API documentation

class aspecd.plotting.Plotter

Bases: object

Base class for plots.

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

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

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

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

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

style

plotting style to use

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

Type

str

Note

If you set the style via aspecd.plotting.Plotter.style, all following figures will use this style, until you set another style.

As it seems, there is no way in matplotlib to find out the current style, and hence reset to it. One way to fix this problem would be to revert to the default style by issuing the following command:

matplotlib.pyplot.style.use('default')
Raises

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

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

Check whether plot is applicable to the given dataset.

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

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

save(saver=None)

Save the plot to a file.

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

Parameters

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

Returns

saver – Saver used to save the plot

Return type

aspecd.plotting.Saver

Raises

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

class aspecd.plotting.SinglePlotter

Bases: aspecd.plotting.Plotter

Base class for plots of single datasets.

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

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

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

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

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

properties

Properties of the plot, defining its appearance

Type

aspecd.plotting.SinglePlotProperties

dataset

Dataset the plotting should be done for

Type

aspecd.dataset.Dataset

drawing

Actual graphical representation of the data

Type

matplotlib.artist.Artist

Raises
plot(dataset=None, from_dataset=False)

Perform the actual plotting on the given dataset.

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

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

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

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

  • from_dataset (boolean) –

    whether we are called from within a dataset

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

Returns

dataset – dataset plot has been performed for

Return type

aspecd.dataset.Dataset

Raises
create_history_record()

Create history record to be added to the dataset.

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

Returns

history_record – history record for plotting step

Return type

aspecd.history.PlotHistoryRecord

static applicable(dataset)

Check whether plot is applicable to the given dataset.

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

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

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.

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

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

Return the allowed plot types.

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

Check whether plot is applicable to the given dataset.

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

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

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.

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

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.SinglePlot2DProperties class.

Type

aspecd.plotting.SinglePlot2DProperties

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.

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

Check whether plot is applicable to the given dataset.

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

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

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.

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

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
static applicable(dataset)

Check whether plot is applicable to the given dataset.

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

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

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.

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

Raises
plot()

Perform the actual plotting on the given list of datasets.

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

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

Note

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

Raises
static applicable(dataset)

Check whether plot is applicable to the given dataset.

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

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

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.

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

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.

property allowed_types

Return the allowed plot types.

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

Check whether plot is applicable to the given dataset.

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

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.

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.

Returns

allowed_types – List of strings

Return type

list

static applicable(dataset)

Check whether plot is applicable to the given dataset.

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

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.

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.

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.

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.

static applicable(dataset)

Check whether plot is applicable to the given dataset.

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

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

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.

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

static applicable(dataset)

Check whether plot is applicable to the given dataset.

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

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

Returns

applicableTrue if successful, False otherwise.

Return type

bool

property ax

Short hand for axes.

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.

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Raises

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

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.

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Type

tuple

dpi

Figure resolution in dots per inch.

Default: 100

Type

float

title

Title for the figure as a whole

Type

str

Raises

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

apply(figure=None)

Apply properties to figure.

Parameters

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

Raises

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

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

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

Raises

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

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Raises

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

property location

Alias for aspecd.plotting.LegendProperties.loc

apply(legend=None)

Apply properties to legend.

Parameters

legend (matplotlib.legend.Legend) – 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()

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

class aspecd.plotting.GridProperties

Bases: aspecd.utils.Properties

Properties of a line within a plot.

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

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.

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

Create dictionary containing public attributes of an object.

Returns

public_attributes – Ordered dictionary containing the public attributes of the object

The order of attribute definition is preserved

Return type

collections.OrderedDict

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