| 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(&) and then, optionally, text to describe the |
| 557 |
variable.</para> |
| 558 |
|
| 559 |
<para><token>descriptor & 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 & WIND DIRECTION |
| 566 |
11002 & WIND SPEED |
| 567 |
10195 & 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 & WIND DIRECTION at 10 m |
| 601 |
11012 & WIND SPEED at 10m |
| 602 |
20001 & HORIZONTAL VISIBILITY |
| 603 |
20003 & PRESENT WEATHER |
| 604 |
12004 & TEMPERATURE at 2m |
| 605 |
20012 & MEDIUM CLOUD |
| 606 |
20012 & HIGH CLOUD |
| 607 |
10051 & MSL PRESSURE |
| 608 |
10063 & PRESSURE TENDENCY CHARACTERISTIC (a) |
| 609 |
10061 & PRESSURE TENDENCY AMOUNT (pp) |
| 610 |
20004 & PAST WEATHER (1) |
| 611 |
20005 & PAST WEATHER (2) |
| 612 |
20011 & CLOUD AMOUNT (nh) |
| 613 |
20013 & HEIGHT OF CLOUD BASE (h) |
| 614 |
20012 & LOW CLOUD |
| 615 |
12006 & DEWPOINT at 2m |
| 616 |
22042 & SEA TEMPERATURE |
| 617 |
1012 & SHIP'S DIRECTION |
| 618 |
1013 & SHIP'S SPEED |
| 619 |
20010 & TOTAL CLOUD |
| 620 |
22002 & DIRECTION OF WIND WAVES |
| 621 |
22012 & PERIOD OF WIND WAVES |
| 622 |
22022 & HEIGHT OF WIND WAVES |
| 623 |
22003 & DIRECTION OF SWELL WAVES |
| 624 |
22013 & PERIOD OF SWELL WAVES |
| 625 |
22023 & HEIGHT OF SWELL WAVES |
| 626 |
22001 & DIRECTION OF WAVES |
| 627 |
22011 & PERIOD OF WAVES |
| 628 |
20021 & HEIGHT OF WAVES |
| 629 |
4004 & HOUR |
| 630 |
4005 & MINUTE |
| 631 |
5001 & LATITUDE (HIGH ACCURACY) |
| 632 |
5002 & LATITUDE (COARSE ACCURACY) |
| 633 |
6001 & LONGITUDE (HGIH ACCURACY) |
| 634 |
6002 & LONGITUDE (COARSE ACCURACY) |
| 635 |
7001 & HEIGHT OF STATION in mtrs |
| 636 |
7061 & DEPTH BELOW LAND SURFACE |
| 637 |
12030 & 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 & WIND DIRECTION |
| 657 |
11002 & WIND SPEED |
| 658 |
10195 & HEIGHT in mtrs |
| 659 |
12003 & DEW POINT TEMPERATURE |
| 660 |
12001 & TEMPERATURE |
| 661 |
7004 & PRESSURE level in pascals |
| 662 |
7006 & HEIGHT ABOVE STATION in mtrs |
| 663 |
22042 & SEA TEMPERATURE |
| 664 |
11003 & U-COMPONENT |
| 665 |
11004 & V-COMPONENT |
| 666 |
10003 & HEIGHT in gp mtrs |
| 667 |
11192 & U-COMPONENT at 10m |
| 668 |
11193 & V-COMPONENT at 10m |
| 669 |
7002 & ALTITUDE in mtrs |
| 670 |
12007 & VIRTUAL TEMPERATURE |
| 671 |
13016 & PRECIPITABLE WATER |
| 672 |
20010 & TOTAL CLOUD |
| 673 |
10004 & 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> |