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.
Overview
As there are a lot of different plotters available, each for different
purposes, Fig. 15 gives a
first overview of the different Plotter classes.
Fig. 15 First overview of the different Plotter classes available in
the plotting module. The three classes marked
as abstract (with the “A”, i.e. Plotter,
SinglePlotter, and MultiPlotter) are not true abstract
classes, but nevertheless base classes that shall not used directly for
plotting purposes.
For each Plotter class, there exists a dedicated
PlotProperties class, besides further properties classes for those
plot elements independent of a concrete plotter. For a first overview,
see Fig. 16.
Fig. 16 First overview of the different PlotProperties classes
available in the plotting module. For each
Plotter, there is a separate PlotProperties class.
Furthermore, there are additional classes for properties of elements of
plots, such as FigureProperties and DrawingProperties.
Note that SinglePlot2DStackedProperties inherits from
MultiPlot1DProperties. This is due to the very similar
behaviour of the two plotters, with respect to the resulting plots.
For more explanation and details on the individual classes and how to best make use of them, continue reading.
Types of abstract plotters
Abstract plotters are the base classes for all plotters actually used to graphically display data. If you are mire interested in actually plotting data rather than the overall concepts, have a look at the concrete plotters.
Generally, two types of plotters can be distinguished:
Plotters for handling single datasets
Shall be derived from
aspecd.plotting.SinglePlotter.Plotters for handling multiple datasets
Shall be derived from
aspecd.plotting.MultiPlotter.
In the first case, the plot is usually handled using the plot() method
of the respective aspecd.dataset.Dataset object. Additionally,
those plotters always only operate on the data of a single dataset, and the
plot can easily be attached as a representation to the respective dataset.
Plotters handling single datasets should always inherit from the
aspecd.plotting.SinglePlotter class.
In the second case, the plot is handled using the plot() method of the
aspecd.plotting.Plotter object, and the datasets are stored as a list
within the plotter. As these plots span several datasets, there is no easy
connection between a single dataset and such a plot in sense of
representations stored in datasets. Plotters handling multiple datasets should
always inherit from the aspecd.plotting.MultiPlotter class.
In a certain sense, there is a third type of plotters:
Plotters consisting of more than one axes
Shall be derived from
aspecd.plotting.CompositePlotter.
However, practically mostly these composite plotters will behave like plotters handling either single or multiple datasets. Generally, these composite plotters will use other types of plotters to perform the actual plot tasks. This modular approach allows for great flexibility.
Regardless of the type of plotter, saving plots is always done using
objects of the aspecd.plotting.Saver class. The actual task of
saving a plot is as easy as calling the save() method of a plotter
with a saver object as its argument.
A note on array dimensions and axes
Something often quite confusing is the apparent inconsistency between the order of array dimensions and the order of axes. While we are used to assigning axes in the order x, y, z, and assuming x to be horizontal, y vertical (and z sticking out of the paper plane), arrays are usually (at least in the C world as compared to the FORTRAN world) indexed row-first, column-second. That means, however, that if you simply plot a 2D array in axes, your first dimension is along the y axis, the second dimension along the x axis.
Therefore, as the axes of your datasets will always correspond to the array dimensions of your data, in case of 2D plots you will need to either use the information contained in the second axis object for your x axis label, and the information from the first axis object for your y axis label, or to transpose the data array.
Another aspect to have in mind is the position of the origin. Usually, in a Cartesian coordinate system, convention is to have the origin (0, 0) in the lower left of the axes (for the positive quadrant). However, for images, convention is to have the corresponding (0, 0) pixel located in the upper left edge of your image. Therefore, those plotting methods dealing with images will usually revert the direction of your y axis. Most probably, eventually you will have to check with real data and ensure the plotters to plot data and axes in a consistent fashion.
Types of concrete plotters
The ASpecD framework comes with a series of concrete plotters included ready to be used. As stated above, plotters can generally be divided into two types: plotters operating on single datasets and plotters combining the data of multiple datasets into a single figure.
Additionally, plotters can be categorised with regard to creating figures
consisting of a single or multiple axes. The latter are plotters inheriting
from the aspecd.plotting.CompositePlotter class. The latter can be
thought of as templates for the other plotters to operate on, i.e. they
provide the axes for other plotters to display their results.
Concrete plotters for single datasets
aspecd.plotting.SinglePlotter1DBasic line plots for single datasets, allowing to plot a series of line-type plots, including (semi)log plots
aspecd.plotting.SinglePlotter2DBasic 2D plots for single datasets, allowing to plot a series of 2D plots, including contour plots and image-type display
aspecd.plotting.SinglePlotter2DStackedStacked plots of 2D data, converting a 2D display into a series of 1D line plots stacked on top of each other.
aspecd.plotting.SingleCompositePlotterComposite plotter for single datasets, allowing to plot different views of one and the same datasets by using existing plotters for single datasets.
aspecd.plotting.MultiDeviceDataPlotter1DBasic line plots for multiple device data of a single dataset, allowing to plot a series of line-type plots, including (semi)log plots
Concrete plotters for multiple datasets
aspecd.plotting.MultiPlotter1DBasic line plots for multiple datasets, allowing to plot a series of line-type plots, including (semi)log plots
aspecd.plotting.MultiPlotter1DStackedStacked line plots for multiple datasets, allowing to plot a series of line-type plots, including (semi)log plots
Properties of plot(ter)s
Plots can be controlled extensively regarding their appearance. While Matplotlib provides both, sensible defaults and an extensive list of customisation options for the plot appearance, the ASpecD framework tries to homogenise these settings and currently provides only a subset of the possibilities the underlying Matplotlib library would allow.
The properties of plots and their individual components are reflected in a
hierarchy of objects. Each plotter has a corresponding properties
attribute that contains an object of the respective
aspecd.plotting.PlotProperties class.
To give you an idea of the hierarchy of classes handling the plot properties, below is a (hopefully complete) list:
Each of the plot properties classes, i.e. all subclasses of
aspecd.plotting.PlotProperties, contain other properties classes as
attributes.
Getting and setting plot properties is somewhat complicated by the fact that Matplotlib usually allows setting properties only when instantiating objects, or sometimes with explicit setter methods. Similarly, there may or may not be getter methods for the relevant attributes.
In any case, while you can set and get properties of plots programmatically within the ASpecD framework, using recipe-driven data analysis is highly recommended.
General tips and tricks
Plotting can become horribly complicated, simply due to the complexity of
the matter involved and the parameters one can (and often want to) control.
For the convenience of the user, a few more general cases are discussed
below and example recipes provided for each case. For details on
recipe-driven data analysis, see either the introduction
or the documentation of the aspecd.tasks module.
Overall figure properties
On the figure level, i.e. the level of the overall graphical representation, only a few properties can be set, namely size (in inches), resolution (in dots per inch), and title:
- kind: singleplot
type: SinglePlotter1D
properties:
properties:
figure:
size: [8, 5]
resolution: 600
title: My fancy figure
filename: output.pdf
Important
If you have a second axis on top of the axes, setting the figure title will result in the figure title clashing with the upper axis. Hence, in such case, try setting the axis title.
Overall axes properties
Axes properties can be set for SinglePlotter and
MultiPlotter, but for obvious reasons not for
CompositePlotter. In case of the latter, the properties of the axes
are set for the individual plotters that are used to plot in the different
axes.
Below is a demonstration of just a subset of the properties that can be set.
For further details, see the AxesProperties class. Note in
particular that all the settings shown here for the x axis can be applied to
the y axis analogously.
- kind: singleplot
type: SinglePlotter1D
properties:
properties:
axes:
title: My fancy plot
aspect: equal
facecolor: darkgreen
xlabel: $foo$ / bar
xlim: [-5, 5]
xticklabelangle: 45
invert: x
filename: output.pdf
Important
If you have a second axis on top of the axes, setting the figure title will result in the figure title clashing with the upper axis. Hence, in such case, try setting the axis title.
Removing axes labels
Generally, axes labels are set according to the settings in the dataset
plotted. However, sometimes you would like to remove a label entirely. To
do so, set the label to None. The equivalent in YAML, hence in
recipes, is null. Hence, removing the y axis label in a plot
translates to:
- kind: singleplot
type: SinglePlotter1D
properties:
properties:
axes:
ylabel: null
Of course, you can do the same with the x axis label and with all kinds of plotters.
New in version 0.9.3.
Type of plot for 1D plotters
When plotting one-dimensional (1D) data, there is of course more than the
usual line plot. For the actual types of plots that you can use, see the
SinglePlotter1D.allowed_types and MultiPlotter1D.allowed_types
attributes.
To make a semilogy plot (i.e., with logarithmic y axis), invoke the plotter as follows:
- kind: singleplot
type: SinglePlotter1D
properties:
type: semilogy
filename: output.pdf
And analogous for the MultiPlot1D plotter:
- kind: multiplot
type: MultiPlotter1D
properties:
type: semilogy
filename: output.pdf
Important
As the logarithm of negative values is not defined, usually having a
logarithmic axis with negative values will lead to unexpected
results. Matplotlib defaults to clipping the invalid values. To help
you with debugging the unexpected results, a warning will be logged
(and printed to the terminal when serving a recipe) in case a
logarithmic axis is affected by negative values. In such case,
the easiest is to add an offset to your data, using
aspecd.processing.ScalarAlgebra.
Appearance of individual drawings
The individual drawings within the axes of a plot can be controlled in quite
some detail. Depending on the overall type, be it a line or a surface,
there are different classes responsible for setting the properties:
LineProperties and SurfaceProperties. The general class is
DrawingProperties.
Below is a (real-world) example of a multiplotter containing two lines, and in this particular case with standard settings.
- kind: multiplot
type: MultiPlotter1D
properties:
properties:
drawings:
- label: Substance 1
color: '#1f77b4'
drawstyle: default
linestyle: '-'
linewidth: 1.5
marker: None
- label: Substance 2
color: '#ff7f0e'
drawstyle: default
linestyle: '-'
linewidth: 1.5
marker: None
Controlling the appearance of zero lines
While a grid is not shown by default, zero lines are, as long as the zero
value is present in either or both axes ranges. While it is a sensible
default to display zero lines, and switching them off is a matter of
setting the parameter show_zero_lines to False, controlling the
appearance of these lines is often useful. Below is a (real-world) example
of the available settings for the zero lines (with default values).
- kind: multiplot
type: MultiPlotter1D
properties:
parameters:
show_zero_lines: true
properties:
zero_lines:
label: ''
color: '#cccccc'
drawstyle: default
linestyle: solid
linewidth: 1.0
marker: ''
While it rarely makes sense to set line markers for these lines, the line
properties are simply all properties that can be set using the
LineProperties class. Besides controlling the appearance of zero
lines, you can display a grid and control the appearance of these lines.
See below for more details.
Adding a grid
Particularly when comparing plots or when you want to extract values from a
plot, a grid can come in quite handy. As a grid is already quite complicated
– for which axis (x, y, or both) to set the grid, for which ticks (minor,
major, or both) – and as you may even want to control the appearance of the
grid lines, all these properties are handled by the GridProperties
class. You can add a grid to both, SinglePlotter and
MultiPlotter instances.
- kind: singleplot
type: SinglePlotter1D
properties:
properties:
grid:
show: True
ticks: major
axis: both
If you now even want to control the appearance of the grid lines (you can not, however, control individual grid lines, only all grid lines at once), things get even more complex:
- kind: singleplot
type: SinglePlotter1D
properties:
properties:
grid:
show: True
ticks: major
axis: both
lines:
color: #123456
linestyle: dashed
linewidth: 3
marker: triangle_up
Note that the values for the lines are not necessarily sensible for grid
lines. For a full list of possible properties, see the
LineProperties class. The same as shown here for a
SinglePlotter can be done for a MultiPlotter accordingly.
Adding a legend
As soon as there is more than one line in a plot, adding a legend comes in quite handy. Again, a legend can be controlled in quite some detail. An example showing some of the properties that can be set is given below:
- kind: 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 notself.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:
ToDictMixinBase 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 byplot().Note
Usually, you will never implement an instance of this class for actual plotting tasks, but rather one of the child classes.
- parameters
All parameters necessary for the plot, implicit and explicit
The following keys exist:
- show_legend
bool Whether to show a legend in the plot
Default: False
- show_zero_lines
bool 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.propertiesattribute.Default: True
- tight_layout
bool 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_data
strorlist 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, seeaspecd.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:
- show_legend
- properties
Properties of the plot, defining its appearance
- figure
Reference to figure object
- Type:
- axes
Reference to axes object used for actual plotting
- Type:
- filename
Name of file to save the plot to
Actual saving is done using an
aspecd.plotting.Saverobject.- Type:
- caption
User-supplied information for the figure.
- Type:
- legend
Legend object
- Type:
- style
plotting style to use
You can use all plotting styles understood by matplotlib. See
matplotlib.stylefor 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:
- annotations
List of annotations added to the plotter.
Each annotation is an object of class
aspecd.annotation.PlotAnnotation.- Type:
- Raises:
aspecd.exceptions.MissingSaverError – Raised when no saver is provided when trying to save
Changed in version 0.6: New attribute
labelChanged in version 0.6.2: New parameter
tight_layoutChanged in version 0.6.4: New attribute
commentChanged in version 0.9: New parameter ‘’device_data’’
- plot()
Perform the actual plotting.
The actual plotting should be implemented within the private method
_create_plot().
- static applicable(data)
Check whether plot is applicable to the dataset.
Returns True by default and needs to be implemented in classes inheriting from Plotter according to their needs.
A typical example would be a 2D plot applied to a 1D dataset that will most probably not be possible/sensible.
- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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:
- 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.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlotter
Bases:
PlotterBase class for plots of single datasets.
Each class actually plotting data of a dataset should inherit from this class. Furthermore, all parameters, implicit and explicit, necessary to perform the plot, should eventually be stored in the property
parameters(currently a dictionary).There are two concrete classes available for conveniently performing plots of single datasets:
aspecd.plotting.SinglePlotter1D1D plots, such as line, scatter, log, semilog
aspecd.plotting.SinglePlotter2D2D plots, such as contour, image
To perform the plot, call the
plot()method of the dataset the plot should be performed for, and provide a reference to the actual plotter object to it.Further things that need to be changed upon inheriting from this class are the string stored in
description, being basically a one-liner.The actual implementation of the plotting is done in the private method
_create_plot()that in turn gets called byplot()which is called by theaspecd.dataset.Dataset.plot()method of the dataset object.- properties
Properties of the plot, defining its appearance
- dataset
Dataset the plotting should be done for
- Type:
- 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_dataofPlotter.parametersfor details.- Type:
- drawing
Actual graphical representation of the data
- Type:
- Raises:
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
aspecd.exceptions.NotApplicableToDatasetError – Raised when processing step is not applicable to dataset
Changed in version 0.9: New attribute ‘’data’’
- plot(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 methodapplicable().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 forfrom_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:
- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
- create_history_record()
Create history record to be added to the dataset.
Usually, this method gets called from within the
aspecd.dataset.Dataset.plot()method of theaspecd.dataset.Datasetclass and ensures the history of each plotting step to get written properly.- Returns:
history_record – history record for plotting step
- Return type:
- 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:
- static applicable(data)
Check whether plot is applicable to the dataset.
Returns True by default and needs to be implemented in classes inheriting from Plotter according to their needs.
A typical example would be a 2D plot applied to a 1D dataset that will most probably not be possible/sensible.
- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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
Shorthand for
figure.
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlotter1D
Bases:
SinglePlotter1D 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.typeattribute. Allowed types are stored in theaspecd.plotting.SinglePlotter1D.allowed_typesattribute.Quite a number of properties for figure, axes, and line can be set using the
aspecd.plotting.SinglePlotter1D.propertiesattribute. 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.SinglePlot1DPropertiesclass.
- 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_axes
bool 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:
- tight:
- 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_typesattribute 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_axesparameter 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
timestampin the dataset:- kind: singleplot type: SinglePlotter1D properties: parameters: device_data: timestamp filename: output.pdf
Changed in version 0.7: New parameter
switch_axesChanged 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:
- property type
Get or set the plot type.
Types need to be methods of the
matplotlib.axes.Axesclass.Allowed plot types are stored in the
aspecd.plotting.SinglePlotter1D.allowed_typesattribute.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.dataattribute. Returns True if data are one-dimensional, and False otherwise.- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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:
- 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 theaspecd.dataset.Datasetclass and ensures the history of each plotting step to get written properly.- Returns:
history_record – history record for plotting step
- Return type:
- delete_annotation(index=None)
Remove annotation record from dataset.
- Parameters:
index (int) – Number of analysis in analyses to delete
- property fig
Shorthand 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 methodapplicable().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 forfrom_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:
- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlotter2D
Bases:
SinglePlotter2D 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.typeattribute. Allowed types are stored in theaspecd.plotting.SinglePlotter2D.allowed_typesattribute.Quite a number of properties for figure, axes, and surface can be set using the
aspecd.plotting.SinglePlotter2D.propertiesattribute. 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_axesparameter 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_axes
bool 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
- levels
int Number of levels of a contour plot
If None, the number of levels will be determined automatically.
Default: None
- show_contour_lines
bool Whether to show contour lines in case of contourf plot
- show_colorbar
bool Whether to show a colorbar
New in version 0.9.
- Type:
- switch_axes
- properties
aspecd.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.SinglePlot2DPropertiesclass.
- 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:
- property type
Get or set the plot type.
Types need to be methods of the
matplotlib.axes.Axesclass.Allowed plot types are stored in the
aspecd.plotting.SinglePlotter2D.allowed_typesattribute.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.dataattribute. Returns True if data are two-dimensional, and False otherwise.- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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:
- 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 theaspecd.dataset.Datasetclass and ensures the history of each plotting step to get written properly.- Returns:
history_record – history record for plotting step
- Return type:
- delete_annotation(index=None)
Remove annotation record from dataset.
- Parameters:
index (int) – Number of analysis in analyses to delete
- property fig
Shorthand 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 methodapplicable().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 forfrom_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:
- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlotter2DStacked
Bases:
SinglePlotterStacked 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:
- drawing
Actual graphical representation of the data.
List of
matplotlib.artist.Artistobjects, one for each of the actual lines of the plot- Type:
- parameters
All parameters necessary for the plot, implicit and explicit
The following keys exist, in addition to the keys inherited from the superclass:
- show_legend
bool Whether to show a legend in the plot
Default: False
- show_zero_lines
bool 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.propertiesattribute.Default: False
- stacking_dimension
int dimension of data along which to stack the plot
Default: 1
- offset
float 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
- yticklabelformat
string 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
- ytickcount
int 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:
- show_legend
- properties
Properties of the plot, defining its appearance
For the properties that can be set this way, see the documentation of the
aspecd.plotting.SinglePlot2DStackedPropertiesclass.
Examples
For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see
aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.In the simplest case, just invoke the plotter with default values:
- kind: singleplot type: SinglePlotter2DStacked properties: filename: output.pdf
If you need to more precisely control the formatting of the y tick labels, particularly the number of decimals shown, you can set the formatting accordingly:
- kind: singleplot type: SinglePlotter2DStacked properties: filename: output.pdf parameters: yticklabelformat: '%.2f'
In this particular case, the y tick labels will appear with only two decimals. Note that currently, the “old style” formatting specifications are used due to their widespread use in other programming languages and hence the familiarity of many users with this particular notation.
Sometimes you want to have horizontal “zero lines” appear for each individual trace of the stacked plot. This can be achieved explicitly setting the “show_zero_lines” parameter to “True” that is set to “False” by default:
- kind: singleplot type: SinglePlotter2DStacked properties: filename: output.pdf parameters: show_zero_lines: True
As always, you can set the appearance of the plot in quite some detail. If you would like to style the individual lines, i.e.
drawings, provide a list of properties for each individual drawing and make sure to provide as many items in the list as there are lines in the plot:- kind: singleplot type: SinglePlotter2DStacked properties: properties: drawings: - color: '#FF0000' label: foo - color: '#00FF00' label: bar - color: '#0000FF' label: foobar
Important
If you set colours using the hexadecimal RGB triple prefixed by
#, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.Suppose you want to set identical properties for all lines. This is possible as well, by not providing the
drawingskey (plural) but thedrawingkey (singular) - and of course, this time not a list:- kind: singleplot type: SinglePlotter2DStacked properties: properties: drawing: color: '#FF0000'
Changed in version 0.6: ylabel is set to third axis if offset = 0; new parameter “tight”
Changed in version 0.6.2: New parameter
ytickcountChanged in version 0.10: Properties changed to
SinglePlot2DStackedProperties- property drawings
Actual graphical representation of the data.
List of
matplotlib.artist.Artistobjects, one for each of the actual lines of the plotThis is identical to
drawingand has been added to work conveniently withSinglePlot2DStackedProperties.- Returns:
drawings – Actual graphical representation of the data.
- Return type:
New in version 0.10.
- static applicable(data)
Check whether plot is applicable to the dataset.
Checks for the dimension of the data of the dataset, i.e. the
aspecd.dataset.Data.dataattribute. Returns True if data are two-dimensional, and False otherwise.- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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:
- 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 theaspecd.dataset.Datasetclass and ensures the history of each plotting step to get written properly.- Returns:
history_record – history record for plotting step
- Return type:
- delete_annotation(index=None)
Remove annotation record from dataset.
- Parameters:
index (int) – Number of analysis in analyses to delete
- property fig
Shorthand 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 methodapplicable().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 forfrom_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:
- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.MultiDeviceDataPlotter1D
Bases:
SinglePlotter1D1D 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.typeattribute. Allowed types are stored in theSinglePlotter1D.allowed_typesattribute.Quite a number of properties for figure, axes, and line can be set using the
MultiDeviceDataPlotter1D.propertiesattribute. 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:
- data
Actual data that should be plotted.
List of
aspecd.dataset.DeviceDataobjects corresponding to the device data selected using the parameterdevice_data.- Type:
- drawing
List of
matplotlib.artist.Artistobjects, one for each of the actual lines of the plot- Type:
- properties
Properties of the plot, defining its appearance
For the properties that can be set this way, see the documentation of the
aspecd.plotting.MultiPlot1DPropertiesclass.
- parameters
All parameters necessary for the plot, implicit and explicit
The following keys exist, in addition to those of the superclass:
- axes
list List of objects of class
aspecd.dataset.AxisThere 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_axes
bool 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:
- axes
- 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.labelset, 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 theMultiPlot1DProperties.drawingattribute, 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
MultiPlot1DPropertiesasproperties, 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.dataattribute. Returns True if data are one-dimensional, and False otherwise.- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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:
- 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:
- 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 theaspecd.dataset.Datasetclass and ensures the history of each plotting step to get written properly.- Returns:
history_record – history record for plotting step
- Return type:
- delete_annotation(index=None)
Remove annotation record from dataset.
- Parameters:
index (int) – Number of analysis in analyses to delete
- property fig
Shorthand 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 methodapplicable().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 forfrom_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:
- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- property type
Get or set the plot type.
Types need to be methods of the
matplotlib.axes.Axesclass.Allowed plot types are stored in the
aspecd.plotting.SinglePlotter1D.allowed_typesattribute.Default: ‘plot’
- Raises:
TypeError – Raised in case of wrong type
- class aspecd.plotting.MultiPlotter
Bases:
PlotterBase 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 byplot()that needs to be called directly (not from a dataset).- properties
Properties of the plot, defining its appearance
- 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_dataofPlotter.parametersfor details.- Type:
- parameters
All parameters necessary for the plot, implicit and explicit
The following keys exist, in addition to the keys inherited from the superclass:
- axes
list List of objects of class
aspecd.dataset.AxisThere 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:
- axes
- Raises:
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
aspecd.exceptions.NotApplicableToDatasetError – Raised when processing step is not applicable to dataset
Changed in version 0.9: New attribute ‘’data’’
- plot()
Perform the actual plotting on the given list of datasets.
If no dataset is added to the list of datasets of the object, the method will raise a respective exception.
The actual plotting should be implemented within the non-public method
_create_plot(). Besides that, the applicability of the plotting to the given list of datasets will be checked automatically. These checks should be implemented in the methodapplicable().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.parametersproperty containing a list ofaspecd.dataset.Axisobjects. Alternatively, if no such information is provided, the axes of each dataset are checked for consistency, and if they are found to be identical, this information is used.- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to at least one of the datasets listed in
datasetsaspecd.exceptions.MissingDatasetError – Raised when no datasets exist to act on
- annotate(annotation=None)
Add annotation to dataset.
- Parameters:
annotation (
aspecd.annotation.PlotAnnotation) – Annotation to add to the plotter- Returns:
annotation – Annotation added to the plot(ter)
- Return type:
- static applicable(data)
Check whether plot is applicable to the dataset.
Returns True by default and needs to be implemented in classes inheriting from Plotter according to their needs.
A typical example would be a 2D plot applied to a 1D dataset that will most probably not be possible/sensible.
- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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
Shorthand for
figure.
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.MultiPlotter1D
Bases:
MultiPlotter1D 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.typeattribute. Allowed types are stored in theaspecd.plotting.MultiPlotter1D.allowed_typesattribute.Quite a number of properties for figure, axes, and line can be set using the
aspecd.plotting.MultiPlotter1D.propertiesattribute. For details, see the documentation of its respective class,aspecd.plotting.MultiPlot1DProperties.To perform the plot, call the
plot()method of the plotter directly.- properties
Properties of the plot, defining its appearance
For the properties that can be set this way, see the documentation of the
aspecd.plotting.MultiPlotPropertiesclass.
- parameters
All parameters necessary for this step.
Additionally, to those from
aspecd.plotting.MultiPlotter, the following parameters are allowed:- switch_axes
bool 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:
- switch_axes
Examples
For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see
aspecd.tasks) is given below for how to make use of this class. Of course, all parameters settable for the superclasses can be set as well. The examples focus each on a single aspect.In the simplest case, just invoke the plotter with default values:
- kind: multiplot type: MultiPlotter1D properties: filename: output.pdf
To change the settings of each individual line (here the colour and label), supposing you have three lines, you need to specify the properties in a list for each of the drawings:
- kind: multiplot type: MultiPlotter1D properties: filename: output.pdf properties: drawings: - color: '#FF0000' label: foo - color: '#00FF00' label: bar - color: '#0000FF' label: foobar
Important
If you set colours using the hexadecimal RGB triple prefixed by
#, you need to explicitly tell YAML that these are strings, surrounding the values by quotation marks.Suppose you want to set identical properties for all lines. This is possible as well, by not providing the
drawingskey (plural) but thedrawingkey (singular) - and of course, this time not a list:- kind: multiplot type: MultiPlotter1D properties: properties: drawing: color: '#FF0000'
Of course, line plots are not the only plot type available. Check the
MultiPlotter1D.allowed_typesattribute 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_axesparameter accordingly:- kind: multiplot type: MultiPlotter1D properties: parameters: switch_axes: true filename: output.pdf
Changed in version 0.7: New parameters
switch_axesandtightChanged 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:
- property type
Get or set the plot type.
Types need to be methods of the
matplotlib.axes.Axesclass.Allowed plot types are stored in the
aspecd.plotting.SinglePlotter1D.allowed_typesattribute.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.dataattribute. Returns True if data are one-dimensional, and False otherwise.- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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:
- 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
Shorthand 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 methodapplicable().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.parametersproperty containing a list ofaspecd.dataset.Axisobjects. Alternatively, if no such information is provided, the axes of each dataset are checked for consistency, and if they are found to be identical, this information is used.- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to at least one of the datasets listed in
datasetsaspecd.exceptions.MissingDatasetError – Raised when no datasets exist to act on
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.MultiPlotter1DStacked
Bases:
MultiPlotter1DStacked 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.typeattribute. Allowed types are stored in theaspecd.plotting.MultiPlotter1D.allowed_typesattribute.Quite a number of properties for figure, axes, and line can be set using the
aspecd.plotting.MultiPlotter1D.propertiesattribute. 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.
- offset
float The offset used for stacking the individual lines of the plot.
If not provided, automatically a best fit will be calculated.
Default: None
- show_zero_lines
bool 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.propertiesattribute.Default: False
- Type:
- offset
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:
- 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:
- 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.dataattribute. Returns True if data are one-dimensional, and False otherwise.- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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
Shorthand 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 methodapplicable().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.parametersproperty containing a list ofaspecd.dataset.Axisobjects. Alternatively, if no such information is provided, the axes of each dataset are checked for consistency, and if they are found to be identical, this information is used.- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to at least one of the datasets listed in
datasetsaspecd.exceptions.MissingDatasetError – Raised when no datasets exist to act on
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- property type
Get or set the plot type.
Types need to be methods of the
matplotlib.axes.Axesclass.Allowed plot types are stored in the
aspecd.plotting.SinglePlotter1D.allowed_typesattribute.Default: ‘plot’
- Raises:
TypeError – Raised in case of wrong type
- class aspecd.plotting.CompositePlotter
Bases:
PlotterBase 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_dimensionsandsubplot_locationsbelow.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 theplot()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
SingleCompositePlotterclass. This class pretty much behaves like an ordinary SinglePlotter, where you can (and should) use theaspecd.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 theplot()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-dataandprocessed-dataare previously defined figures using different datasets. Therefore, it is important to give results of a processing task a unique identifier if it is used in such a composite plotter.- kind: compositeplot type: CompositePlotter properties: plotter: - raw-data - processed-data filename: comparison.pdf grid_dimensions: [1, 2] subplot_locations: - [0, 0, 1, 1] - [0, 1, 1, 1]
Suppose you have a more complex plot with three axes, and you want to share the x axes only for those axes in the same column(s).
- kind: compositeplot type: CompositePlotter properties: properties: grid_spec: hspace: 0 plotter: - plotter1 - plotter2 - plotter3 filename: comparison.pdf grid_dimensions: [2, 2] subplot_locations: - [0, 0, 1, 1] - [1, 0, 1, 1] - [0, 1, 2, 1] sharex: True
In this case, only the two axes in the left column will share their x axes, and as you have defined the top axes first, the axes below will share their x axis with the top axes. Further note that
hspace, i.e. the vertical space between the axes, has been set to zero (the property starts with a “h” for height).You could do the same for three axes where you would like to have the y axes of those plots in the same row shared:
- kind: compositeplot type: CompositePlotter properties: properties: grid_spec: wspace: 0 plotter: - plotter1 - plotter2 - plotter3 filename: comparison.pdf grid_dimensions: [2, 2] subplot_locations: - [0, 0, 1, 1] - [1, 1, 1, 1] - [1, 0, 1, 2] sharey: True
In this case, only the two axes in the top row will share their y axes, and as you have defined the left axes first, the axes to the right will share their y axis with the left axes. Further note that
wspace, i.e. the horizontal space between the axes, has been set to zero (the property starts with a “w” for width).- axes
List of axes
Will eventually be objects of subtypes of
matplotlib.axes.Axesand populated upon callingaspecd.plotting.Plotter.plot().- Type:
- grid_dimensions
Dimensions of the grid used to layout the figure
two elements: number of rows, number of columns
Default: [1, 1]
- Type:
- grid_spec
Grid layout used to place the subplots within the figure.
The properties of the grid layout can be controlled using the
CompositePlotProperties.grid_specattribute that is part ofpropertiesattribute.
- 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:
- 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:
- 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 itsaspecd.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:
Whether to share the x axes of all subplots.
If set to
Trueorall, all x axes are shared, starting with the first defined axes.If set to one of
["col", "columns", "column-wise"], the x axes in each column are shared, starting with the first defined axes in each column.In both cases, only the outer x axes will be shown.
Typically, you will want to set the
hspaceproperty inCompositePlotProperties.grid_specto a small value.New in version 0.10.
Whether to share the y axes of all subplots.
If set to
Trueorall, all y axes are shared, starting with the first defined axes.If set to one of
["row", "rows", "row-wise"], the y axes in each row are shared, starting with the first defined axes in each row.In both cases, only the outer y axes will be shown.
Typically, you will want to set the
wspaceproperty inCompositePlotProperties.grid_specto a small value.New in version 0.10.
- 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.CompositePlotPropertiesclass.
- 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.
- to_dict(remove_empty=False)
Create dictionary containing public attributes of an object.
For some reason,
matplotlib.gridspec.GridSpecleads to an infinite recursion, hence the attribute is emptied before creating the dict, and afterwards readded.- Parameters:
remove_empty (
bool) –Whether to remove keys with empty values
Default: False
- Returns:
public_attributes – Ordered dictionary containing the public attributes of the object
The order of attribute definition is preserved
- Return type:
- 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:
- static applicable(data)
Check whether plot is applicable to the dataset.
Returns True by default and needs to be implemented in classes inheriting from Plotter according to their needs.
A typical example would be a 2D plot applied to a 1D dataset that will most probably not be possible/sensible.
- Returns:
applicable – True if successful, False otherwise.
- Return type:
- delete_annotation(index=None)
Remove annotation record from dataset.
- Parameters:
index (int) – Number of analysis in analyses to delete
- property fig
Shorthand 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.Saverthat 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:
CompositePlotterComposite 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’saspecd.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. Callingplot()by means ofaspecd.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:
- Raises:
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
aspecd.exceptions.NotApplicableToDatasetError – Raised when processing step is not applicable to dataset
- plot(dataset=None, from_dataset=False)
Perform the actual plotting on the given dataset.
If no dataset is set as property in the object, the method will raise a respective exception. The dataset object
plot()method always assigns its dataset as the respective dataset attribute of the plotter class.The actual plotting should be implemented within the non-public method
_create_plot(). Besides that, the applicability of the plotting to the given dataset will be checked automatically. These checks should be implemented in the methodapplicable().- Parameters:
dataset (
aspecd.dataset.Dataset) – dataset to perform plot forfrom_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:
- Raises:
aspecd.exceptions.NotApplicableToDatasetError – Raised when plotting is not applicable to dataset
aspecd.exceptions.MissingDatasetError – Raised when no dataset exists to act on
- create_history_record()
Create history record to be added to the dataset.
Usually, this method gets called from within the
aspecd.dataset.plot()method of theaspecd.dataset.Datasetclass and ensures the history of each plotting step to get written properly.- Returns:
history_record – history record for plotting step
- Return type:
- 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:
- static applicable(data)
Check whether plot is applicable to the dataset.
Returns True by default and needs to be implemented in classes inheriting from Plotter according to their needs.
A typical example would be a 2D plot applied to a 1D dataset that will most probably not be possible/sensible.
- Returns:
applicable – True if successful, False otherwise.
- Return type:
- 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
Shorthand for
figure.
- save(saver=None)
Save the plot to a file.
The actual saving is postponed to an object of class
aspecd.plotting.Saverthat is submitted as parameter.- Parameters:
saver (aspecd.plotting.Saver) – Saver handling the actual saving of the plot
- Returns:
saver – Saver used to save the plot
- Return type:
aspecd.plotting.Saver
- Raises:
aspecd.exceptions.MissingSaverError – Raised if no Saver is provided as parameter.
- to_dict(remove_empty=False)
Create dictionary containing public attributes of an object.
For some reason,
matplotlib.gridspec.GridSpecleads to an infinite recursion, hence the attribute is emptied before creating the dict, and afterwards readded.- Parameters:
remove_empty (
bool) –Whether to remove keys with empty values
Default: False
- Returns:
public_attributes – Ordered dictionary containing the public attributes of the object
The order of attribute definition is preserved
- Return type:
- class aspecd.plotting.Saver(filename=None)
Bases:
objectBase class for saving plots.
For basic saving of plots, no subclassing is necessary, as the
save()method usesmatplotlib.figure.Figure.savefig()and can cope with all possible parameters via theparametersproperty.- parameters
Key-value store of parameters for saving.
See
matplotlib.figure.Figure.savefig()for details and available options.- Type:
- plotter
Plotter whose plot should be saved.
- Type:
- Raises:
aspecd.exceptions.MissingFilenameError – Raised if no filename is provided for saver.
aspecd.exceptions.MissingPlotError – Raised if no plot is provided to act upon.
- save(plotter=None)
Save the plot to a file.
If no plotter is provided at method call, but is set as property in the Saver object, the
aspecd.plotting.Plotter.save()method of the plotter will be called.If no plotter is provided at method call nor as property of the object, the method will raise a respective exception.
The actual saving is implemented within the private method
_save_plot().- Parameters:
plotter (aspecd.plotting.Plotter) – plot to be saved
- Raises:
aspecd.exceptions.MissingFilenameError – Raised if no filename is provided for saver.
aspecd.exceptions.MissingPlotError – Raised if no plot is provided to act upon.
- class aspecd.plotting.Caption
Bases:
PropertiesCaption for figures.
- title
usually one sentence describing the intent of the figure
Often plotted bold-face in a figure caption.
- Type:
- 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:
- 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:
- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.PlotProperties
Bases:
PropertiesProperties 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.FigurePropertiesclass.
- legend
Properties of the legend.
For the properties that can be set this way, see the documentation of the
aspecd.plotting.LegendPropertiesclass.
- zero_lines
Properties of the zero lines.
For the properties that can be set this way, see the documentation of the
aspecd.plotting.LinePropertiesclass.Default values for the zero lines are:
color: #cccccc
- 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.PlotPropertiesneed 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlotProperties
Bases:
PlotPropertiesProperties 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.AxesPropertiesclass.
- grid
Properties of the grid.
For the properties that can be set this way, see the documentation of the
aspecd.plotting.GridPropertiesclass.
- drawing
Properties of the line within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.DrawingPropertiesclass.
- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlot1DProperties
Bases:
SinglePlotPropertiesProperties 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.LinePropertiesclass.
- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SinglePlot2DProperties
Bases:
SinglePlotPropertiesProperties 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.SurfacePropertiesclass.
- 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.ColorbarPropertiesclass.New in version 0.9.
- 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
cmapinaspecd.plotting.SurfacePropertieswill 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 propertycmapinaspecd.plotting.SurfaceProperties. However, setting a value will be propagated to the propertycmapinaspecd.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
_rto 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.MultiPlotProperties
Bases:
PlotPropertiesProperties 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.AxesPropertiesclass.
- grid
Properties of the grid.
For the properties that can be set this way, see the documentation of the
aspecd.plotting.GridPropertiesclass.
- drawings
Properties of the lines within a plot.
Each element is a
aspecd.plotting.DrawingPropertiesobjectFor the properties that can be set this way, see the documentation of the
aspecd.plotting.DrawingPropertiesclass.- Type:
- Raises:
aspecd.plotting.MissingPlotterError – Raised if no plotter is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
The key
drawingsis handled in a special way: First of all,aspecd.plotting.MultiPlotProperties.drawingsis 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.DrawingPropertiesobject 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.MultiPlotPropertiesfor theirpropertiesproperty. These properties classes should override this method to ensure the correct type ofaspecd.plotting.DrawingPropertiesis 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.MultiPlot1DProperties
Bases:
MultiPlotPropertiesProperties of a 1D multiplot, defining its appearance.
- drawings
list Properties of the lines within a plot.
Each element is a
aspecd.plotting.LinePropertiesobjectFor the properties that can be set this way, see the documentation of the
aspecd.plotting.LinePropertiesclass.- colormap
str 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
_rto 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- from_dict(dict_=None)
Set attributes from dictionary.
The key
drawing(singular!) is handled in a special way: If it exists in the dictionary, it gets used to set all drawings to this one set of properties.Otherwise, the behaviour is identical to that of the superclass method: see
MultiPLotProperties.from_dict()for details.- Parameters:
dict (
dict) – Dictionary containing information of a task.
New in version 0.10.
- add_drawing()
Add a
aspecd.plotting.LinePropertiesobject to the list.The default properties are set as well, as obtained from
matplotlib.pyplot.rcParams. These contain at least colour, width, marker, and style of a line.Note
If you provide a key “drawing” (singular!) in the dictionary with the properties, instead of setting default properties the properties of this dict will be set to all drawings. Thus, you can conveniently set identical settings for all lines.
Changed in version 0.10: Handling of the
drawingkey.
- apply(plotter=None)
Apply properties to plot.
The main difference to the parent class: if you set a colormap property, the lines will be coloured according to the colormap. Note that this needs to be done on this level, as we need to know how many drawings (i.e. lines) there are to colour.
- Parameters:
plotter (
aspecd.plotting.MultiPlotter) – Plotter the properties should be applied to.- Raises:
aspecd.exceptions.MissingPlotterError – Raised if no plotter is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- drawings
- class aspecd.plotting.SinglePlot2DStackedProperties
Bases:
MultiPlot1DPropertiesProperties of a 2D stacked singleplot, defining its appearance.
- drawings
list Properties of the lines within a plot.
Each element is a
aspecd.plotting.LinePropertiesobjectFor the properties that can be set this way, see the documentation of the
aspecd.plotting.LinePropertiesclass.- colormap
str 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
_rto the name of a colormap will reverse it.
- Raises:
aspecd.exceptions.MissingPlotterError – Raised if no plotter is provided.
New in version 0.10.
- property drawing
Properties of the lines within a plot.
Each element is a
aspecd.plotting.LinePropertiesobjectFor the properties that can be set this way, see the documentation of the
aspecd.plotting.LinePropertiesclass.This is identical to
drawingsand has been added to work conveniently withSinglePlotter2DStacked.- Returns:
drawing – Properties of the lines within a plot.
- Return type:
New in version 0.10.
- add_drawing()
Add a
aspecd.plotting.LinePropertiesobject to the list.The default properties are set as well, as obtained from
matplotlib.pyplot.rcParams. These contain at least colour, width, marker, and style of a line.Note
If you provide a key “drawing” (singular!) in the dictionary with the properties, instead of setting default properties the properties of this dict will be set to all drawings. Thus, you can conveniently set identical settings for all lines.
Changed in version 0.10: Handling of the
drawingkey.
- apply(plotter=None)
Apply properties to plot.
The main difference to the parent class: if you set a colormap property, the lines will be coloured according to the colormap. Note that this needs to be done on this level, as we need to know how many drawings (i.e. lines) there are to colour.
- Parameters:
plotter (
aspecd.plotting.MultiPlotter) – Plotter the properties should be applied to.- Raises:
aspecd.exceptions.MissingPlotterError – Raised if no plotter is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
The key
drawing(singular!) is handled in a special way: If it exists in the dictionary, it gets used to set all drawings to this one set of properties.Otherwise, the behaviour is identical to that of the superclass method: see
MultiPLotProperties.from_dict()for details.- Parameters:
dict (
dict) – Dictionary containing information of a task.
New in version 0.10.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- drawings
- class aspecd.plotting.CompositePlotProperties
Bases:
PlotPropertiesProperties of a composite plot, defining its appearance.
For the plotter class, see
CompositePlotter.- 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
AxesPropertiesclass.- Type:
- grid_spec
Properties for the subplot grid specs.
This property is used to set properties for the subplot grid.
For the properties that can be set this way, see the documentation of the
SubplotGridSpecsclass.New in version 0.10.
- Type:
- Raises:
aspecd.exceptions.MissingPlotterError – Raised if no plotter is provided.
Changed in version 0.10: Property
grid_specadded.- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.FigureProperties
Bases:
PropertiesProperties of a figure of a plot, i.e., the most general aspects.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.figure.Figureobjects.- 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:
- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.AxesProperties
Bases:
PropertiesProperties of an axis of a plot.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.axes.Axesobjects.- 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:
- 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:
- xlabel
label for the x-axis
To remove the xlabel entirely, set it to
None(ornullin YAML).Default: ‘’
- Type:
- xlabelposition
Position of the label for the x-axis.
Possible values are: “left”, “center”, “right”.
Default: “center”
New in version 0.11.
- Type:
- xticks
y ticks with list of ticks
Default: None
- ylabel
label for the y-axis
To remove the xlabel entirely, set it to
None(ornullin YAML).Default: ‘’
- Type:
- ylabelposition
Position of the label for the y-axis.
Possible values are: “left”, “center”, “right”, “bottom”, “top”, where “left”/”bottom” and “right”/”top” are equivalent.
Default: “center”
New in version 0.11.
- Type:
- yticks
y ticks with list of ticks
Default: None
- 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-largeDefault:
plt.rcParams['font.size']New in version 0.9.
- 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.
New in version 0.9.
- frame_on
Whether to draw the “frame” (aka “spines”) around the axes.
Note that setting this attribute to
Falsewill remove the entire frame, hence it is usually not what you intended.Default:
TrueNew in version 0.11.
- Type:
- spines
Settings for axes spines.
Axes spines are basically the four lines in the four edges of an axes, where the tick marks are attached.
See class
SpinesandSpinePropertiesfor details.New in version 0.11.
- Type:
- Raises:
aspecd.exceptions.MissingAxisError – Raised if no axis is provided.
Changed in version 0.6: New properties
xticklabelangleandyticklabelangleChanged in version 0.9: New property
invertChanged in version 0.9: New property
label_fontsizeChanged in version 0.9.3: Properties
xlabelandylabelcan be removed by setting toNullChanged in version 0.11: New properties
frame_on,spines,xlabelposition, andylabelposition- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.LegendProperties
Bases:
PropertiesProperties of a legend of a plot, i.e., the most general aspects.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.legend.Legendobjects.- loc
Location of the legend
For possible values, see
matplotlib.legend.Legend- Type:
- labelspacing
Vertical space between the legend entries, in font-size units.
Default: 0.5
- Type:
- 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-largeDefault:
plt.rcParams['font.size']
- Raises:
aspecd.exceptions.MissingLegendError – Raised if no legend is provided.
Changed in version 0.7: Added attributes
labelspacingandfontsizeChanged in version 0.8: Added attribute
ncolChanged 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.DrawingProperties
Bases:
PropertiesProperties of a drawing within a plot.
A drawing is the most abstract object representing data within axes, such as a line, contour, etcetera.
While a base class for more specific kinds of drawings, such as lines, surfaces, or even text, drawing properties come with two essential attributes: a label and the zorder.
The latter means that you can control the z stacking of the different parts of a plot. Artists with lower zorder are drawn first.
For specific kinds of drawings and their respective properties, see
LineProperties,SurfaceProperties, andTextProperties.- alpha
Alpha value used for blending
Must be within the 0-1 range, inclusive, or
None.New in version 0.11.
- Type:
- zorder
Zorder for the artist.
Artists with lower zorder are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
New in version 0.10.
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no drawing is provided.
Examples
Drawing properties are always set in context of concrete plotters, and furthermore, the individual main elements of a plot are always referred to as
drawingordrawingswithin their respectivePlotProperties.An example for setting the drawing properties of a
SinglePlotter1Dare given below:- kind: singleplot type: SinglePlotter1D properties: properties: drawings: label: Substance 1 zorder: 3
In context of a plotter with a legend, the label would appear in this legend, and in this particular case, the zorder is set to 3, i.e. the line in the plotter would appear behind other elements.
Changed in version 0.10: New property
zorderChanged in version 0.11: New property
alpha- apply(drawing=None)
Apply properties to drawing.
For each property, the corresponding “set_<property>” method of the artist will be called.
- Parameters:
drawing (
matplotlib.artist.Artist) – Artist to set properties for- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.LineProperties
Bases:
DrawingPropertiesProperties of a line within a plot.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.lines.Line2Dobjects.- 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:
- linestyle
style of the line, default: ‘solid’
For details see
matplotlib.lines.Line2D.set_linestyle()- Type:
- marker
marker used for the line, default: ‘’
For details see
matplotlib.markers- Type:
- zorder
Zorder for the artist.
Artists with lower zorder are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
New in version 0.10.
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no line is provided.
Examples
Drawing properties are always set in context of concrete plotters, and furthermore, the individual main elements of a plot are always referred to as
drawingordrawingswithin their respectivePlotProperties.An example for setting the line properties of a
SinglePlotter1Dare given below:- kind: singleplot type: SinglePlotter1D properties: properties: drawings: label: Substance 1 zorder: 3 color: '#1f77b4' drawstyle: default linestyle: '-' linewidth: 1.5 marker: None
Here, all currently possible properties are shown.
- settable_properties()
Return properties that are not empty or None.
- Returns:
properties – Dictionary containing all settable properties, i.e. properties that are neither empty nor None.
- Return type:
- apply(drawing=None)
Apply properties to drawing.
For each property, the corresponding “set_<property>” method of the artist will be called.
- Parameters:
drawing (
matplotlib.artist.Artist) – Artist to set properties for- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SurfaceProperties
Bases:
DrawingPropertiesProperties of a surface within a plot.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.contour.ContourSetandmatplotlib.image.AxesImageobjects.- cmap
name of the colormap to use
For details see
matplotlib.colors.Colormap- Type:
- zorder
Zorder for the artist.
Artists with lower zorder are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
New in version 0.10.
- Type:
- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.GridProperties
Bases:
PropertiesProperties of the grid of a plot.
- ticks
ticks to set grid lines for: {‘major’, ‘minor’, ‘both’}
For details see the
whichparameter ofmatplotlib.axes.Axes.grid()- Type:
- axis
axis to set grid lines for: {‘both’, ‘x’, ‘y’}
For details see
matplotlib.axes.Axes.grid()- Type:
- lines
line properties of the grid
- Raises:
TypeError – Raised if no axes is provided.
- apply(axes=None)
Apply properties to axes.
If
showis 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.ColorbarProperties
Bases:
PropertiesProperties 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:
- pad
Fraction of original axes between colorbar and new image axes.
Default: 0.05 if vertical, 0.15 if horizontal
- Type:
- label
The label on the colorbar’s long axis and its properties.
The following keys exist:
- text
str The label text
- location
str 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:
- text
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.
- 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,
**kwargsis the expansion of the returned dictionary.- Returns:
kwargs – dict with kwargs that can be set when instantiating the colorbar.
- Return type:
- apply(colorbar=None)
Apply properties to colorbar.
- Parameters:
colorbar (
matplotlib.colorbar.Colorbar) – Colorbar the properties should be applied to.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.TextProperties
Bases:
DrawingPropertiesProperties of text within a plot.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.text.Textobjects.- backgroundcolor
Color used as background for the text
If set to
None, no background will be set (and the bbox removed from the Matplotlib artist)- Type:
- fontfamily
Font family or font name
Font family can be one of: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, ‘monospace’
- Type:
- fontsize
Size of the font
Either a numeric value or one of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’
- fontstretch
Stretch of the font
A numeric value in range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultra-expanded’
- fontvariant
Variant of the font
One of: ‘normal’, ‘small-caps’
- Type:
:class:``
- fontweight
Weight of the font
A numeric value in range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.
- linespacing
Line spacing of the text
The value is interpreted as multiple of the font size
- Type:
- parse_math
Set mathtext parsing for text
If False, no mathtext will be used. If True, mathtext will be used if there is an even number of unescaped dollar signs.
- Type:
- rotation
Rotation of the text
Either a scalar number or one of: ‘vertical’, ‘horizontal’
- rotation_mode
Rotation mode of the text
One of: ‘default’, ‘anchor’
If “default”, the text will be first rotated, then aligned according to their horizontal and vertical alignments. If “anchor”, then alignment occurs before rotation.
- Type:
- usetex
Whether to render using TeX
None means to use
rcParams["text.usetex"](default: False).- Type:
boolorNone
- verticalalignment
Vertical alignment of the text
One of: ‘baseline’, ‘bottom’, ‘center’, ‘center_baseline’, ‘top’
- Type:
- wrap
Set whether the text can be wrapped.
Wrapping makes sure the text is confined to the (sub)figure box. It does not take into account any other artists.
- Type:
- zorder
Zorder for the artist.
Artists with lower zorder values are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no text is provided.
New in version 0.10.
- apply(drawing=None)
Apply properties to text.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SubplotGridSpecs
Bases:
PropertiesProperties for the subplot grid specs.
This class is used to set properties for the subplot grid of the
CompositePlotterclass. As such, it is part of theCompositePlotPropertiesclass. For further details, see thematplotlib.gridspec.GridSpecdocumentation.- left
Left extent of the subplots as a fraction of figure width.
Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.
- Type:
- bottom
Bottom extent of the subplots as a fraction of figure height.
Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.
- Type:
- right
Right extent of the subplots as a fraction of figure width.
Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.
- Type:
- top
Top extent of the subplots as a fraction of figure height.
Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time.
- Type:
- wspace
The amount of width reserved for space between subplots.
Expressed as a fraction of the average axis width. If not given, the values will be inferred from a figure or rcParams when necessary.
- Type:
- hspace
The amount of height reserved for space between subplots.
Expressed as a fraction of the average axis height. If not given, the values will be inferred from a figure or rcParams when necessary.
- Type:
- width_ratios
Relative width of the columns.
Each column gets a relative width of
width_ratios[i] / sum(width_ratios). If not given, all columns will have the same width.- Type:
- height_ratios
Relative height of the rows.
Each row gets a relative height of
height_ratios[i] / sum(height_ratios). If not given, all rows will have the same height.- Type:
Examples
For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see
aspecd.tasks) is given below for how to make use of this class.Subplot grid spec properties are always set in context of a concrete
CompositePlotter.An example for setting the subplot grid specs of a
CompositePlotterare given below:- kind: compositeplot type: CompositePlotter properties: properties: grid_spec: wspace: 0 hspace: 0 plotter: - raw-data - processed-data filename: comparison.pdf grid_dimensions: [1, 2] subplot_locations: - [0, 0, 1, 1] - [0, 1, 1, 1]
New in version 0.10.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.PatchProperties
Bases:
DrawingPropertiesProperties of a patch within a plot.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.patches.Patchobjects.- color
color of the patch
For details see
matplotlib.colors- Type:
color
- edgecolor
edge color of the patch
For details see
matplotlib.colors- Type:
color
- facecolor
face color of the patch
For details see
matplotlib.colors- Type:
color
- hatch
hatching pattern.
hatch can be one of:
/ - diagonal hatching \ - back diagonal | - vertical - - horizontal + - crossed x - crossed diagonal o - small circle O - large circle . - dots * - stars
Letters can be combined, in which case all the specified hatchings are done. If same letter repeats, it increases the density of hatching of that pattern.
- Type:
str|None
- linestyle
Style of the line.
Default: ‘solid’
For details see
matplotlib.lines.Line2D.set_linestyle()- Type:
- snap
Snapping behavior.
Possible values:
True: Snap vertices to the nearest pixel center.
False: Do not modify vertex positions.
None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center.
- Type:
- zorder
Zorder for the artist.
Artists with lower zorder are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
- Type:
Examples
A typical use case for patches are horizontal or vertical spans as used for plot annotations. For details, see the
aspecd.annotation.VerticalSpanclass.New in version 0.11.
- apply(drawing=None)
Apply properties to drawing.
For each property, the corresponding “set_<property>” method of the artist will be called.
- Parameters:
drawing (
matplotlib.artist.Artist) – Artist to set properties for- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.AnnotationTextProperties
Bases:
DrawingPropertiesProperties of text of an annotation.
Basically, the attributes are a subset of what
matplotlibdefines formatplotlib.text.Textobjects. However, the alignment properties are missing that are present inTextProperties, as they would interfere with the functionality of theaspecd.annotate.TextWithLineclass.- backgroundcolor
Color used as background for the text
If set to
None, no background will be set (and the bbox removed from the Matplotlib artist)- Type:
- fontfamily
Font family or font name
Font family can be one of: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, ‘monospace’
- Type:
- fontsize
Size of the font
Either a numeric value or one of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’
- fontstretch
Stretch of the font
A numeric value in range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultra-expanded’
- fontvariant
Variant of the font
One of: ‘normal’, ‘small-caps’
- Type:
:class:``
- fontweight
Weight of the font
A numeric value in range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’.
- linespacing
Line spacing of the text
The value is interpreted as multiple of the font size
- Type:
- parse_math
Set mathtext parsing for text
If False, no mathtext will be used. If True, mathtext will be used if there is an even number of unescaped dollar signs.
- Type:
- rotation
Rotation of the text
Either a scalar number or one of: ‘vertical’, ‘horizontal’
- rotation_mode
Rotation mode of the text
One of: ‘default’, ‘anchor’
If “default”, the text will be first rotated, then aligned according to their horizontal and vertical alignments. If “anchor”, then alignment occurs before rotation.
- Type:
- usetex
Whether to render using TeX
None means to use
rcParams["text.usetex"](default: False).- Type:
boolorNone
- wrap
Set whether the text can be wrapped.
Wrapping makes sure the text is confined to the (sub)figure box. It does not take into account any other artists.
- Type:
- zorder
Zorder for the artist.
Artists with lower zorder values are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no text is provided.
New in version 0.11.
- apply(drawing=None)
Apply properties to text.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.AnnotationProperties
Bases:
PropertiesProperties for the text and line of annotations.
This class is used to set properties for the
aspecd.annotation.TextWithLineclass.- text
Properties of the text part of the annotation
- Type:
- line
Properties of the line part of the annotation
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no text is provided.
New in version 0.11.
- apply(drawing=None)
Apply properties to drawing.
Properties will be set independently for the text and line parts of the annotation, and the underlying
AnnotationTextProperties.apply()andPatchProperties.apply()method be called.- Parameters:
drawing (
matplotlib.axes.Axes) – axis to set properties for- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no line is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.Spines
Bases:
PropertiesProperties proxy for spines of an axes.
Axes spines are basically the four lines in the four edges of an axes, where the tick marks are attached.
This class serves as a “container” for the four individual spines.
- left
Properties of the left axes spine
- Type:
- bottom
Properties of the bottom axes spine
- Type:
- right
Properties of the right axes spine
- Type:
- top
Properties of the top axes spine
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no drawing is provided.
Examples
For detailed examples on how to set the spine properties in a plot, see the documentation of the
SpinePropertiesclass.New in version 0.11.
- apply(axes=None)
Apply properties to spine.
For each spine, the corresponding
SpineProperties.apply()method will be called.- Parameters:
axes (
matplotlib.axes.Axes) – Axis to set spine properties for- Raises:
aspecd.exceptions.MissingAxisError – Raised if no axes is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.SpineProperties(edge='left')
Bases:
DrawingPropertiesProperties proxy for spines of an axes.
Axes spines are basically the four lines in the four edges of an axes, where the tick marks are attached.
For details, see the documentation of the
matplotlib.spines.Spineclass.- position
Type and value of the positioning of a spine.
The position type is one of
outward, axes, data:- outward
Place the spine out from the data area by the specified number of points. (Negative values place the spine inwards.)
- axes
Place the spine at the specified Axes coordinate (0 to 1).
- data
Place the spine at the specified data coordinate.
Two shorthand notations exist, where
positionis only a string, no longer a tuple (or list):- center
Sets spline at the centre of the axis.
Same as
('axes', 0.5)- zero
Sets spline to the zero value of the data.
Same as
('data', 0.0)
- Type:
- bounds
tuple Lower and higher spine bound in axes coordinates.
- arrow
bool Whether to draw arrows at the tip of the spine
Particularly with only two spines shown and perhaps with spines positioned at zero (the origin of the Cartesian coordinate system), adding arrow heads at the tips of the spines makes sense.
Note that this is not a default property of the underlying
matplotlib.spines.Spine, but adds the arrow heads as additional plots.This functionality is inspired by an example in the Matplotlib documentation: https://matplotlib.org/stable/gallery/spines/centered_spines_with_arrows.html
- Parameters:
edge (
str) –Position the spline belongs to in an axis: left, bottom, right, top.
This information is relevant for adding arrow heads.
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no drawing is provided.
Examples
For convenience, a series of examples in recipe style (for details of the recipe-driven data analysis, see
aspecd.tasks) is given below for how to make use of this class.Spines are set within the axes properties, hence in the axes block. Note that there are four spines:
left,bottom,right, andtop, for whom you can (and need to) set the properties separately.To get rid of the top and right spine (a typical use case), just set the visibility of those two to
False:- kind: singleplot type: SinglePlotter1D properties: properties: axes: spines: right: visible: False top: visible: False
If you want to detach the spines, you could explicitly set both,
boundsandpositions:- kind: singleplot type: SinglePlotter1D properties: properties: axes: spines: left: bounds: [0, 1] position: ["outward", 5] bottom: bounds: [-10, 10] position: ["outward", 5] right: visible: False top: visible: False
Suppose you want to draw what the Matplotlib documentation calls a “math textbook style plot”, where the spines are centred at zero (in the origin of the Cartesian coordinate system) and have arrows at their ends:
- kind: singleplot type: SinglePlotter1D properties: properties: axes: xlabel: Null ylabel: Null invert: - x - y spines: left: position: zero arrow: True bottom: position: zero arrow: True right: visible: False top: visible: False
New in version 0.11.
- apply(drawing=None)
Apply properties to spine.
For each property, the corresponding “set_<property>” method of the spine will be called.
- Parameters:
drawing (
matplotlib.spines.Spine) – Spine of an axis to set properties for- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no line is provided.
- 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:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.
- class aspecd.plotting.MarkerProperties
Bases:
DrawingPropertiesProperties for marker.
Basically, the attributes are a subset of what
matplotlibdefines for the marker part ofmatplotlib.lines.Line2Dobjects.- edgecolor
edge color of the marker
For details see
matplotlib.colorsTo remove the color, set it to
None(orNullin YAML)Default: “#000000”
- Type:
color
- facecolor
face color of the marker
For details see
matplotlib.colorsTo remove the color, set it to
None(orNullin YAML)Default: “#000000”
- Type:
color
- facecoloralt
Alternative face color of the marker
This color gets interesting depending on the fill style.
For details see
matplotlib.colorsTo remove the color, set it to
None(orNullin YAML)Default: “none”
- Type:
color
- fillstyle
Style to use to fill the marker.
Allowed values are: “full”, “left”, “right”, “bottom”, “top”, “none”
- Type:
- zorder
Zorder for the artist.
Artists with lower zorder are drawn first.
For a summary of the default zorder values, see the Matplotlib documentation
- Type:
- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no marker is provided.
Examples
Markers are typically used for plot annotations. For details, see the
aspecd.annotation.Markerclass.New in version 0.11.
- apply(drawing=None)
Apply properties to drawing.
For each property, the corresponding “set_<property>” method of the artist will be called.
- Parameters:
drawing (
matplotlib.artist.Artist) – Artist to set properties for- Raises:
aspecd.exceptions.MissingDrawingError – Raised if no artist is provided.
- from_dict(dict_=None)
Set attributes from dictionary.
- Parameters:
dict (
dict) – Dictionary containing information of a task.- Raises:
aspecd.plotting.MissingDictError – Raised if no dict is provided.
- get_properties()
Return (public) properties, i.e. attributes that are not methods.
- Returns:
properties – public properties
- Return type:
- 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:
Changed in version 0.6: New parameter remove_empty
Changed in version 0.9: Settings for properties to exclude and include are not traversed
Changed in version 0.9.1: Dictionaries get copied before traversing, as otherwise, the special variables
__dict__and__0dict__are modified, what may result in strange behaviour.Changed in version 0.9.2: Dictionaries do not get copied by default, but there is a private method that can be overridden in derived classes to copy the dictionary.