RubyNetCDF Reference Manual

RubyNetCDF version : 0.7.1

---------------------------------------------

Overview

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

Structure

RubyNetCDF consists of the four classes in the following.

Data type

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.

Error handling

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.

Security features

Security handling is done just as in the pre-defined File class.

Usage

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:

file = NumRu::NetCDF.create('tmp.nc')
x = file.def_dim('x',10)
y = file.def_dim('y',10)
v = file.def_var('v','float',[x,y])
file.close

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.

---------------------------------------------

How to read this manual

method_name(argument1, argument2, ...) -- arguments that can be omitted are expressed as Argument_name=Default_value

Explanation of its function

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

---------------------------------------------

Method Index

---------------------------------------------

class NetCDF

constants

Class Methods

NetCDF.nc4?

Returens wheather the linked NetCDF library is NetCDF-4 (true/false). false means that it is version 3.

NetCDF.creation_format=(cmode)

(Available only when NetCDF version 4 is used. Error is raised if not.) Set the file format created by NetCDF.create. The initial setting is "classic" (conventional netcdf 3 format).

Arguments

NetCDF.creation_format

(Available only when NetCDF version 4 is used. Error is raised if not.) Returns the current setting of the creation format.

NetCDF.open(filename, mode="r", share=false)

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

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

NetCDF.new

Aliased to NetCDF.open

NetCDF.create(filename, noclobber=false, share=false)

Creates a NetCDF file (class method)

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

NetCDF.create_tmp(tmpdir=ENV['TMPDIR']||ENV['TMP']||ENV['TEMP']||'.', share=false)

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

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

Instance Methods

close

Closes the file.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

ndims

Returns the number of dimensions in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

nvars

Returns the number of variables in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

natts

Returns the number of global attributes in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

unlimited

Returns the unlimited dimension in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

path

Returns the path of the file (contents of the filename specified when opened/created)

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

redef

Switches to the define mode. Does nothing if already in it (nil returned).

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

enddef

Switches to the data mode. Does nothing if already in it (nil returned).

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

define_mode?

Inquire whether the file is in the define mode.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

sync

Synchronizes the disk copy of a netCDF dataset with in-memory buffer

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

def_dim(dimension_name, length)

Define a dimension

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

put_att(attribute_name, value, atttype=nil)

Sets a global attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

def_var(name, vartype, dimensions)

Defines a variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

def_var_with_dim(name, vartype, shape_ul0, dimnames)

Same as def_var but defines dimensions first if needed. Raise exception if it conflicts with the lengths of existing dimensions.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

var(var_name)

Opens an existing variable in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

vars(names)

Opens existing variables in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

dim(dimension_name)

Opens an existing dimension in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

dims(names)

Opens existing dimensions in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

att(attribute_name)

Opens an existing global attribute in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

fill=(filemode)

Sets a fill mode. (Default behavior of NetCDF is FILL.)

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

each_dim{ ... }

Iterator regarding the dimensions in the file. Ex.: {|i| print i.name,"\n"} prints names of all dimensions

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

each_var{ ... }

Iterator regarding the variables in the file. Ex.: {|i| print i.name,"\n"} prints names of all variables

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

each_att{ ... }

Iterator regarding the global attributes of the file. Ex.: {|i| print i.name,"\n"} prints names of all of them.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

dim_names

Returns the names of all dimensions in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

var_names

Returns the names of all variables in the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

att_names

Returns the names of all the global attributes of the file

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

---------------------------------------------

class NetCDFDim

Class Methods

Instance Methods

length

Returns the length of the dimension

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

length_ul0

Same as length but returns 0 for the unlimited dimension

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

name=(dimension_newname)

Rename the dimension

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

name

Returns the name of the dimension

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

unlimited?

Inquires whether the dimension is unlimited or not

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

---------------------------------------------

class NetCDFVar

Class Methods

NetCDFVar.new(file,varname,mode="r",share=false)

open a NetCDF variable. This can also be done with NetCDF#var (instance method of NetCDF class), which is recommended over this method.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

NetCDFVar.unpack_type=(na_type)

Fix the NArray type to be used in unpack.

Arguments

Return value

NetCDFVar.unpack_type

Returns the NArray type set by NetCDFVar.unpack_type=.

Return value

Instance Methods

deflate(deflate_level, shuffle=false)

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

Arguments

Return value

deflate_params

(Available only when NetCDF version 4 is used. Error is raised if not.) Returns the present deflation parameters.

Return value

endian=(endian)

(Available only when NetCDF version 4 is used. Error is raised if not.) Sets (changes) the endian. See deflate for when to use it.

Arguments

Return value

endian

(Available only when NetCDF version 4 is used. Error is raised if not.) Returns the current endian setting.

Return value

dim(dim_num)

Inquires the dim_num-th dimension of the variable (dim_num=0,1,2,..)

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

dims

Returns an array of all the dimensions of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

shape_ul0

Returns the shape of the variable, but the length of the unlimited dimension is set to zero. Good to define another variable.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

shape_current

Returns the current shape of the variable.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

each_att{ ... }

Iterator regarding the global attributes of the variables. Ex.: {|i| print i.name,"\n"} prints names of all of them.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

dim_names

Returns the names of all the dimensions of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

att_names

Returns the names of all the attributes of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

name

Returns the name of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

name=(variable_newname)

Rename the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

ndims

Number of dimensions of the variable (which is rank of the variable).

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

rank

Aliased to ndims

ntype

Aliased to vartype

vartype

Inquires the data value type of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

typecode

Inquires the data type of the variable (returns a typecode of NArray)

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

natts

Returns the number of the attributes of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

file

Inquires the file that the variable is in

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

att(attribute_name)

Returns the attribute specified by its name

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

put_att(attribute_name, value, atttype=nil)

Sets an attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

put(value, option=nil)

Aliased to simple_put

simple_put(value, option=nil)

Set the values of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

pack(na)

Pack 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-add_offset)/scale_factor. Returns na if not.

Arguments

Return value

scaled_put(value, option=nil)

Same as simple_put but interprets the attributes scale_factor and/or add_offset using pack.

See the document for simple_put for arguments etc.

get(option=nil)

Aliased to simple_get.

simple_get(option=nil)

Returns values of the variable

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

unpack(na)

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=.

Arguments

Return value

scaled_get(option=nil)

Same as simple_get but interprets the attributes scale_factor and/or add_offset using unpack.

See the document for simple_get for arguments etc.

[]

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.

Instance Methods added by requiring "numru/netcdf_miss"

get_with_miss(option=nil)

Same as get but interprets data missing.

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.

Arguments

Return value

Possible exception in addition to NetcdfError.

Corresponding (dependent) function(s) in the C library of NetCDF

EXAMPLE

get_with_miss_and_scaling(option=nil)

Same as get_with_miss but handles data scaling too using unpack.

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.

EXAMPLE

put_with_miss(value, option=nil)

Same as put but interprets data missing.

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.

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

EXAMPLE

put_with_miss_and_scaling(value, option=nil)

Same as put_with_miss but handles data scaling too using pack.

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.

EXAMPLE

---------------------------------------------

class NetCDFAtt

Class Methods

Instance Methods

name

Returns the name of the attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

name=(attribute_newname)

Rename the attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

copy(var_or_file)

Copies an attribute to a variable or a file. If file, becomes an global attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

delete

Delete an attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

put(value, atttype=nil)

Sets the value of the attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

get

Returns the values of the attribute

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

atttype

Inquires the type of attribute values

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF

atttype

Inquires the type of attribute values (returns a NArray typecode)

Arguments

Return value

Corresponding (dependent) function(s) in the C library of NetCDF