Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Excerpt
hiddentrue

Local definitions are required when one needs to store information which is not part of the standard GRIB header. This might be local parameters or local definitions.


Warning

Please note:
According to the WMO, the use of local tables in messages intended for non-local or international exchange is strongly discouraged.

First of all ask the data provider for any local tables/definitions which they used in their GRIB messages.

Step-by-step guide

Local tables for parameters

A common 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 and units.def in directories:

Code Block
languagebash
/usr/local/share/eccodes/definitions/grib[edition]

The parameter descriptions for a given centre are contained in the directories:

Code Block
languagebash
/usr/local/share/eccodes/definitions/grib[edition]/localConcepts/[centre:s]

So for example the GRIB edition 2 local parameters for DWD (centre=edzw) are defined in definitions/grib2/localConcepts/edzw and GRIB edition 1 local parameters for SMHI (centre=eswi) are in definitions/grib1/localConcepts/eswi.

The following in an example of the contents for the above files in order to handle ECMWF parameter Geopotential in GRIB edition 1:

Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/name.def
#Geopotential
'Geopotential' = {
    table2Version = 128 ;
    indicatorOfParameter = 129 ;
}


Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/paramId.def
#Geopotential
'129' = {
    table2Version = 128 ;
    indicatorOfParameter = 129 ;
}


Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/shortName.def
#Geopotential
'z' = {
    table2Version = 128 ;
    indicatorOfParameter = 129 ;
}


Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib1/localConcepts/ecmf/units.def
#Geopotential
'm**2 s**-2' = {
    table2Version = 128 ;
    indicatorOfParameter = 129 ;
}


And for GRIB edition 2, the contents of the same files for parameter Potential temperature gradient are:

Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/name.def
#Potential temperature gradient
'Potential temperature gradient' = {
    discipline = 192 ;
    parameterCategory = 129 ;
    parameterNumber = 3 ;
}


Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/paramId.def
#Potential temperature gradient
'129003' = {
    discipline = 192 ;
    parameterCategory = 129 ;
    parameterNumber = 3 ;
}


Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/shortName.def
#Potential temperature gradient
'ptgrd' = {
    discipline = 192 ;
    parameterCategory = 129 ;
    parameterNumber = 3 ;
}


Code Block
languagebash
title/usr/local/share/eccodes/definitions/grib2/localConcepts/ecmf/units.def
#Potential temperature gradient
'K' = {
    discipline = 192 ;
    parameterCategory = 129 ;
    parameterNumber = 3 ;
}


Local Definitions (Local Use section)

Local definitions are also required when one needs to store information which is not part of the standard GRIB header. This would typically be a MARS key (like class, stream, type and version number or experiment identifier, expver) or information that the data producer wants to have in each GRIB for convenience.

Local definitions have a version, and they are stored in different sections depending on the GRIB edition:

In ecCodes, local definitions are defined using a combination of the originating centre and the version of the local definition:

Code Block
languagebash
/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
languagebash
titlelocal.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
languagebash
titlegrib2LocalSectionNumber.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
languagebash
titlelocal.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
languagebash
titlelocal.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 catalogue
  • stream, used at ECMWF to define a forecasting system within a class (like oper for the deterministic system, enfo for ensemble forecast or seas for seasonal forecast). Examples of mars streams under class od 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
languagebash
title/usr/site/eccodes/definitions/mars/class.table
# GRIBcode   Acronym    Long name
1            so         Site operations
2            sr         Site research


Code Block
languagebash
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


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
languagebash
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

(smile)


Also please study the slides here:  Training course presentation.
And the How-To Article GRIB: Converting edition 1 to 2 (The "Local configuration" section)

Content by Label
showLabelsfalse
max5
spaces~usa
showSpacefalse
sortmodified
reversetrue
typepage
cqllabel in ("eccodes-faqs","eccbufr-faqs") and label in ("local-definitions","definitions") and type = "page" and space = "UDOC"
labelskb-how-to-article