Reads data from a GRIB2 meteorological data file, and loads it or converts it to a spreadsheet file (D.B. Baird).
Options
PRINT = string token |
What information to print (catalogue); default cata |
|---|---|
OUTTYPE = string token |
Output file type (GEN, GSH, GWB, XLS, XLSX, TXT, CSV, RECORDS); default GWB |
METHOD = string token |
Whether to load data into the Genstat server after creating the file, or merely to create the file (create, load); default load |
SERIAL = string token |
Whether to store the records in series, in a single column, instead of in parallel columns (no, yes); default no |
LONGITUDERANGE = string token |
What range to use for longitude (negative, positive); default posi |
MISSING = scalar |
What value represents a missing value; default -999 |
GRID = variate |
Specifies limits on the longitude and latitude for the data to be read; default * i.e. read all grid points |
ENDTIME = string token |
Whether to keep the end time for each period when SERIAL = yes (yes, no); default no |
SCOPE = string token |
Whether to create the data locally in a procedure that is using GRIBIMPORT, or globally in the whole program (local, global); default loca |
Parameters
FILE = texts |
Input file or URL to be read |
|---|---|
OUTFILE = texts |
Name of the output file to be created; if this is not provided a temporary file will be created, and then deleted if the data are loaded |
RECORDS = scalars or variates |
The numbers of the records to read; default is to read all the records in the file |
MATCH = texts |
Text strings to match in the record descriptions; default * requests all the records selected by RECORDS |
COLUMNS = texts |
Names and/or type codes for the columns that are read (the type of column can be forced by ending the column name, if supplied, with the code ! for a factor, # for a variate, and $ for a text), using a name of ‘*‘ will cause a column to be dropped |
ISAVE = pointers |
Saves the identifiers of the columns |
Description
The name of the file, containing the data values to be imported, is specified by the FILE parameter. This can also be an internet URL prefixed with http://, https:// ftp:// or file://. The data source is then downloaded and imported. This procedure requires wgrib2.exe available from http://www.cpc.ncep.noaa.gov/products/wesley/wgrib2 to be installed. Open a GRIB file in the Genstat client to get help installing this. Note, this procedure does not support the older GRIB 1 data format.
Data in the file are extracted and saved in the specified file format, depending on the extension of OUTFILE. If this is not provided, the type is indicated by the OUTTYPE option, as either GEN (Genstat Command file), GSH (Genstat Spreadsheet), GWB (Genstat Spreadsheet Book), XLS (Excel 5 Spreadsheet), XLSX (Excel 2007 Spreadsheet), TXT (ASCII Text file) or CSV (comma-delimited file); the default is GWB. Setting OUTTYPE=RECORDS reads the record names descriptions and grid definitions into columns Id, Message, LonMin, LonMax, LatMin, LatMax, NPoints; these give the record number, description, minimum and maximum longitude and latitude, and number of grid points, respectively. If PRINT=catalogue, the record details are printed in the output window.
If METHOD=load, the resulting file is read into Genstat data structures. When GRIBIMPORT is used within a procedure, the SCOPE option controls whether the structures are created locally in the procedure (default), or globally in the main program.
The RECORDS and MATCH parameters can be used to read just a selection of the records in the file. RECORDS identifies records by non-negative integers (e.g. 0,1,2…), which may contain a sub-record number after the decimal point (e.g. 8.1, 8.2). MATCH specifies strings of characters to indicate records to read: a record is read if its description contains any of the strings specified by MATCH. This can be used to select all variables with a specific time, type, level or other option (e.g. ‘d=2018100812‘, ‘TMP:’ or ‘MM-ENS=2‘). If both RECORDS and MATCH are specified, their actions are combined to include all records selected by either parameter. If neither is specified, all the records are read. The COLUMNS parameter can be used to set the names and types of the structures in the columns (see below).
The LONGITUDERANGE controls the range of values used for longitudes: negative uses values between -180 and 180, and positive uses values between 0 and 360.
The GRID option can be used to read a sub-grid of values by providing a variate of length 4 containing the minimum and maximum longitude, and the minimum and maximum latitude, of the sub-grid. The GRID values should use the longitude range within the GRIB file, rather than that specified by the LONGITUDERANGE option.
The MISSING option specifies a value that represents missing values within the records. If MISSING = *, rows for values that are undefined will not be output, giving incomplete grids. These may cause problems with multiple records in parallel format. So, if there are undefined values in the records when reading in parallel format, it is best to set MISSING to a value that does not occur any of the records.
The SERIAL option indicates how data are to be imported, with the following settings:
no |
each record is loaded into its own column with two factors Longitude and Latitude at the start of the data to index the grid; and |
yes |
all the record data are loaded into a single column, Measurement, with factors Time0, Time1 (if ENDTIME = yes), Variable, Level, Longitude and Latitude at the start of the data to index the start and end times, record variable, level and grid. |
If SERIAL= yes, the ENDTIME option controls whether an end time for a measurement (Time1) is included in the data. The end time is used for variables that are taken over a period such as rainfall, a maximum wind gust or an average temperature. If no variables of this type are in your data, the end time will be the same as the start time, and can safely be dropped (the default setting).
The COLUMNS parameter can be used to specify the names for the columns, in a text. The type of each column can be forced by providing a !, # or $ character on the end of its string. A string ‘*‘ can be given as a name in COLUMNS, to remove a column from the data that are read. If only a single type character is given, only the types of the column (and not its names) is changed.
Options: PRINT, OUTTYPE, METHOD, SERIAL, LONGITUDERANGE, MISSING, GRID, ENDTIME, SCOPE.
Parameters: FILE, OUTFILE, RECORDS, MATCH, COLUMNS, ISAVE.
Method
The request is passed to the DATALOAD.DLL library which uses wgrib2.exe to read the file, and save the results to OUTFILE, or to a temporary file if OUTFILE is not specified.
Action with RESTRICT
Restrictions are not applicable to any of the parameters.
See also
Directive: SPLOAD.
Procedures: IMPORT, WINDROSE.
Commands for: Input and output.
Example
CAPTION 'GRIBIMPORT example','Global temperatures 6 May 2018';\
STYLE=meta,minor
GRIBIMPORT [OUTTYPE=records] '%Data%/ECMF_Global_Temperature2018050612.grib';\
ISAVE=Records
IF NVALUES(Records) > 0
TEXT Columns; VALUES=!T('Longitude','Latitude','Temp_6May18')
GRIBIMPORT [PRINT=*;LONGITUDE=negative;MISSING=-999] \
'%Data%/ECMF_Global_Temperature2018050612.grib'; COLUMNS=Columns;\
ISAVE=Data
CALCULATE Temp_6May18 = Temp_6May18 - 273.15 "Convert from Kevin to Celcius"
GETATTR [ATTR=levels] Longitude,Latitude; Long,Lat
TABULATE [CLASS=Latitude,Longitude] Temp_6May18; MEANS = mtemp
MATRIX [ROWS=Lat['levels'];COLUMNS=Long['levels']] TempGrid; VALUES=mtemp
XAXIS [RESET=yes] WINDOW=1; TITLE='Longitude'; MARKS=30; LOWER=-180
YAXIS [RESET=yes] WINDOW=1; TITLE='Latitude'; MARKS=15
PEN 2,3; COLOUR='blue','red'
DSHADE [TITLE='Global temperature forecast on 6 May 2018';\
YORIENT=normal; GRID=*] TempGrid; PEN=!(2,3)
ENDIF