You're reading the documentation for a development version. For the latest released version, please have a look at v0.10.
Plot annotations: Vertical span (area)
Classes used:
Models:
Plotting:
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.
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
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:
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.
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
resultkey 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.