../lib/numru/gphys/grads_gridded.rb

# NumRu::GrADS_Gridded -- a class for GrADS gridded datasets

by T Horinouchi and R Mizuta

## 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

- The "units" field in variable definitions are only partially interpreted. Interpreted are 99 or 0 (default), and -1,30.
- 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.

- Partial support of the "template" option (only %m2,%y2,%y4) (Time is assumed to be increasing monotonically).

## 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" (read only) or "w" (write only).

  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.

#### `GrADS_Gridded.create(ctlfilename, noclobber=false, share=false)`

  make a new GrADS_Gridded object with creating a new control file

  REMARK

  - It is used with writing methods, but currently writing methods does not work.

## Methods

#### `ndims`

  returns the number of dimensions in the file (always 4).

#### `nvars`

  returns the number of variables in the file.

#### `natts`

  returns the number of attributes of the variable.

#### `path`

  returns the path of the control file.

#### `put_att( attname, value )`

  set global attribute

  ARGUMENTS

  - attrname (String): name of an attribute
  - value (String): value of an attribute

#### `def_var(name="noname",nlev=0,option="99",description="")`

  define a variable

  ARGUMENTS

  - name (String): name of the variable
  - nlev (Integer): number of vertical levels
  - option (String): variable placement option ("99": normal, "-1,30": transpose lon and lat)

#### `var( varname=nil )`

  opens an existing variable in the file.

  ARGUMENTS

  - varname (String): name of the variable to open

  RETURN VALUE

  - a GrADSVar object.

#### `vars( names=nil )`

  opens existing variables in the file.

  ARGUMENTS

  - names (Array): names(String) of the variable to open

  RETURN VALUE

  - Array of GrADSVar objects. returns all variables if names==nil

#### `get_att( key=nil )`

  returns tha value of the global attribute

#### `dim_names`

  returns the names of all dimensions in the control file.

#### `var_names`

  returns the names of all variables in the control file.

#### `att_names`

  returns the names of all the global attributes.

#### `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.

#### `put(ary)`

  writes the NArray on the binary data file.

  ARGUMENTS

  - ary (NArray): data to write.

#### `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).

#### `get_dim(dim)`

  returns positions of a dimension as an NArray.

  ARGUMENTS

  - dim (String): a dimension name

  RETURN VALUE

  - an NArray

#### `title`

#### `title=`

  get/set the title

#### `undef`

#### `undef=`

  get/set the undef value

#### `dset`

#### `dset=`

  get/set the dset string

# GrADSVar -- a class for a variable of GrADS gridded datasets

by R Mizuta

## Overview

a GrADSVar object corresponds to one variable in a GrADS control file. It is intended to behave as a correspondent of a NetCDFVar object.

## Current Limitations

- Only a part of the methods can work.
- Writing methods are not supported.

## Class Methods

#### `GrADSVar.new(file, varname)`

  make a new GrADSVar object.

  ARGUMENTS

  - file (GrADS_Gridded or String): a GrADS_Gridded object or a name of the control file to open
  - varname (String): name of the variable to open

## Methods

#### `shape_ul0`

  returns the shape of the variable, but the length of the unlimited dimension is set to zero.

  RETURN VALUE

  - Array. [length of 0th dim, length of 1st dim,.. ]

#### `shape_current`

  returns the current shape of the variable.

  RETURN VALUE

  - Array. [length of 0th dim, length of 1st dim,.. ]

#### `dim_names`

  returns the names of all dimensions of the variable.

#### `att_names`

  returns the names of all attributes of the variable.

#### `name`

  returns the name of the variable.

#### `ndims`

  returns the number of dimensions in the file (always 4).

#### `rank`

  alias of ndims

#### `vartype`

  returns "sfloat" in order to behave as NetCDFVar#vartype.

#### `natts`

  returns the number of attributes of the variable.

#### `file`

  returns the file name that controls the variable.

#### `get_att( name=nil )`

  returns tha value of the attribute of the variable.

#### `put_att( name, value )`

  set an attribute of the variable.

  ARGUMENTS

  - name (String): name of an attribute
  - value (String): value of an attribute

#### `get(hash=nil)`

  returns values of the variable.

  ARGUMENTS

  - hash (Hash) : Optional argument to limit the portion of the variable to output values. If omitted, the whole variable is subject to the output. This argument accepts a Hash whose keys contain either "index" or a combination of "start","end", and "stride". The value of "index" points the index of a scalar portion of the variable. The other case is used to designate a regularly ordered subset, where "start" and "end" specifies bounds in each dimension and "stride" specifies intervals in it. As in Array "start", "end", and "index" can take negative values to specify index backward from the end. However, "stride" has to be positive, so reversing the array must be done afterwards if you like.

  RETURN VALUE

  - an NArray object

  REMARK "stride","index" is not supported yet.

#### `[]`

  Same as GrADSVar#get but a subset is specified as in the method [] of NArray.