Overview
Get started
Gallery
Email lists
What's New
Popular links
    resources
    functions
    tools
    color tables
Quirks & tips
Known bugs
Website info
Privacy policy
Terms of use

NCL Home > Documentation > Manuals > Reference

Information on supported data formats

This page provides more detailed information about each of the supported data formats in NCL. Information about referencing files and file variables is provided in the Files and file variables section of the reference guide. Everything discussed in that section applies to all supported data formats regardless of type. The discussion here focuses on specific conventions and limitations of each format and its NCL implementation. The most detailed discussion involves the GRIB format, because of all the supported formats, it has required the most work to recast into a NetCDF-like model.

NCL's supported data formats are:

NetCDF - Network Common Data Format

Online documentation for NetCDF is available at http://www.unidata.ucar.edu/packages/netcdf/index.html.

NCL offers read and write access to existing NetCDF files as well as the ability to create NetCDF files from scratch. Nearly all the NetCDF features are supported by NCL because NCL's data model is patterned after NetCDF.

As of version 4.3.1 or later, NCL provides beta-level support for "classic" mode NetCDF version 4.0 files. These files are restricted to the same interface provided by earlier versions of NetCDF, but like all NetCDF 4 files, use HDF 5 for the underlying storage format. The main advantage of "classic" mode is that it allows access to the built-in data compression provided by HDF 5, which in many cases can dramatically reduce overall file sizes. (*)

The procedure filedimdef can be used to create file dimensions that are unlimited, and the procedure filevardef can be used to pre-define variables. Global file attributes can be written to NetCDF files by assigning attributes to the variable that references the file, in the same way that attributes are assigned to normal NCL variables. Doing this causes NCL to write the attribute into the file.

File options

The setfileoption procedure allows access to a number of NetCDF-specific options.

Data model differences

Even though NCL's data model is based on NetCDF, there are some differences: (*) Support for NetCDF 4 files is not yet available on every system, as NetCDF 4 is still in beta testing, and does not work for 64-bit systems.

HDF - Hierarchical Data Format - Scientific Data Sets (SDS only)

Online documentation for HDF is available at http://hdf.ncsa.uiuc.edu/.

NCL has interfaces that understand a subset of the content available in HDF4-formatted files. NCL can read and write data that uses the SDS (Scientific Data Set) interface. Opening an HDF file in the NCL environment is entirely analogous to opening a NetCDF file as documented above, with some minor exceptions.

HDF-EOS - - Hierarchical Data Format - Earth Observing System (GRID and SWATH only)

Online documentation for HDF-EOS is available at http://hdfeos.gsfc.nasa.gov/hdfeos/Info/index.cfm.

NCL provides limited read-only access for SWATH and GRID data groups in HDF-EOS files. POINT data groups are currently ignored. As with all NCL's supported formats, HDF-EOS files are read into file variables that use NetCDF-like conventions.

Non-alphanumeric characters in HDF-EOS variable names are replaced the '_' character when listed from NCL and are referenced from NCL in this fashion. Note that due to the hierarchical structure of HDF files, variables with the same name can appear in different groups. Since NCL's NetCDF-like interface flattens this hierarchy, it appends the group name, preceded by an underscore, to all variable names in order to ensure that each variable name is unique within the context of the NCL file variable.

NCL does not yet handle geolocation or time information in HDF-EOS files. No coordinate variables are associated with the dimensions. Geolocation variables in SWATH data are ignored.

CCM - Community Climate Model History Tape Format

The CCM format is a format, originally in CRAY COS blocked form, written by the NCAR CCM1, CCM2, and CCM3 global climate models. It is also possible to have IEEE CCM files. Currently, NCL does not support IEEE CCM files due to lack of documentation. It is possible to use the public domain tool called "ccm2nc" (available on almost all SCD computers; "man ccm2nc") to convert these files to NetCDF. NCL can then reference the NetCDF file(s). If not on SCD machines then the "ccm2nc" software can be downloaded from http://ftp.cgd.ucar.edu/cms/ccm3/tools/

CCM files are pretty straightforward (no special naming convention is needed as with GRIB files); the variable names and unit information are stored as character data in the CCM files. When a CCM file is opened, NCL scans the file and creates an index of all the data in the files. This can be expensive for large files, but it facilitates quickly accessing individual variables of the file. Because this can be expensive, you should avoid repeatedly calling addfile on the same file whenever possible.

For more information on the CCM model and CCM file format, see the CCM3 User's Guide.

GRIB - Gridded Binary (version 1) or General Regularly-distributed Information in Binary Form (version 2)

(GRIB2 support available in versions 4.3.0 or later. )

Online documentation for GRIB is available at:

GRIB1
http://www.nco.ncep.noaa.gov/pmb/docs/on388/
GRIB2
http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc.shtml.

NCL provides read-only support for data in GRIB1 and GRIB2 formats. To open a file, you only need to know that the file is GRIB. NCL figures out which version of GRIB is in the file and processes the file accordingly. NCL's support for GRIB is an evolving process. As an ever more diverse set of GRIB files have been encountered, NCL has been improved to handle many more features of the GRIB format. However, since GRIB has many features that are obscure enough that they have never been encountered in practice by the NCL developers, there are still some aspects of GRIB that NCL does not handle properly. Generally, the NCL developers try to support features that appear in GRIB files that users are actually using. The best way to help improve the GRIB-decoding capabilities of NCL is to call attention to files that are important to your work but that NCL does not seem to interpret correctly. If you have problems reading a particular set of GRIB files, please send email to ncl-talk@ucar.edu. You will need to subscribe first, if you haven't already.

At some point NCL may provide the ability to write GRIB, but, for now, the NCL developers consider their mission is to provide read access to as many types of GRIB files as possible.

GRIB is a compact file format composed of a series of independent records each generally containing a grid of data points covering some geographical extent. Each record contains in a coded form the information required to derive the location of the data points in space and time, the type of quantity the data represents, and the origin of the data, including who produced it and the generating model. But in order to decode the data, external information is required. This much is true both for GRIB1 and GRIB2. But while decoders for GRIB1 or for GRIB2 both rely on information from external tables and many of the individual pieces of information in the tables are the same, the organization of the tables is quite different. As the newer format, GRIB2 has the capability to allow for much more diversity of data without the need for the local extensions that have evolved over the years out of necessity in GRIB1. Also in spite of the evidence of some initial divergence there is hope at least that the GRIB 2 tables will become standardized enough that one set of tables can be used to decode GRIB files from anywhere in the world.

Before discussing the specifics of NCL's treatment of each format, it is worth looking at the common features. These arise partly from basic similarities in the formats, but also significantly from NCL's unifying data model.

Dimensions in GRIB

The fundamental thing that NCL does for both GRIB1 and GRIB2 is to assemble related records into NetCDF-like variables with named dimensions and coordinate variables. The right-most dimensions (usually two) are specified by the grid associated with each individual record. The naming conventions for the dimensions and coordinate variables vary somewhat between GRIB versions and are discussed in the version-specific details below. Dimensions to the left of the grid dimensions result from sorting the related records into a coherent order. These dimensions, in order from left to right (slowest to fastest varying) are: Of course, variables in GRIB files seldom have all possible dimensions present. If the variable does not belong to an ensemble or probability sequence forecast, this dimension will be absent. If all the records have the same initial time then the initial time is by default presented as an attribute of the variable. This is likewise true for forecast time and level. Note, however, that as of version 4.3.0 or later, it is possible to tell NCL to convert any or all of these attributes into single element dimensions using an option to the setfileoption procedure called "SingleElementDimensions". This option is intended to simplify the concatenation of conforming variables from multiple files.

Generally these dimensions have associated one-dimensional coordinate variables. Following standard NetCDF conventions the coordinate variables have the same name as the dimensions. These variables have long names, types, and units that conform as much as possible to standard CF conventions. However, there are details peculiar to each of these dimensions that need discussion:

ensemble
The ensemble dimension uses an index variable as its coordinate variable. This variable simply serves to give a numeric ordering to the ensemble members. Otherwise, there is not always an easily-defined order to these elements. An auxiliary variable, implemented as an array of strings, gives information about each ensemble member.
probability
The probability dimension has as its coordinate variable an ascending series of threshold values of the quantity who probability is measured. Note that the variable itself contains percentage values indicating the likelihood of the quantity at each coordinate value. Note that, currently, NCL allows for only one of the ensemble or probability dimensions for any single variable. If this becomes a problem, it may change with future releases.
initial_time
As of version 4.3.0 or later the initial_time coordinate is expressed in a CF-compliant form as the number of hours since Jan 1, 1800. Prior to this release, it was by default an array of strings giving the date and time in a printable form. However, because string arrays do not have (in NCL, at least) the property of monotonicity, this type of coordinate variable was awkward for visualization purposes, and therefore it was changed. However, an option to the setfileoption procedure called "InitialTimeCoordinateType" allows you to revert to NCL's former behavior regarding the initial_time coordinate. Also, regardless of the type of the initial_time coordinate variable, NCL always supplies three representations of this information:
  • number of hours since Jan 1, 1800 (double type)
  • string array representation of date and time
  • an encoded representation of the date of type double, with units yyyymmddhh.hh_frac indicating the position and number of digits for the year, month, day, hour, and fractional part of the hour.
forecast_time
The forecast_time dimension is an integer offset from the initial_time. Its units are usually, but not always, hours.
levels
If GRIB records for a quantity exist at multiple vertical levels, NCL creates a level dimension for the variable. Depending on the level type, GRIB may specify a single level value, or it may specify the lower and upper bounds of the level. If the quantity is defined using a single value for each level, these values are incorporated into a normal coordinate variable. However, if the quantity is defined using the lower and upper bounds of the level, a standard coordinate variable (a one-dimensional variable with the same name as the dimension) cannot be used. Instead two auxiliary variables are supplied that are named by adding the suffixes "_l0" for the lower bounding level and "_l1" for the upper bounding level to the name of the dimension. NCL uses another scheme to represent GRIB hybrid level types. However, since hybrid levels are currently supported only for GRIB1, the particulars of this scheme are described below in the GRIB1 specific section.

GRIB Grids

NCL supports most of the same grid types in both versions of GRIB. Grids that are fully supported, with one exception, supply one or two dimensional coordinate variables that can be used to locate each point of the grid in latitude and longitude. For other grids, NCL still makes the data available as long as it can figure out the dimension sizes of the data. However, these grids provide no coordinate variables and NCL issues a warning noting that the support for the grid type is incomplete.

Grids with one-dimensional coordinates follow the standard NetCDF convention where the name of the dimension and the name of the coordinate variable are the same. These grids include:

Latitude/Longitude and Gaussian Latitude/Longitude grids may be encoded in a "thinned" ("quasi-regular" in the GRIB documentation) format. These grids are progressively thinned, generally along the longitudinal dimension, as the latitude coordinates approach the poles, thus maintaining a more or less uniform distance between grid points as the circles around each latitude become shorter. NCL automatically interpolates such grids to standard rectangular grids, building normal 1D coordinate variables for them in the process. This process is transparent to the user except that the coordinate attributes specify that the grid is "quasi-regular". By default (as of version 4.3.0), a cubic interpolation algorithm is used because it has been determined to be the most accurate. However, the NCL procedure setfileoption has an option called "ThinnedGridInterpolation" which allows you to use a linear interpolation instead. The linear interpolation is also forced in cases where a bit-mask is used to omit some of the grid points.

Variables with grids that require two-dimensional coordinates use the CF-conforming attribute coordinates to list the names of the two associated two-dimensional coordinate variables. These two variables give the latitude and longitude respectively of each point in the grid. These variables also provide attributes that give sufficient information to generate a "native" map projection that exactly conforms to the projection parameters of the data. In addition, an auxiliary rotation variable gives the rotation angle that needs to be applied to vector data at each grid point to convert between grid-based angles and earth-based angles. Since in most cases the vector data angles are supplied relative to the grid, you would generally need to perform this operation in order to visualize vector data in projections other than the native projection. The formulas for converting the rotation angle are given in attributes of the rotation variable. The supported grids of this type are:

NCL also supports grids of Spherical Harmonic Coefficients. These are unique in that NCL separates the real and imaginary components into a third grid dimension called "real_imaginary". As supplied, the x and y axis do not have geographic meaning. In order to convert such a grid to a Latitude/Longitude or Gaussian grid it is necessary to process the data through an appropriate function.

Note: the GRIB1 reader also supports the following three specialized versions of Rotated Latitude/Longitude Grids:

Information specific to these grids is covered in the "GRIB1 Support Details" section below

GRIB1 Support Details

As of version 4.3.0 NCL can read GRIB1 files of basically unlimited size on any operating system that supports 64-bit file offsets.

GRIB1 relies on parameter tables to match a specific octet (byte) in the GRIB record to a particular parameter name. These tables have proliferated over the years because each center uses different models and produces different quantities for analysis. The WMO mandates a single standard parameter table for table entries 1 - 127, but any originating center can legitimately define its own tables for entries 128 - 255. Furthermore, in spite of the supposed mandate, important centers such as ECMWF define their own values for the lower-numbered entries as well. Additionally the GRIB specification allows a single center, such as ECMWF, to define multiple parameter tables each specialized for different kinds of data. These are distinguished using another octet called the "parameter table version".

Since there is no central repository of GRIB parameter tables and the originating centers span the globe, it is not realistic for a single GRIB reading tool to have access to all the tables needed to parse every GRIB file; or, even assuming the necessary tables are available, to be able to decide in every case which table applies to a particular GRIB record. Consequently, NCL's approach is to provide built-in access to a set of parameter tables that are considered to be generally reliable, but, in addition, to allow the user to supply their own parameter tables locally as text files. Because the user-supplied tables take precedence over the built-in tables, the user ultimately controls which parameter table applies to a particular GRIB file. More detailed information about the parameter tables appears at the end of this document in the sections Built-in GRIB1 parameter tables and User-defined GRIB1 parameter tables.

Since GRIB files usually have records with same parameter on different grids and different level types, using various time range indicators, NCL has introduced naming conventions that encode these distinctions to help ensure unique variable names. For example, consider the variable TMP (temperature). One GRIB file may contain the variable with many different variations. Some records might represent average temperature, others temperature differences from one time to the next, and yet others the temperature at tropopause. Clearly, these need to be treated as different variables in the file, but GRIB gives them all the parameter number corresponding to TMP.

The following section gives the algorithm NCL uses to assign names to GRIB1 variables.

GRIB1 data variable name encoding

    (Note: examples show intermediate steps in the formation of the name)

    if entry matching parameter table version and parameter number is found (either in built-in or user-supplied table):
       if recognized as probability product:
          <probability_parameter_short_name>_<subject_variable_short_name> (ex: PROB_A_PCP) 
       else:
          <parameter_short_name> (ex: TMP) 
    else:
       VAR_<parameter_number> (ex: VAR_179)

    if pre-defined grid:
       _<pre-defined_grid_number> (ex: TMP_6)
    else if grid defined in GDS (Grid Description Section):
       _GDS<grid_type_number> (ex: TMP_GDS4)

    _<level_type_abbreviation> (ex: TMP_GDS4_ISBL)

    if not statistically processed variable and not duplicate name the name is complete at this point.

    if statistically-processed variable with constant specified statistical processing duration:
          _<statistical_processing_type_abbreviation><statistical_processing_duration><duration_units> (ex: ACPCP_44_SFC_acc6h) 
    else if statistically-processed variable with no specified processing duration
       _<statistical_processing_type_abbreviation> (ex: A_PCP_192_SFC_acc)

    if variable name is duplicate of existing variable name (this should not normally occur):
       _n (where n begins with 1 for first duplicate) (ex: TMP_GDS4_ISBL_1)
Notes:

GRIB1 dimensions, coordinate, and auxiliary variables

In order to ensure the uniqueness of dimension and coordinate variable names, NCL assigns each GRIB1 dimension a unique number when it is first recognized. This number is usually appended to the end of the name.

GRIB1 grids
A single GRIB record generally contains data on a two-dimensional horizontal grid locating variables on the surface of the globe. This grid forms the two rightmost (occasionally three rightmost) dimensions of an NCL GRIB variable.

GRIB1 has two systems for defining these horizontal grids. There is a set of "pre-defined" grids that are indexed by a single octet (byte) in the GRIB record. These are completely specified as to the type of projection, number of grid points, and extent. Since these are by definition unique, dimensions and coordinates that specify these grids do not use the dimension number in their names. The other system uses the GDS (Grid Description Section) to assign a general grid type (e.g Lambert Conformal) and to specify the projection parameters and number of grid points. In this case, the grid type is not sufficient to uniquely specify the grid and therefore the unique dimension number is appended to the dimensions and coordinate variables.

The grid dimensions, coordinate variables, and associated auxiliary rotation variables are named as follows: 

if grid is pre-defined and has single-dimensioned coordinates:
    dimensions and coordinates:  
       lat_<pre-defined_grid_number>, lon_<pre-defined_grid_number> (ex: lat_30, lon_30)
else if grid is pre-defined:
    dimensions:
       gridx_<pre-defined_grid_number>, gridy_<pre-defined_grid_number> (ex: gridx_6, gridy_6)
    coordinates:
       gridlat_<pre-defined_grid_number>, gridlon_<pre-defined_grid_number> (ex: gridlat_6, gridlon_6)
    auxiliary rotation variable:
       gridrot_<pre-defined_grid_number> (ex: gridrot_6)
else if GDS grid has single-dimensioned coordinates:
    dimensions and coordinates:  
       g<grid_type_number>_lat_<dimension_number>, g<grid_type_number>_lon_<dimension_number> (ex: g0_lat_7, g0_lon_8)
else if GDS grid type is 50 (Spherical Harmonic Coefficients)
    dimensions: 
       real_imaginary, g50_lat_<dimension_number>, g50_lon_<dimension_number> (ex: real_imaginary, g50_lat_1, g50_lon_2)
else if GDS grid type is 203 (Arakawa semi-staggered E-Grid)
    mass dimensions: 
       g203m_x_<dimension_number>, g203m_y_<dimension_number> (ex: g203m_x_0, g203m_y_1)
    mass coordinates:
       g203m_lat_<dimension_number>, g203m_lon_<dimension_number> (ex: g203m_lat_0, g203m_lon_1)
    velocity dimensions: 
       g203v_x_<dimension_number>, g203v_y_<dimension_number> (ex: g203v_x_5, g203v_y_6)
    velocity coordinates:
       g203v_lat_<dimension_number>, g203v_lon_<dimension_number> (ex: g203v_lat_5, g203m_lon_6)
else (other GDS grid):
    dimensions: 
       g<grid_type_number>_x_<dimension_number>, g<grid_type_number>_y_<dimension_number> (ex: g10_x_5, g10_y_6)
    coordinates:
       g<grid_type_number>_lat_<dimension_number>, g<grid_type_number>_lon_<dimension_number> (ex: g10_lat_5, g10_lon_6)
   auxiliary rotation variable:
       g<grid_type_number>_rot_<dimension_number> (ex: g10_rot_6)
Notes:
GRIB1 levels
If a variable exists on more than one vertical level, it will have a level dimension. As stated earlier, depending on level type, a level may be specified as a single value, or using two bounding values. For hybrid level types, each GRIB record encodes the coefficients required to convert the hybrid levels into pressure level values. These appear as auxiliary variables. The actual level coordinate in this case is just an integer index. However it specifies how to compute the pressure levels using the CF-compliant attribute formula_terms. The naming scheme for level dimensions, coordinates, and auxiliary variables is as follows: 
if single level value:
    if level type is not hybrid level:
       dimensions and coordinates:  
           lv_<level_type_abbreviation><dimension_number> (ex: lv_ISBL7)
    else:
       if hybrid coefficients given at level midpoints -- DWD convention:
           dimensions and coordinates:
               lv_HYBL<dimension_number> (ex: lv_HYBL9)
           auxiliary hybrid vertical coordinates (includes scalar parameterization values as attributes):
               lv_HYBL<dimension_number>_vc (ex: lv_HYBL9_vc) 
       else if hybrid coefficients given at level midpoints:
           dimensions and coordinates:
               lv_HYBL<dimension_number> (ex: lv_HYBL0)
           auxiliary hybrid A coefficient:
               lv_HYBL<dimension_number>_a (ex: lv_HYBL0_a) 
           auxiliary hybrid B coefficient:
               lv_HYBL<dimension_number>_b (ex: lv_HYBL0_b)
           auxiliary scalar reference pressure:
               P0
       else if hybrid coefficient given at level boundaries:
           dimensions and coordinates:
               lv_HYBL<dimension_number> (ex: lv_HYBL0)
           auxiliary boundary interface dimension (sized one greater than number of levels):
               lv_HYBL_i<dimension_number> (ex: lv_HYBL_i1)
           auxiliary hybrid A boundary interface coefficient:
               lv_HYBL_i<dimension_number>_a (ex: lv_HYBL_i1_a) 
           auxiliary hybrid B boundary interface coefficient:
               lv_HYBL_i<dimension_number>_b (ex: lv_HYBL_i1_b)
           auxiliary hybrid a coefficient (derived as average of adjacent interface coefficients):
               lv_HYBL<dimension_number>_a (ex: lv_HYBL0_a) 
           auxiliary hybrid b coefficient (derived as average of adjacent interface coefficients):
               lv_HYBL<dimension_number>_b (ex: lv_HYBL0_b)
           auxiliary scalar reference pressure:
               P0
else (if lower and upper boundary level values):
    dimensions:
        lv_<level_type_abbreviation><dimension_number> (ex: lv_DBLY8)
    auxiliary lower boundary level values:                 
        lv_<level_type_abbreviation><dimension_number>_l0 (ex: lv_DBLY8_l0)
    auxiliary upper boundary level values:                 
        lv_<level_type_abbreviation><dimension_number>_l1 (ex: lv_DBLY8_l1)
Notes:
GRIB1 forecast_time
The forecast_time dimension is handled in a very straightforward way in GRIB1. The dimension and coordinate names are derived as follows: 
dimensions and coordinates:  
   forecast_time<dimension_number> (ex: forecast_time3)
Notes:
GRIB1 initial_time
Version 4.3.0 changed the default type of the initial_time coordinate dimension from an array of strings to an array of doubles with units of "hours since 1800-01-01 00:00". As noted earlier, you can revert to the earlier behavior using the setfileoption procedure option called "InitialTimeCoordinateType". Dimensions, coordinates, and associated auxiliary variables are named as follows: 
if setfileoption option "InitialTimeCoordinateType" is set to "Numeric" (default):
   dimensions and coordinates (units of hours since 1800-01-01 00:00):  
      initial_time<dimension_number>_hours (ex: initial_time0_hours)
   auxiliary string representation:
      initial_time<dimension_number> (ex: initial_time0)
   auxiliary encoded double representation (units of yyyymmddhh.hh_frac):
      initial_time<dimension_number>_encoded (ex: initial_time0_encoded)
else (if setfileoption option "InitialTimeCoordinateType" is set to "String":
   dimensions and coordinates:  
      initial_time<dimension_number> (ex: initial_time0)
   auxiliary numeric representation (units of hours since 1800-01-01 00:00):
      initial_time<dimension_number> (ex: initial_time0)
   auxiliary encoded double representation (units of yyyymmddhh.hh_frac):
      initial_time<dimension_number>_encoded (ex: initial_time0_encoded)
GRIB1 ensemble
The ensemble dimension coordinate variable is a simple integer index. It has an auxiliary variable that explains the significance of each element in the ensemble dimension: 
dimensions and coordinates:  
   ensemble<dimension_number> (ex: ensemble2)
auxiliary informational string array:
   ensemble<dimension_number>_info (ex: ensemble2_info)
GRIB1 probability
The probability dimension coordinate variable is composed of the values representing threshold values of the quantity whose probability is under consideration. 
dimensions and coordinates:  
   probability<dimension_number> (ex: probability4)

GRIB2 Support Details

Available in version 4.3.0 or later.

NCL uses the GRIB2 g2clib encoder/decoder library from NCEP to perform the low-level decoding of GRIB2 files. Since this library is limited to processing files that are less than 2 GB in size, NCL only supports reading GRIB2 files of 2 GB or less.

NCL distinguishes records that need to be classified into separate variables based on differences in the following characteristics:

The GRIB2 documentation provides more information about these characteristics. You may notice that they are selected from different sections of the GRIB2 record structure. Some, such as "type of statistical processing", are only applicable when the "product definition template number" has certain values. Generally speaking all of the applicable characteristics must be the same for two records to be considered part of the same variable. NCL uses a different set of characteristics to sort the records into a coherent variable with ordered dimensions.

NCL forms a name for each unique variable it discovers based on the characteristics that usually vary within a file. Some characteristics, such as the originating center, are normally constant for all the records in a single GRIB file (or for that matter in set of conforming files) and therefore are not encoded into the name. Most of the information required to establish the name is contained the GRIB2 code tables that are supplied with NCL. In particular the initial prefix (the "short name") of the variable is determined by looking up three characteristics: product discipline, parameter category, and parameter number. Files produced for the TIGGE project use a slightly different scheme that involves considering other characteristics, such as the type of statistical processing, to determine the initial prefix for the variable. Because this scheme is more complex, a table embedded in the source code is currently used to determine TIGGE name prefixes. Unlike the tables supplied by NCEP, TIGGE prefixes are conventionally in lower case. The following section gives the algorithm for encoding data variable names in GRIB2.

GRIB2 data variable name encoding

    (Note: examples show intermediate steps in the formation of the name)

    if production status is TIGGE test or operational and matches entry in TIGGE table:
       <parameter_short_name> (ex: t) 
    else if entry matching product discipline, parameter category, and parameter number is found:
       <parameter_short_name> (ex: TMP) 
    else:
       VAR_<product_discipline_number>_<parameter_category_number>_<parameter_number> (ex: VAR_3_0_9)

    _P<product_definition_template_number> (ex: TMP_P0)

    if single level type:
       _L<level_type_number> (ex: TMP_P0_L103)
    else if two levels of the same type: 
       _2L<level_type_number> (ex: TMP_P0_2L106)
    else if two levels of different types: 
       _2L<_first_level_type_number>_<second_level_type_number> (ex: LCLD_P0_2L212_213)

    if grid type is supported (fully or partially):
       _G<grid_abbreviation><grid_number> (ex: UGRD_P0_L108_GLC0)
    else:
       _G<grid_number> (ex: UGRD_P0_2L104_G0)

    if not statistically processed variable and not duplicate name the name is complete at this point.

    if statistically-processed variable and constant statistical processing duration:
       if statistical processing type is defined:
          _<statistical_processing_type_abbreviation><statistical_processing_duration><duration_units> (ex: APCP_P8_L1_GLL0_acc3h) 
       else
          _<statistical_processing_duration><duration_units> (ex: TMAX_P8_L103_GCA0_6h)
    else if statistically-processed variable and variable-duration processing always begins at initial time:
       _<statistical_processing_type_abbreviation> (ex: ssr_P11_GCA0_acc)

    if variable name is duplicate of existing variable name (this should not normally occur):
       _n (where n begins with 1 for first duplicate) (ex: TMAX_P8_L103_GCA0_6h_1)
The fully or partially supported grid type abbreviations are: The statistical processing type abbreviations are:

GRIB2 dimensions, coordinate, and auxiliary variables

NCL's GRIB2 reader uses a slightly different scheme than the GRIB1 reader to ensure the uniqueness of dimension and coordinate variable names. Whereas the GRIB1 reader maintains a single count and numbering system for dimensions of all types, the GRIB2 reader numbers each dimension type separately. For example, in GRIB1 the name forecast_time2 means the third (since the count starts with 0) unique dimension of any sort encountered while processing a file, but in GRIB2 this same name means the third unique dimension of type forecast_time.
GRIB2 grids
Unlike GRIB1, GRIB2 uses only one system, a "Grid Description Template", for specifying the parameters of a grid. NCL uses a single grid number that is sequentially incremented as new grids are encountered to label all the dimensions and coordinate variables belonging to a particular grid. NCL also uses the same naming scheme for all GRIB2 grid types. This means that NCL's system of naming GRIB2 grid dimensions and variables is considerably simpler than the GRIB1 scheme. The grid dimensions, coordinate variables, and associated auxiliary rotation variables are named as follows: 
if grid has single-dimensioned coordinates:
    dimensions and coordinates:  
       lat_<grid_number>, lon_<grid_number> (ex: lat_4, lon_4)
else if grid type is Spherical Harmonic Coefficients:
    dimensions: 
       real_imaginary, lat_<grid_number>, lon_<grid_number> (ex: real_imaginary, lat_1, lon_1)
else (2D coordinates):
    dimensions: 
       ygrid_<grid_number>, xgrid_<grid_number> (ex: ygrid_4, xgrid_4)
    coordinates:
       gridlat_<grid_number>, gridlon_<grid_number> (ex: gridlat_4, gridlon_4)
    auxiliary rotation variable:
       gridrot_<grid_number> (ex: gridrot_4)
Notes:
GRIB2 levels
GRIB2 level dimensions and coordinates have names that are very similar to GRIB1 level names. One difference is that no auxiliary variables are currently supplied for hybrid levels. As with GRIB1, depending on level type, a level may be specified as a single value, or using two bounding values. The naming scheme for level dimensions, coordinates, and auxiliary variables is as follows: 
if single level value:
    dimensions and coordinates:  
       lv_<level_type_abbreviation><level_dimension_number> (ex: lv_ISBL7)
    else:
else (if lower and upper boundary level values):
    dimensions:
        lv_<level_type_abbreviation><level_dimension_number> (ex: lv_DBLY8)
    auxiliary lower boundary level values:                 
        lv_<level_type_abbreviation><level_dimension_number>_l0 (ex: lv_DBLY8_l0)
    auxiliary upper boundary level values:                 
        lv_<level_type_abbreviation><level_dimension_number>_l1 (ex: lv_DBLY8_l1)
Notes:
GRIB2 forecast_time, initial_time, ensemble, and probability
The remaining GRIB2 dimensions and coordinate variables are handled exactly like the corresponding GRIB1 dimensions and coordinate variables, except that each dimension type is separately counted and numbered. Refer to the corresponding GRIB1 sections for details:

Built-in GRIB1 parameter tables

NCL's built-in parameter tables have been assembled from a number of sources. A prominent acknowledgement must go to the freely available wgrib program (http://wesley.wwb.noaa.gov/wgrib.html). The ECMWF tables are available at http://www.ecmwf.int/publications/manuals/libraries/tables/tables_index.html. The FSL tables were obtained from private contacts at NOAA's Forecast Systems Laboratory in Boulder. Thanks also to Wenchieh Yen of the Institut fuer Physick der Atmosphere who provided recent new and updated table versions for DWD. Here is a list of the supported tables with links to their contents: The first table in this list, the NMC operational table, contains the WMO standard entries described in the GRIB documentation (http://www.nco.ncep.noaa.gov/pmb/docs/on388/table2.html). Since the parameters less than 128 are mandated by the GRIB documents, they are used by default when NCL cannot otherwise determine an applicable parameter table. Note, however, that user-defined parameter tables must include these parameters even if they match the standard table. NCL does not default to the standard table for any unfound indexes if it has found a suitable user-defined parameter table.

User-defined GRIB1 parameter tables

An NCL GRIB parameter table file is a text file that specifies one or more distinct parameter tables for NCL to use when reading GRIB files. Setting the environment variable NCL_GRIB_PTABLE_PATH to the pathname of the file causes NCL to parse it and incorporate its parameter tables when first asked to open a GRIB file. Optionally, NCL_GRIB_PTABLE_PATH may be set to a directory path, in which case all files in the directory with the suffix '.gtb' are opened as parameter tables.

A line beginning with a '!' (optionally preceded by whitespace) is a comment. The separator string is adjustable: it may be set to any non-alphanumeric, non-whitespace character, or it may simply be two spaces in a row. It is determined from what follows immediately after the first table header row signal index (-1). Any amount of whitespace may surround the separator string. There is no way to escape the separator string, so it must be set to something that is not used in any of the informational fields.

The table header row consists of the signal index (-1) followed by 3 required fields: center, subcenter, and parameter table version. The parameter table that follows will be used for any GRIB record whose center, subcenter, and table version matches what is specified in the table header row, overriding any built-in parameter tables that would otherwise match. Setting any of these fields to '-1' results in an automatic match. If you set all three fields to '-1' the table will be used for all GRIB files. If two or more tables would equally match for a particular GRIB record, it is undefined which will be used.

Parameter rows consist of the parameter index followed by an abbreviation suitable for use as an NCL file variable, then a string representing units, and finally the longname (a short description of the variable). The abbreviation must contain only alphanumeric characters and/or the underscore character. Index values that are not defined need not be included.

Here is a sample portion of a valid parameter table file: 

-1 : 98 : 0 : 128 
018 : T : 	K : 	Temperature
019 : Z : 	m2/s2 : 	Surface geopotential
020 : GP : 	kg/s2 : 	Geopotential
021 : U_TE : 	J/ms : 	Total energy u-flux
022 : V_TE : 	J/ms : 	Total energy v-flux
081 : U_KE : 	J/ms : 	Kinetic energy u-flux
082 : V_KE : 	J/ms : 	Kinetic energy v-flux
The table header row indicates center 98, subcenter 0, parameter table version 128. From the list of originating centers at http://www.nco.ncep.noaa.gov/pmb/docs/on388/table0.html in the GRIB documentation, one can determine that this means the center is the European Center for Medium-Range Weather Forecasts - Reading or ECMWF, and in fact this is an alternate version of the standard ECMWF parameter table version 128, required to decode a specific GRIB dataset.

NCL is a product of the Computational & Information Systems Laboratory at the National Center for Atmospheric Research (NCAR), with support from NSF
Contact webmaster