GrADS_Gridded -- a class for GrADS gridded datasets

by T Horinouchi

Overview

a GrADS_Gridded object corresponds to a GrADS control file, through which the users can also access its binary data file(s).

Current Limitations

Multiple files are not supported (i.e., the template option is ignored)
The "units" field in variable definitions are only partially interpreted. Interpreted are 99 or 0 (default), and -1,30.
Endian conversion is not supported
options yrev and zrev are not interpreted
option 365_day_calendar is not interpreted

Partial support of possible units of the time increment: mn (minutes), hr (hours) and dy (days) are supported, but mo (month) and yr (year) is not.

(Developer's memo): Time is stored as Julian day and is handled with
the Date standard library. Thus, it's not difficult to support the
unsupported units. However, it would be tricky to support the
365_day_calendar option.

Class Methods

GrADS_Gridded.new(ctlfilename, mode="r")

same as GrADS_Gridded.open

GrADS_Gridded.open(ctlfilename, mode="r")

make a new GrADS_Gridded object.

ARGUMENTS

ctlfilename (String): name of the control file to open
mode (String): IO mode. "r" or "w+" (precisely speaking, you can use "w", but it is interpreted as "w+". Thus, all files opened will be readable). CURRENTLY, ONLY "r" IS HANDLED.

REMARK

You can modify the object through instance methods even if mode=="r". In that case, the modification will not be written in the original control file.

Methods

to_ctl

returns the contents of the corresponding control file as a String.

REMARK

The contents is reconstructed from the internal data of the object. Therefore, even when the object is based on a read-only control file, it is not necessarily the same as the original one. It is especially true when the object was modified after it is opened.

get(name, level, time)

reads the binary data and returns as a NArray.

ARGUMENTS

name (String): name of the variable to read
level (Integer, currently): vertical level to read (0,1,2,...; starting from 0). Currently only one vertical levels must be chosen, but in the future, it is planned to support multiple levels.
time (Integer, currently): time to read (0,1,2,...; starting from 0). Currently only one time must be chosen, but in the future, it is planned to support multiple times.

varnames

Returns names of the variable in the GrADS file as an Array in the order placed.

dimensions

Returns info on the four dimensions.

RETURN VALUE

an Array of 4 elements: dimension[0] for x, dimension[1] for y, dimension[2] for z, and dimension[3] for t. Each of them is a Hash like the following:
```
{:name=>"x", 
:len=>132, 
:flag=>"LINEAR",
:spec=>"-0.7500         1.5000",
:start=>-0.75, :increment=>1.5,
:description=>"longitude", 
:units=>"degrees_east"}
```
Here, :len, :flag, and :spec are directly from the control file, while others are derived properties for internal use.

WARNING

Each elements of the return value is not a clone but is a direct association to an internal object of the object. Therefore, to modify it is to modify the object. That is, dimensions[0][:len]=10 would actually change the internal variable, while dimensions[0]=nil has no effect (the former is a substitution IN a Hash, while the latter is a substitution OF the Hash).

ctlfilename

path of the control file

get/set the title

get/set the undef value

dset

dset=

get/set the dset string