| 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 |
<chapter id="Graph_Plotting" label="8"> |
| 13 |
<title>Graph Plotting</title> |
| 14 |
|
| 15 |
<xi:include href="../phrases/chapterinfo_mod.xml" |
| 16 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 17 |
|
| 18 |
<section id="Graph_Introduction"> |
| 19 |
<title>Introduction</title> |
| 20 |
|
| 21 |
<para>Graph plotting in <productname>Magics</productname> is the plotting of |
| 22 |
line charts (curves), bar charts, area charts and box plots within a |
| 23 |
set of axes.</para> |
| 24 |
|
| 25 |
|
| 26 |
<para>To plot a graph, it is necessary to pass information to |
| 27 |
<productname>Magics</productname> that |
| 28 |
describes the graph required. This information is passed to |
| 29 |
<productname>Magics</productname> via |
| 30 |
one-dimensional arrays, holding the X and Y values of the graph. |
| 31 |
The X/Y values refer to the X and Y axes which may be set up by using |
| 32 |
<productname>Magics</productname> AXIS facilities or may be defined |
| 33 |
automatically from the input graph data.</para> |
| 34 |
|
| 35 |
<para>There are facilities in graph plotting that allow the user to |
| 36 |
control the line style, colour and thickness of each graph and, |
| 37 |
if required, a legend describing the graph may be plotted.</para> |
| 38 |
|
| 39 |
<para>A summary of GRAPH parameters and examples of graph plotting can be found toards the end of this chapter.</para> |
| 40 |
|
| 41 |
|
| 42 |
<important> <title>Magics++</title> |
| 43 |
<productname>Magics++</productname> requires that a user program |
| 44 |
specifies Cartesian projection when plotting graphs: |
| 45 |
|
| 46 |
<programlisting> |
| 47 |
CALL <function>PSETC</function> ('<parameter>SUBPAGE_MAP_PROJECTION</parameter>', 'CARTESIAN') |
| 48 |
</programlisting> |
| 49 |
|
| 50 |
Please do this at the start of your program. This requirement is new to <productname>Magics++</productname>. |
| 51 |
|
| 52 |
</important> |
| 53 |
|
| 54 |
|
| 55 |
|
| 56 |
</section> |
| 57 |
|
| 58 |
|
| 59 |
<section id="Action_Routine_PGRAPH"> |
| 60 |
<title>Action Routine PGRAPH</title> |
| 61 |
|
| 62 |
<para>Plotting of line charts (curves), bar charts, and area charts is |
| 63 |
achieved in <productname>Magics</productname> by calling action routine |
| 64 |
<function>PGRAPH</function> which, like all <productname>Magics</productname> |
| 65 |
action routines, has no arguments. |
| 66 |
<function>PGRAPH</function> will only draw one graph each time it is called. |
| 67 |
Parameters associated with graph plotting may be set before |
| 68 |
<function>PGRAPH</function> is called. <function>PGRAPH</function> will |
| 69 |
take into account only those parameters which have been set before it is called. |
| 70 |
All other graph parameters will be assigned their default values, |
| 71 |
if they exist.</para> |
| 72 |
|
| 73 |
<para>Plotting of box plots is achived by calling a separate action routine, |
| 74 |
<function>PBOXPLOT</function> - see |
| 75 |
<olink targetdoc="Magics_boxplot" targetptr="MAGICS_Boxplots" />.</para> |
| 76 |
</section> |
| 77 |
|
| 78 |
|
| 79 |
<section id="Graph_Plotting_Parameters_Section"> |
| 80 |
<title>Graph Plotting Parameters</title> |
| 81 |
|
| 82 |
<para>Parameters associated with graph plotting start with |
| 83 |
the prefix <parameter>GRAPH</parameter>, |
| 84 |
e.g. <parameter>GRAPH_LINE_STYLE</parameter>. |
| 85 |
These parameters describe the input data and the type of graph |
| 86 |
plotting required, i.e. curve, bar chart or area chart. |
| 87 |
The parameters |
| 88 |
describe the attributes of the graphs, e.g. line style, colour and |
| 89 |
thickness of plotted output. Thus, the user has full control over |
| 90 |
all aspects of graph plotting.</para> |
| 91 |
A full list of GRAPH parameters appears in |
| 92 |
<olink targetdoc="Magics_graph" targetptr="pgraph_tables" /> |
| 93 |
</section> |
| 94 |
|
| 95 |
|
| 96 |
<section id="Graph_Input_Data"> |
| 97 |
<title>Input Data</title> |
| 98 |
|
| 99 |
<para>All input data for graph plotting are passed to |
| 100 |
<productname>Magics</productname> via arrays. |
| 101 |
The parameter <parameter>GRAPH_TYPE</parameter> is used to describe |
| 102 |
the type of graph required. Valid values are <code>CURVE</code> (default), |
| 103 |
<code>BAR</code> and <code>AREA</code>. When set to <code>CURVE</code>, |
| 104 |
two one-dimensional arrays are |
| 105 |
used to pass the data describing the curve, e.g.</para> |
| 106 |
|
| 107 |
<programlisting> |
| 108 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE_X_VALUES</parameter>', XAR, M) |
| 109 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE_Y_VALUES</parameter>', YAR, M) |
| 110 |
</programlisting> |
| 111 |
|
| 112 |
<para>where <code>XAR</code> and <code>YAR</code> are arrays of <code>M</code> elements. |
| 113 |
The first array should contain the X values and the second array should contain |
| 114 |
the Y values.</para> |
| 115 |
|
| 116 |
|
| 117 |
<para>If <parameter>GRAPH_TYPE</parameter> is set to <code>AREA</code>, |
| 118 |
users may shade the area between two curves. The first curve is defined |
| 119 |
in the same way as for <code>CURVE</code> and the second one as follows:</para> |
| 120 |
|
| 121 |
<programlisting> |
| 122 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE2_X_VALUES</parameter>', XAR2, M2) |
| 123 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE2_Y_VALUES</parameter>', YAR2, M2) |
| 124 |
</programlisting> |
| 125 |
|
| 126 |
|
| 127 |
<para>Input data for <code>BAR</code> charts are passed in three arrays as follows:</para> |
| 128 |
|
| 129 |
<programlisting> |
| 130 |
CALL <function>PSET1R</function>('<parameter>GRAPH_BAR_X_VALUES</parameter>', XAR1, M) |
| 131 |
CALL <function>PSET1R</function>('<parameter>GRAPH_BAR_Y_LOWER_VALUES</parameter>', YAR1, M) |
| 132 |
CALL <function>PSET1R</function>('<parameter>GRAPH_BAR_Y_UPPER_VALUES</parameter>', YAR2, M) |
| 133 |
</programlisting> |
| 134 |
|
| 135 |
<para>where <code>XAR1</code>, <code>YAR1</code> and <code>YAR2</code> are arrays of <code>M</code> |
| 136 |
elements each. <code>XAR1</code> should contain the X values for the bars. The lengths |
| 137 |
of the bars in the Y direction are defined by their upper and lower Y values. |
| 138 |
This means that users have the capability of plotting 'hidden' and 'overlapping' |
| 139 |
<code>BAR</code> charts.</para> |
| 140 |
|
| 141 |
|
| 142 |
<para>When the axis system has been set up as a <code>DATE/TIME</code> axis, there are |
| 143 |
separate parameters for the incoming data for all three types of graph plotting. |
| 144 |
For a <code>DATE/TIME</code> curve on the X axis values are passed as follows:</para> |
| 145 |
|
| 146 |
<programlisting> |
| 147 |
CALL <function>PSET1C</function>('<parameter>GRAPH_CURVE_DATE_X_VALUES</parameter>', CXAR, M) |
| 148 |
</programlisting> |
| 149 |
|
| 150 |
|
| 151 |
<para>where <code>CXAR</code> is a character array of <code>M</code> elements. |
| 152 |
Similarly, for a <code>DATE/TIME</code> curve on the Y axis values are passed as follows:</para> |
| 153 |
|
| 154 |
<programlisting> |
| 155 |
CALL <function>PSET1C</function>('<parameter>GRAPH_CURVE_DATE_Y_VALUES</parameter>', CYAR, M) |
| 156 |
</programlisting> |
| 157 |
|
| 158 |
|
| 159 |
<para>The format for date values is given in |
| 160 |
<olink targetdoc="Magics_graph" targetptr="Graph_Mapping_XY_Values" />. |
| 161 |
For <code>BAR</code> and <code>AREA</code> graphs, the values are defined by the parameters:</para> |
| 162 |
|
| 163 |
<programlisting> |
| 164 |
<parameter>GRAPH_BAR_DATE_X_VALUES</parameter> |
| 165 |
<parameter>GRAPH_BAR_DATE_Y_UPPER_VALUES</parameter> |
| 166 |
<parameter>GRAPH_BAR_DATE_Y_LOWER_VALUES</parameter> |
| 167 |
<parameter>GRAPH_CURVE2_DATE_X_VALUES</parameter> |
| 168 |
<parameter>GRAPH_CURVE2_DATE_Y_VALUES</parameter> |
| 169 |
</programlisting> |
| 170 |
|
| 171 |
</section> <!-- end of section Graph_Input_Data --> |
| 172 |
|
| 173 |
|
| 174 |
|
| 175 |
<section id="Graph_Mapping_XY_Values"> |
| 176 |
<title>Mapping of X/Y Values</title> |
| 177 |
|
| 178 |
|
| 179 |
<para>The X and Y values passed by the input arrays are relative to the values of the X and Y |
| 180 |
axes respectively. The X/Y axis system may be defined by setting the parameters |
| 181 |
<parameter>AXIS_MIN_VALUE</parameter> and <parameter>AXIS_MAX_VALUE</parameter> |
| 182 |
to the required values or may be defined automatically. To define the axes automatically, |
| 183 |
the parameter <parameter>GRAPH_AXIS_CONTROL</parameter> should be set to |
| 184 |
<code>AUTOMATIC</code>, the default being <code>OFF</code>. If set to |
| 185 |
<code>AUTOMATIC</code>, <productname>Magics</productname> will calculate |
| 186 |
the minimum and maximum values of the X/Y axes from the incoming GRAPH data. |
| 187 |
When the axis system is not automatic, incoming GRAPH data should be within |
| 188 |
the range of <parameter>AXIS_MIN_VALUE</parameter> and <parameter>AXIS_MAX_VALUE</parameter>. |
| 189 |
Any part of the graph falling outside the current axis limits is not plotted.</para> |
| 190 |
|
| 191 |
<para>Setting <parameter>GRAPH_POSITION_MODE</parameter> to <code>GEOGRAPHIC</code> or |
| 192 |
<code>PAPER</code> allows for the facility of drawing curves on maps. |
| 193 |
It is not necessary to set up an axis system as <productname>Magics</productname> will |
| 194 |
set up a system that matches the current map requirements. If the mode is |
| 195 |
<code>GEOGRAPHIC</code>, the incoming X/Y curve values should be the positions in |
| 196 |
latitude and longitude of the curve points. If set to <code>PAPER</code>, the points |
| 197 |
should be defined as offsets in centimetres from the bottom left hand corner of the |
| 198 |
subpage. This feature applies to curves only and not bars or area curves. |
| 199 |
The default value for <parameter>GRAPH_POSITION_MODE</parameter> is <code>AXIS</code>.</para> |
| 200 |
|
| 201 |
|
| 202 |
<para><code>DATE/TIME</code> axes can be drawn on both horizontal and vertical axes. |
| 203 |
When the axis system has been set up as a <code>DATE/TIME</code> axis, the incoming data |
| 204 |
for all three types of graph plotting should be in format |
| 205 |
<code>YYYY-MM-DD HH:mm:ss</code> (<code>YYYY</code> =year, e.g. 1991), <code>MM</code> =month, |
| 206 |
e.g. June=06, <code>DD</code> =day of month (1-31), <code>HH</code> =hour, <code>mm</code> =minutes, |
| 207 |
<code>ss</code> =seconds). Therefore 1200UTC on 15 June 1991 would have the value |
| 208 |
'<code>1991-06-15 12:00:0</code>' .</para> |
| 209 |
|
| 210 |
<!-- See Date/Time Axis Plotting for full details. --> |
| 211 |
|
| 212 |
</section> <!-- end of section Graph_Mapping_XY_Values --> |
| 213 |
|
| 214 |
|
| 215 |
<section id="Types_of_Graph_Plotting"> |
| 216 |
<title>Types of Graph Plotting</title> |
| 217 |
|
| 218 |
<para>There are three types of graph plotting available, Line Charts (Curves), |
| 219 |
Bar Charts and Area Charts. The type required may be defined by setting the parameter |
| 220 |
<parameter>GRAPH_TYPE</parameter> to '<code>BAR</code>', '<code>AREA</code>' or |
| 221 |
'<code>CURVE</code>' (default).</para> |
| 222 |
|
| 223 |
</section> |
| 224 |
|
| 225 |
|
| 226 |
<section id="Curve_Plotting"> |
| 227 |
<title>Curve Plotting</title> |
| 228 |
|
| 229 |
<para>Curve plotting in <productname>Magics</productname> means the drawing of polylines, |
| 230 |
where the lines to be drawn are described by their X and Y values within a set of X/Y axes. |
| 231 |
Any number of curves may be drawn on the same set of axes. Action routine |
| 232 |
<function>PGRAPH</function> must be called for each curve. |
| 233 |
The user may define the line style, colour and thickness of each curve to be plotted |
| 234 |
by setting the parameters <parameter>GRAPH_LINE_STYLE</parameter>, |
| 235 |
<parameter>GRAPH_LINE_COLOUR</parameter> and <parameter>GRAPH_LINE_THICKNESS</parameter>. |
| 236 |
By using variations of these three parameters, users can plot many curves and still |
| 237 |
distinguish them from one another.</para> |
| 238 |
|
| 239 |
<section id="Methods_of_Curve_Plotting"> |
| 240 |
<title>Methods of Curve Plotting</title> |
| 241 |
|
| 242 |
<para>There are two different methods of drawing curves:</para> |
| 243 |
|
| 244 |
<itemizedlist> |
| 245 |
<listitem> |
| 246 |
<para><code>STRAIGHT</code>, where the points on the curve are joined by straight lines. |
| 247 |
There is no smoothing applied in this case.</para> |
| 248 |
</listitem> |
| 249 |
|
| 250 |
<listitem> |
| 251 |
<para><code>ROUNDED</code>, where a smoothing algorithm is applied to the curve.</para> |
| 252 |
</listitem> |
| 253 |
</itemizedlist> |
| 254 |
|
| 255 |
|
| 256 |
<para>The parameter <parameter>GRAPH_CURVE_METHOD</parameter> should be set to denote |
| 257 |
the method required. The default is to have straight curves. For rounded curves, |
| 258 |
there are various interpolations available, for example <code>SPLINE</code> |
| 259 |
and <code>CUBIC</code>. Users may select an interpolation by setting |
| 260 |
<parameter>GRAPH_CURVE_INTERPOLATION</parameter> to the desired one, the default being |
| 261 |
<code>SPLINE</code>.</para> |
| 262 |
|
| 263 |
<para>The degree of smoothing applied can be controlled by the user setting the parameter |
| 264 |
<parameter>GRAPH_SMOOTHING_FACTOR</parameter> to an integer value. The default is |
| 265 |
<code>3</code> which means that the smoothing algorithm will be applied three times.</para> |
| 266 |
|
| 267 |
<para>It is also possible to plot curves marked with marker symbols. Symbols in this case |
| 268 |
are <productname>Magics</productname> marker symbols |
| 269 |
<!--(see <olink targetdoc="Magics_symbol" targetptr="Symbol_Plotting" /> for details)--> |
| 270 |
and are plotted on the position of each data point on the curve. |
| 271 |
The parameter <parameter>GRAPH_SYMBOL</parameter> controls the plotting of symbols on curves. |
| 272 |
It has three valid values: <code>ON</code>, <code>OFF</code> and <code>SYMBOLS_ONLY</code>:</para> |
| 273 |
|
| 274 |
|
| 275 |
<itemizedlist> |
| 276 |
<listitem> |
| 277 |
<para><code>OFF</code> - No symbol plotting will take place</para> |
| 278 |
</listitem> |
| 279 |
|
| 280 |
<listitem> |
| 281 |
<para><code>ON</code> - A symbol is plotted on the position of each data point in the curve. |
| 282 |
The curve itself will not be drawn in the vicinity of the symbol, i.e. the symbols will be |
| 283 |
blanked. A curve with symbols may be straight or rounded.</para> |
| 284 |
</listitem> |
| 285 |
|
| 286 |
<listitem> |
| 287 |
<para><code>SYMBOLS_ONLY</code> - A symbol is plotted on the position of each data point in the curve. |
| 288 |
The curve itself will not be drawn in the vicinity of the symbol, i.e. the symbols will be |
| 289 |
blanked. A curve with symbols may be straight or rounded.</para> |
| 290 |
</listitem> |
| 291 |
</itemizedlist> |
| 292 |
|
| 293 |
|
| 294 |
<para><parameter>GRAPH_SYMBOL_MARKER_INDEX</parameter> should be set to the index number |
| 295 |
of the marker symbol required. <parameter>GRAPH_SYMBOL_HEIGHT</parameter> |
| 296 |
and <parameter>GRAPH_SYMBOL_COLOUR</parameter> enable the user to control the height |
| 297 |
and colour of the marker symbols.</para> |
| 298 |
|
| 299 |
</section> <!-- end of section Methods_of_Curve_Plotting --> |
| 300 |
|
| 301 |
|
| 302 |
<section id="Blanking_of_Crossing_Curves"> |
| 303 |
<title>Blanking of Crossing Curves</title> |
| 304 |
|
| 305 |
<para>Each curve drawn can have a blanking applied to it, if required. That is, a |
| 306 |
certain area each side of the curve will be blanked and any previous plotting in |
| 307 |
those areas will be deleted. The parameter <parameter>GRAPH_BLANKING</parameter> is |
| 308 |
used to control blanking of curves, the default being '<code>OFF</code>'. |
| 309 |
<parameter>GRAPH_BLANKING_GAP</parameter> may be used to define the width of the |
| 310 |
blanking area around the curve. The default is <code>0.2</code> cm.</para> |
| 311 |
|
| 312 |
</section> |
| 313 |
|
| 314 |
|
| 315 |
<section id="Graph_Curve Missing_Data"> |
| 316 |
<title>Missing Data</title> |
| 317 |
|
| 318 |
<para>Missing data occurs when the data presented for graph plotting contains data |
| 319 |
that is outside the current axis system in either the X or Y direction. |
| 320 |
The user may also instruct <productname>Magics</productname> to ignore data above |
| 321 |
or below certain values. For the Y axis, the parameters |
| 322 |
<parameter>GRAPH_Y_SUPPRESS_ABOVE</parameter> and |
| 323 |
<parameter>GRAPH_Y_SUPPRESS_BELOW</parameter> may be used to achieve this. |
| 324 |
The default values for these parameters are <code>21.E6</code> and <code>-21.E6</code> |
| 325 |
respectively. Similarly, for the X axis, the parameters |
| 326 |
<parameter>GRAPH_X_SUPPRESS_ABOVE</parameter> and |
| 327 |
<parameter>GRAPH_X_SUPPRESS_BELOW</parameter> may be used. |
| 328 |
If data falls outside the axis system but inside the suppress values, |
| 329 |
an error will be printed.</para> |
| 330 |
|
| 331 |
|
| 332 |
<para>For DATE/TIME axis, there are separate suppress parameters:</para> |
| 333 |
<para><parameter>GRAPH_DATE_X_SUPPRESS_ABOVE</parameter></para> |
| 334 |
<para><parameter>GRAPH_DATE_X_SUPPRESS_BELOW</parameter></para> |
| 335 |
<para><parameter>GRAPH_DATE_Y_SUPPRESS_BELOW</parameter></para> |
| 336 |
<para><parameter>GRAPH_DATE_Y_SUPPRESS_ABOVE</parameter></para> |
| 337 |
|
| 338 |
<para>The format of the values for these parameters is the same as for |
| 339 |
<parameter>GRAPH_CURVE_DATE_X_VALUES</parameter> described above |
| 340 |
(see <olink targetdoc="Magics_graph" targetptr="Graph_Mapping_XY_Values" />).</para> |
| 341 |
|
| 342 |
|
| 343 |
<para><productname>Magics</productname> gives the user three options to deal with |
| 344 |
missing data. The parameter <parameter>GRAPH_MISSING_DATA_MODE</parameter> is used to |
| 345 |
control missing data and may be set to one of the three following values: |
| 346 |
<code>IGNORE</code>, <code>JOIN</code> or <code>DROP</code>:</para> |
| 347 |
|
| 348 |
|
| 349 |
<itemizedlist> |
| 350 |
<listitem> |
| 351 |
<para><code>IGNORE</code> - <productname>Magics</productname> will only plot that |
| 352 |
part of the curve for which data exists. This means that, if there are missing data, |
| 353 |
no lines will be drawn from the point preceding the missing data or to the point following.</para> |
| 354 |
</listitem> |
| 355 |
|
| 356 |
<listitem> |
| 357 |
<para><code>JOIN</code> - this option means that the curve will be drawn as if |
| 358 |
the missing points do not exist. In this case the part of the curve, from the |
| 359 |
point preceding the missing data to the point following it, will be drawn.</para> |
| 360 |
</listitem> |
| 361 |
|
| 362 |
<listitem> |
| 363 |
<para><code>DROP</code> - this means that, if there are missing data, the curve |
| 364 |
will continue to be drawn but, the curve will be drawn from the point preceding the |
| 365 |
missing data towards the point outside the axis until it reaches the X axis. It is |
| 366 |
then drawn along the X axis until the last point outside the axis when it will be |
| 367 |
drawn towards the point following the missing data.</para> |
| 368 |
</listitem> |
| 369 |
</itemizedlist> |
| 370 |
|
| 371 |
<para>There are parameters to control the colour, line style and thickness of missing |
| 372 |
data when plotted.</para> |
| 373 |
|
| 374 |
</section> |
| 375 |
|
| 376 |
</section> <!-- end of section Curve_Plotting --> |
| 377 |
|
| 378 |
|
| 379 |
|
| 380 |
<section id="Bar_Chart_Plotting"> |
| 381 |
<title>Bar Chart Plotting</title> |
| 382 |
|
| 383 |
<para>Bar chart plotting in <productname>Magics</productname> is the plotting of |
| 384 |
vertical Bars within an axis system. Each Bar in the chart is defined by its X values |
| 385 |
and by the lower and upper Y values. The X and Y values relate to the X and Y axes |
| 386 |
respectively. X values give the positions of centres of the Bars in the X direction |
| 387 |
and may be passed in an array using the parameter |
| 388 |
<parameter>GRAPH_BAR_X_VALUES</parameter>. The starting positions of the bars in the |
| 389 |
Y direction is given by the values in the array set by the parameter |
| 390 |
<parameter>GRAPH_BAR_Y_LOWER_VALUES</parameter>. The end positions are given by the |
| 391 |
values in the array set by <parameter>GRAPH_BAR_Y_UPPER_VALUES</parameter>. |
| 392 |
If <parameter>GRAPH_BAR_Y_LOWER_VALUES</parameter> is not set by the user, |
| 393 |
<productname>Magics</productname> will assume that all the Y values start at the X axis, |
| 394 |
i.e. they all have a value of 0.0. The width of the Bar may be set by the |
| 395 |
user by setting the parameter <parameter>GRAPH_BAR_WIDTH</parameter> to the desired width. |
| 396 |
The default value for the width is half the distance between major ticks on the X axis. |
| 397 |
If any of the X and Y values would cause any part of the Bar to be drawn outside the |
| 398 |
subpage, this part of the Bar will not be plotted and an error message will be given. |
| 399 |
For <code>DATE/TIME</code> axis the appropriate parameters can be found in |
| 400 |
<olink targetdoc="Magics_graph" targetptr="pgraph_tables" />.</para> |
| 401 |
|
| 402 |
|
| 403 |
<para>The parameter <parameter>GRAPH_SHADE</parameter> should be set to <code>OFF</code> |
| 404 |
if no shading of the bars is required. The default is <code>ON</code>. When shading |
| 405 |
is turned off, the outline of the bars will be drawn. <parameter>GRAPH_SHADE_STYLE</parameter> |
| 406 |
may be set to define the type of shading required. Three types of shading are available: |
| 407 |
<code>AREA_FILL</code> (solid shading), <code>HATCH</code> and <code>DOT</code>. |
| 408 |
<parameter>GRAPH_SHADE_COLOUR</parameter> and <parameter>GRAPH_SHADE_DENSITY</parameter> |
| 409 |
may be set to define the shade colour and density of dots required.</para> |
| 410 |
|
| 411 |
<para>The standard Bar Chart in <productname>Magics</productname> consists of one set of |
| 412 |
data per graph. Action routine <function>PGRAPH</function> will only draw one Bar chart |
| 413 |
each time it is called. However, by using the <productname>Magics</productname> graph |
| 414 |
facilities, users can display more than one set of Bar Chart data on the same graph. |
| 415 |
Following are some examples of bar charts the user can plot. Please note that these |
| 416 |
bar charts are not available in <productname>Magics</productname> by name but can be |
| 417 |
user-generated.</para> |
| 418 |
|
| 419 |
|
| 420 |
<itemizedlist> |
| 421 |
<listitem> |
| 422 |
<para>Clustered. In this case, a different bar chart can be plotted for each different |
| 423 |
set of data. The different bars can be placed next to each other, by varying the X axis |
| 424 |
values, and can be coloured and/or shaded differently.</para> |
| 425 |
</listitem> |
| 426 |
|
| 427 |
<listitem> |
| 428 |
<para>Overlapping. Here, the bars for the second set of data can be moved slightly |
| 429 |
to one side and then plotted over the first set.</para> |
| 430 |
</listitem> |
| 431 |
|
| 432 |
<listitem> |
| 433 |
<para>Hidden. This is like overlapping bars, except that the second set of bars is |
| 434 |
plotted in the same position as the first.</para> |
| 435 |
</listitem> |
| 436 |
|
| 437 |
<listitem> |
| 438 |
<para>Stacked. The second set of bars can be plotted on top of the first set. Thus, |
| 439 |
both sets of bars should be completely visible.</para> |
| 440 |
</listitem> |
| 441 |
</itemizedlist> |
| 442 |
|
| 443 |
|
| 444 |
<para>The above bar charts can only be achieved by calling <function>PGRAPH</function> |
| 445 |
for each set of data to be plotted. It is the user's responsibility to change the |
| 446 |
width, colour, shading etc. of the bars for each call. The parameter |
| 447 |
<parameter>GRAPH_BLANKING</parameter> should be set to '<code>ON</code>' for overlapping |
| 448 |
or hidden bar charts. It is also the user's responsibility to provide the correct |
| 449 |
X values for clustering/overlapping bars and the correct Y values for stacked/hidden bars.</para> |
| 450 |
|
| 451 |
<!--<para>Examples of different types of Bar charts can be found in Graph Program ExamplesXXXX.</para>--> |
| 452 |
|
| 453 |
</section> <!-- end of section Bar_Chart_Plotting --> |
| 454 |
|
| 455 |
|
| 456 |
|
| 457 |
<section id="Area_Chart_Plotting"> |
| 458 |
<title>Area Chart Plotting</title> |
| 459 |
|
| 460 |
<para>An area chart is one in which the area between two curves can be shaded. |
| 461 |
To plot area curves, the parameter <parameter>GRAPH_TYPE</parameter> |
| 462 |
should be set to <code>AREA</code>. Data for the first curve should be passed |
| 463 |
in the same way as for <code>CURVE</code> plotting, e.g.</para> |
| 464 |
|
| 465 |
<programlisting> |
| 466 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE_X_VALUES</parameter>', XAR, M) |
| 467 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE_Y_VALUES</parameter>', YAR, M) |
| 468 |
</programlisting> |
| 469 |
|
| 470 |
<para>The data for the second curve may be passed to <productname>Magics</productname> |
| 471 |
in two arrays as follows:</para> |
| 472 |
|
| 473 |
<programlisting> |
| 474 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE2_X_VALUES</parameter>', XAR2, M2) |
| 475 |
CALL <function>PSET1R</function>('<parameter>GRAPH_CURVE2_Y_VALUES</parameter>', YAR2, M2) |
| 476 |
</programlisting> |
| 477 |
|
| 478 |
|
| 479 |
<para>For <code>DATE/TIME</code> axes the appropriate parameters can be found in |
| 480 |
<olink targetdoc="Magics_graph" targetptr="pgraph_tables" />. |
| 481 |
If the <parameter>CURVE2</parameter> values are not set, it is assumed by |
| 482 |
<productname>Magics</productname> that the second curve is all zeros, i.e. |
| 483 |
the second curve travels along the X axis.</para> |
| 484 |
|
| 485 |
<para>The curve lines will not be plotted. If required, they may be plotted by setting |
| 486 |
<parameter>GRAPH_TYPE</parameter> to <code>CURVE</code> and calling <function>PGRAPH</function> |
| 487 |
again.</para> |
| 488 |
|
| 489 |
<para>The parameter <parameter>GRAPH_SHADE_STYLE</parameter> may be set to define the |
| 490 |
type of shading required. Three types of shading are available: |
| 491 |
<code>AREA_FILL</code> (solid shading), <code>HATCH</code> and <code>DOT</code>. |
| 492 |
The parameters <parameter>GRAPH_SHADE_COLOUR</parameter>, <parameter>GRAPH_SHADE_DOT_SIZE</parameter> |
| 493 |
and <parameter>GRAPH_SHADE_DENSITY</parameter> may be set to define the colour of the |
| 494 |
shading, size and the density of dots required.</para> |
| 495 |
|
| 496 |
<para>There are two type of area charts, straight and rounded, and these are similar to |
| 497 |
straight and rounded curves. The parameter <parameter>GRAPH_CURVE_METHOD</parameter> should |
| 498 |
be set to the required value, the default being straight.</para> |
| 499 |
|
| 500 |
<!--<para>Examples of area charts can be found in Graph Program ExamplesXXXX.</para>--> |
| 501 |
|
| 502 |
</section> <!-- end of section Area_Chart_Plotting --> |
| 503 |
|
| 504 |
|
| 505 |
|
| 506 |
<section id="Graph_Legend"> |
| 507 |
<title>Graph Legend</title> |
| 508 |
|
| 509 |
<para>It is possible to plot a legend to describe the graph(s) plotted. |
| 510 |
This may be achieved by setting the parameter <parameter>LEGEND</parameter> to |
| 511 |
'<code>ON</code>', e.g.</para> |
| 512 |
|
| 513 |
<programlisting> |
| 514 |
CALL <function>PSETC</function>('<parameter>LEGEND</parameter>','ON'). |
| 515 |
</programlisting> |
| 516 |
|
| 517 |
<para> The legend plotted depends on the type of graphs required - bars, curves or area curves. |
| 518 |
A curve legend will basically consist of a description of each curve plotted in the current page, |
| 519 |
i.e. line style, colour, thickness.</para> |
| 520 |
|
| 521 |
<para>If symbols have been plotted, an example will appear in the legend. A bar chart or |
| 522 |
area chart legend will consist of a box filled with the same type of shading as used in |
| 523 |
the plotting.</para> |
| 524 |
|
| 525 |
<para>The legend text in graph plotting should be supplied by the user. If not supplied, |
| 526 |
<productname>Magics</productname> will plot a default text of a question mark (?)</para> |
| 527 |
|
| 528 |
</section> |
| 529 |
|
| 530 |
|
| 531 |
<xi:include href="../paramtables/pgraph_tables.xml" |
| 532 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 533 |
|
| 534 |
|
| 535 |
</chapter> |