Debian Codegraph @

docs/manual/chapters/boxplot.xml

raw
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 (C) Copyright 1996-2016 ECMWF.
4
5 This software is licensed under the terms of the Apache Licence Version 2.0
6 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
7 In applying this licence, ECMWF does not waive the privileges and immunities
8 granted to it by virtue of its status as an intergovernmental organisation nor
9 does it submit to any jurisdiction.
10 -->
11
12 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
13 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
14 <chapter id="MAGICS_Boxplots" label="10">
15 <title>Boxplot Plotting</title>
16
17 <xi:include href="../phrases/chapterinfo_mod.xml"
18 xmlns:xi="http://www.w3.org/2001/XInclude" />
19
20 <section id="Boxplot_Introduction">
21 <title>Introduction</title>
22
23 <para>A boxplot is a way of visually summarising the
24 distribution of a set of data. Three components of the boxplot
25 show the following information:</para>
26
27 <itemizedlist>
28 <listitem>
29 <para>Box: the upper and lower bounds of the box typically show
30 the 25th and 75th percentiles (interquartile range), although in
31 practice they could represent different percentiles.</para>
32 </listitem>
33 <listitem>
34 <para>Median line: a line across the box shows the position of
35 the median. </para>
36 </listitem>
37 <listitem>
38 <para>Whiskers: two vertical lines coming out of the box show
39 the extent of the data which are not considered outliers.</para>
40 </listitem>
41 </itemizedlist>
42
43 <para>The following diagram shows a sample boxplot:</para>
44
45 <figure id="figure_sample_boxplot">
46 <title>A Sample Boxplot</title>
47 <mediaobject id="boxplot_example">
48 <imageobject role="fo">
49 <imagedata fileref="../diagrams/diagram_boxplot.gif" format="GIF"
50 width="8cm" depth="8cm" align="center"/>
51 </imageobject>
52
53 <imageobject role="html">
54 <imagedata fileref="images/diagrams/diagram_boxplot.gif" format="GIF"
55 align="center"/>
56 </imageobject>
57 </mediaobject>
58 </figure>
59
60
61 <para><productname>Magics</productname> allows the user to pass data
62 representing these values in array form, defining several
63 boxplots at the one time. Then all may be plotted with a single
64 action routine, <function>PBOXPLOT</function>.</para>
65
66 <para>Various parameters exist to control the style and plotting
67 attributes of the boxplots. They start with
68 the prefix <parameter>BOXPLOT</parameter>,
69 e.g. <parameter>BOXPLOT_BOX_COLOUR</parameter>.
70 These parameters describe the input data and plotting attributes.</para>
71
72 <para>A summary of BOXPLOT parameters, error codes and program examples
73 of graph plotting are in later sections.</para>
74 </section>
75
76
77 <section id="Boxplot_Input_Data">
78 <title>Input Data</title>
79
80 <para>All input data for boxplot plotting are passed to
81 <productname>Magics</productname> via arrays. Each array defines
82 the values for one parameter for multiple boxplots. The following
83 FORTRAN listing shows how to pass these arrays to
84 <productname>Magics</productname>:</para>
85
86
87 <programlisting>
88 CALL <function>PSET1R</function>('<parameter>BOXPLOT_POSITIONS</parameter>', XARR, M)
89 CALL <function>PSET1R</function>('<parameter>BOXPLOT_MINIMUM_VALUES</parameter>', MINARR, M)
90 CALL <function>PSET1R</function>('<parameter>BOXPLOT_MAXIMUM_VALUES</parameter>', MAXARR, M)
91 CALL <function>PSET1R</function>('<parameter>BOXPLOT_MEDIAN_VALUES</parameter>', MEDARR, M)
92 CALL <function>PSET1R</function>('<parameter>BOXPLOT_BOX_UPPER_VALUES</parameter>', UPPARR, M)
93 CALL <function>PSET1R</function>('<parameter>BOXPLOT_BOX_LOWER_VALUES</parameter>', LOWARR, M)
94 </programlisting>
95
96
97 <para>Note that the first line in this example sets up
98 the list of coordinates at which the data will be plotted. Although it
99 is not strictly data input as such, it is useful to include it here
100 in order to provide a complete piece of code.</para>
101
102 </section>
103
104
105 <section id="Boxplot_Mapping">
106 <title>Mapping of X/Y Values</title>
107
108 <para>The X and Y values passed by the input arrays are relative to the
109 values of the X and Y axes respectively. The X/Y axis system may be defined
110 by setting the parameters <parameter>AXIS_MIN_VALUE</parameter> and
111 <parameter>AXIS_MAX_VALUE</parameter> to the required values. Incoming
112 BOXPLOT data should be within the range of the axes. Any part of a boxplot
113 falling outside the current axis limits is not plotted.</para>
114 </section>
115
116
117
118 <section id="Boxplot_Plotting">
119 <title>Boxplot Plotting</title>
120
121 <para>Once the input data has been set up as described in the previous section,
122 there are only two things left to consider: the positioning of the
123 data plots and the plotting attributes.</para>
124
125 <para>As already mentioned in the previous section, the parameter
126 <parameter>BOXPLOT_POSITIONS</parameter> is used to set up the coordinates
127 at which the boxplots will be plotted. Note that each boxplot has only
128 one coordinate, as the other is determined by the data values.</para>
129
130 <para>The parameters starting with <parameter>BOXPLOT_BOX</parameter>
131 change the plotting behaviour of the interquartile range box such
132 as colour and width.</para>
133
134 <para>The parameters starting with <parameter>BOXPLOT_MEDIAN</parameter>
135 change the plotting behaviour of the median line such
136 as colour and thickness.</para>
137
138 <para>The parameters starting with <parameter>BOXPLOT_WHISKER</parameter>
139 change the plotting behaviour of the whisker. There are two styles of
140 whisker plotting: line and box. When <parameter>BOXPLOT_WHISKER</parameter>
141 is set to <code>LINE</code>, the whiskers are drawn as lines and are
142 affected by the parameters starting with
143 <parameter>BOXPLOT_WHISKER_LINE</parameter>.
144 When <parameter>BOXPLOT_WHISKER</parameter>
145 is set to <code>BOX</code>, the whiskers are drawn as filled boxes and are
146 affected by the parameters starting with
147 <parameter>BOXPLOT_WHISKER_BOX</parameter>.</para>
148 </section>
149
150
151
152 <xi:include href="../paramtables/pboxplot_tables.xml"
153 xmlns:xi="http://www.w3.org/2001/XInclude" />
154 <!--
155 <xi:include href="../paramtables/BoxPlotVisualiser_boxplot_magml_tables.xml"
156 xmlns:xi="http://www.w3.org/2001/XInclude" />
157
158 <xi:include href="../paramtables/BoxPlotVisualiser_boxplot_magml_flat_tables.xml"
159 xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
160
161 <section id="Boxplot_Program_Examples">
162 <title>Program Examples</title>
163
164 <para>The following examples demonstrate the use of boxplots.</para>
165 </section>
166
167 <xi:include href="../examples/manual/xml/boxplot_examples.xml"
168 xmlns:xi="http://www.w3.org/2001/XInclude" />
169
170 </chapter>