You're reading an old version of this documentation. For up-to-date information, please have a look at v0.10.
aspecd.annotation module
Annotations of data, e.g. characteristics, that cannot be automated.
Annotations of data (and plots, i.e. graphical representations of data) are eventually something that cannot be automated. Nevertheless, they can be quite important for the analysis and hence for providing new scientific insight. Furthermore, annotations of data can sometimes be added to a graphical representation. A typical example would be to mark an artefact with an asterisk or to highlight a characteristic. Therefore, dataset annotations may have graphical realisations as plot annotations.
Dataset annotations
All dataset annotations inherit from the
aspecd.annotation.DatasetAnnotation
base class.
Concrete dataset annotations are:
-
The simplest form of an annotation is a comment applying to an entire dataset, such as comments stored in the metadata written during data acquisition. Hence, those comments do not belong to the metadata part of a dataset, but are stored as an annotation using this class.
Other frequent types of annotations are artefacts and characteristics, for which dedicated classes are available within the ASpecD framework:
Todo
Flesh out these additional DatasetAnnotation classes, particularly in light of the newly created PlotAnnotation classes that may eventually be a way to graphically display the dataset annotations.
For other types of annotations, simply subclass the
aspecd.annotation.DatasetAnnotation
base class.
Plot(ter) annotations
Similar to datasets, plots, i.e. graphical representations of the data of
one or multiple datasets, can be annotated as well. Plot annotations will
always result in a graphical object of some kind added to the plot created
by a aspecd.plotting.Plotter
. Additionally, each plotter has a list
of annotations attached to it. As such, plot annotations are independent of
individual datasets and can span multiple datasets in case of plotters
involving the data of multiple datasets.
While generally, it should not matter whether a plot annotation gets added
to the plotter object before or after the actual plotting process, adding
the graphical elements annotations consist eventually of to the plot is only
possible once the aspecd.plotting.Plotter.plot()
method has been
called and the respective aspecd.plotting.Plotter.figure
and
aspecd.plotting.Plotter.axes
attributes are set. To this end, a plot
annotation will only actually add graphical elements if the plot exists
already, and the plotter will in turn add any annotations added prior to
plotting when its aspecd.plotting.Plotter.plot()
method is called.
This avoids side effects, as annotating a plotter does not create a
graphical representation that did not exist before.
All plot annotations inherit from the aspecd.annotation.PlotAnnotation
base class.
Concrete plot annotations are:
aspecd.annotation.VerticalLine
Add vertical line(s) to a plot(ter).
aspecd.annotation.HorizontalLine
Add horizontal line(s) to a plot(ter).
aspecd.annotation.VerticalSpan
Add vertical span(s) (rectangles) to a plot(ter).
aspecd.annotation.HorizontalSpan
Add horizontal span(s) (rectangles) to a plot(ter).
-
Add text(s) to a plot(ter).
aspecd.annotation.TextWithLine
Add text(s) with a connecting line to a plot(ter).
-
Add marker(s) to a plot(ter).
-
Coloured surface under a curve or between curves.
Module documentation
- class aspecd.annotation.DatasetAnnotation
Bases:
ToDictMixin
Annotations are user-supplied additional information to datasets.
Whereas many processing steps of data can be fully automated, annotations are mostly the domain of human interaction, looking at the data of a dataset and providing some sort of comments, trying to make sense of the data.
Annotations can have different types, such as simple “comments”, e.g. saying that a dataset is not useful as something during measurement went wrong, they can highlight “characteristics” of the data, they can point to “artefacts”. Each of these types is represented by a class on its own that is derived from the
DatasetAnnotation
base class. Additionally, the type is reflected in the “type” property that gets set automatically to the class name in lower-case letters.Each annotation has a scope (such as “point”, “slice”, “area”, “distance”, “dataset”) it belongs to, and a “contents” property (dict) containing the actual content of the annotation.
- type
Textual description of the type of annotation: lowercase class name
Set automatically, don’t change
- Type:
- dataset
Dataset the annotation belongs to
- Type:
- Raises:
aspecd.annotation.NoContentError – Raised when annotation contains no content(s)
aspecd.annotation.MissingDatasetError – Raised when no dataset exists to act on
- property scope
Get or set the scope the annotation applies to.
The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)
Currently, allowed scopes are:
dataset
,slice
,point
,area
,distance
.
- annotate(dataset=None, from_dataset=False)
Annotate a dataset with the given annotation.
If no dataset is provided at method call, but is set as property in the Annotation object, the
aspecd.dataset.Dataset.annotate()
method of the dataset will be called and thus the history written.If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.
If no scope is set in the
aspecd.annotation.Annotation
object, a default value will be used that can be set in derived classes in the private property_default_scope
. A full list of scopes is contained in the private property_allowed_scopes
. See thescope
property for details.The
aspecd.dataset.Dataset
object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.- Parameters:
dataset (
aspecd.dataset.Dataset
) – dataset to annotatefrom_dataset (
bool
) –whether we are called from within a dataset
Defaults to “False” and shall never be set manually.
- Returns:
dataset – dataset that has been annotated
- Return type:
- create_history_record()
Create history record to be added to the dataset.
Usually, this method gets called from within the
aspecd.dataset.Dataset.annotate()
method of theaspecd.dataset.Dataset
class and ensures the history of each annotation step to get written properly.- Returns:
history_record – history record for annotation step
- 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.annotation.Comment
Bases:
DatasetAnnotation
The most basic form of annotation: a simple textual comment.
- property comment
Get comment of annotation.
- Returns:
comment – Actual comment string
- Return type:
- annotate(dataset=None, from_dataset=False)
Annotate a dataset with the given annotation.
If no dataset is provided at method call, but is set as property in the Annotation object, the
aspecd.dataset.Dataset.annotate()
method of the dataset will be called and thus the history written.If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.
If no scope is set in the
aspecd.annotation.Annotation
object, a default value will be used that can be set in derived classes in the private property_default_scope
. A full list of scopes is contained in the private property_allowed_scopes
. See thescope
property for details.The
aspecd.dataset.Dataset
object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.- Parameters:
dataset (
aspecd.dataset.Dataset
) – dataset to annotatefrom_dataset (
bool
) –whether we are called from within a dataset
Defaults to “False” and shall never be set manually.
- Returns:
dataset – dataset that has been annotated
- Return type:
- create_history_record()
Create history record to be added to the dataset.
Usually, this method gets called from within the
aspecd.dataset.Dataset.annotate()
method of theaspecd.dataset.Dataset
class and ensures the history of each annotation step to get written properly.- Returns:
history_record – history record for annotation step
- Return type:
- property scope
Get or set the scope the annotation applies to.
The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)
Currently, allowed scopes are:
dataset
,slice
,point
,area
,distance
.
- 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.annotation.Artefact
Bases:
DatasetAnnotation
Mark something as an artefact.
- annotate(dataset=None, from_dataset=False)
Annotate a dataset with the given annotation.
If no dataset is provided at method call, but is set as property in the Annotation object, the
aspecd.dataset.Dataset.annotate()
method of the dataset will be called and thus the history written.If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.
If no scope is set in the
aspecd.annotation.Annotation
object, a default value will be used that can be set in derived classes in the private property_default_scope
. A full list of scopes is contained in the private property_allowed_scopes
. See thescope
property for details.The
aspecd.dataset.Dataset
object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.- Parameters:
dataset (
aspecd.dataset.Dataset
) – dataset to annotatefrom_dataset (
bool
) –whether we are called from within a dataset
Defaults to “False” and shall never be set manually.
- Returns:
dataset – dataset that has been annotated
- Return type:
- create_history_record()
Create history record to be added to the dataset.
Usually, this method gets called from within the
aspecd.dataset.Dataset.annotate()
method of theaspecd.dataset.Dataset
class and ensures the history of each annotation step to get written properly.- Returns:
history_record – history record for annotation step
- Return type:
- property scope
Get or set the scope the annotation applies to.
The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)
Currently, allowed scopes are:
dataset
,slice
,point
,area
,distance
.
- 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.annotation.Characteristic
Bases:
DatasetAnnotation
Base class for characteristics.
- annotate(dataset=None, from_dataset=False)
Annotate a dataset with the given annotation.
If no dataset is provided at method call, but is set as property in the Annotation object, the
aspecd.dataset.Dataset.annotate()
method of the dataset will be called and thus the history written.If no dataset is provided at method call nor as property in the object, the method will raise a respective exception.
If no scope is set in the
aspecd.annotation.Annotation
object, a default value will be used that can be set in derived classes in the private property_default_scope
. A full list of scopes is contained in the private property_allowed_scopes
. See thescope
property for details.The
aspecd.dataset.Dataset
object always calls this method with the respective dataset as argument. Therefore, in this case setting the dataset property within the Annotation object is not necessary.- Parameters:
dataset (
aspecd.dataset.Dataset
) – dataset to annotatefrom_dataset (
bool
) –whether we are called from within a dataset
Defaults to “False” and shall never be set manually.
- Returns:
dataset – dataset that has been annotated
- Return type:
- create_history_record()
Create history record to be added to the dataset.
Usually, this method gets called from within the
aspecd.dataset.Dataset.annotate()
method of theaspecd.dataset.Dataset
class and ensures the history of each annotation step to get written properly.- Returns:
history_record – history record for annotation step
- Return type:
- property scope
Get or set the scope the annotation applies to.
The list of allowed scopes is stored in the private property _allowed_scopes, and if no scope is set when the annotation is finally applied to a dataset, a default scope will be used that is stored in the private property _default_scope (and is defined as one element of the list of allowed scopes)
Currently, allowed scopes are:
dataset
,slice
,point
,area
,distance
.
- 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.annotation.PlotAnnotation
Bases:
ToDictMixin
Base class for annotations for graphical representations (plots).
Whereas many processing steps of data can be fully automated, annotations are mostly the domain of human interaction, looking at the graphical representation of the data of a dataset and providing some sort of comments, trying to make sense of the data. Often, being able to add some kind of annotation to these graphical representations is both, tremendously helpful and required for further analysis.
Annotations can have different types, such as horizontal and vertical lines added to a plot for comparing different data.
Each of these types is represented by a class on its own that is derived from the
PlotAnnotation
base class. Additionally, the type is reflected in the “type” property that gets set automatically to the class name in lower-case letters.While generally, it should not matter whether a plot annotation gets added to the plotter object before or after the actual plotting process, adding the graphical elements annotations consist eventually of to the plot is only possible once the
aspecd.plotting.Plotter.plot()
method has been called and the respectiveaspecd.plotting.Plotter.figure
andaspecd.plotting.Plotter.axes
attributes are set. To this end, a plot annotation will only actually add graphical elements if the plot exists already, and the plotter will in turn add any annotations added prior to plotting when itsaspecd.plotting.Plotter.plot()
method is called. This avoids side effects, as annotating a plotter does not create a graphical representation that did not exist before.- plotter
Plotter the annotation belongs to
- Type:
- type
Textual description of the type of annotation: lowercase class name
Set automatically, don’t change
- Type:
- properties
Properties of the annotation, defining its appearance
- Type:
None
Examples
For examples of how such a report task may be included into a recipe, see 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 theplotter
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.
New in version 0.9.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.VerticalLine
Bases:
PlotAnnotation
Vertical line(s) added to a plot.
Vertical lines are often useful to compare peak positions or as a general guide to the eye of the observer.
The properties of the lines can be controlled in quite some detail using the
properties
property. Note that all lines will share the same properties. If you need to add lines with different properties to the same plot, use severalVerticalLine
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions vertical lines should appear at
Values are in axis (data) units.
- limits
list
Limits of the vertical lines
If not given, the vertical lines will span the entire range of the current axes.
Values are in relative units, within a range of [0, 1].
- Type:
- positions
- properties
Properties of the line(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.LineProperties
class.
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. The examples focus each on a single aspect.Generally and 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 theplotter
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.
New in version 0.9.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.HorizontalLine
Bases:
PlotAnnotation
Horizontal line(s) added to a plot.
Horizontal lines are often useful to compare peak positions or as a general guide to the eye of the observer.
The properties of the lines can be controlled in quite some detail using the
properties
property. Note that all lines will share the same properties. If you need to add lines with different properties to the same plot, use severalHorizontalLine
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions horizontal lines should appear at
Values are in axis (data) units.
- limits
list
Limits of the horizontal lines
If not given, the horizontal lines will span the entire range of the current axes.
Values are in relative units, within a range of [0, 1].
- Type:
- positions
- properties
Properties of the line(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.LineProperties
class.
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. The examples focus each on a single aspect.Generally and 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: HorizontalLine 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 theplotter
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: HorizontalLine properties: parameters: positions: - 21 - 42 properties: color: green linewidth: 1 linestyle: dotted result: hlines - kind: multiplot type: MultiPlotter1DStacked properties: filename: plot1Dstacked.pdf annotations: - hlines
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: HorizontalLine 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.
New in version 0.9.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.Text
Bases:
PlotAnnotation
Text added to a plot.
One of the most versatile ways to annotate a plot is adding text labels at defined positions. Basically, this class is the ASpecD wrapper to
matplotlib.axes.Axes.text()
. In short, you provide coordinates (x, y) for the location and a text label. By default, coordinates are data coordinates and specify the bottom left corner of the text.The properties of the texts can be controlled in quite some detail using the
properties
property. Note that all texts will share the same properties. If you need to add texts with different properties to the same plot, use severalText
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions texts should appear at.
Note that each position is itself a list: [x, y]
Values are in axis (data) units.
- xpositions
list
List of the x positions texts should appear at.
This allows to set x positions from the result of other tasks, e.g. a peak finding analysis step.
If
xpositions
is set, you need to setypositions
as well. However, you can set either a single element or even a scalar (not a list). In this case, the single y position is expanded to match the number of x positions, i.e., all texts will appear with the same y position.If you provide both,
positions
andxpositions
/ypositions
, the latter couple wins.Values are in axis (data) units.
- ypositions
list
orfloat
List of the y positions texts should appear at.
If
xpositions
is set, you need to setypositions
as well. However, you can set either a single element or even a scalar (not a list). In this case, the single y position is expanded to match the number of x positions, i.e., all texts will appear with the same y position.If you provide both,
positions
andxpositions
/ypositions
, the latter couple wins.Values are in axis (data) units.
- texts
list
Texts that should appear at the individual positions.
Each text is a
str
, obviously.
- Type:
- positions
- properties
Properties of the text(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.TextProperties
class.
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. The examples focus each on a single aspect.Generally and 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: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf result: plot1D - kind: plotannotation type: Text properties: parameters: positions: - [0.5, 0.5] - [1.0, 0.5] texts: - "Lorem ipsum" - "dolor sit amet" properties: color: green fontsize: large fontstyle: oblique rotation: 30 plotter: plot1D
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 theplotter
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: Text properties: parameters: positions: - [0.5, 0.5] - [1.0, 0.5] texts: - "Lorem ipsum" - "dolor sit amet" properties: color: green fontsize: large fontstyle: oblique rotation: 30 result: text - kind: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf annotations: - text
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: singleplot type: SinglePlotter1D result: plot1 - kind: singleplot type: SinglePlotter1D result: plot2 - kind: plotannotation type: Text properties: parameters: positions: - [0.5, 0.5] - [1.0, 0.5] texts: - "Lorem ipsum" - "dolor sit amet" 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.
New in version 0.10.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.VerticalSpan
Bases:
PlotAnnotation
Vertical span(s) (rectangle) added to a plot.
Vertical spans are often useful to highlight areas of a plot, such as peaks.
The properties of the spans can be controlled in quite some detail using the
properties
property. Note that all spans will share the same properties. If you need to add spans with different properties to the same plot, use severalVerticalSpan
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions vertical spans should appear at.
Each span needs two coordinates: [xmin, xmax].
If you want to have more than one span, provide a list of lists.
Values are in axis (data) units.
- limits
list
Limits of the vertical spans
If not given, the vertical spans will span the entire range of the current axes.
Values are in relative units, within a range of [0, 1].
- Type:
- positions
- properties
Properties of the span(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.PatchProperties
class.
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. The examples focus each on a single aspect.Generally and 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: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf result: plot1D - kind: plotannotation type: VerticalSpan properties: parameters: positions: [[35, 42]] properties: edgecolor: Null facecolor: green alpha: 0.5 plotter: plot1D
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 theplotter
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: VerticalSpan properties: parameters: positions: - [35, 42] - [21, 24] properties: edgecolor: Null facecolor: green alpha: 0.5 result: vspans - kind: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf annotations: - vspans
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: singleplot type: SinglePlotter1D result: plot1 - kind: singleplot type: SinglePlotter1D result: plot2 - kind: plotannotation type: VerticalSpan 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.
New in version 0.11.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.HorizontalSpan
Bases:
PlotAnnotation
Horizontal span(s) (rectangle) added to a plot.
Horizontal spans are often useful to highlight areas of a plot.
The properties of the spans can be controlled in quite some detail using the
properties
property. Note that all spans will share the same properties. If you need to add spans with different properties to the same plot, use severalHorizontalSpan
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions hoizontal spans should appear at.
Each span needs two coordinates: [ymin, ymax].
If you want to have more than one span, provide a list of lists.
Values are in axis (data) units.
- limits
list
Limits of the hoizontal spans
If not given, the hoizontal spans will span the entire range of the current axes.
Values are in relative units, within a range of [0, 1].
- Type:
- positions
- properties
Properties of the span(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.PatchProperties
class.
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. The examples focus each on a single aspect.Generally and 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: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf result: plot1D - kind: plotannotation type: HorizontalSpan properties: parameters: positions: [[35, 42]] properties: edgecolor: Null facecolor: green alpha: 0.5 plotter: plot1D
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 theplotter
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: HorizontalSpan properties: parameters: positions: - [35, 42] - [21, 24] properties: edgecolor: Null facecolor: green alpha: 0.5 result: vspans - kind: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf annotations: - vspans
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: singleplot type: SinglePlotter1D result: plot1 - kind: singleplot type: SinglePlotter1D result: plot2 - kind: plotannotation type: HorizontalSpan 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.
New in version 0.11.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.TextWithLine
Bases:
PlotAnnotation
Text with connecting line added to a plot.
One of the most versatile ways to annotate a plot is adding text labels at defined positions. However, if you intend to annotate data points, sometimes it is helpful to have a connecting line between data point and text. This class uses
matplotlib.axes.Axes.annotate()
under the hood. Basically, you provide coordinates (x, y) for the location, an offset (dx, dy), and a text label. By default, coordinates are data coordinates.Depending on the horizontal offset dx, the connecting line is either a straight line (dx = 0), or it has a 45° hook in the upper part to the left (dx < 0) or to the right (dx > 0). Similarly, if you set a negative vertical offset, the hook is obviously in the lower part.
In ASCII art, this may look like this:
foo foo foo | | | \ | / | | | \ | / | | | | | | / | \ | | | / | \ | | | foo foo foo
The properties of the texts and the connecting line can be controlled in quite some detail using the
properties
property. Note that all texts will share the same properties. If you need to add texts with different properties to the same plot, use severalTextWithLine
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions the lines should point to.
Note that each position is itself a list: [x, y]
Values are in axis (data) units.
- offsets
list
List of the offsets texts should appear at.
Note that each position is itself a list: [dx, dy]
Depending on the horizontal offset dx, the connecting line is either a straight line (dx = 0), or it has a 45° hook in the upper part to the left (dx < 0) or to the right (dx > 0). Similarly, if you set a negative vertical offset, the hook is obviously in the lower part.
Values are in axis (data) units.
- xpositions
list
List of the x positions texts should appear at.
This allows to set x positions from the result of other tasks, e.g. a peak finding analysis step.
If
xpositions
is set, you need to setypositions
as well. However, you can set either a single element or even a scalar (not a list). In this case, the single y position is expanded to match the number of x positions, i.e., all texts will appear with the same y position.If you provide both,
positions
andxpositions
/ypositions
, the latter couple wins.Values are in axis (data) units.
- ypositions
list
orfloat
List of the y positions texts should appear at.
If
xpositions
is set, you need to setypositions
as well. However, you can set either a single element or even a scalar (not a list). In this case, the single y position is expanded to match the number of x positions, i.e., all texts will appear with the same y position.If you provide both,
positions
andxpositions
/ypositions
, the latter couple wins.Values are in axis (data) units.
- texts
list
Texts that should appear at the individual positions.
Each text is a
str
, obviously.
- Type:
- positions
- properties
Properties of the text(s) and line(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.AnnotationProperties
class.
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. The examples focus each on a single aspect.Generally and 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: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf result: plot1D - kind: plotannotation type: TextWithLine properties: parameters: positions: - [0.5, 0.5] - [0.55, 0.5] offsets: - [0.5, 2] - [0.8, 2] texts: - "Lorem ipsum" - "dolor sit amet" properties: text: color: green fontsize: large fontstyle: oblique line: linestyle: ":" plotter: plot1D
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 theplotter
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: TextWithLine properties: parameters: positions: - [0.5, 0.5] - [0.55, 0.5] offsets: - [0.5, 2] - [0.8, 2] texts: - "Lorem ipsum" - "dolor sit amet" properties: text: color: green fontsize: large fontstyle: oblique line: linestyle: ":" result: text - kind: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf annotations: - text
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: singleplot type: SinglePlotter1D result: plot1 - kind: singleplot type: SinglePlotter1D result: plot2 - kind: plotannotation type: TextWithLine properties: parameters: positions: - [0.5, 0.5] - [0.55, 0.5] offsets: - [0.5, 2] - [0.8, 2] texts: - "Lorem ipsum" - "dolor sit amet" 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.
New in version 0.11.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.Marker
Bases:
PlotAnnotation
Marker added to a plot.
One very common way to annotate a plot is adding markers at defined positions. Basically, this class is the ASpecD wrapper to
matplotlib.axes.Axes.plot()
with only a marker used and no line drawn. Basically, you provide coordinates (x, y) for the location and a marker. By default, coordinates are data coordinates and specify the centre of the marker.The properties of the markers can be controlled in quite some detail using the
properties
property. Note that all markers will share the same properties. If you need to add markers with different properties to the same plot, use severalMarker
objects and annotate separately.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- positions
list
List of the positions markers should appear at.
Note that each position is itself a list: [x, y]
Values are in axis (data) units.
- xpositions
list
List of the x positions markers should appear at.
This allows to set x positions from the result of other tasks, e.g. a peak finding analysis step.
If
xpositions
is set, you need to setypositions
as well. However, you can set either a single element or even a scalar (not a list). In this case, the single y position is expanded to match the number of x positions, i.e., all markers will appear with the same y position.If you provide both,
positions
andxpositions
/ypositions
, the latter couple wins.Values are in axis (data) units.
- ypositions
list
orfloat
List of the y positions markers should appear at.
If
xpositions
is set, you need to setypositions
as well. However, you can set either a single element or even a scalar (not a list). In this case, the single y position is expanded to match the number of x positions, i.e., all markers will appear with the same y position.If you provide both,
positions
andxpositions
/ypositions
, the latter couple wins.Values are in axis (data) units.
- yoffset
float
Additional offset for the y direction added to the y position.
Useful, e.g., when you want to mark peaks, but not on the line itself, but slightly above (positive offset values) or below ( negative offset values).
Default: 0
- marker
str
Marker that shall be added to the plot.
There is a large list of predefined markers available. For details, see
matplotlib.markers
. Note that you can use both, the code and the keyword of a specific marker, as returned by thematplotlib.lines.Line2D.markers
attribute:code
keyword
"."
point
","
pixel
"o"
circle
"v"
triangle_down
"^"
triangle_up
"<"
triangle_left
">"
triangle_right
"1"
tri_down
"2"
tri_up
"3"
tri_left
"4"
tri_right
"8"
octagon
"s"
square
"p"
pentagon
"*"
star
"h"
hexagon1
"H"
hexagon2
"+"
plus
"x"
x
"D"
diamond
"d"
thin_diamond
"|"
vline
"_"
hline
"P"
plus_filled
"X"
x_filled
0
tickleft
1
tickright
2
tickup
3
tickdown
4
caretleft
5
caretright
6
caretup
7
caretdown
8
caretleftbase
9
caretrightbase
10
caretupbase
11
caretdownbase
Please note the difference between the string
"1"
and the number1
that result in triangle down and tick right markers, respectively.Furthermore, you can use markers created from TeX symbols using MathText (LaTeX needs not to be installed). Just surround your marker with
$
signs, such as"$\u266B$"
or"$\mathcal{A}$"
.If you provide multiple positions, the same marker will be added multiple times.
- Type:
- positions
- properties
Properties of the marker(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.MarkerProperties
class.
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. The examples focus each on a single aspect.Generally and 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: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf result: plot1D - kind: plotannotation type: Marker properties: parameters: positions: - [0.5, 0.5] - [1.0, 0.5] marker: o properties: edgecolor: green size: 12 plotter: plot1D
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 theplotter
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: Marker properties: parameters: positions: - [0.5, 0.5] - [1.0, 0.5] marker: o properties: edgecolor: green size: 12 result: text - kind: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf annotations: - text
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: singleplot type: SinglePlotter1D result: plot1 - kind: singleplot type: SinglePlotter1D result: plot2 - kind: plotannotation type: Marker properties: parameters: positions: - [0.5, 0.5] - [1.0, 0.5] marker: o 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.
New in version 0.11.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.annotation.FillBetween
Bases:
PlotAnnotation
Coloured surface under a curve or between curves.
Particularly in signal decomposition, highlighting the individual components with coloured surfaces is a common task. But similarly, confidence intervals for a fit (between two lines or curves) can be marked this way.
Basically, this class is the ASpecD wrapper to
matplotlib.axes.Axes.fill_between()
, although (currently) with some restrictions.- parameters
All parameters necessary for the annotation, implicit and explicit
The following keys exist:
- data
aspecd.dataset.Dataset
|list
Dataset or list of datasets.
Datasets used to fill the area below. Strictly speaking, without further parameters, the area between the data points and zero is filled.
- second
float
|aspecd.dataset.Dataset
|list
Scalar, dataset or list (of scalars or datasets).
Second value used to fill the area between.
If a scalar, the scalar value is broadcast to the length of the y values in
data
.If a dataset, the data need to be of same shape as the data of the dataset in
data
.If a list, it needs to contain at least as many elements as
data
. Note that you can mix scalars and datasets in the list.Default: 0
- Type:
- data
- properties
Properties of the marker(s) within a plot
For the properties that can be set this way, see the documentation of the
aspecd.plotting.PatchProperties
class.
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. The examples focus each on a single aspect.Generally and 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: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf result: plot1D - kind: plotannotation type: FillBetween properties: parameters: data: component properties: facecolor: green alpha: 0.3 plotter: plot1D
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 theplotter
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.Note that
component
refers to a dataset available within your recipe.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: FillBetween properties: parameters: data: component properties: facecolor: green alpha: 0.3 result: fillbetween - kind: singleplot type: SinglePlotter1D properties: filename: plot1D.pdf annotations: - fillbetween
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: singleplot type: SinglePlotter1D result: plot1 - kind: singleplot type: SinglePlotter1D result: plot2 - kind: plotannotation type: FillBetween properties: parameters: data: component properties: facecolor: green alpha: 0.3 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.
New in version 0.11.
- annotate(plotter=None, from_plotter=False)
Annotate a plot(ter) with the given annotation.
If no plotter is provided at method call, but is set as property in the Annotation object, the
aspecd.plotting.Plotter.annotate()
method of the plotter will be called and thus the history written.If no plotter is provided at method call nor as property in the object, the method will raise a respective exception.
- Parameters:
plotter (
aspecd.plotting.Plotter
) – Plot(ter) to annotatefrom_plotter (
bool
) –whether we are called from within a plotter
Defaults to “False” and shall never be set manually.
- Returns:
plotter – Plotter that has been annotated
- 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.