Recipe 002
Title: Saving GrADS Variable data to a text file.
Author: Arlindo da Silva <dasilva@opengrads.org>
Created: 2008-08-30
Status: ACTIVE
Requires: GrADS v1.9b4 or later


Problem

You would like to open a GrADS data file and save one or more variables to an ASCII file for visual examination or to export the data to another application.

Solution

Starting with GrADS v1.9 the graphics option set gxout print allows the result of a display command to be printed the screen. Such output could be cut and then pasted into to a file. The script below eliminates the need for the cut-and-paste by writing the result directly into a file.

GrADS Script: fprintf.gs


function fprintf(args)

* Command line argumets
* ---------------------
  expr = subwrd(args,1)
  file = subwrd(args,2)
  format = subwrd(args,3)
  numl = subwrd(args,4)
  numb = subwrd(args,5)
  u = subwrd(args,6)

  if ( file='' )
    say ''
    say 'NAME'
    say '     fprintf - print GrADS variables to a text file'
    say ''
    say 'SYNOPSIS'
    say '     fprintf  expr  txtFile  [format numl numb [u]]'
    say ''
    say 'DESCRIPTION'
    say '     Evaluates the contents of the GrADS expression *expr* writing'
    say '     its values to a formatted text file *txtFile*. On output, the'
    say '     number of values and the undef values are returned; a negative'
    say '     number of values signals an error condition.'
    say ''
    say '     Unlike the output of *set gxout print*, the resulting ASCII'
    say '     file has only the data values and *no header*.'
    say ''
    say 'OPTIONS'
    say '     The optional parameters are the same as the ones required by'
    say '     the GrADS command *set prnopts*, namely'
    say '     format   a C language template for formatting ASCII output.'
    say '              Default is %g.'
    say '     numl     number of values to print per record. Default is 8.'
    say '     numb     number of blanks to insert between values. Default is 1.'
    say '     u        print "Undef" instead of the numerical value for'
    say '              missing data.'
    say 'BUGS'
    say '     The GrADS expression cannot have spaces in it.'
    say ''    
    say 'COPYRIGHT'
    say '     This script has been placed in the public domain'
    say ''
    return
  endif

* Set the display environment and produce buffered ASCII output
* -------------------------------------------------------------
  'set gxout print'
  if ( format != '' )
    'set prnopts ' format ' ' numl ' ' numb ' ' u ' '
  endif
  'display ' expr
   if ( rc!=0 ); return -1; endif

*  Get rid of header line: Printing Grid -- 3358 Values -- Undef = 1e+20
*  but record number of values and undef values for later reference
*  ---------------------------------------------------------------------
   buffer = result
   i = 1; line = sublin(buffer,i)
   n = subwrd(line,4)
   undef = subwrd(line,9)
 
* Now write the data values to text file: first line...
* -----------------------------------------------------
  i = 2; line = sublin(buffer,i)
  if ( write_(file,line) > 0 ); return -2; endif

* Append subsequent lines
* -----------------------
  i = i + 1; line = sublin(buffer,i)
  while ( line != '' )
    if ( write_(file,line,append) != 0 ); return -3; endif 
    i = i + 1; line = sublin(buffer,i)
  endwhile
  if ( close(file) != 0 ); return -4; endif

* All done
* --------
  say 'wrote ' n ' values to file "' file '"'
  return n ' ' undef ' ' 

function write_(file,line)
   rc = write(file,line)
   return subwrd(rc,1)

Discussion

The GrADS script fprintf above is very flexible. The format parameters allow you to customize the ASCII output as the examples below illustrate. For these examples you need to obtain the Sample GrADS Test Data Files and save the script above to a file named fprintf.gs. Then, start one of the GrADS executables and open a test file:

% grads
...
ga-> open model.ctl
Scanning description file:  model
Data file model.grb is open as file 1
LON set to 0 360 
LAT set to -90 90 
LEV set to 1000 1000 
Time values set: 1987:1:1:0 1987:1:1:0 

Simple ASCII output

Using the format defaults:

ga-> fprintf ts ts.txt
wrote 3358 values to file "ts.txt"

The abbreviated contents of the file ts.txt are:

258.493 258.493 258.493 258.493 258.493 258.493 258.493 258.493 
258.493 258.493 258.493 258.493 258.493 258.493 258.493 258.493  
...
246.493 246.493 246.493 246.493 246.493 246.493 246.493 246.493 
246.493 246.493 246.493 246.493 246.493 246.493 246.493 246.493 
246.493 246.493 246.493 246.493 246.493 246.493

Finding out the coordinates of each data point

Internally, GrADS keeps gridded data columnwise, like in Fortran, and the the data is written to file in the same order. The easiest way to find out the coordinate of each data point is to save to similar files the intrinsic lat/lon/lev variables provided by GrADS, e.g.,

ga-> set x 1 72
ga-> fprintf.gs lat lat.txt %g 72
ga-> fprintf.gs lon lon.txt %g 72
ga-> fprintf.gs lev lev.txt %g 72

The lon.txt file reads

0 5 10 15 20 25 ... 335 340 345 350 355 
0 5 10 15 20 25 ... 335 340 345 350 355
0 5 10 15 20 25 ... 335 340 345 350 355
...

while the lat.txt file has

-90 -90 -90 -90 ... -90 -90 -90 -90
-86 -86 -86 -86 ... -86 -86 -86 -86 
-82 -82 -82 -82 ... -82 -82 -82 -82 
...
 82  82  82  82 ...  82  82  82  82 
 86  86  86  86 ...  86  86  86  86
 90  90  90  90 ...  90  90  90  90

The file lev.txt in this example has the same number of rows and columns with a single number: 1000.

Comma Separated Values (CSV) for use in Spreadsheets

The current sample file has 72 longitudinal points and 46 latitudinal points. You save an ASCII with 46 rows, one row per latitude, having the longitude values comma separated.

ga-> set x 1 72
ga-> fprintf ts ts.csv %g, 72 0

The CSV file looks like this:

258.493,258.493,258.493,258.493,258.493,..
258.493,261.493,260.993,260.993,260.493,...
...

File ts.csv can be imported directly into Microsoft(tm) Excel. Start Excel, click on [Data]/[Get External Data]/[Import Text File...] and follow the instructions, selected commas as the column separator.

Excel csv.png

Text File for Loading into Matlab

In this case you just write a file space delimited columns:

ga-> fprintf.gs ts ts.txt %g 72

which can be directly loaded into Matlab(tm):

Ts matlab.png

Note: The JyGrADS based interface is a much more efficient way of getting GrADS data into Matlab.

See Also

No Warranty

Because the software provided in this Recipe is licensed free of charge, there is no warranty for it, to the extent permitted by applicable law. Except when otherwise stated in writing the authors and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair or correction.

Copyright

This document has been placed in the public domain.

Powered by MediaWiki