...
Local definitions have a version, and they are stored in different sections depending on the GRIB edition:
- In GRIB edition 1 local definitions are an extension of section 1. This is the complete list of ECMWF GRIB 1 local definitions
- In GRIB edition 2 local definitions are stored in section 2 (which is optional). This is the complete list of ECMWF GRIB 2 local definitions
In ecCodes, local definitions are defined using a combination of the originating centre and the version of the local definition:
Code Block language bash /usr/local/share/eccodes/definitions/grib[edition]/local.[centre].[localDefinitionNumber].def
For example, ECMWF's local definition 1 for GRIB 1 data is defined in a file called:
Code Block /usr/local/share/eccodes/definitions/grib1/local.98.1.def
A sample local definition is defined here:
Code Block language bash title local.98.1.def template mars_labeling "grib1/mars_labeling.def"; unsigned[1] perturbationNumber : dump; alias number = perturbationNumber; unsigned[1] numberOfForecastsInEnsemble : dump; alias totalNumber=numberOfForecastsInEnsemble; pad padding_local1_1(1);
and the MARS labelling present on each ECMWF local definition is included from a separate file
mars_labelling.def
, which is shown below:Code Block title /usr/local/share/eccodes/definitions/grib1/mars_labelling.def codetable[1] marsClass "mars/class.table" = "od" : dump,lowercase; codetable[1] marsType "mars/type.table" = "an" : dump,string_type,lowercase; codetable[2] marsStream "mars/stream.table" = "oper" : dump,lowercase ; ksec1expver[4] experimentVersionNumber = "0001" : dump; alias mars.class = marsClass; alias mars.type = marsType; alias mars.stream = marsStream; alias mars.expver = experimentVersionNumber;
Example of a GRIB2 local definition
Suppose we want to add a GRIB2 local definition for a given centre (let's say code 87). The local definition will have some integer keys and a string key.
So first we create the file "grib2LocalSectionNumber.87.table" and place it in the definitions/grib2 directory. This is a codetable with codes for the local definition numbers and a brief description.Code Block language bash title grib2LocalSectionNumber.87.table 0 0 Empty local section 1 1 Example local definition for centre 87 255 255 MISSING
Now create the file "local.87.def" which is a template for all the local definitions for this centre:
Code Block language bash title local.87.def # Local section for example alias localDefinitionNumber=grib2LocalSectionNumber; template localSection "grib2/local.[centreForLocal:l].[grib2LocalSectionNumber:l].def"; # MARS Labelling template mars_labeling "grib2/mars_labeling.def"; position offsetAfterLocalSection;
Here we assume we need the MARS keys as well (this allows archiving such GRIB messages)
Now let's finally create the actual local definition (number 1):
Code Block language bash title local.87.1.def unsigned[2] myVersion : dump ; ascii[10] myName : dump ; unsigned[1] myNumber : dump ;
Here we assign 2 bytes to the myVersion field (a positive integer), 10 bytes to the ASCII character string myName and 1 byte to the final myNumber integer.
Creating your own tables
Sites can create their own tables in order to adapt ecCodes to their needs. The clear candidates for site specific tables are:
class
, used at ECMWF to define a system (like operations:od
or research:rd
) or a project (like ERA-40:e4
, ERA-Interim:ei
, MACC:mc
or TIGGE:ti
). Examples of mars classes used at ECMWF are listed on the webmars cataloguestream
, used at ECMWF to define a forecasting system within a class (likeoper
for the deterministic system,enfo
for ensemble forecast orseas
for seasonal forecast). Examples of mars streams under classod
used at ECMWF are listed on the webmars catalogue
In order to override the above, you can create files with your own content, for example:
Code Block language bash title /usr/site/eccodes/definitions/mars/class.table # GRIBcode Acronym Long name 1 so Site operations 2 sr Site research
Code Block language bash title /usr/site/eccodes/definitions/mars/stream.table # GRIBcode Acronym Long name 1001 eebc Ensemble using ECMWF data as Boundary Conditions 1002 eeic Ensemble using ECMWF data as Initial Conditions
Another candidate for local adaptation is the handling of local parameters. The standard parameter descriptions are contained in the files
name.def
,paramId.def
,shortName.def
andunits.def
in directories:Code Block language bash /usr/local/share/eccodes/definitions/grib[edition]
The parameter descriptions for a given
centre
are contained in the files directories:Code Block language bash /usr/local/share/eccodes/definitions/grib[edition]/localConcepts/[centre:s]
The following are examples of the contents for the above files in order to handle ECMWF parameter
Geopotential
in GRIB edition 1:Code Block language bash title /usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/name.def #Geopotential 'Geopotential' = { table2Version = 128 ; indicatorOfParameter = 129 ; }
Code Block language bash title /usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/paramId.def #Geopotential '129' = { table2Version = 128 ; indicatorOfParameter = 129 ; }
Code Block language bash title /usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/shortName.def #Geopotential 'z' = { table2Version = 128 ; indicatorOfParameter = 129 ; }
Code Block language bash title /usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/units.def #Geopotential 'm**2 s**-2' = { table2Version = 128 ; indicatorOfParameter = 129 ; }
In GRIB edition 2, the contents of the same files for parameter
Geopotential
are:Code Block language bash title /usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/name.def #Geopotential 'Geopotential' = { discipline = 0 ; parameterCategory = 3 ; parameterNumber = 4 ; }
Code Block language bash title /usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/paramId.def #Geopotential '129' = { discipline = 0 ; parameterCategory = 3 ; parameterNumber = 4 ; }
Code Block language bash title /usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/shortName.def #Geopotential 'z' = { discipline = 0 ; parameterCategory = 3 ; parameterNumber = 4 ; }
Code Block language bash title /usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/units.def #Geopotential 'm**2 s**-2' = { discipline = 0 ; parameterCategory = 3 ; parameterNumber = 4 ; }
Install and test your changes
ecCodes can be instructed to search for definition files in one or more directory trees with environment variable
ECCODES_DEFINITION_PATH
. All the site specific files have to be stored in a sub-directory tree similar to the hierarchy of the ecCodes distribution. Then, the site specific directory has to be included first in the search path. For example:Code Block language bash ECCODES_DEFINITION_PATH=/usr/site/eccodes/definitions:/usr/local/share/eccodes/definitions
The tool codes_info will tell you if you are using this environment variable or using the standard location for definitions.
To test the local definition we added earlier, you can take a GRIB2 sample file and change its centre to 87 and add the local definition to it:
Code Block > grib_set -s centre=87,setLocalDefinition=1,localDefinitionNumber=1 GRIB2.tmpl out.grib2
Now dump the out.grib2 file to check its section 2 contents to make sure your local definition keys are there
See Also please study the slides in this here: Training course presentation.
Also And the How-To Article GRIB: Converting edition 1 to 2 (The "Local configuration" section)
...