PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-strict.dtd">

RubyNetCDF レファレンスマニュアル

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

概要

RubyNetCDF は NetCDF ライブラリーの Ruby インターフェースである。Ruby はフリーなオブジェクト指向スクリプト言語であり、 http://www.ruby-lang.org/ja/ から入手できる。RubyNetCDF は数値配列として、 Ruby で一般的に使われている多次元数値配列ライブラリー NArray を用いて いる(http://www.ruby-lang.org/en/raa-list.rhtml?name=NArray)。 NArray はデータを、C のポインターが指す連続したメモリー領域 に保持し、計算機資源を効率よく利用する。NArray は Python における NumPy と似るが、幾つかのテストは NArray のほうが NumPy より効率が良い ことを示唆している。

構成

RubyNetCDF は以下の4つのクラスから構成される。

データ型

本ライブラリーでは全ての NetCDF 変数の型 char, byte, short, int, float, double がサポートされている。しかし、これらは Ruby の(より正確 に言うと NArray の)慣例に従って、それぞれ "char", "byte", "sint", "int", "sfloat", "float" と呼ばれる。従って、NetCDFVar クラスの vartype (=ntype) はこれらの文字列の一つを返す。また、NetCDFクラスの def_var メ ソッドは、変数を定義する際、これらを受け付ける。特に注意する必要がある のは、本ライブラリーでの "float" は C で言うところの double を意味する ということである。これは Ruby の慣例のせいである -- 組み込みの Float クラスは、C の float でなく double に対応するのである。

NetCDFVar クラスの get メソッドはファイル中と同じ型の NArray 変数に値 を読み込むが、"char" 型変数については "byte" 型 NArray に読み込まれる。 これは NArray が "char" 型を持たないからである。ただ、そもそも NArray は byte 型で文字列を簡単に扱えるので、特に不都合はないと考えられる。

エラー処理

エラーは基本的には例外を発生することにより対処する。但し、値を返すメソッ ドでは軽微なエラーは nil を返すことで対処する(属性値を得るために指定 された名前の属性が存在しないときなど)。例外的な状況で nil を発生する メソッドについてはマニュアルに明記してある。

セキュリティ

組み込みの File クラスと同じセキュリティー対応をしていてる。

使用法

RubyNetCDFライブラリーを利用するためには、まず次の行を Ruby プログラムに書い てライブラリーをロードする必要がある。

require 'numru/netcdf'

ここで、'numru' ("Numerical Ruby"から取られた) はユーザーのライブラリー ロードパス中のサブディレクトリーで、RubyNetCDF ライブラリーが置かれる。 すると、以下のように利用できるようになる。

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

ここで、NumRu はこのライブラリーを含むモジュールである。このようなモジュー ルにくるんであるのは、名前空間での衝突を避けるためである。このような扱 いをしない場合、もしもユーザーが、本ライブラリー中のクラスと名前が衝突 するクラスやモジュールを含むライブラリーを使おうとすると、問題が起る。

このような問題が起こらないであろう場合は、"NumRu::" という冠は、NumRu モジュールを「インクルード」することで外せる(現在のスコープにおいてと いうこである)。従って次のように書ける。

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

さらなる使用例としてはダウンロード用パッケージに含まれる demo や test プログラムを参照せよ。

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

マニュアルの見方

メソッド名(引数1, 引数2, ...) -- 省略可能な引数は 引数名=デフォルト値 の形で示す

機能の解説

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

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

メソッドインデックス

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

クラス NetCDF

クラスメソッド

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

ファイルオープン(クラスメソッド)mode="w" でファイルが存在しなければ新規作成

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

NetCDF.new

NetCDF.openメソッドのエイリアスである

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

NetCDFファイルを作る(クラスメソッド)

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

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

テンポラリーNetCDFファイルを作る(クラスメソッド) 名前は自動で決まる。クローズされると消される。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

インスタンスメソッド

close

ファイルクローズ

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

ndims

ファイル中の次元の数を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

nvars

ファイル中の変数の数を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

natts

ファイル中のグローバル属性の数を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

unlimited

ファイル中のunlimited dimensionを返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

path

ファイルのパス. open/create時のfilename引数の中身を返す.

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

redef

define modeにする。既にそうなら何もしない。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

enddef

data mode に入る。既にそうなら何もしない。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

sync

メモリー中のバッファーをディスク上に反映してファイルを同期させる

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

def_dim(dimension_name, length)

dimensionを定義

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

put_att(attribute_name, value, atttype=nil)

グローバル属性を設定

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

def_var(variable_name, vartype, dimensions)

変数を定義

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

def_var_with_dim(variable_name, vartype, shape_ul0, dimnames)

def_varと同じだが必要ならまず次元を定義する。 既存次元の長さと合わない場合例外。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

var(var_name)

ファイルに既存の変数をオープン

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

dim(dimension_name)

既存の次元をオープン

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

att(attribute_name)

既存のグローバル属性をオープン

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

fill=(filemode)

fillmodeの変更。(NetCDF のデフォルトは FILL である。)

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

each_dim{ ... }

次元に関するイテレータ. 例: {|i| print i.name,"\n"} で全次元の名前を表示.

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

each_var{ ... }

変数に関するイテレータ. 例: {|i| print i.name,"\n"} で全変数の名前を表示.

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

each_att{ ... }

グローバル属性に関するイテレータ. 例: {|i| print i.name,"\n"} で全属性の名前を表示.

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

dim_names

ファイル中の全次元の名前を配列に入れて返す。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

var_names

ファイル中の全変数の名前を配列に入れて返す。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

att_names

ファイル中の全グローバル属性の名前を配列に入れて返す。 引数

戻り値

対応する(利用する) C 版 NetCDF の関数

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

クラス NetCDFDim

クラスメソッド

インスタンスメソッド

length

次元の長さを返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

length_ul0

length と同じだが、無制限次元に関しゼロを返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

name=(dimension_newname)

名前をつけかえる

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

name

名前を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

unlimited?

無制限次元かどうか?

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

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

クラス NetCDFVar

クラスメソッド

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

NetCDF変数をオープンする。これは、NetCDF#var (NetCDFクラスのイン スタンスメソッドvar) を使っても出来るし、そちらのほうを推奨する。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

インスタンスメソッド

dim(dim_num)

その変数における dim_num 番目(0から数える)の次元を問合わせる。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

dims

その変数の全次元を配列にいれて返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

shape_ul0

変数の形を返す. 但し無制限次元の長さはゼロ. 他の変数の定義に便利.

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

shape_current

変数の現在の形を返す.

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

each_att{ ... }

変数中の全属性(NetCDFAtt)に関するイテレータ

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

dim_names

変数中の全次元の名前を配列に入れて返す。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

att_names

変数中の全属性の名前を配列に入れて返す。

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

name

変数の名前を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

name=(variable_newname)

名前を付け替える

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

ndims

次元の数を問う

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

ntype

vartypeの別名

vartype

変数値の型を問う

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

natts

属性の数を問う

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

file

その変数が属するファイルを問合わせる

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

att(attribute_name)

名前を指定した属性を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

put_att(attribute_name, value, atttype=nil)

属性を設定

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

put(value, option=nil)

値を入れる

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

scaled_put(value, option=nil)

put と同様だが、属性 scale_factor と add_offset を解釈する

scale_factor と/または add_offset が定義されていたら、書き込む前 に (value-add_offset)/scale_factor を行う。 もしもどちらか一つの属性が定義されていなければ、ファクターなら1、オ フセットなら0を仮定する。

引数等については put の解説を参照のこと

get(option=nil)

値を取り出す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

scaled_get(option=nil)

get と同様だが、属性 scale_factor と add_offset を解釈する

scale_factor と/または add_offset が定義されていたら、 value*scale_factor+add_offset を返す。 もしもどちらか一つの属性が定義されていなければ、ファクターなら1、オ フセットなら0を仮定する。 返り値(NArray)の型は、NetCDF変数が int または float なら float (倍 精度)、それ以外なら sfloat (単精度) となる。

引数等については put の解説を参照のこと

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

クラス NetCDFAtt

クラスメソッド

インスタンスメソッド

name

属性の名前を返す

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

name=(attribute_newname)

属性の名前を変更

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

copy(var_or_file)

属性を別の変数またはファイルにコピー。ファイルの場合はグローバル属性になる

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

delete

属性を削除

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

put(value, atttype=nil)

属性の値を設定

引数

戻り値

対応する(利用する) C 版 NetCDF の関数

get

属性の中身を取り出す

引数

戻り値

NArrayになる)
対応する(利用する) C 版 NetCDF の関数
*  nc_get_att_<type>
atttype

属性の種類を問う

引数

戻り値

対応する(利用する) C 版 NetCDF の関数