Debian Codegraph @

docs/manual/chapters/data.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
15 <chapter id="Data_Input" label="5">
16 <title>Data Input</title>
17
18 <xi:include href="../phrases/chapterinfo_mod.xml"
19 xmlns:xi="http://www.w3.org/2001/XInclude" />
20
21 <section id="Data_Introduction">
22 <title>Introduction</title>
23
24 <para>Data to be plotted can be presented to
25 <productname>Magics</productname> in a number of ways, depending on its
26 type: contour fields, wind fields, observations, symbols, axes, graphs and
27 images.</para>
28
29 <para>A contour field can be presented as either a rectangular array of
30 grid point values or in GRIB code format. GRIB code itself can be
31 presented as either an external file, or as a one dimensional data
32 array.</para>
33
34 <para>A wind field can be presented in GRIB code format or as a pair of
35 rectangular arrays of grid point values<remark>, or as a single rectangular array
36 of wind speed values (when plotting isotachs)</remark>. The pair of rectangular
37 arrays can contain U and V velocity components<remark>, vorticity and divergence
38 components</remark> or speed and direction components of the wind. GRIB code can be
39 presented as either an external file, or as a pair of one dimensional data
40 arrays. <remark>See Wind and Contour ARRAY Input</remark> and <remark>GRIB
41 Code Input</remark> for full details on data input for contouring and wind
42 plotting.</para>
43
44 <para>Observation data must presented as an input file containing
45 observations in WMO standard BUFR code.<remark> See OBSERVATION Data
46 Input</remark>.</para>
47
48 <para>Data for symbol plotting are presented in arrays, which should all
49 have the same number of elements. Two arrays are used to pass the position
50 information. There are four different types of symbol input data: markers,
51 numbers, text and wind. NUMBER input data are passed as an real array,
52 TEXT input data consists of text strings. MARKER input data consists of
53 indices to <productname>Magics</productname> markers and wind input data consists of two arrays
54 containing wind direction and speed respectively. Symbols can be plotted
55 in INDIVIDUAL or TABLE mode. <remark>See SYMBOL Plotting Data
56 Input</remark></para>
57
58 <para>Typically, graph data are presented in two one-dimensional arrays,
59 where one holds the X-axis values and the other holds the Y-axis values.
60 <remark>See GRAPH Data Input</remark></para>
61
62 <para>Satellite Image data must be presented in GRIB code<!--, as described in
63 section <remark>IMAGE Data Input</remark>-->.</para>
64
65 <para>Before presenting data to <productname>Magics</productname>, the
66 users should firstly decide on the type of data and the method by which
67 they wish to present it. The Diagrams with the
68 <productname>Magics</productname> parameter charts in this chapter should
69 help.</para>
70
71 <para>When passing fields in GRIB code format, the necessary
72 <productname>Magics</productname> INPUT parameters are automatically given
73 appropriate values to ensure that a reasonable plot is obtained. When
74 passing fields in array format, the user should select the appropriate
75 values for the <productname>Magics</productname> INPUT parameters.</para>
76
77 <para>Although the use of GRIB input is essentially easier than the use of
78 array input, the description of GRIB input in this chapter occurs after
79 that of array input. This is because the array input description explains
80 the function of those parameters that are set automatically when using
81 GRIB input.</para>
82
83 <para>A contouring plot requires a single data field, whereas a wind plot
84 requires two data fields for its full specification. The two fields can be
85 U and V components or speed and direction components<remark> or vorticity and
86 divergence components. Vorticity and divergence components can only be
87 passed when using GRIB code data input. If isotachs are being plotted,
88 then the field may be specified by the wind speed component only.</remark></para>
89 <important>
90 <title>Magics++</title>
91 Magics++ cannot handle fields in spherical-harmonic representation. The user has to provide
92 the data on a Gaussian or regular grid. This has the advantage that expensive interpolations are not
93 performed when plotting data but at the time of retrieval. Most data users will handle are either in Gaussian or regular grid.
94 </important>
95 <para></para>
96
97 </section>
98
99 <section id="Wind_and_Contour_ARRAY_Input">
100 <title>Wind and Contour ARRAY Input</title>
101
102 <para>Data fields are passed to <productname>Magics</productname> using
103 the routine <function>PSET2R</function> as follows.</para>
104
105 <para>Contouring Fields:</para>
106
107 <programlisting> CALL <function>PSET2R</function> ('<parameter>INPUT_FIELD</parameter>', C, M, N)</programlisting>
108
109 <para>Wind Fields passed by U and V Components for plotting wind arrows
110 and wind flags<remark>, streamlines and isotachs</remark>:</para>
111
112 <programlisting> CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_U_COMPONENT</parameter>', W1, M, N)
113 CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_V_COMPONENT</parameter>', W2, M, N)</programlisting>
114
115 <para>Wind Fields passed by Speed and Direction Components for plotting
116 wind arrows and wind flags<remark>, streamlines and isotachs</remark>:</para>
117
118 <programlisting> CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_SPEED</parameter>', W1, M, N)
119 CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_DIRECTION</parameter>', W2, M, N)</programlisting>
120
121 <remark>
122 <para>Wind Fields passed by Speed Component for plotting isotachs:</para>
123
124 <programlisting> CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_SPEED</parameter>', W1, M, N)</programlisting>
125 </remark>
126
127 <para>where <code>C</code> is an array <code>C(M,N)</code> containing a
128 contouring field, <code>W1</code> and <code>W2</code> are arrays
129 <code>W1(M,N)</code>, <code>W2(M,N)</code> containing the components of a
130 wind field, <code>M</code> is the number of points in the direction of the
131 first index and <code>N</code> is the number of points in the direction of
132 the second index.</para>
133
134 <para>See <olink targetdoc="Magics_data" targetptr="table_InputMatrix_parameters" />
135 for a list of all the available parameters for accessing data stored in
136 arrays.</para>
137
138 </section>
139
140 <section id="Organization_of_the_Input_Field">
141 <title>Organization of the Input Field</title>
142
143 <para>If the field is passed in array form, the user needs to describe how
144 the array is to be mapped onto the subplot or geographical area which the
145 array covers.</para>
146
147 <para>The input field organization is controlled by the parameter
148 <parameter>INPUT_FIELD_ORGANIZATION</parameter> which can have two values:
149 '<code>REGULAR</code>' or '<code>GAUSSIAN</code>',
150 the default value being '<code>REGULAR</code>'.</para>
151
152 <para>For a regular field, the default values for the parameters
153 concerning array organization are set for a global latitude/ longitude
154 field with 1.5 degrees resolution in both directions, going from 90.0
155 degrees north to 90.0 degrees south in latitude and from 0.0 degrees to
156 358.5 degrees in longitude.</para>
157
158 <para>For a gaussian field, the default values for the parameters
159 concerning array organization are set for a global latitude/ longitude
160 field with 1.125 degrees resolution in longitude and 1.1213 degrees in
161 latitude, going from 89.142 degrees north to 89.142 degrees south in
162 latitude and from 0.0 degrees to 358.875 degrees in longitude. (This
163 conforms to a ECMWF T106 model post processed surface field).</para>
164
165
166 <important> <title>Magics++</title>
167 With <productname>Magics++</productname>, the concept of a 'FITTED' matrix no longer
168 exists. The correct approach is to plot in a CARTESIAN projection and set
169 <parameter>INPUT_FIELD_INITIAL_X</parameter>, <parameter>INPUT_FIELD_FINAL_X</parameter>,
170 <parameter>INPUT_FIELD_INITIAL_Y</parameter> and <parameter>INPUT_FIELD_FINAL_Y</parameter>.
171 </important>
172
173 </section>
174
175
176
177
178 <section id="REGULAR_Spaced_Latitude_Longitude_Grid">
179 <title>REGULAR Spaced Latitude/Longitude Grid</title>
180
181 <para>When <parameter>INPUT_FIELD_ORGANIZATION</parameter> is set to
182 '<code>REGULAR</code>' the field is assumed to be on a regular
183 latitude/longitude grid.</para>
184
185 <para><productname>Magics</productname> will perform the contouring in
186 this grid and then plot the result according to the subpage mapping
187 parameters, i.e. the field can either be global or a subpart of the field.
188 Since the contouring is performed in the original grid it is ensured that
189 all field values are taken into account when the isolines are generated.
190 When using this method, a full specification of the input array is
191 required:</para>
192
193 <orderedlist>
194 <listitem>
195 <para>The longitude and latitude position of the first element, (1,1),
196 in the array may be set with the parameters:</para>
197
198 <programlisting> <parameter>INPUT_FIELD_INITIAL_LONGITUDE</parameter>
199 <parameter>INPUT_FIELD_INITIAL_LATITUDE</parameter></programlisting>
200
201 <para>The default values are <code>0.0</code> and <code>90.0</code>,
202 respectively.</para>
203 </listitem>
204
205 <listitem>
206 <para>The step lengths between positions of array elements in
207 longitude and latitude directions are set by using the
208 parameters:</para>
209
210 <programlisting> <parameter>INPUT_FIELD_LONGITUDE_STEP</parameter>
211 <parameter>INPUT_FIELD_LATITUDE_STEP</parameter></programlisting>
212
213 <para>Positive values indicate for longitudes that the positions go
214 from west to east and for latitudes from south to north. Negative
215 values are used to indicate opposite directions.</para>
216
217 <para>The default values are <code>1.5</code> for
218 <parameter>INPUT_FIELD_LONGITUDE_STEP</parameter> and
219 <code>-1.5</code> for
220 <parameter>INPUT_FIELD_LATITUDE_STEP</parameter>.</para>
221 </listitem>
222
223 <listitem>
224 <para>By default the first index of the array refers to longitude
225 positions and the second index refers to latitudes. If these are
226 interchanged, <parameter>INPUT_FIELD_PRIMARY_INDEX</parameter> should
227 be set to '<code>LATITUDE</code>'. Default is
228 '<code>LONGITUDE</code>'.</para>
229 </listitem>
230
231 <listitem>
232 <para>The following is a full list of the default values for
233 describing the default input field with a regular grid.</para>
234
235 <programlisting> <parameter>INPUT_FIELD_INITIAL_LATITUDE</parameter> 90.0
236 <parameter>INPUT_FIELD_INITIAL_LONGITUDE</parameter> 0.0
237 <parameter>INPUT_FIELD_LONGITUDE_STEP</parameter> 1.5
238 <parameter>INPUT_FIELD_LATITUDE_STEP</parameter> -1.5
239 <parameter>INPUT_FIELD_PRIMARY_INDEX</parameter> LONGITUDE</programlisting>
240
241 <para>In the default situation, the contouring or wind field array(s)
242 passed to <productname>Magics</productname> via
243 <function>PSET2R</function> should have dimensions of 240 in the
244 direction of the first index and 121 in the direction of the second
245 index.</para>
246
247 </listitem>
248 </orderedlist>
249 </section>
250
251 <section id="GAUSSIAN_Grid">
252 <title>GAUSSIAN Grid</title>
253
254 <para>When <parameter>INPUT_FIELD_ORGANIZATION</parameter> is set to
255 '<code>GAUSSIAN</code>', <productname>Magics</productname> will accept
256 fields on a gaussian grid, even though the field is not regularly
257 spaced.</para>
258
259 <para>The distance between grid points for gaussian grid fields is regular
260 in the longitude direction but irregular in the latitude direction.
261 However the variance in the grid distance along the irregularly spaced
262 line is small enough that it may be regarded as regular and
263 <productname>Magics</productname> makes this assumption.</para>
264
265 <para>Users should set <parameter>INPUT_FIELD_LATITUDE_STEP</parameter> to
266 the average value of the latitude grid interval, which should be
267 calculated as accurately as possible.</para>
268
269 <para>The following is a full list of the default values for the
270 parameters describing an input field with a gaussian grid. (i.e. an ECMWF
271 T106 model post processed surface field).</para>
272
273 <programlisting><parameter> INPUT_FIELD_INITIAL_LATITUDE</parameter> 89.142
274 <parameter>INPUT_FIELD_INITIAL_LONGITUDE</parameter> 0.0
275 <parameter>INPUT_FIELD_LONGITUDE_STEP</parameter> 1.125
276 <parameter>INPUT_FIELD_LATITUDE_STEP</parameter> 1.1213
277 <parameter>INPUT_FIELD_PRIMARY_INDEX</parameter> LONGITUDE</programlisting>
278
279 <para>In the default situation, the contouring or wind field array(s)
280 passed to <productname>Magics</productname> via
281 <function>PSET2R</function> should have dimensions of 320 in the direction
282 of the first index and 160 in the direction of the second index.</para>
283 </section>
284
285
286 <section id="Data_Suppression">
287 <title>Data Suppression</title>
288
289 <para>By using the suppress parameters
290 <parameter>INPUT_FIELD_SUPPRESS_ABOVE</parameter> and
291 <parameter>INPUT_FIELD_SUPPRESS_BELOW</parameter>, users may suppress data
292 values beyond a certain value in a contouring or wind field. This may be
293 necessary when the user is aware that some of his data are invalid above
294 or below a certain value.</para>
295
296 <para>In the case of a contouring field, suppression means that the data
297 values outside the permitted range are eliminated before any calculation
298 of contour levels or gradient estimation takes place.</para>
299
300 <para>For example, by setting
301 <parameter>INPUT_FIELD_SUPPRESS_ABOVE</parameter> to <code>1.0E20</code> ,
302 all contour levels above <code>1.0E20</code> would be suppressed. Please
303 note that the suppress parameters should only be used to suppress invalid
304 data. If used wrongly, the data plotted may not be accurate, particularly
305 contour maxima/minima values.</para>
306 </section>
307
308 <section id="GRIB_Code_Input">
309 <title>GRIB Code Input</title>
310
311 <para>To facilitate the plotting of GRIB code fields, there is an
312 interface that enables users to plot GRIB code with a minimum of
313 programming effort. The action routine is called <function>PGRIB</function>.</para>
314
315 <para><productname>Magics</productname> uses ECMWF's GRIB_API for the decoding
316 of GRIB files. See
317 <ulink url="http://www.ecmwf.int/products/data/software/grib_api.html">GRIB_API</ulink>
318 for more details.</para>
319
320 <para>Note that the GRIB_API supports the updating of definition files without the
321 need for a new release of the library. This is enabled through setting the environment
322 variable</para>
323
324 <para><code>GRIB_DEFINITION_PATH</code></para>
325
326 <para>to the path where the new definition files reside.</para>
327
328
329
330 <para>See <olink targetdoc="Magics_data" targetptr="pgrib_tables" />
331 for a list of all the available parameters for accessing GRIB data.</para>
332 </section>
333
334 <section id="Pseudo_Action_Routine_PGRIB">
335 <title>Pseudo Action Routine PGRIB</title>
336
337 <para>The pseudo action routine <function>PGRIB</function> allows the
338 automatic processing of GRIB code data. Users may call
339 <function>PGRIB</function> to decode GRIB code data and, if required, to
340 set the appropriate <productname>Magics</productname> input field,
341 contour, wind, image and text parameters. <function>PGRIB</function> can
342 deal with GRIB code on regular and Gaussian grids.<remark> It can also deal with
343 GRIB coded polar stereographic data and with stretched/rotated GRIB
344 data.</remark></para>
345
346 <para>Basically, <function>PGRIB</function> will set up
347 <productname>Magics</productname> parameters for plotting one
348 meteorological field each time it is called. This field could be a wind
349 field, which requires two input GRIB fields, normally U and
350 V. The user will maintain the responsibility for setting up the
351 page layout and mapping parameters as well as calling the action
352 routines to perform the plotting, i.e. <function>PCONT</function>,
353 <function>PWIND</function>, <function>PIMAGE</function> and
354 <function>PTEXT</function>.</para>
355
356 <para>There are some <productname>Magics</productname> parameters
357 associated with <function>PGRIB</function> that should be set before
358 <function>PGRIB</function> is called. These parameters are explained
359 later as are all the functions of <function>PGRIB</function>.</para>
360
361 <para>The format for calling pseudo action routine
362 <function>PGRIB</function> is <code>CALL PGRIB</code>, with no
363 arguments. It is necessary to call <function>PGRIB</function> before any
364 action routine that requires the decoded data. After calling
365 <function>PGRIB</function> and before calling an action routine, the
366 user may set or reset any of the contouring, text, image or wind
367 parameters, if required.<!-- The user may supply two arrays into which
368 <function>PGRIB</function> can pass back information about the type of
369 field, level etc. <function>PGRIB</function> will also set a <productname>Magics</productname>
370 parameter to inform the user which action routine should be called, or
371 if an error has occurred while handling the GRIB code field. This
372 mechanism enables users to decide which actions to take after calling
373 <function>PGRIB</function>.--></para>
374
375 <para>GRIB code may be passed to <productname>Magics</productname> as an
376 input file or in a one dimensional array.</para>
377
378 </section>
379
380 <section id="Functions_of_PGRIB">
381 <title>Functions of PGRIB</title>
382
383 <para>Depending on the user's requirements, <function>PGRIB</function>
384 can perform some or all of the following functions:</para>
385
386 <itemizedlist>
387 <listitem>
388 <para>Decode GRIB data.</para>
389 </listitem>
390
391 <!--
392 <listitem>
393 <para>Convert upper air fields from spectral to grid point, if
394 necessary. The user may supply the resolution of the grid point
395 field by setting a <productname>Magics</productname>
396 parameter.</para>
397 </listitem>
398 -->
399
400 <listitem>
401 <para>Scale the meteorological fields, i.e. convert fields to
402 standard units for plotting purposes, e.g. convert temperature
403 fields from Kelvin to Celsius. The user may request, by setting a
404 <productname>Magics</productname> parameter, that the fields should
405 not be scaled. The standard units used by <function>PGRIB</function>
406 can be found in the section on GRIB Table 2.</para>
407 </listitem>
408
409 <!--
410 a) is this true?
411 b) does the user need to know it?
412 <listitem>
413 <para>Set <parameter>INPUT_FIELD</parameter> parameters to the
414 appropriate values. These parameters include
415 <parameter>INPUT_FIELD_ORGANIZATION</parameter>.
416 <function>PGRIB</function> will handle the setting up of the array
417 for contouring etc by calling <function>PSET2R</function>. This
418 feature relieves the user of the responsibility for setting the
419 <parameter>INPUT_FIELD</parameter> parameters.</para>
420 </listitem>
421 -->
422 <listitem>
423 <para>Build <productname>Magics</productname> text blocks to
424 describe the data field. This text will include such information as
425 time/date and type of field. Users may reset
426 <productname>Magics</productname> text parameters after calling
427 <function>PGRIB</function> and before calling action
428 routines.</para>
429 </listitem>
430
431 <!--
432 This does not seem to be true (as of 06/02/2007)
433 <listitem>
434 <para>Set appropriate <productname>Magics</productname> contouring,
435 wind and image parameters. This is achieved in
436 <productname>Magics</productname> by retrieving the appropriate
437 specification group from a library of such groups. This library
438 contains a separate specification group for each type of
439 meteorological field that is likely to be required. An example of a
440 specification group from the library is given later. Users may reset
441 any contouring or wind parameters by calling the appropriate
442 parameter setting routines after calling <function>PGRIB</function>.
443 <function>PGRIB</function> also sets up the appropriate
444 <productname>Magics</productname> parameters for plotting satellite
445 image data.</para>
446 </listitem>
447 -->
448 <listitem>
449 <para>If the map required is not a global map,
450 <function>PGRIB</function> can extract a subarea from the input
451 field so that it covers almost exactly the geographic area required
452 to be plotted. This helps reduce memory when contouring.</para>
453 </listitem>
454 </itemizedlist>
455 </section>
456
457 <!--
458 <section id="Modes_of_PGRIB">
459 <title>Modes of PGRIB</title>
460
461 <para></para>
462
463 <highlights>
464 <para>Check all of this page for accuracy with regards to
465 Magics++</para>
466 </highlights>
467 </section>
468 -->
469
470
471
472 <section id="Observation_Data_Input">
473 <title>Observation Data Input</title>
474
475 This section needs to be thoroughly reviewed!
476
477 <para>Data for observation plotting may be presented to
478 <productname>Magics</productname> in the form of an input BUFR file<remark> or in an
479 array</remark>.</para>
480
481 <para>The parameter <parameter>OBS_INPUT_TYPE</parameter> may be set to
482 inform <productname>Magics</productname> of the data input type. It
483 should be set to '<code>ARRAY</code>' if the input data is in an array.
484 The default value is '<code>FILE</code>'.</para>
485
486 <para>An array may be used if only one observation is to be plotted, in
487 which case the parameter <parameter>OBS_INPUT_FIELD</parameter> should
488 be set using <function>PSET2R</function>.</para>
489
490 <programlisting>CALL PSET1C ('OBS_INPUT_TYPE', 'ARRAY')
491 CALL PSET1I ('OBS_INPUT_FIELD', IFIELD, N)</programlisting>
492
493 <para>where <code>IFIELD</code> is an integer array of dimension
494 <code>N.</code></para>
495
496 <para><code>For passing more than one observation, an input file should
497 be used, which can contain any number of observations of varying
498 observation types and code types.</code></para>
499
500 <para><code>In this case, the parameter
501 <parameter>OBS_INPUT_FILE_UNIT</parameter> should be set using
502 <function>PSETI</function>, for example:</code> <programlisting>CALL PSETI ('OBS_INPUT_FILE_UNIT', 2)</programlisting></para>
503
504 <para>informs <productname>Magics</productname> that data for
505 observation plotting is on file unit 2.</para>
506 </section>
507
508 <section id="Data_BUFR_Tables">
509 <title>BUFR Tables</title>
510
511 <para>To enable the decoding of observations coded in BUFR, it is
512 necessary to have tables which describe the contents of the BUFR code,
513 e.g. the names and units of parameters, reference values and scale
514 factors. The "parameters", as understood in the BUFR context, include
515 not just the meteorological variables, but also the location of the
516 observation, block/station number, instrumentation etc. Each parameter
517 is described by a descriptor, which is an integer number that uniquely
518 identifies the parameter, e.g. Temperature, Pressure,
519 latitude/longitude, block number. These BUFR tables are stored at an
520 address defined by an environment variable (which is made known to
521 <productname>Magics</productname> installers at the various sites). The
522 tables are then used in the BUFR decoding part of
523 <productname>Magics</productname> and their use is transparent to the
524 user. There are standard descriptor numbers for each of the
525 "parameters". It is possible to use local descriptor numbers instead of
526 the standard ones and these local descriptors would be described in the
527 BUFR tables.</para>
528
529 <para>The EMOSLIB library is used for the handling of BUFR data. It is possible
530 to specify a path to a different set of tables by setting the the environment variable</para>
531 <para><code>BUFR_TABLES</code></para>
532 <para>to the path where the tables reside. An example value for this variable would be:
533 <filename>/home/ma/emos/tables/bufr/linux/000240</filename>.</para>
534
535 </section>
536
537 <section id="Data_BUFR_Parameter_Lists">
538 <title>BUFR Parameter Lists</title>
539
540 <para>To make it possible for <productname>Magics</productname> to be
541 able to plot observations from BUFR code from varying originating
542 centres, which may or may not use local descriptor numbers, it is
543 necessary for <productname>Magics</productname> to be able to identify
544 the descriptor numbers of the meteorological variables and those
545 "parameters" that describe the position and time of the observation. To
546 enable this for each originating centre, there are external files called
547 BUFR Parameter Lists, where each file consists of a list of descriptors
548 for the meteorological variables and the position and time "parameters".
549 For each originating centre, these descriptor numbers should match those
550 in the BUFR Tables described above.</para>
551
552 <para>There are two BUFR Parameter Lists for each originating centre,
553 one for surface observations and one for upper air. Each list consists
554 of entry lines, one entry line per meteorological variable or
555 "parameter". An entry line consists of a descriptor number followed by
556 an ampersand(&amp;) and then, optionally, text to describe the
557 variable.</para>
558
559 <para><token>descriptor &amp; text describing the meteorological
560 variable</token></para>
561
562 <para>For example, the first three lines of the upper air BUFR Parameter
563 List should be as follows:</para>
564
565 <programlisting>11001 &amp; WIND DIRECTION
566 11002 &amp; WIND SPEED
567 10195 &amp; HEIGHT in mtrs</programlisting>
568
569 <para>The position of the line in the list, not the text, is what
570 actually defines the meteorological variable, e.g. the first entry line
571 in the upper air BUFR Parameter Table is always the entry for Wind
572 Direction, the second Wind Speed and the third Height. It is necessary
573 to include each entry line in the file, even if they are not to be used.
574 Complete lists for upper air and surface are given below.</para>
575 </section>
576
577 <section id="Data_Accessing_BUFR_Parameter_Lists">
578 <title>Accessing BUFR Parameter Lists</title>
579
580 <para>There are two modes of accessing the BUFR Parameter Lists in
581 <productname>Magics</productname>. By default, the lists are stored at
582 an address path controlled by an environment variable, which is made
583 known to installers at the various sites. The other mode of access is by
584 setting a <productname>Magics</productname> parameter,
585 <parameter>BUFR_PARAM_TABLE_ADDRESS_PATH</parameter>, to the address
586 path of the tables. This means that users can then force
587 <productname>Magics</productname> to use their own lists. Each upper air
588 list name should have the format <token>bufrtab_ua_nn</token> (surface
589 lists should have the format <token>bufrtab_surf_nn</token> ) where
590 <token>nn</token> is the number of the originating Centre of the BUFR
591 data, e.g. 98 for ECMWF, 85 for France.</para>
592 </section>
593
594 <section id="Data_Surface_BUFR_Parameter_List">
595 <title>Surface BUFR Parameter List</title>
596
597 <para>The ECMWF BUFR Parameter List for surface data,
598 <token>bufrtab_surf_98</token> is as follows (38 lines):</para>
599
600 <programlisting>11011 &amp; WIND DIRECTION at 10 m
601 11012 &amp; WIND SPEED at 10m
602 20001 &amp; HORIZONTAL VISIBILITY
603 20003 &amp; PRESENT WEATHER
604 12004 &amp; TEMPERATURE at 2m
605 20012 &amp; MEDIUM CLOUD
606 20012 &amp; HIGH CLOUD
607 10051 &amp; MSL PRESSURE
608 10063 &amp; PRESSURE TENDENCY CHARACTERISTIC (a)
609 10061 &amp; PRESSURE TENDENCY AMOUNT (pp)
610 20004 &amp; PAST WEATHER (1)
611 20005 &amp; PAST WEATHER (2)
612 20011 &amp; CLOUD AMOUNT (nh)
613 20013 &amp; HEIGHT OF CLOUD BASE (h)
614 20012 &amp; LOW CLOUD
615 12006 &amp; DEWPOINT at 2m
616 22042 &amp; SEA TEMPERATURE
617 1012 &amp; SHIP'S DIRECTION
618 1013 &amp; SHIP'S SPEED
619 20010 &amp; TOTAL CLOUD
620 22002 &amp; DIRECTION OF WIND WAVES
621 22012 &amp; PERIOD OF WIND WAVES
622 22022 &amp; HEIGHT OF WIND WAVES
623 22003 &amp; DIRECTION OF SWELL WAVES
624 22013 &amp; PERIOD OF SWELL WAVES
625 22023 &amp; HEIGHT OF SWELL WAVES
626 22001 &amp; DIRECTION OF WAVES
627 22011 &amp; PERIOD OF WAVES
628 20021 &amp; HEIGHT OF WAVES
629 4004 &amp; HOUR
630 4005 &amp; MINUTE
631 5001 &amp; LATITUDE (HIGH ACCURACY)
632 5002 &amp; LATITUDE (COARSE ACCURACY)
633 6001 &amp; LONGITUDE (HGIH ACCURACY)
634 6002 &amp; LONGITUDE (COARSE ACCURACY)
635 7001 &amp; HEIGHT OF STATION in mtrs
636 7061 &amp; DEPTH BELOW LAND SURFACE
637 12030 &amp; SOIL TEMPERATURES</programlisting>
638
639 <para>To make local surface BUFR Parameter Lists, it is only necessary
640 to copy the above ECMWF surface list to a new list (with an appropriate
641 name) and change the descriptor numbers to the ones to be used locally.
642 It is important that all the above lines are included in each list, even
643 if they are not to be used in plotting.</para>
644
645 <para>The position and time "parameters" are only given in the surface
646 list.</para>
647 </section>
648
649 <section id="Data_Upper_Air_BUFR_Parameter_List">
650 <title>Upper Air BUFR Parameter List</title>
651
652 <para>Following is a listing of all the entries in the ECMWF BUFR
653 Parameter List for upper air, <code>bufrtab_ua_98</code> (18
654 lines):</para>
655
656 <programlisting>11001 &amp; WIND DIRECTION
657 11002 &amp; WIND SPEED
658 10195 &amp; HEIGHT in mtrs
659 12003 &amp; DEW POINT TEMPERATURE
660 12001 &amp; TEMPERATURE
661 7004 &amp; PRESSURE level in pascals
662 7006 &amp; HEIGHT ABOVE STATION in mtrs
663 22042 &amp; SEA TEMPERATURE
664 11003 &amp; U-COMPONENT
665 11004 &amp; V-COMPONENT
666 10003 &amp; HEIGHT in gp mtrs
667 11192 &amp; U-COMPONENT at 10m
668 11193 &amp; V-COMPONENT at 10m
669 7002 &amp; ALTITUDE in mtrs
670 12007 &amp; VIRTUAL TEMPERATURE
671 13016 &amp; PRECIPITABLE WATER
672 20010 &amp; TOTAL CLOUD
673 10004 &amp; PRESSURE in pascals</programlisting>
674
675 <para>To make local upper air BUFR Parameter Lists, it is only necessary
676 to copy the above ECMWF upper air list to a new list (with an
677 appropriate name) and change the descriptor numbers to the ones to be
678 used locally. It is important that all the above lines are included in
679 each list, even if they are not to be used in plotting.</para>
680
681 <highlights>
682 <para>Diagram 8</para>
683 </highlights>
684 </section>
685
686
687
688 <section id="SYMBOL_Plotting_Data_Input">
689 <title>Symbol Plotting Data Input</title>
690
691 <para>There are three different types of SYMBOL input data, i.e. numbers,
692 text and markers. The parameter <parameter>SYMBOL_TYPE</parameter> is used
693 to define the type of symbol required, e.g.</para>
694
695 <programlisting> CALL <function>PSETC</function> ('<parameter>SYMBOL_TYPE</parameter>','MARKER')</programlisting>
696
697 <para>It can have one of four values, <code>NUMBER</code> (default),
698 <code>TEXT</code>, <code>MARKER</code> or <code>WIND</code>. Only one of
699 the above four types can be plotted in any one call to
700 <function>PSYMB</function>.</para>
701
702 <para><code>NUMBER</code> input data are the actual numbers to be plotted
703 and are passed as follows:</para>
704
705 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_INPUT_NUMBER_LIST</parameter>',RARAY,N)</programlisting>
706
707 <para>where <code>RARAY</code> is a real array of <code>N</code>
708 elements.</para>
709
710 <para><code>TEXT</code> input data consists of text strings which are to
711 be plotted and are passed as follows:</para>
712
713 <programlisting> CALL <function>PSET1C</function> ('<parameter>SYMBOL_INPUT_TEXT_LIST</parameter>',CARAY,N)</programlisting>
714
715 <para>where <code>CARAY</code> is a character array of <code>N</code>
716 elements.</para>
717
718 <para><code>MARKER</code> input data consists of indices to
719 <productname>Magics</productname> markers<remark>(see Figure XII-2 on page
720 XII-13)</remark> and are passed as follows:</para>
721
722 <programlisting> CALL <function>PSET1I</function> ('<parameter>SYMBOL_INPUT_MARKER_LIST</parameter>',IARAY,N)</programlisting>
723
724 <para>where <code>IARAY</code> is an integer array of <code>N</code>
725 elements.</para>
726
727 <para><code>WIND</code> data consists of the wind speed and direction and
728 are passed as follows:</para>
729
730 <programlisting> CALL <function>PSETR</function> ('<parameter>SYMBOL_INPUT_WIND_SPEED</parameter>', SPARAY,N)
731 CALL <function>PSETR</function> ('<parameter>SYMBOL_INPUT_WIND_DIRECTION</parameter>',DARAY,N)</programlisting>
732
733 <para>where <code>SPARAY</code> and <code>DARAY</code> are real arrays of
734 <code>N</code> elements.</para>
735
736 <para>The <code>POSITION</code> arrays and the <code>DATA INPUT</code>
737 arrays should all have the same number of elements. The symbol in the i-th
738 element of the <code>DATA</code> array will be plotted in the position
739 given by the i-th elements of the <code>POSITION</code> arrays. It is the
740 user's responsibility to ensure that they correspond correctly. If the
741 arrays are of different lengths, <productname>Magics</productname> will
742 limit all the arrays to the size of the smallest array and a warning
743 message will be printed.</para>
744
745 <para><code>TABLE</code> mode allows users to plot symbols within
746 specified ranges of values and with varying colours and heights. To plot
747 symbols in <code>TABLE</code> mode the parameter
748 <parameter>SYMBOL_TABLE_MODE</parameter> should be set to
749 '<code>ON</code>' . When calling <function>PSYMB</function> in
750 <code>TABLE</code> mode, the user must pass information to
751 <productname>Magics</productname> to describe the minimum and maximum of
752 each range required and may also pass information to describe the height
753 and/or colour for each of the desired ranges. All this information should
754 be passed in the form of tables and <productname>Magics</productname>
755 parameters exist to enable this. <remark>Example PROGRAM DATA05 gives a
756 description of plotting NUMBER symbols in TABLE mode.</remark> The
757 parameters for passing the minimum and maximum of the ranges are
758 <parameter>SYMBOL_MIN_TABLE</parameter> and
759 <parameter>SYMBOL_MAX_TABLE</parameter> , respectively. The minimum values
760 of the required ranges may be passed to <productname>Magics</productname>
761 as follows:</para>
762
763 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_MIN_TABLE</parameter>',RMIN,N)</programlisting>
764
765 <para>where <code>RMIN</code> is a real array of <code>N</code> elements.
766 The maximum values should be placed in the corresponding elements of an
767 array and passed to <productname>Magics</productname> as follows:</para>
768
769 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_MAX_TABLE</parameter>',RMAX,N)</programlisting>
770
771 <para>where <code>RMAX</code> is a real array of <code>N</code> elements.
772 The colour to be used for each of the ranges may be passed using the
773 parameter <parameter>SYMBOL_COLOUR_TABLE</parameter>, e.g.</para>
774
775 <programlisting> CALL <function>PSET1C</function> ('<parameter>SYMBOL_COLOUR_TABLE</parameter>',COLTAB,N)</programlisting>
776
777 <para>where <code>COLTAB</code> is a character array of <code>N</code>
778 elements. Similarly, the heights for each range may be passed as
779 follows:</para>
780
781 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_HEIGHT_TABLE</parameter>',HGTAB,N)</programlisting>
782
783 <para>The following will enable the passing of text for each of the ranges
784 in table mode:</para>
785
786 <programlisting> CALL <function>PSET1C</function> ('<parameter>SYMBOL_TEXT_TABLE</parameter>',TEXTAB,N)</programlisting>
787
788 <para>Passing marker data for each of the ranges in table mode is achieved
789 as follows:</para>
790
791 <programlisting> CALL <function>PSET1I</function> ('<parameter>SYMBOL_MARKER_TABLE</parameter>',SYMTAB,N)</programlisting>
792
793 </section>
794
795
796 <section id="ODB_Input">
797 <title>ODB Data Input</title>
798
799 <para>With <productname>Magics++</productname>, <productname>Magics</productname> has the facility
800 to import data from an ODB database using the action routine
801 <function>PODB</function> and its associated parameters. A portion of
802 FORTRAN code will show the basic usage and a discussion will
803 follow.</para>
804
805 <programlisting>
806 CALL <function>PSETC</function>('<parameter>odb_database</parameter>',
807 + 'odb://server/dir/subdir/database_file')
808
809 CALL <function>PSETC</function> ('<parameter>odb_query</parameter>',
810 + 'SELECT lat, lon, obsvalue
811 + FROM hdr, body
812 + WHERE varno=$t2m AND obsvalue IS NOT null')
813
814 CALL <function>PSETC</function> ('<parameter>odb_latitude</parameter>', 'lat@hdr')
815 CALL <function>PSETC</function> ('<parameter>odb_longitude</parameter>', 'lon@hdr')
816 CALL <function>PSETC</function> ('<parameter>odb_observation</parameter>', 'obsvalue@body')
817 CALL <function>PSETI</function> ('<parameter>odb_nb_rows</parameter>', 200000)
818 CALL <function>PODB</function>
819 </programlisting>
820
821 <para>The first thing is to set the path to the database using the
822 parameter <parameter>ODB_DATABASE</parameter>. An SQL query to retrieve
823 the data is set in the parameter <parameter>ODB_QUERY</parameter>.
824 Parameters <parameter>ODB_LATITUDE</parameter>,
825 <parameter>ODB_LONGITUDE</parameter> and
826 <parameter>ODB_OBSERVATION</parameter> are used to identify the columns
827 containing the latitude, longitude and observation values in the data;
828 also available is the parameter <parameter>ODB_LEVEL</parameter>.</para>
829
830 <para>For curve plotting, the parameters <parameter>ODB_X</parameter> and
831 <parameter>ODB_Y</parameter> can be set to the names of the columns to be
832 used for the x- and y-coordinates.</para>
833
834 <para><remark>ODB_PARAMETERS</remark></para>
835
836 <para>The start row and the maximum number of rows to retrieve can be set
837 using the parameters <parameter>ODB_STARTING_ROW</parameter> and
838 <parameter>ODB_NB_ROWS</parameter> respectively.</para>
839
840 <para>Finally, the action routine <function>PODB</function> is called
841 without any parameters. The resulting data may be plotting using the
842 symbol plotting routines
843 <!--(see <olink targetdoc="Magics_symbol" targetptr="Symbol_Plotting" />) -->
844 or the curve plotting routines<remark>(see ???)</remark>.</para>
845
846 <para>Note that the automatic title that <productname>Magics++</productname> produces
847 for data retrieved from the ODB data is the query itself.</para>
848
849 <!--<para>See <olink targetdoc="Magics_data" targetptr="table_OdbDecoder_parameters" />
850 for a list of all the available parameters for accessing ODB data.</para>-->
851
852 </section>
853
854 <section id="NetCDF_Data_Input">
855 <title>NetCDF Data Input</title>
856
857 <para><productname>Magics++</productname> is capable of
858 reading NetCDF data files. A
859 portion of FORTRAN code will show the basic usage and a discussion will
860 follow.</para>
861
862 <programlisting>
863 CALL <function>PSETC</function> ('<parameter>NETCDF_FILENAME</parameter>', 'data/rh850.nc')
864 CALL <function>PSETC</function> ('<parameter>NETCDF_FIELD_VARIABLE_NAME</parameter>', 'r')
865 CALL <function>PSETC</function> ('<parameter>NETCDF_LATITUDE_VARIABLE_NAME</parameter>', 'latitude')
866 CALL <function>PSETC</function> ('<parameter>NETCDF_LONGITUDE_VARIABLE_NAME</parameter>', 'longitude')
867 CALL <function>PSETR</function> ('<parameter>NETCDF_FIELD_SCALING_FACTOR</parameter>', 1.0)
868 CALL <function>PSETR</function> ('<parameter>NETCDF_FIELD_ADD_OFFSET</parameter>', 0.0)
869 CALL <function>PNETCDF</function>
870 </programlisting>
871
872 <para>The path to the file to be read is set via
873 <parameter>NETCDF_FILENAME</parameter>. The variables in the NetCDF file
874 to be used as latitude, longitude and value are specified using the
875 parameters <parameter>NETCDF_LATITUDE_VARIABLE_NAME</parameter>,
876 <parameter>NETCDF_LONGITUDE_VARIABLE_NAME</parameter>, and
877 <parameter>NETCDF_FIELD_VARIABLE_NAME</parameter> respectively. The
878 resultant data values can be multiplied by setting
879 <parameter>NETCDF_FIELD_SCALING_FACTOR</parameter> to a value other than
880 <code>1.0</code>, and a constant added to each value via the parameter
881 <parameter>NETCDF_FIELD_ADD_OFFSET</parameter>.</para>
882
883 <para><remark>Parameters netcdf_dimension_setting, netcdf_x_variable_name,
884 netcdf_y_variable_name, netcdf_y_transformation, netcdf_type,
885 netcdf_convention.</remark></para>
886
887 <para>Finally, the action routine <function>PNETCDF</function> is called
888 without any parameters. Note that in the above example, most of the
889 parameters are not required as their default values are the same. See
890 <olink targetdoc="Magics_data" targetptr="pnetcdf_tables" />
891 for the complete list of parameters and their defaults.<!-- See
892 <olink targetdoc="Magics_data" targetptr="Program_data_netcdf" /> for
893 a complete program which further illustrates the use of NetCDF data
894 in <productname>Magics</productname>.--></para>
895
896 <para>Note that <productname>Magics</productname> does not currently produce
897 an automatic title for NetCDF data - an appropriate title should be
898 supplied by the user.</para>
899 </section>
900
901 <section id="GRAPH_Data_Input">
902 <title>GRAPH Data Input</title>
903
904 <para>All input data for graph plotting are passed to
905 <productname>Magics</productname> via arrays. The parameter
906 <parameter>GRAPH_TYPE</parameter> is used to describe the type of graph
907 required. Valid values are <code>CURVE</code> (default), <code>BAR</code>
908 and <code>AREA</code>.</para>
909
910 <para>When set to <code>CURVE</code>, two one-dimensional arrays are used
911 to pass the data describing the curve, e.g.</para>
912
913 <programlisting> CALL <function>PSET1R</function> ('<parameter>GRAPH_CURVE_X_VALUES</parameter>',XAR,M)
914 CALL <function>PSET1R</function> ('<parameter>GRAPH_CURVE_Y_VALUES</parameter>',YAR,M)</programlisting>
915
916 <para>where <code>XAR</code> and <code>YAR</code> are arrays of
917 <code>M</code> elements. The first array should contain the X values and
918 the second array should contain the Y values.</para>
919
920 <para>If <parameter>GRAPH_TYPE</parameter> is set to '<code>AREA</code>' ,
921 users may shade the area between two curves. The first curve is defined in
922 the same way as for '<code>CURVE</code>' and the second one as
923 follows:</para>
924
925 <programlisting> CALL <function>PSET1R</function> ('<parameter>GRAPH_CURVE2_X_VALUES</parameter>',XAR2,M2)
926 CALL <function>PSET1R</function> ('<parameter>GRAPH_CURVE2_Y_VALUES</parameter>',YAR2,M2)</programlisting>
927
928 <para>Input data for <code>BAR</code> charts are passed in three arrays as
929 follows:</para>
930
931 <programlisting> CALL <function>PSET1R</function> ('<parameter>GRAPH_BAR_X_VALUES</parameter>',XAR1,M)
932 CALL <function>PSET1R</function> ('<parameter>GRAPH_BAR_Y_LOWER_VALUES</parameter>',YAR1,M)
933 CALL <function>PSET1R</function> ('<parameter>GRAPH_BAR_Y_UPPER_VALUES</parameter>',YAR2,M)</programlisting>
934
935 <para>where <code>XAR1</code>, <code>YAR1</code> and <code>YAR2</code> are
936 arrays of <code>M</code> elements each. <code>XAR1</code> should contain
937 the X values for the bars. The lengths of the bars in the Y direction are
938 defined by their upper and lower Y values. This means that users have the
939 capability of plotting 'hidden' and 'overlapping' <code>BAR</code>
940 charts.</para>
941 </section>
942
943
944 <xi:include href="../paramtables/pgrib_tables.xml"
945 xmlns:xi="http://www.w3.org/2001/XInclude" />
946
947 <!--
948 <xi:include href="../paramtables/pbufr_tables.xml"
949 xmlns:xi="http://www.w3.org/2001/XInclude" />
950 -->
951
952 <xi:include href="../paramtables/pnetcdf_tables.xml"
953 xmlns:xi="http://www.w3.org/2001/XInclude" />
954
955 <!--
956 <xi:include href="../paramtables/psymb_tables.xml"
957 xmlns:xi="http://www.w3.org/2001/XInclude" />
958 -->
959
960 <!--
961 <xi:include href="../paramtables/podb_tables.xml"
962 xmlns:xi="http://www.w3.org/2001/XInclude" />
963 -->
964
965
966 <xi:include href="../paramtables/input_matrix_tables.xml"
967 xmlns:xi="http://www.w3.org/2001/XInclude" />
968
969
970
971 <section id = 'GRIB_input_magml_all_tables'>
972 <title>MagML Templates for GRIB Input</title>
973
974 <xi:include href="../paramtables/GribDecoder_grib_magml_tables.xml"
975 xmlns:xi="http://www.w3.org/2001/XInclude" />
976
977 <xi:include href="../paramtables/GribDecoder_grib_magml_flat_tables.xml"
978 xmlns:xi="http://www.w3.org/2001/XInclude" />
979 </section>
980
981
982 <section id = 'GRIBloop_input_magml_all_tables'>
983 <title>MagML Templates for GRIB Loop Input</title>
984 <xi:include href="../paramtables/GribLoop_gribloop_magml_tables.xml"
985 xmlns:xi="http://www.w3.org/2001/XInclude" />
986
987 <xi:include href="../paramtables/GribLoop_gribloop_magml_flat_tables.xml"
988 xmlns:xi="http://www.w3.org/2001/XInclude" />
989 </section>
990
991
992 <!--
993 <xi:include href="../paramtables/ObsDecoder_bufr_magml_tables.xml"
994 xmlns:xi="http://www.w3.org/2001/XInclude" />
995 -->
996
997 <section id = 'NetCDF_input_magml_all_tables'>
998 <title>MagML Templates for NetCDF Input</title>
999
1000 <xi:include href="../paramtables/NetcdfDecoder_netcdf_magml_tables.xml"
1001 xmlns:xi="http://www.w3.org/2001/XInclude" />
1002
1003 <xi:include href="../paramtables/NetcdfDecoder_netcdf_magml_flat_tables.xml"
1004 xmlns:xi="http://www.w3.org/2001/XInclude" />
1005 </section>
1006
1007 <!--
1008 <xi:include href="../paramtables/OdbDecoder_odb_magml_tables.xml"
1009 xmlns:xi="http://www.w3.org/2001/XInclude" />
1010 -->
1011
1012 <!--
1013 <xi:include href="../paramtables/ImportAction_magml_tables.xml"
1014 xmlns:xi="http://www.w3.org/2001/XInclude" />
1015 -->
1016
1017 <!--
1018 <xi:include href="../paramtables/SimplePolylineInput_magml_tables.xml"
1019 xmlns:xi="http://www.w3.org/2001/XInclude" />
1020 -->
1021
1022 <section id="Data_Program_Examples">
1023 <title>Program Examples</title>
1024
1025 <para>These examples illustrate the use of the data input
1026 facilities in <productname>Magics</productname>.</para>
1027 </section>
1028
1029 <xi:include href="../examples/manual/xml/data_examples.xml"
1030 xmlns:xi="http://www.w3.org/2001/XInclude" />
1031
1032
1033 <!--
1034 <xi:include href="../paramtables/data_input_tables.xml"
1035 xmlns:xi="http://www.w3.org/2001/XInclude" />
1036 -->
1037
1038 </chapter>