LatLong Matrix

From ASCII Data File to LLMatrix Icon

An ASCII file containing a regular grid of Lat Long data with individual values separated by blank spaces (spaces, tabs) and rows separated by newline characters, is known as an LLMatrix (Latitude Longitude Matrix).

With a simple addition to the file you can circumvent the need to encode the data in GRIB format - Metview assigns a particular icon to this type of ASCII data files and they can be used just like GRIB files. The procedure is as follows :

• Edit the file outside the Metview environment - if the file is brought into the Metview environment prior to being modified as described below, it is assigned a Notes icon which can’t be modified afterwards. If you have done this, delete the Notes icon (you may need to copythe file back to a storage folder outside the Metview environment, using the UNIX prompt).
• Add some lines of information to the beginning of the file, then save it - these header lines provide required information - grid mesh, geographical extent, parameter name, ..., that allow Metview to "understand" the file.
• Move/copy/link the file into the Metview environment. When this is done, Metview assigns an LLMatrix icon to the file automatically as it recognises the format details of the header you have introduced in the previous step.

The file is now ready to be used as a normal GRIB file (as input, visualisation, etc). You can also convert it to a GRIB file through the icon Save result action.

There is no macro language equivalent - use macro read() function to read the ASCII data.

An alternative to this procedure is to use the Matrix icon which does not require you to introduce a header in the ASCII file and allows you to specify a path for a remote file. It is however more limited in scope.

Adding a Header to an ASCII Data File

The modification required to make Metview understand an ASCII Matrix data file, consists of adding a few lines to the beginning of the ASCII data file :

• The first line must contain the keyword #LLMATRIX
• Then follow with a variable number of elements (one per line) such as grid mesh, geographical extent, parameter name, ...
• Then add a line with the keyword #DATA

The original data follows these lines. Schematically your file will look like :

#LLMATRIX
...LLMatrixHeader components here...
#DATA
253 256 252 254 ...
255 253 253 256 ...
...

The LLMatrixHeader elements that you have to add (the lines between #LLMATRIX and #DATA) are detailed (list and description) in "LLMatrix Header Components" below. The #LLMATRIX and #DATA lines act as delimiters, separating data from header elements.

LLMatrix Header Components

The header parameters which you can specify are as follows :

NORTH

Geographical parameter. Enter the northernmost coordinate of your field (southern latitudes are negative), e.g. NORTH=70. This parameter must always be given

WEST

Geographical parameter. Enter the westernmost coordinate of your field (western longitudes are negative), e.g. WEST=-120. This parameter must always be given

NLAT

Geographical parameter. Enter the number of grid points from North to South, e.g. NLAT=240. This parameter must always be given.

NLON

Geographical parameter. Enter the number of grid points from West to East, e.g. NLON=121 . This parameter must always be given

GRID

Geographical parameter. Enter the grid resolution(s) in degrees as two numbers separated by a slash (E-W resolution and N-S resolution), e.g. GRID=2.5/2.5. This parameter must always be given

HSCAN

Ordering parameter. Enter the data horizontal scanning direction as a two letter string : WE for West to East (default), or EW for East to West. This parameter is optional.

VSCAN

Ordering parameter. Enter the data vertical scanning direction as a two letter string: NS for North to South (default), or SN for South to North. This parameter is optional.

SCANDIR

Ordering parameter. Enter the data primary scanning direction as a string : HORIZONTAL (default) to read data row by row or VERTICAL to read data column by column. Depending on which you choose you may have to specify either HSCAN or VSCAN. This parameter is optional.

MISSING

Ordering parameter. Enter the value used for missing values within your data matrix, e.g. MISSING=-99. The default value is the maximum floating point value of the machine you are using (hence unlikely to occur in a data file). This parameter is optional.

PARAM

Contents parameter. Enter the value of the parameter number, e.g. PARAM=129. The default value is 255 , a GRIB generic value. These numbers are defined in GRIB Table 2 (e.g. Z=129 , T=130 ). There are several versions of this table and you may use parameter TABLE2 to specify which version you want to use. This parameter is optional.

TABLE2

Contents parameter. Enter the version number of GRIB Table 2 that contains the definition of the parameter PARAM ., e.g. TABLE2=128 . Version numbers 128-254 are reserved for local use, while other numbers are defined by WMO for international exchange (currently using 1). The default value is 128 , for the default ECMWF GRIB Table 2. Other local tables have been defined at ECMWF, such as 131, 140, 151, 160, 170, 254 . This parameter is optional.

LEVEL

Contents parameter. Enter the pressure level of data in hPa, e.g. LEVEL=500 . Model levels are not catered for. If LEVEL is not given, surface level is assumed. This parameter is optional.

CENTRE

Contents parameter. Enter the code of the generating centre, e.g. CENTRE=98 (default). Use your own centre code if outside ECMWF (see GRIB Table 0). This parameter is optional.

DATE

Time parameter. Enter the date of your data as a string with the format YYYYMMDD.hh , e.g. DATE=19980425.25 (= 06h00 of the 25th April 1998). Note how the time of day is expressed as a fraction of the date. Alternatively, you can use dates relative to today, e.g. DATE=-2 (two days ago), but these cannot handle time of the day. Default date is 0 , i.e. today. This parameter is optional.

FCAST

Time parameter. Forecast time step in hours, e.g. FCAST=48 . Use this if your data is forecast data valid at DATE+FCAS . If FCAST is not used or it is set to 0 , the data is interpreted as being analysis.

The example below shows the header of a LLMatrix with data starting at 90N, 0W covering the whole globe with a grid of mesh 1.5 degrees; hence dimensions are 240=1+(358.5-0)/1.5 by 121=1+(90-(-90))/1.5). Data is organised by row and is to be scanned from West to East. Data is analysis of 850mb Temperature for 06h00 of the 4th January 1998. The LLMatrixHeader has the following format :

#LLMATRIX
NORTH = 90
WEST = 0
GRID = 1.5/1.5
NLAT = 121
NLON = 240
HSCAN = WE
SCANDIR = H
PARAM = 130
LEVEL = 850
DATE = 19980104.25
#DATA
251 253 252 252 ...
253 253 251 251 ...
...