| 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> |