RubyNetCDF is the Ruby interface of the NetCDF library. Ruby is a free
object-oriented scripting language and is freely available from
the Ruby homepage.
To handle numeric data, RubyNetCDF uses
NArray, which is the standard numeric multi-dimensional array class
for Ruby. Thus, you have to have installed it before installing this library.
An NArray object holds numeric data in a consecutive memory area
pointed by a C pointer. Thus, it is computationally efficient.
NArray is similar to NumPy for Python, but results of some benchmark
tests suggests that NArray is more efficient than NumPy.
Optionally, RubyNetCDF offers methods to handle data missing
automatically. To use it, you will also
need NArrayMiss.
See Usage for details.

Currently, NetCDF-4 support is partial (the new data models have not been
supported).

All the NetCDF variable types char, byte, short, int, float, and
double are supported in this Ruby interface. These types are called,
however, differently in it to adhere to the convention of Ruby, or,
more specifically, of NArray. These types are named to as "char",
"byte", "sint", "int", "sfloat", and "float", respectively. Therefore,
the vartype (=ntype) method of the NetCDFVar class returns one of these
strings. The def_var method of the NetCDF class also accepts one of
them to define a variable. It should be noted especially that "float"
in this library means the double in the NetCDF terminology. This is
due to the convention of Ruby -- the predefined Float class
corresponds to the double in C, not the float.

The "get" method of NetCDFVar class reads a variable in a NArray of
the same type as in the file, except for the "char" type which is read
into a "byte". This is because NArray does not have a "char" type.
However, it not is not supposed to be a problem, since a byte NArray
can easily handle string data.

Errors are basically handled by raising exceptions. However, light
errors in value-returning methods are handled by returning nil (e.g.,
if a non-existent attribute name is specified in attribute reading).
Those methods that return nil on error are explicitly written as such
in the following.

To use the RubyNetCDF library, load the library first by placing the
following line in your Ruby program to load the library:

require 'numru/netcdf'

If you want to use automatic data-missing-handling methods
(of NetCDFVar class), use the following:

require 'numru/netcdf_miss'

This will call require 'numru/netcdf' inside at the beginning, so
you do not have to call the both. The missing-data handling is done
with NArrayMiss,
so you have have installed it. This is, however, not needed if you only
call require 'numru/netcdf'.

Here, 'numru', which stands for "Numerical Ruby", is the name of
the subdirectory in the user's load path where the RubyNetCDF library
is placed. Then, it can be used as in the following:

Here, NumRu is the module that has the library in it. The
reason why NetCDF library is wrapped in such a module is to avoid
conflicts in the name space. Without this kind of treatment,
problems happen if the user wants to use a library that happens to
have a class or module with the same name as even one of the classes
in this library.

If such a problem is not expected to happen, the prefix "NumRu::" can
be eliminated by "including" the NumRu module as in the following, so
that to place "NumRu::" is not needed anymore in the current scope:

include NumRu
file = NetCDF.create('tmp.nc')
...

For more examples, see demo and test programs included in the
distribution package.

Opens a file (class method). If mode="w" and the file does not
exist, a new file is created.

Arguments

filename (String): file name (path)

mode (String) : IO mode "r" (read only); "w","w+" (write --
current contents are overwritten (eliminated!)); "r+","a","a+"
(append -- writable while current contents are preserved).
All the options permit reading, unlike the predefined File class.
Note that to "append" will require extra time and disk
space due to the limitations of the original NetCDF library,
which is used in this library.

share (true or false) : Whether to use the "shared" mode or not
(set true if a file being written may be read from other
processes. See nc_open in Ch.5 of users' guide of the C version)

Creates a temporary NetCDF file (class method).
Its name is automatically generated, and it is deleted when closed.

Arguments

tmpdir (String) : directory to place the temporary file.
By default, "." or a directory specified by an environmental
variable (TMPDIR or TMP or TEMP) is used. In a secure mode,
theses environmental variable is NOT used, and the default
value is '.'.

(Available only when NetCDF version 4 is used. Error is raised if not.)
Makes the current (newly created) variable "deflated" (=compressed).
This method must be called after
defining a variable (NetCDF#def_var) and before calling NetCDF#enddef.

value : value to set (Numeric, Array of Numeric (1D only), or
NArray (possibly multi-D)). If it is a Numeric or length==1, the value
is set uniformly.

option (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.

Example: If the variable is 2D:

{"start"=>[2,5],"end"=>[6,-1],"stride"=>[2,4]} -- Specifies a
subset made as follows: the 1st dimension from the element 2
to the element 6 (note that the count starts with 0, so that
the element 2 is the 3rd one) with an interval of 2;
the 2nd dimension from the element 6 to the last element
(designated by -1) with an interval of 5.

{"index"=>[0,0]}: Scalar of the fist element

{"index"=>[0,-2]}: Scalar from the 1st element of with
respect to the 1st dimension and the 2nd element from the last
with respect to the 2nd dimension

Unpack a NArray (etc) using the attributes scale_factor and/or add_offset of self.

If scale_factor and/or add_offset is defined, returns
na * scale_factor + add_offset. Returns na if not.
Type conversion is made by the coercing -- for example
if na is sint and scale_factor and add_offset is sfloat,
return value is sfloat. The type of the return value can be specified
explicitly with NetCDFVar.unpack_type=.

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

In addition to the subset specifications supported by NArray,
ranges with steps are supported, which is specified
like {0..-1, 3}, i.e., a 1-element Hash with the key and value
representing the range (Range) and the step (Integer), respectively.
Unlike NArray, 1-dimensional indexing of multi-dimensional
variables is not support.

Same as NetCDFVar#put but a subset is specified as in the method []= of NArray.

In addition to the subset specifications supported by NArray,
ranges with steps are supported, which is specified
like {0..-1, 3}, i.e., a 1-element Hash with the key and value
representing the range (Range) and the step (Integer), respectively.
Unlike NArray, 1-dimensional indexing of multi-dimensional
variables is not support.

Data missing is specified by the standard attributes valid_range,
(valid_min and/or valid_max), or missing_value, with the precedence being
this order. Unlike the
recommendation in the NetCDF User's guide, missing_value is
interpreted if present. If missing_value and valid_* present
simultaneously, missing_value must be outside the valid range.
Otherwise, exception is raised.

If data missing is specified as stated above, this method returns a NArrayMiss.
If not, it returns a NArray. Thus, you can use this whether
data missing is defined or not.

Missing data handling using valid_* / missing_value is applied
basically to packed data, which is consistent with most
conventions. However, it is applied to unpacked data
if and only if the type of valid_* / missing_value is not the same as
the packed data and is the samed as the unpacked data.
This treatment can handle all conventions.

If value is an NArray, the methods behaves as put.
Data missing in value is interpreted if it is an NArrayMiss
and data missing is specified by attributes in self
(see get_with_miss ).
Namely, the data which are "invalid" in the value is replaced
with a missing value when written in the file.
(missing_value or _FillValue or a value outside
the valid range). No check is made whether "valid" values in the
NArrayMiss is within the valid range of self.

Missing data handling using valid_* / missing_value is applied
basically to packed data, which is consistent with most
conventions. However, it is applied to unpacked data
if and only if the type of valid_* / missing_value is not the same as
the packed data and is the samed as the unpacked data.
This treatment can handle all conventions.