Introduction

The -netcdf option writes the grid values to a specified file in netcdf format using COARDS convention for the Latitude-Longitude, Mercator and Gaussian grids and the CF-1.0 convention for Lambert and Polar stereographic projection grids. Other grid templates and projections are not supported yet.

Default the grid values are written as 4 bytes float having {TIME,LAT,LON} dimension shape (3D data) and possible vertical LEV information added to the name of variables. For example, V wind component defined at 10 m level in atmosphere will have default name VGRD_10maboveground. With some minimal efforts and using the sub-options described below it is also possible to write data as a 4D data with the {TIME,LEV,LAT,LON} dimension shape that could be usefull for the vertical structure analysis etc.

3D and 4D data could be mixed in the same netcdf file if both have the same horizontal grid shapes. Practically any number of variables could be placed in to the single netcdf file as well as time dimension can be almost arbitrary extended. For these purposes please use the wgrib2 -append option. All missing values in data are replaced by the _FillValue defined in wgrib2 as 9.999e+20 for the float data, 32767 for short-packed data and 127 for byte-packed data.

Simple usage

-netcdf file_name

Example 1

$ wgrib2 ../example/eta.t00z.awphys18.grb2 -netcdf eta.nc

The above line converts the grib2 file into a netcdf file.

Sub-options for -netcdf

Next sub-options could help to customize created netcdf file(s). All sub-options must preceed the -netcdf option as it is the wgrib2 rule. More then one -netcdf option could be given on the wgrib2 command line, please read the documentation for wgrib2. Almost all sub-options have -no_... version that annulates previous assignment. For the advanced users it is recommended to use the GRIB2 to NETCDF conversion table with the -nc_table sub-option or combine the command line options with instructions in the -nc_table conversion file.

The -append option makes possible to create single large data set for long time series of gridded data. Time dimension of data in the netcdf file is "unlimited", it could be extended "forward" when adding new data but not "backward" before the first defined time value. If data for the same time step already exist in the updated netcdf file these will be silently overwritten.

The -nc_nlev option is needed to export data to netcdf as 4D data defined in {TIME,LEV,LAT,LON} space. It must be followed by integer max_number_of_vertical_levels which defines the vertical dimension size of 4D data exported to the netcdf file. This value can not be found from each single grib2 message or sub-message, usually it has to be scanned the entire grib2 file or even number of files. It is the reason why the max_number_of_vertical_levels value must be provided by user.

Grib2 types of vertical levels eligible for export to the netcdf as 4D data are defined in the wgrib2 internal table and now include next types of GRIB2 levels:

20
:
K level
100
:
pressure level
104
:
sigma level
105
:
hybrid level
107
:
K isentropic level
160
:
ocean depth below sea level

Data for the first found eligible level type are treated as 4D and vertical level information is not added to the variable names. Error is generetad if data for other then first found eligible level type are met in the input stream. Data on the non-eligible levels are treated as 3D data defined in the {TIME,LAT,LON} space with the possible level information included into the variable names or with the user-specified names (see -nc_table option description below for how to do it).

The -nc_nlev option has not -no_... option, please use instead the max_number_of_vertical_levels equal to 0. In this case all data from the input stream will be threated as 3D.

When existing netcdf file is updated in the -append mode the value of max_number_of_vertical_levels must not exceed initial value provided when the netcdf file was first created (defined). By default when first creating the netcdf file, vertical level values are not fixed (are undefined) and these are defined one-by-one when data at new level are added to the netcdf file, up to the max_number_of_vertical_levels. To overcome this feature please use the -nc_table option.

The -nc_pack option makes it possible to limit the range of defined values and pack data in the netcdf file specifying data range and packing type as min:max[:float|byte|short]. Type float here is default and do not assume data packing, only data range is checked. Data outside of specified range are replaced by missing value code for all types of packing. This replacement is done in the local copy of unpacked data, so main data array stays unchanged. Values of min and max could be any signed float. Packing is applied to all new variables in the input stream. If some variable was already defined in the netcdf file and now is appended to it in the -append mode the initially defined and fixed in the netcdf file valid range and packing parameters are used.

The packing is possible to the short (2 bytes) or byte (1 byte) values with potential loss of precision. Both zero values of min and max packing parameters for the short or byte packing activate 'auto' packing when min and max values are defined from the first entered field.

PS: packing in 'byte' is not directly accepted by GrADS v1.9b4 if netcdf file is open with 'sdfopen' command. But by some reasons using the GrADS data description file (catalog) for the same netcdf file helps in this situation.

The -nc_grads option activates some tests for the created netcdf file to be GrADS (version 1.9b4) compatible, or to be open by sdfopen in gradsnc or gradsdods. The GrADS support only COARDS convention netcdf files; it do not support non-constant data time stepping and silently generates wrong time stamps for such netcdf files. Packing to byte also is not directly recognized by GrADS v1.9b4. With this option an error is raised and processing stops if any of criterias above is determined.

The -nc_table option followed by the file_name is most usefull for the advanced users as it specifies the file where user can customize many features of created netcdf file. Next examples demonstrate which directives and conversion rules could be given in the -nc_table file. Almost all of them are optional with exception of $nlev for the case when user explicitly specifies the vertical level values $levs.

$lev_type 100:pressure:pressure level:mb:0.01

This directive explicitly defines the type of vertical level in the grib2 file that becomes eligible for treating data at these levels as 4D data and some it attributes for netcdf file. Default, first found level type listed in the wgrib2 build-in table of eligible levels is selected if no $lev_type directive found.

Fields here include:

100
-
the grib2 level type code number
for treating data as 4D. In this example it is the code number for pressure levels, integer
pressure
-

short_name for the vertical axis in the netcdf file, string
pressure level
-
long_name for the vertical axis in the netcdf file, string, could include spaces
mb
-
vertical axis units as written in the netcdf file, string
0.01
-
decimal scale to convert grib2 level values to the netcdf-stored values, float. In this example we convert Pa to mb (hPa). It is default conversion scale for the pressure levels when exporting to the netcdf file

This directive is an equivalent of the -nc_nlev command line option but value in the -nc_table file has precedence over the command line option if both are found. It is required if next $levs directive is specified.

$levs lev(1) lev(2) lev(3)...

...lev(I-1) lev(I) lev(I+1)...

...lev(X-1) lev(X)

This directive explicitly specifies the vertical level values to be exported to the netcdf file, in the netcdf units. If this directive exists in the -nc_table file and there is found the grib2 data eligible for the 4D presentation but defined on other then listed level - these data are skipped from export and work is silently continued. All data conversion parameters are checked before the $levs is checked. List of level values could consist of multiple lines; max line length in the -nc_table file is limited by _MAX_PATH symbols (about 255 symbols); use space, ',', ';' or ':' as lev(i) fields separator.

Impact of $nlev and $levs directives is different depending on does the netcdf file is first created or it is updated. When the netcdf file is first created these values are written to the netcdf file fixing 4D data vertical structure. When updating an existing netcdf file in the -append mode these parameters will work like filter limiting possible updates of 4D data by these that satisfy to the given $levs only and ignoring other. 3D (TIME,LAT,LON) data are not affected by these directives.

The $nlev and $levs directives could be necessary if records in the grib2 file have randomly changing vertical level values that makes it impossible sequentionally define valid order of vertical levels.

$grads 1

This directive is an equivalent of the -nc_grads command line option if passed value is 1 or to the -no_nc_grads if value is 0. Directive in the -nc_table file has precedence over the command line option.

wgib2_name:wgrib2_level|*:nc_name|ignore[:ignore|no|float|short|byte[:min:max]]

All non-empty lines in the -nc_table file not starting from the '$' symbol or from the comment mark '#' are treated as grib2 to netcdf conversion rules for the specified variables. In these strings the wgib2_name and wgrib2_level are strings as returned by the wgrib2 inventory; * used as the wgrib2_level will apply to all levels not given explicitly. The valid range and packing information is optional but it overwrites common packing rule if such is specified by the -nc_pack command line option. Absence of packing information means no packing for this variable. Min and max values are any signed float values. Both could be omitted or put to zero. Last case means that automatic scaling will be estimated from the first entered wgib2_name field at the wgrib2_level or at the first level in case of * as level value.

If the keyword ignore is found as a netcdf variable name or as a packing type value, the corresponding data are ignored and do not written to the netcdf file. Impact from this keyword is similar to the wgrib2 -not option or filtering data with the grep utility.

The ignore keyword is recommended if the data from the same grib2 file are exported in number of output files (netcdf or other) by the same wgrib2 process. Then the same decoded data could be passed for the output in other file of any supported type. Doing export to the single netcdf file it is not recommended to use the ignore keyword as corresponding data are first decoded and after that skipped from writing to the netcdf file.

In the next example two lines from the -nc_table file instruct the wgrib2 utility export to the netcdf file the geopotential height changing name from HGT (wgrib2) to geopotential in the netcdf file, at all levels except at 975 mb if these data would be found in the grib2 decoded input data stream:

HGT:*:geopotential
HGT:975 mb:ignore

Example 2

Next example shows the content of user-defined -nc_table file for one special case of Japan Meteorological Agency MSM system grib2 data conversion. Same -nc_table file includes the rules for conversion of both 'surface' and upper air data although the input grib2 files are different.

#
# File name: jma_msm_g2nc.table
# Description: Specifies parameters for conversion to Netcdf format
# hourly analyses and forecasts of JMA MSM system as best suited to
# my purposes: forcing of ocean model and reference data for analysis
# of meteorological conditions with GrADS-based visualization tools.
# Sergey Varlamov, July 2007
#
$lev_type  100:p:pressure level:mb:0.01
$nlev      16
$levs  1000 975 950 925 900 850 800 700 600 500
        400 300 250 200 150 100
$grads 1
#
# Upper air data on pressure levels, 05.2007 - 16 pressure levels
#
UGRD:*:u
VGRD:*:v
#UGRD:*:u:ignore
#VGRD:*:v:ignore
TMP:*:temp
#write HGT at any level as hgtprs:
HGT:*:hgtprs
#but skip HGT at 100 mb, now commented - example and test
#HGT:100 mb:hgtprs:ignore
RH:*:rh:short:-2:110
VVEL:*:omega
#
# JMA MSM model surface data conversion rules
#
PRMSL:mean sea level:prmsl
PRES:surface:prsfc
UGRD:10 m above ground:u10m
VGRD:10 m above ground:v10m
TMP:1.5 m above ground:t2m
RH:1.5 m above ground:rh2m:short:-5:110
TCDC:surface:ncld:short:-5:110
LCDC:surface:ncld_low:short:-5:110
MCDC:surface:ncld_mid:short:-5:110
HCDC:surface:ncld_upper:short:-5:110
APCP:surface:r1h
# End of file


Using above file we could create the daily file with 3h analyses
at the 'surface' layers from the input grib2 files
with the next simple shell script:


date=20070715
for (( j=0; j<=21; j+=3 )) #hour of day loop
do
  if [ $j -lt  10 ]
  then
    h=0$j
  else
    h=$j
  fi
  gpath=../example/Z__C_RJTD_${date}${h}0000_MSM_GPV_Rjp_Lsurf_FH00-15_grib2.bin

  wgrib2 $gpath -match ":anl:" -nc_table ./jma_msm_g2nc.table -append -netcdf ./msm_s_${date}.nc
  code=$?
  if [ $code -eq 0 ]
  then
    echo ${date}${h}': created/added to Netcdf'
  else
    echo ${date}${h}': wgrib2 failed...'
    exit $code
  fi
done


Or create the netcdf file with the 4D 3h analyses at 16 pressure levels if replace:

gpath=../example/Z__C_RJTD_${date}${h}0000_MSM_GPV_Rjp_L-pall_FH00-15_grib2.bin

and change the name for the output file:

./msm_s_${date}.nc to the ./msm_p_${date}.nc

Resulting netcdf files could be used directly at least from the GrADS (gradsnc or gradsdods)
utility for data visualization and analyses.

Example 3

Version 1, using loops and a temporary file

rm tempfile
for f in gfs.t00z.pgrb2f[01]?
do
   wgrib2 - -match ':HGT:' -match ':(200|500|700) mb:'  -append -new_grid_winds earth -new_grid latlon 0:40:2 20:20:2 tempfile
done
wgrib2 tempfile -netcdf ~/myfile.nc
rm tempfile

Version 2, data-flow 

1:   cat gfs.t00z.pgrb2f[01]? | \
2:   wgrib2 - -match ':HGT:' -match ':(200|500|700) mb:'  -inv /dev/null \
3:      -new_grid_winds earth -new_grid latlon 0:40:2 20:20:2 - | \
4:   wgrib2 - -netcdf ~/myfile.nc


Line 1 (cat), takes all the desired grib files and writes to stdout
Line 2 (wgrib2), reads the grib file from stdin and selects the desired fields
Line 3 (-new_grid), is a continuation of the wgrib2 command and writes the new grid to stdout
Line 4 (wgrib2), reads the new grid from stdin and writes out a netcdf file (myfile.nc)

See also: -bin, -ieee -text -spread -append