Data Input
Introduction
Data to be plotted can be presented to
Magics in a number of ways, depending on its
type: contour fields, wind fields, observations, symbols, axes, graphs and
images.
A contour field can be presented as either a rectangular array of
grid point values or in GRIB code format. GRIB code itself can be
presented as either an external file, or as a one dimensional data
array.
A wind field can be presented in GRIB code format or as a pair of
rectangular arrays of grid point values, or as a single rectangular array
of wind speed values (when plotting isotachs). The pair of rectangular
arrays can contain U and V velocity components, vorticity and divergence
components or speed and direction components of the wind. GRIB code can be
presented as either an external file, or as a pair of one dimensional data
arrays. See Wind and Contour ARRAY Input and GRIB
Code Input for full details on data input for contouring and wind
plotting.
Observation data must presented as an input file containing
observations in WMO standard BUFR code. See OBSERVATION Data
Input.
Data for symbol plotting are presented in arrays, which should all
have the same number of elements. Two arrays are used to pass the position
information. There are four different types of symbol input data: markers,
numbers, text and wind. NUMBER input data are passed as an real array,
TEXT input data consists of text strings. MARKER input data consists of
indices to Magics markers and wind input data consists of two arrays
containing wind direction and speed respectively. Symbols can be plotted
in INDIVIDUAL or TABLE mode. See SYMBOL Plotting Data
Input
Typically, graph data are presented in two one-dimensional arrays,
where one holds the X-axis values and the other holds the Y-axis values.
See GRAPH Data Input
Satellite Image data must be presented in GRIB code.
Before presenting data to Magics, the
users should firstly decide on the type of data and the method by which
they wish to present it. The Diagrams with the
Magics parameter charts in this chapter should
help.
When passing fields in GRIB code format, the necessary
Magics INPUT parameters are automatically given
appropriate values to ensure that a reasonable plot is obtained. When
passing fields in array format, the user should select the appropriate
values for the Magics INPUT parameters.
Although the use of GRIB input is essentially easier than the use of
array input, the description of GRIB input in this chapter occurs after
that of array input. This is because the array input description explains
the function of those parameters that are set automatically when using
GRIB input.
A contouring plot requires a single data field, whereas a wind plot
requires two data fields for its full specification. The two fields can be
U and V components or speed and direction components or vorticity and
divergence components. Vorticity and divergence components can only be
passed when using GRIB code data input. If isotachs are being plotted,
then the field may be specified by the wind speed component only.
Magics++
Magics++ cannot handle fields in spherical-harmonic representation. The user has to provide
the data on a Gaussian or regular grid. This has the advantage that expensive interpolations are not
performed when plotting data but at the time of retrieval. Most data users will handle are either in Gaussian or regular grid.
REGULAR Spaced Latitude/Longitude Grid
When INPUT_FIELD_ORGANIZATION is set to
'REGULAR' the field is assumed to be on a regular
latitude/longitude grid.
Magics will perform the contouring in
this grid and then plot the result according to the subpage mapping
parameters, i.e. the field can either be global or a subpart of the field.
Since the contouring is performed in the original grid it is ensured that
all field values are taken into account when the isolines are generated.
When using this method, a full specification of the input array is
required:
The longitude and latitude position of the first element, (1,1),
in the array may be set with the parameters:
INPUT_FIELD_INITIAL_LONGITUDE
INPUT_FIELD_INITIAL_LATITUDE
The default values are 0.0 and 90.0,
respectively.
The step lengths between positions of array elements in
longitude and latitude directions are set by using the
parameters:
INPUT_FIELD_LONGITUDE_STEP
INPUT_FIELD_LATITUDE_STEP
Positive values indicate for longitudes that the positions go
from west to east and for latitudes from south to north. Negative
values are used to indicate opposite directions.
The default values are 1.5 for
INPUT_FIELD_LONGITUDE_STEP and
-1.5 for
INPUT_FIELD_LATITUDE_STEP.
By default the first index of the array refers to longitude
positions and the second index refers to latitudes. If these are
interchanged, INPUT_FIELD_PRIMARY_INDEX should
be set to 'LATITUDE'. Default is
'LONGITUDE'.
The following is a full list of the default values for
describing the default input field with a regular grid.
INPUT_FIELD_INITIAL_LATITUDE 90.0
INPUT_FIELD_INITIAL_LONGITUDE 0.0
INPUT_FIELD_LONGITUDE_STEP 1.5
INPUT_FIELD_LATITUDE_STEP -1.5
INPUT_FIELD_PRIMARY_INDEX LONGITUDE
In the default situation, the contouring or wind field array(s)
passed to Magics via
PSET2R should have dimensions of 240 in the
direction of the first index and 121 in the direction of the second
index.
GAUSSIAN Grid
When INPUT_FIELD_ORGANIZATION is set to
'GAUSSIAN', Magics will accept
fields on a gaussian grid, even though the field is not regularly
spaced.
The distance between grid points for gaussian grid fields is regular
in the longitude direction but irregular in the latitude direction.
However the variance in the grid distance along the irregularly spaced
line is small enough that it may be regarded as regular and
Magics makes this assumption.
Users should set INPUT_FIELD_LATITUDE_STEP to
the average value of the latitude grid interval, which should be
calculated as accurately as possible.
The following is a full list of the default values for the
parameters describing an input field with a gaussian grid. (i.e. an ECMWF
T106 model post processed surface field).
INPUT_FIELD_INITIAL_LATITUDE 89.142
INPUT_FIELD_INITIAL_LONGITUDE 0.0
INPUT_FIELD_LONGITUDE_STEP 1.125
INPUT_FIELD_LATITUDE_STEP 1.1213
INPUT_FIELD_PRIMARY_INDEX LONGITUDE
In the default situation, the contouring or wind field array(s)
passed to Magics via
PSET2R should have dimensions of 320 in the direction
of the first index and 160 in the direction of the second index.
Data Suppression
By using the suppress parameters
INPUT_FIELD_SUPPRESS_ABOVE and
INPUT_FIELD_SUPPRESS_BELOW, users may suppress data
values beyond a certain value in a contouring or wind field. This may be
necessary when the user is aware that some of his data are invalid above
or below a certain value.
In the case of a contouring field, suppression means that the data
values outside the permitted range are eliminated before any calculation
of contour levels or gradient estimation takes place.
For example, by setting
INPUT_FIELD_SUPPRESS_ABOVE to 1.0E20 ,
all contour levels above 1.0E20 would be suppressed. Please
note that the suppress parameters should only be used to suppress invalid
data. If used wrongly, the data plotted may not be accurate, particularly
contour maxima/minima values.
Pseudo Action Routine PGRIB
The pseudo action routine PGRIB allows the
automatic processing of GRIB code data. Users may call
PGRIB to decode GRIB code data and, if required, to
set the appropriate Magics input field,
contour, wind, image and text parameters. PGRIB can
deal with GRIB code on regular and Gaussian grids. It can also deal with
GRIB coded polar stereographic data and with stretched/rotated GRIB
data.
Basically, PGRIB will set up
Magics parameters for plotting one
meteorological field each time it is called. This field could be a wind
field, which requires two input GRIB fields, normally U and
V. The user will maintain the responsibility for setting up the
page layout and mapping parameters as well as calling the action
routines to perform the plotting, i.e. PCONT,
PWIND, PIMAGE and
PTEXT.
There are some Magics parameters
associated with PGRIB that should be set before
PGRIB is called. These parameters are explained
later as are all the functions of PGRIB.
The format for calling pseudo action routine
PGRIB is CALL PGRIB, with no
arguments. It is necessary to call PGRIB before any
action routine that requires the decoded data. After calling
PGRIB and before calling an action routine, the
user may set or reset any of the contouring, text, image or wind
parameters, if required.
GRIB code may be passed to Magics as an
input file or in a one dimensional array.
Functions of PGRIB
Depending on the user's requirements, PGRIB
can perform some or all of the following functions:
Decode GRIB data.
Scale the meteorological fields, i.e. convert fields to
standard units for plotting purposes, e.g. convert temperature
fields from Kelvin to Celsius. The user may request, by setting a
Magics parameter, that the fields should
not be scaled. The standard units used by PGRIB
can be found in the section on GRIB Table 2.
Build Magics text blocks to
describe the data field. This text will include such information as
time/date and type of field. Users may reset
Magics text parameters after calling
PGRIB and before calling action
routines.
If the map required is not a global map,
PGRIB can extract a subarea from the input
field so that it covers almost exactly the geographic area required
to be plotted. This helps reduce memory when contouring.
BUFR Tables
To enable the decoding of observations coded in BUFR, it is
necessary to have tables which describe the contents of the BUFR code,
e.g. the names and units of parameters, reference values and scale
factors. The "parameters", as understood in the BUFR context, include
not just the meteorological variables, but also the location of the
observation, block/station number, instrumentation etc. Each parameter
is described by a descriptor, which is an integer number that uniquely
identifies the parameter, e.g. Temperature, Pressure,
latitude/longitude, block number. These BUFR tables are stored at an
address defined by an environment variable (which is made known to
Magics installers at the various sites). The
tables are then used in the BUFR decoding part of
Magics and their use is transparent to the
user. There are standard descriptor numbers for each of the
"parameters". It is possible to use local descriptor numbers instead of
the standard ones and these local descriptors would be described in the
BUFR tables.
The EMOSLIB library is used for the handling of BUFR data. It is possible
to specify a path to a different set of tables by setting the the environment variable
BUFR_TABLES
to the path where the tables reside. An example value for this variable would be:
/home/ma/emos/tables/bufr/linux/000240.
BUFR Parameter Lists
To make it possible for Magics to be
able to plot observations from BUFR code from varying originating
centres, which may or may not use local descriptor numbers, it is
necessary for Magics to be able to identify
the descriptor numbers of the meteorological variables and those
"parameters" that describe the position and time of the observation. To
enable this for each originating centre, there are external files called
BUFR Parameter Lists, where each file consists of a list of descriptors
for the meteorological variables and the position and time "parameters".
For each originating centre, these descriptor numbers should match those
in the BUFR Tables described above.
There are two BUFR Parameter Lists for each originating centre,
one for surface observations and one for upper air. Each list consists
of entry lines, one entry line per meteorological variable or
"parameter". An entry line consists of a descriptor number followed by
an ampersand(&) and then, optionally, text to describe the
variable.
descriptor & text describing the meteorological
variable
For example, the first three lines of the upper air BUFR Parameter
List should be as follows:
11001 & WIND DIRECTION
11002 & WIND SPEED
10195 & HEIGHT in mtrs
The position of the line in the list, not the text, is what
actually defines the meteorological variable, e.g. the first entry line
in the upper air BUFR Parameter Table is always the entry for Wind
Direction, the second Wind Speed and the third Height. It is necessary
to include each entry line in the file, even if they are not to be used.
Complete lists for upper air and surface are given below.
Accessing BUFR Parameter Lists
There are two modes of accessing the BUFR Parameter Lists in
Magics. By default, the lists are stored at
an address path controlled by an environment variable, which is made
known to installers at the various sites. The other mode of access is by
setting a Magics parameter,
BUFR_PARAM_TABLE_ADDRESS_PATH, to the address
path of the tables. This means that users can then force
Magics to use their own lists. Each upper air
list name should have the format bufrtab_ua_nn (surface
lists should have the format bufrtab_surf_nn ) where
nn is the number of the originating Centre of the BUFR
data, e.g. 98 for ECMWF, 85 for France.
Surface BUFR Parameter List
The ECMWF BUFR Parameter List for surface data,
bufrtab_surf_98 is as follows (38 lines):
11011 & WIND DIRECTION at 10 m
11012 & WIND SPEED at 10m
20001 & HORIZONTAL VISIBILITY
20003 & PRESENT WEATHER
12004 & TEMPERATURE at 2m
20012 & MEDIUM CLOUD
20012 & HIGH CLOUD
10051 & MSL PRESSURE
10063 & PRESSURE TENDENCY CHARACTERISTIC (a)
10061 & PRESSURE TENDENCY AMOUNT (pp)
20004 & PAST WEATHER (1)
20005 & PAST WEATHER (2)
20011 & CLOUD AMOUNT (nh)
20013 & HEIGHT OF CLOUD BASE (h)
20012 & LOW CLOUD
12006 & DEWPOINT at 2m
22042 & SEA TEMPERATURE
1012 & SHIP'S DIRECTION
1013 & SHIP'S SPEED
20010 & TOTAL CLOUD
22002 & DIRECTION OF WIND WAVES
22012 & PERIOD OF WIND WAVES
22022 & HEIGHT OF WIND WAVES
22003 & DIRECTION OF SWELL WAVES
22013 & PERIOD OF SWELL WAVES
22023 & HEIGHT OF SWELL WAVES
22001 & DIRECTION OF WAVES
22011 & PERIOD OF WAVES
20021 & HEIGHT OF WAVES
4004 & HOUR
4005 & MINUTE
5001 & LATITUDE (HIGH ACCURACY)
5002 & LATITUDE (COARSE ACCURACY)
6001 & LONGITUDE (HGIH ACCURACY)
6002 & LONGITUDE (COARSE ACCURACY)
7001 & HEIGHT OF STATION in mtrs
7061 & DEPTH BELOW LAND SURFACE
12030 & SOIL TEMPERATURES
To make local surface BUFR Parameter Lists, it is only necessary
to copy the above ECMWF surface list to a new list (with an appropriate
name) and change the descriptor numbers to the ones to be used locally.
It is important that all the above lines are included in each list, even
if they are not to be used in plotting.
The position and time "parameters" are only given in the surface
list.
Upper Air BUFR Parameter List
Following is a listing of all the entries in the ECMWF BUFR
Parameter List for upper air, bufrtab_ua_98 (18
lines):
11001 & WIND DIRECTION
11002 & WIND SPEED
10195 & HEIGHT in mtrs
12003 & DEW POINT TEMPERATURE
12001 & TEMPERATURE
7004 & PRESSURE level in pascals
7006 & HEIGHT ABOVE STATION in mtrs
22042 & SEA TEMPERATURE
11003 & U-COMPONENT
11004 & V-COMPONENT
10003 & HEIGHT in gp mtrs
11192 & U-COMPONENT at 10m
11193 & V-COMPONENT at 10m
7002 & ALTITUDE in mtrs
12007 & VIRTUAL TEMPERATURE
13016 & PRECIPITABLE WATER
20010 & TOTAL CLOUD
10004 & PRESSURE in pascals
To make local upper air BUFR Parameter Lists, it is only necessary
to copy the above ECMWF upper air list to a new list (with an
appropriate name) and change the descriptor numbers to the ones to be
used locally. It is important that all the above lines are included in
each list, even if they are not to be used in plotting.
Diagram 8
Program Examples
These examples illustrate the use of the data input
facilities in Magics.