GFD Dennou Club / Dennou Ruby / Products

RubyNetCDF -- Ruby interface to NetCDF

by T Horinouchi, and T Koshiro, S Otsuka, S Nishizawa, T Sakakima

RubyNetCDF is the Ruby interface to the NetCDF library built on the NArray library, which is an efficient multi-dimensional numeric array class for Ruby.

What's new

Download

If you are neither an user of NetCDF nor Ruby, read both of the two introductions below :-p

Introduction (for NetCDF users)

Ruby is an interpreted, object-oriented language, which is similar to (but arguably is better than) Python. Ruby is supported on wide variety of hardware and operating systems. It is easy to extend Ruby with C programs, for which you don't even need to recompile it.

NArray is an extension of Ruby and is the de facto standard class of numeric multi-dimension array. It has similar features to NumPy for python. It is efficient, since an NArray object consists of a C structure containing a pointer to data and information on type and dimension (contrary, the Array class predefined in Ruby can take any combination of Ruby objects). Therefore, RubyNetCDF, which is built on NArray, is also efficient and suitable to handle large data.

RubyNetCDF is basically a one-to-one interface to the original NetCDF library, but it
(1) consolidates some functions having same purposes and
(2) supports some additional functions to help users by combining the raw functions.

An example of (1) is the consolidation of nc_put_var families (nc_put_var_type, nc_put_var1_type, nc_put_vara_type and nc_put_vars_type. Here, nc_put_varm_type is not covered, since it is realized by rearranging the input array first). Their consolidation is illustrated by the following piece of Ruby code (statements after "#" are comments): 

      require "numru/netcdf"                           # load RubyNetCDF
      include NumRu
      file = NetCDF.create("hogehoge.nc")
      xdim = NetCDF.def_dim("x",10)
      ydim = NetCDF.def_dim("y",20)
      var = file.def_var("var1","sfloat",[xdim,ydim])
                               # the last argument can also be written as
                               # ["x","y"]. The order of dimensions is in the
			       # Fortran way (fastest varying dimension first),
                               # but the array index start with 0.

      var.put( ary2d )         # writes the whole variable at once.
                               # The total size of the array "ary2d" must
                               # be equal to that of "var1" in the file,
                               # which is 200

      var.put( ary, "start"=>[0,0], "end"=>[4,0], "step"=[2,1] )
                               # writes in the subset of "var1" starting
                               # from the beginning of the array ("start"=>[0,0])
                               # and ending at the 5th and 1st elements of
                               # the 1st and 2nd dimensions, respectively
                               # ("end"=>[4,0]), with increments along
                               # the 1st dimension equal to 2. Therefore, 
                               # "ary" must an array of its length equal to 3
			       # to cover indices [0,0], [2,0], and [4,0].

      var.put( 999.0, "index"=>[3,3] )    # "index" specifies a scalar

      file.close

An example of (2) is "iterators", by which iterations are made easy as follows: 

      require "numru/netcdf"                           # load RubyNetCDF
      include NumRu
      file = NetCDF.open("hogehoge.nc")
      var = file.var("var1")
      var.each_att{ |a|
         print a.name,"\n"
      }
By this, names of all the attributes that belong to the variable var1 in the file hogehoge.nc are printed out on your command-line terminal. As you see above, NetCDF variables are represented by only one variable (var1 here), not by a combination of file ID and variable ID. It is the case with dimensions and attributes too (For example, the variable a in the 3rd and 4th lines represent attributes one by one in the iteration loop). Files, dimensions, variables, and attributes are represented by NetCDF, NetCDFDim, NetCDFVar, NetCDFAtt classes, respectively. From a NetCDFVar object, the file that accommodates the variable can be reached by the method "path" (Note: the term "method" is equivalent to "function" for conventional languages). Therefore, if you add the following line after the ruby code above, it would print out "hogehoge.nc", which is the string used to open the file. 
      print var.path,"\n"

Introduction (for Ruby users)

NetCDF (network Common Data Form) is an array-oriented data format as well as is the library to access files of the format. It enable us to store data in a self-descriptive way, by which we mean that a dataset can tell everything needed to handle it -- what is not self-descriptive then is a dataset that needs additional documents. As you see from this argument, self-descriptive datasets are friendly to object-oriented languages.

The NetCDF format is abstract in the sense that the binary structure of a NetCDF file is hidden from the user. He or she must access it through named tags.

The library of NetCDF is written in C. In addition, it has interfaces for a number of languages such as Fortran(77 and 90), Java, and Perl.

Documentation

Installation

Takeshi Horinouchi ()
GFD Dennou Club:
Copyright (C) GFD Dennou Club, 2000, 2001. All rights reserved.