Plot annotations: Vertical span (area)

Classes used:

Graphical representation of data and results is one of the most important aspects of presenting scientific results. A good figure is a figure allowing the reader to immediately catch the important aspects, not relying on reading the (nevertheless always important) caption with more description.

To this end, there is the frequent need to annotate figures, i.e. add additional lines, areas, or even text. This is what can be done with the concrete subclasses of aspecd.annotation.PlotAnnotation.

Here, we focus on simple vertical spans (areas) added to a plot that are often used to highlight particular regions, such as peaks.

Recipe

Shown below is the entire recipe. Although this time, it is rather short, the crucial part will be detailed below in the “Results” section.

Listing 7 Concrete example of a recipe demonstrating how to mark an area by a vertical shaded patch, a “vertical span”.
 1format:
 2  type: ASpecD recipe
 3  version: '0.2'
 4
 5settings:
 6  autosave_plots: False
 7
 8tasks:
 9  - kind: model
10    type: Zeros
11    properties:
12      parameters:
13        shape: 1001
14        range: [-10, 10]
15    result: dummy
16
17  - kind: model
18    type: Lorentzian
19    from_dataset: dummy
20    properties:
21      parameters:
22        width: 2
23    result: model_data
24    comment: >
25      Create Lorentzian with width set explicitly
26
27  - kind: singleplot
28    type: SinglePlotter1D
29    properties:
30      properties:
31        axes:
32          xlabel: "$position$ / a.u."
33      parameters:
34        tight_layout: True
35      filename: plotting-annotation-vertical-span.pdf
36    apply_to:
37      - model_data
38    result:
39      - plot-with-vertical-span
40    comment: >
41      Plotter that gets annotated later
42
43  - kind: plotannotation
44    type: VerticalSpan
45    properties:
46      parameters:
47        positions:
48          - [-2, 2]
49      properties:
50        facecolor: green
51        alpha: 0.3
52        zorder: 0
53    plotter: plot-with-vertical-span
54    result: vertical-lines
55    comment: >
56      Two styled vertical span marking the FWHM

Comments

  • As usual, a model dataset is created at the beginning, to have something to show. Here, a Lorentizan with a slightly increased line width. Using the Lorentzian is based on the very simple mathematical relation between line width and FWHM.

  • For simplicity, a generic plotter is used, to focus on the annotation.

  • The sequence of defining plot and annotation(s) does not matter. You only need to provide the result key with a unique name for whichever task you define first, to refer to it in the later task(s). For details, see the Plot annotations: Lines example.

  • Styling the span, as shown here for demonstration purposes, shall be used carefully in scientific presentations, but can nevertheless be very helpful.

Results

Examples for the figures created in the recipe are given below. While in the recipe, the output format has been set to PDF, for rendering them here they have been converted to PNG.

The scenario: We have a Lorentzian and want to mark the full width at half maximum (FWHM). Thankfully, the respective positions for the vertical lines have a very simple mathematical relation to the line width set: the FWHM is exactly twice the line width.

Here, we first plot the data, and afterwards annotate the plot with an annotation. This is why the plot task as a result set with its result key that is referred to in the annotation task with the plotter key.

27  - kind: singleplot
28    type: SinglePlotter1D
29    properties:
30      properties:
31        axes:
32          xlabel: "$position$ / a.u."
33      parameters:
34        tight_layout: True
35      filename: plotting-annotation-vertical-span.pdf
36    apply_to:
37      - model_data
38    result:
39      - plot-with-vertical-span
40    comment: >
41      Plotter that gets annotated later
42
43  - kind: plotannotation
44    type: VerticalSpan
45    properties:
46      parameters:
47        positions:
48          - [-2, 2]
49      properties:
50        facecolor: green
51        alpha: 0.3
52        zorder: 0
53    plotter: plot-with-vertical-span
54    result: vertical-lines
55    comment: >
56      Two styled vertical span marking the FWHM

Note that you provide a list of positions for the span. As each span has a left and right position, this amounts to a list of lists. Being a list (of lists), this allows you to provide arbitrary numbers of positions for vertical spans.

The appearance of the patches (spans) can be controlled in quite some detail. For the styling available, see the documentation of the aspecd.plotting.PatchProperties class - and use sparingly in scientific context. After all, it is science, not pop art.

The resulting figure is shown below:

../_images/plotting-annotation-vertical-span.png

Fig. 24 Plot with a vertical span as annotation, marking the full width at half maximum (FWHM) of the displayed Lorentzian curve. While not always sensible in scientific context, the span has been styled here using colour, transparency, and zorder. The latter puts the shared area in the background of the figure. Note that here, the plot(ter) has been defined first, with a result key for later reference, and the annotation afterwards, referring to the plotter using the plotter key.