NCL: Handling GrADS (Gridded Datasets) files

• Introduction
• A Climate Data Operator command to convert GrADS ctl/binary to netCDF
• A Ruby script to convert GrADS ctl/binary to netCDF
• Examples

Introduction

GrADS datasets consist of two separate files: (a) the Data Descriptor File (ascii) and (b) the raw binary data. As described in the GrADS documentation:

1. "The data descriptor file contains a complete description of the binary data as well as instructions for GrADS on where to find the data and how to read it." This ascii file has the ".ctl" file extension. Sometimes, it is referred to as the 'control file'.

2. "The binary data file is purely data with no space or time identifiers." By default, GrADS assumes these binary files etc are 'flat' or 'stream' binary files. Languages/tools like C, C++, Matlab, IDL create 'flat' files. However, binary files created by fortran may be 'flat' ["direct"] or may contain record length information ["sequential"]. The latter is the default in fortran. If the binary file is "sequential", the descriptor file should contain the option:

    OPTIONS sequential

NCL can read files created in either binary format. Most commonly, 'flat' files are read via fbindirread and 'sequential' files via fbinrecread . GrADS descriptor files may contain an additional option specifying the type of binary 'endian' used to create the binary file. Examples include:

    OPTIONS big_endian            [little_endian, cray_32bit_ieee]

The setfileoption procedure can be used to accomodate any of these binary specifications.

The Climate Data Operators (CDO) can convert GrADS binary file to netCDF

The following CDO command will convert a binary data file to netCDF:

 
   cdo -f nc import_binary file.ctl ofile.nc 

The import_binary operator imports gridded binary data sets via a GrADS data descriptor file. The GrADS data descriptor file contains a complete description of the binary data as well as instructions on where to find the data and how to read it.

A Ruby script to convert GrADS ctl/binary to netCDF

This section documents a ruby based script that can automatically parse complicated [multiple variables, different dimensionalities, etc] data descriptor files. It will create an NCL script that can create netCDF files.

Saji N. Hameed of the APEC Climate Center in Busan, Korea gave us permission to include his ruby script that parses a GrADs ctl file and generates NCL code to read in the data and create a COARDS compliant netcdf data object.

Saji provided us with his code and this information in an ncl-talk message:

This is a preview version and some essential features may not be implemented: for example currently there is only support for linear grids (I will add support for gaussian grids over the weekend or better if somebody chipped in and added those code, that will be nice too). Meanwhile I would appreciate feedback and reports on possible bugs/errors.

To use:

• Hopefully you have ruby installed in your system

  <<<<<<< grads.xml

• Visit the download page for Ctl2Ncl to download the software. =======
• Visit the download page for Ctl2Ncl to download the software. The latest and previous versions are available. A version is also available here on the NCL website, but it may not be the latest one. >>>>>>> 1.10

• Untar the tar file in somewhere like $HOME/bin

• Point the $PATH variable to this location.

  For example, PATH=$PATH:$HOME/bin/Grad2NCL ; export PATH

  OR

  set path=($HOME/bin/Grad2NCL $path)

• After sourcing your .cshrc or .bashrc,

  run ctl2ncl.rb and follow the instructions

• The help screen is shown below:

  Usage: ctl2ncl.rb [options]
  A grads ctl parser and NCL script generator based on ruby
  Specific options:
      -i, --infile=CTLFILE             the grads ctl file 
      -o, --outfile=NCLFILE            the NCL script file 
      -v, --vars *NUM                  The variables
          --plot                       add code to display figures
  
  Common options: 
          --help                       Show this message
          --version                    Show version
  

Examples

The following simple NCL scripts are included to demonstrate how to read GrADS binary files directly. These are 'file-specific' and not general purpose. The user must examine the GrADS data descriptor file and create a script to read the file. The NCL examples convert to netCDF but this is not necessary. NCL can read/process/plot the binary file directly.

;  Grads control file
; ---------------
; dset snow.grd
; title snow depth  winter
; options sequential big_endian
; undef -9999.00               
; xdef 29 linear 20. 5.
; ydef 8 linear 35.  5.
; zdef 1 linear 1 1
; tdef 60 linear jan1936 1yr
; vars 1
; p 0 0 precipitation 
; endvars
; ---------------

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl" 
begin
  
  diri  = "./"                            ; input directory
  fili  = "snow.grd"                      ; DSET
  fName = diri+fili                       ; path

  nlat  = 8                               ; YDEF
  mlon  = 29                              ; XDEF

  year  = 1936                            ; TDEF
  ntim  = 60                              ; time steps
  nmos  = 12
  
                                          ; create an array to contain data
  UNDEF = -9999.                          ; UNDEF
  x     = new ( (/ntim,nlat,mlon/), float, UNDEF)

  x@long_name = "Snow Depth"              ; VARS
  x@units     = "mm"                 
                                    
  setfileoption("bin","ReadByteOrder","BigEndian")
                                         
  do nt=0,ntim-1                          ; read each record: store in x
     x(nt,:,:) = fbinrecread(fName, nt, (/nlat,mlon/), "float")
  end do

  printVarSummary(x)
  print ("min(x)="+min(x))
  print ("max(x)="+max(x))
end