Recipe format v.0.3: New sub-dict colors in settings.

README.rst

@@ -11,7 +11,7 @@ What is even better: Actual data processing and analysis **no longer requires pr
 
     format:
       type: ASpecD recipe
-      version: '0.2'
+      version: '0.3'
 
     datasets:
       - /path/to/first/dataset

VERSION

@@ -1 +1 @@
-0.12.0.dev35
+0.12.0.dev36

aspecd/plotting.py

@@ -541,8 +541,8 @@
 
 .. code-block:: yaml
 
-    - kind: singleplot
-      type: SinglePlotter1D
+    - kind: multiplot
+      type: MultiPlotter1D
       properties:
         parameters:
           show_legend: True
@@ -562,6 +562,35 @@
 properties explicitly. For details, see the :class:`LegendProperties` class.
 
 
+Removing a line from the legend
+-------------------------------
+
+Sometimes, you may want to have certain lines in your plot not showing up in
+the legend. By default, all lines ("drawings") will enter the legend, either
+by the explicit label you provide or by the label of the corresponding
+dataset. To have a line not showing up in the legend, set its label to
+either the empty string or to ``null`` (the YAML equivalent of :obj:`None`).
+A minimal example is given below:
+
+
+.. code-block:: yaml
+
+    - kind: multiplot
+      type: MultiPlotter1D
+      properties:
+        parameters:
+          show_legend: True
+        properties:
+          drawings:
+          - label: "one line"
+          - label: ""
+          - label: "another line"
+
+
+Here, there should be three lines in the plot, and the second would not
+appear in the legend, as its label is set to the empty string.
+
+
 Annotating plots
 ----------------
 
@@ -4814,7 +4843,7 @@ class MultiPlot1DProperties(MultiPlotProperties):
         Has only an effect if a :attr:`colormap` is provided.
 
     first_color : :class:`int`
-        First color of a choosen colormap to use.
+        First color of a chosen colormap to use.
 
         Particularly with colormaps starting with white or fairly light
         colors, setting an offset within the colormap is often necessary.

aspecd/recipe_mapper.yaml

@@ -2,7 +2,7 @@
 
 format:
   type: metadata mapper
-  version: 0.1
+  version: 0.2
 
 map 1:
   metadata file versions:
@@ -34,4 +34,19 @@ map 1:
 
 map2:
   metadata file versions:
-    - '0.2'
+    - '0.2'
+  move item:
+    - key: default_colormap
+      base dict: settings
+      source dict:
+      target dict: colors
+      create target: True
+    - key: number_of_colors
+      base dict: settings
+      source dict:
+      target dict: colors
+      create target: True
+
+map3:
+  metadata file versions:
+    - '0.3'

aspecd/tasks.py

@@ -48,7 +48,7 @@
 
     format:
       type: ASpecD recipe
-      version: '0.2'
+      version: '0.3'
 
     datasets:
       - loi:xxx
@@ -514,16 +514,41 @@ class you intend to use for parameters you can set (if any). Note that many
 Settings for recipes
 --------------------
 
-At the top level of a recipe, in the `settings` block, you can provide an (
-increasing) list of settings, part of which are described elsewhere as well.
+At the top level of a recipe, in the `settings` block, you can provide an
+(increasing) list of settings, part of which are described elsewhere as well.
 The full and up-to-date list is contained in the
 :class:`aspecd.tasks.Recipe` class documentation. For convenience, the most
 important settings are described below:
 
-  * ``default_package``
+* ``default_package``
 
-    Set the default package tasks are obtained from. Useful mostly for
-    packages derived from the ASpecD framework.
+  Set the default package tasks are obtained from. Useful mostly for
+  packages derived from the ASpecD framework.
+
+* ``autosave_plots``
+
+  Control whether plots are saved by default, even if no filename is
+  provided.
+
+* ``autosave_datasets``
+
+  Control whether datasets are saved by default, even if no target is
+  provided.
+
+  .. versionadded:: 0.8.3
+
+* ``write_history``
+
+  Control whether a history is written when serving a recipe. Setting
+  this to ``False`` will most probably render your data processing and
+  analysis irreproducible and therefore mostly useless. Hence,
+  use *only* for debugging purposes.
+
+* ``colors``
+
+  Settings for colors.
+
+  .. versionadded:: 0.12
 
   * ``default_colormap``
 
@@ -533,6 +558,9 @@ class you intend to use for parameters you can set (if any). Note that many
 
     .. versionadded:: 0.8.2
 
+    .. versionchanged:: 0.12
+        Moved to ``colors`` sub-dictionary
+
   * ``number_of_colors``
 
     Set the number of colours for plots. This will currently only affect
@@ -544,24 +572,18 @@ class you intend to use for parameters you can set (if any). Note that many
 
     .. versionadded:: 0.12
 
-  * ``autosave_plots``
+  * ``first_color``
 
-    Control whether plots are saved by default, even if no filename is
-    provided.
+    Set the first color of a chosen colormap to use.
 
-  * ``autosave_datasets``
+    Particularly with colormaps starting with white or fairly light
+    colors, setting an offset within the colormap is often necessary.
 
-    Control whether datasets are saved by default, even if no target is
-    provided.
-
-    .. versionadded:: 0.8.3
-
-  * ``write_history``
+    This will currently only affect plots showing individual drawings, such as
+    :class:`aspecd.plotting.MultiPlotter1D` or
+    :class:`aspecd.plotting.SinglePlotter2DStacked`.
 
-    Control whether a history is written when serving a recipe. Setting
-    this to ``False`` will most probably render your data processing and
-    analysis irreproducible and therefore mostly useless. Hence,
-    use *only* for debugging purposes.
+    .. versionadded:: 0.12
 
 
 As mentioned, all these settings are set in the ``settings`` block, as shown
@@ -571,9 +593,12 @@ class you intend to use for parameters you can set (if any). Note that many
 
     settings:
       default_package: my_package
-      default_colormap: viridis
       number_of_colors: 7
       autosave_plots: false
+      colors:
+        default_colormap: viridis
+        number_of_colors: 5
+        first_color: 3
 
 
 Executing recipes: serving the cooked results
@@ -1250,12 +1275,15 @@ def __init__(self):
         self.tasks = []
         self.format = {
             "type": "ASpecD recipe",
-            "version": "0.2",
+            "version": "0.3",
         }
         self.settings = {
             "default_package": "",
-            "default_colormap": "",
-            "number_of_colors": None,
+            "colors": {
+                "default_colormap": "",
+                "number_of_colors": None,
+                "first_color": 0,
+            },
             "autosave_plots": True,
             "autosave_datasets": True,
             "write_history": True,
@@ -1295,7 +1323,11 @@ def from_dict(self, dict_=None):  # noqa: MC0001
         for key in ["settings", "directories"]:
             if key in dict_:
                 for subkey, value in dict_[key].items():
-                    getattr(self, key)[subkey] = value
+                    if isinstance(value, dict):
+                        for subsubkey, subvalue in value.items():
+                            getattr(self, key)[subkey][subsubkey] = subvalue
+                    else:
+                        getattr(self, key)[subkey] = value
         if not self.dataset_factory:
             package = (
                 self.settings["default_package"]
@@ -1507,7 +1539,7 @@ def to_yaml(self, remove_empty=False):
 
             format:
               type: ASpecD recipe
-              version: '0.2'
+              version: '0.3'
             settings:
               default_package: ''
               autosave_plots: true
@@ -3315,22 +3347,21 @@ def set_colormap(self):
         .. versionadded:: 0.8.2
 
         """
-        if self.recipe.settings["default_colormap"]:
-            if (
-                hasattr(self._task.properties, "colormap")
-                and not self._task.properties.colormap
-            ):
-                self._task.properties.colormap = self.recipe.settings[
-                    "default_colormap"
-                ]
-        if self.recipe.settings["number_of_colors"]:
-            if (
-                hasattr(self._task.properties, "number_of_colors")
-                and not self._task.properties.number_of_colors
-            ):
-                self._task.properties.number_of_colors = self.recipe.settings[
-                    "number_of_colors"
-                ]
+        task_property_to_settings = {
+            "colormap": "default_colormap",
+            "number_of_colors": "number_of_colors",
+            "first_color": "first_color",
+        }
+        for task_property, settings_key in task_property_to_settings.items():
+            if self.recipe.settings["colors"][settings_key]:
+                if hasattr(
+                    self._task.properties, task_property
+                ) and not getattr(self._task.properties, task_property):
+                    setattr(
+                        self._task.properties,
+                        task_property,
+                        self.recipe.settings["colors"][settings_key],
+                    )
 
 
 class SingleplotTask(PlotTask):

docs/changelog.rst

@@ -18,7 +18,7 @@ New features
 
   * Attribute ``clim`` in :class:`aspecd.plotting.SurfaceProperties`
   * Parameter ``threshold`` for determining the levels of a contour plot in class :class:`aspecd.plotting.SinglePlotter2D`
-  * Attribute ``number_of_colors`` in :class:`aspecd.plotting.MultiPlot1DProperties`: Fixed number of elements from colormap, to have same colour succession in plots with different number of curves if a colormap is specified.
+  * Attributes ``number_of_colors`` and ``first_color`` in :class:`aspecd.plotting.MultiPlot1DProperties`: Fixed number of elements from colormap, to have same colour succession in plots with different number of curves if a colormap is specified, and potential offset in colormap if starting with white/a light colour.
   * Attributes ``norm`` and ``norm_parameters`` in :class:`aspecd.plotting.SurfaceProperties`.
 
 * Plot annotations
@@ -38,6 +38,15 @@ New features
   * Tasks can be marked as to be skipped, using the ``skip`` keyword on the top level of the task definition in a recipe.
 
 
+Changes
+-------
+
+* Recipe structure changed slightly: The ``settings`` dictionary has a new sub-dictionary ``colors``, and the ``default_colormap`` key moved there, together with the new keys ``number_of_colors`` and ``first_color``.
+
+  * **New recipe format version: 0.3**.
+  * Existing recipes are updated automatically on import.
+
+
 Fixes
 -----
 

docs/examples/model-introduction-gaussian.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 tasks:
   - kind: model

docs/examples/model-introduction-sine.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 tasks:
   - kind: model

docs/examples/model-voigt-varying.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 tasks:
   - kind: model

docs/examples/plotting-annotation-fillbetween.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 settings:
   autosave_plots: False

docs/examples/plotting-annotation-lines.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 settings:
   autosave_plots: False

docs/examples/plotting-annotation-marker.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 settings:
   autosave_plots: False

docs/examples/plotting-annotation-text.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 settings:
   autosave_plots: False

docs/examples/plotting-annotation-vertical-span.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 settings:
   autosave_plots: False

docs/examples/plotting-spines.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 settings:
   autosave_plots: False

docs/examples/uvvis-normalised.yaml

@@ -1,6 +1,6 @@
 format:
   type: ASpecD recipe
-  version: '0.2'
+  version: '0.3'
 
 datasets:
   - source: tbt.txt