release 0.10.0

Author: tillbiskup

.git-blame-ignore-revs

@@ -1,3 +1,4 @@
 # First black run
 e87fcdc29cfcce7b9f45510fa19792c4235d3cc4
-
+# Next concerted black run
+f11ad88212493f9e93f34106962b1bad7f383f27

.package_config.yaml

@@ -0,0 +1,36 @@
+package:
+  name: 'aspecd'
+  author: 'Till Biskup'
+  author_email: 'till@till-biskup.de'
+  year: '2018-24'
+  description: 'Framework for handling spectroscopic data..'
+  urls:
+    main: 'https://www.aspecd.de/'
+    documentation: 'https://docs.aspecd.de/'
+    source: 'https://github.com/tillbiskup/aspecd'
+  keywords: [
+    'spectroscopy',
+    'data processing and analysis',
+    'reproducible science',
+    'reproducible research',
+    'good scientific practice',
+    'recipe-driven data analysis',
+  ]
+  install_requires: [
+    'jinja2>=3.0',
+    'matplotlib',
+    'numpy',
+    'scipy>=0.14',
+    'oyaml',
+    'asdf',
+    'bibrecord',
+  ]
+  license: BSD
+documentation:
+  logo: 'aspecd-logo.png'
+  favicon: 'favicon.ico'
+  language: en
+options:
+  logging: true
+  git: true
+  gui: false

.prospector.yaml

@@ -3,6 +3,9 @@
 
 autodetect: false
 
+ignore-paths:
+  - build
+
 inherits:
   - strictness_high
 

VERSION

@@ -1 +1 @@
-0.9.2
+0.10.0

aspecd/analysis.py

@@ -216,7 +216,6 @@
 
 """
 
-
 import copy
 
 import numpy as np

aspecd/annotation.py

@@ -81,12 +81,18 @@
 
     Add horizontal line(s) to a plot(ter).
 
+* :class:`aspecd.annotation.Text`
+
+    Add text(s) to a plot(ter).
+
 
 Module documentation
 ====================
 
 """
 
+import numpy as np
+
 import aspecd.exceptions
 import aspecd.history
 import aspecd.plotting
@@ -832,3 +838,221 @@ def _perform_task(self):
             else:
                 line = self.plotter.ax.axhline(y=position)
             self.drawings.append(line)
+
+
+class Text(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
+    :meth:`matplotlib.axes.Axes.text`. Basically, 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 :attr:`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 several :class:`Text` objects and annotate separately.
+
+
+    Attributes
+    ----------
+    parameters : :class:`dict`
+        All parameters necessary for the annotation, implicit and explicit
+
+        The following keys exist:
+
+        positions : :class:`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 : :class:`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 set ``ypositions`` 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`` and
+            ``xpositions``/``ypositions``, the latter couple wins.
+
+            Values are in axis (data) units.
+
+        ypositions : :class:`list` or :class:`float`
+            List of the *y* positions texts should appear at.
+
+            If ``xpositions`` is set, you need to set ``ypositions`` 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`` and
+            ``xpositions``/``ypositions``, the latter couple wins.
+
+            Values are in axis (data) units.
+
+        texts : :class:`list`
+            Texts that should appear at the individual positions.
+
+            Each text is a :class:`str`, obviously.
+
+    properties : :class:`aspecd.plotting.TextProperties`
+        Properties of the text(s) within a plot
+
+        For the properties that can be set this way, see the documentation
+        of the :class:`aspecd.plotting.TextProperties` class.
+
+    Examples
+    --------
+    For convenience, a series of examples in recipe style (for details of
+    the recipe-driven data analysis, see :mod:`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.
+
+    .. code-block:: yaml
+
+        - 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
+    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:
+
+    .. code-block:: yaml
+
+        - 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:
+
+    .. code-block:: yaml
+
+        - 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.
+
+
+    .. versionadded:: 0.10
+
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.parameters["positions"] = []
+        self.parameters["xpositions"] = []
+        self.parameters["ypositions"] = []
+        self.parameters["texts"] = []
+        self.properties = aspecd.plotting.TextProperties()
+
+    def _perform_task(self):
+        if self.parameters["xpositions"] and self.parameters["ypositions"]:
+            xpositions = self.parameters["xpositions"]
+            ypositions = self.parameters["ypositions"]
+            if np.isscalar(ypositions):
+                ypositions = [ypositions] * len(xpositions)
+            if len(ypositions) == 1:
+                ypositions = ypositions * len(xpositions)
+            positions = []
+            for idx, xposition in enumerate(xpositions):
+                positions.append([xposition, ypositions[idx]])
+        else:
+            positions = self.parameters["positions"]
+        for idx, position in enumerate(positions):
+            text = self.plotter.ax.text(
+                position[0], position[1], self.parameters["texts"][idx]
+            )
+            self.drawings.append(text)

aspecd/io.py

@@ -337,6 +337,7 @@ class may look like the following::
 ====================
 
 """
+
 import copy
 import io
 import logging