RubyNetCDF version : 0.7.1
---------------------------------------------
RubyNetCDF は NetCDF ライブラリーの Ruby インターフェースである。Ruby はフリーなオブジェクト指向スクリプト言語であり、 ここ から入手できる。RubyNetCDF は数値配列として、 Ruby で一般的に使われている多次元数値配列ライブラリー NArray を用るので、あらかじめインストールしておく必要がある。 NArray はデータを、C のポインターが指す連続したメモリー領域 に保持し、計算機資源を効率よく利用する。NArray は Python における NumPy と似るが、幾つかのテストは NArray のほうが NumPy より効率が良い ことを示唆している。 オプションとして、RubyNetCDF はデータ欠損の自動的な取り扱いメソッドを 提供する。これを使うには、 NArrayMiss が必要である。詳しくは使用法を見よ。
現在 NetCDF-4 のサポートは部分的である(新しいデータモデルはサポートしてない)。
RubyNetCDF は以下の4つのクラスから構成される。
クラス NetCDF -- ファイルのクラス
一つのNetCDFクラスのオブジェクトは一つの NetCDF ファイルに対応する
クラス NetCDFDim -- 次元のクラス
C 版 NetCDF では、次元は、ファイルのIDと次元IDという2変数の組で表されるが、 Ruby 版では一つの NetCDFDim オブジェクトで代表される
クラス NetCDFVar -- 変数のクラス
C 版 NetCDF では、変数は、ファイルのIDと変数IDという2変数の組で表されるが、 Ruby 版では一つの NetCDFVar オブジェクトで代表される
クラス NetCDFAtt -- 属性のクラス
C 版 NetCDF では、属性は、ファイルのIDと変数IDと属性名の組で表されるが、 Ruby 版では一つの NetCDFAtt オブジェクトで代表される
本ライブラリーでは全ての 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'
もしも (NetCDFVarクラスの) 自動的なデータ欠損処理メソッドを使いたい場 合は、以下を実行する必要がある。
require 'numru/netcdf_miss'
これは内部で一番最初に require 'numru/netcdf'
を実行するので、
これだけ呼べば良い。データ欠損の扱いは
NArrayMiss
によるので、これをインストールしておかねばならない。
もしも require 'numru/netcdf'
だけを呼ぶのなら、NArrayMiss
は不要である。
ここで、'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 の関数
---------------------------------------------
クラスメソッド
インスタンスメソッド
クラスメソッド
インスタンスメソッド
クラスメソッド
インスタンスメソッド
"numru/netcdf_miss" を require することで追加されるインスタンスメソッド
クラスメソッド
インスタンスメソッド
---------------------------------------------
NetCDF.nc4?
NetCDF.creation_format=(cmode)
(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). NetCDF.create で作られるファイルのフォーマットを指定する. 初期設定は "classic".
引数
NetCDF.creation_format
NetCDF.open(filename, mode="r", share=false)
ファイルオープン(クラスメソッド)mode="w" でファイルが存在しなければ新規作成
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
NetCDF.new
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にする。既にそうなら何もせずnilを返す。
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
enddef
data mode に入る。既にそうなら何もせずnilを返す。
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
define_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 の関数
vars(names = nil)
ファイル中の変数をまとめてオープン
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
dim(dimension_name)
既存の次元をオープン
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
dims(names = nil)
ファイル中の次元をまとめてオープン
引数
戻り値
対応する(利用する) 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 の関数
---------------------------------------------
length
次元の長さを返す
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
length_ul0
length と同じだが、無制限次元に関しゼロを返す
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
name=(dimension_newname)
名前をつけかえる
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
name
名前を返す
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
unlimited?
無制限次元かどうか?
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
---------------------------------------------
NetCDFVar.new(file,varname,mode="r",share=false)
NetCDF変数をオープンする。これは、NetCDF#var (NetCDFクラスのイン スタンスメソッドvar) を使っても出来るし、そちらのほうを推奨する。
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
NetCDFVar.unpack_type=(na_type)
scaled_getで使うNArrayの型を固定する.
引数
戻り値
NetCDFVar.unpack_type
NetCDFVar.unpack_type=で設定したNArrayの型を返す.
戻り値
deflate(deflate_level, shuffle=false)
(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). (新しく作成された)変数が圧縮(deflate)されるようにする. このメソッドは, 変数を作成 (NetCDF#def_var) した後,NetCDF#enddef を呼ぶ前に呼ばなければならない.
引数
戻り値
deflate_params
(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). 現在の圧縮(deflation)パラメターを返す。
戻り値
endian=(endian)
(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). エンディアンを設定する。使用タイミングは deflate と同じ。
Arguments
Return value
endian
(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). 現在のエンディアン設定を返す.
Return value
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 の関数
rank
ntype
vartype
変数値の型を問う
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
typecode
変数値の型を問う(NArrayのtypecodeで返す)
引数
戻り値
対応する(利用する) 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)
simple_put(value, option=nil)
値を入れる
引数
option (Hash) : 変数の一部分を指定するためのオプション引数。省 略すれば、変数全体が対象となる。ハッシュのキーとしては、 "start","end","stride"の組、または"index"が使用できる。"index" は1要素(スカラー)を指す。"end","stride"は省略可。省略するにし ろしないにしろ、書きこむべき要素の数が valueのそれと一致するようにし なければならない。start,end,indexではArrayの場合と同様、負の値で後ろ からの位置を指定できる。"stride"は正の値のみ受け付けるので、配 列を引っくり返したければ後から別途やることになる。
例: 変数が2次元の場合:
{"start"=>[2,5],"end"=>[6,-1],"stride"=>[2,4]} -- 第1次元目は、 要素 2 から 6 まで 1 つおき (0から数えるので要素 2 は 3 番目であ ることに注意)、第2次元目は、要素 6 から 最後(=-1)まで 3 つおき にとったサブセット。
{"index"=>[0,0]}: 最初の要素にあた るスカラー値
{"index"=>[0,-2]}: 1次元目は最初, 2次元目は最後から2番目にあた るスカラー値
戻り値
対応する(利用する) C 版 NetCDF の関数
pack(na)
selfの属性 scale_factor and/or add_offset を用いて NArray 等を "pack" する.
もしも scale_factor and/or add_offset が設定されていれば (na-add_offset)/scale_factor を返す。そうでなければ na を返す。
引数
戻り値
scaled_put(value, option=nil)
simple_put と同様だが、packにより属性 scale_factor と add_offset を解釈する
引数等については put の解説を参照のこと
get(option=nil)
simple_get(option=nil)
値を取り出す
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
unpack(na)
selfの属性 scale_factor and/or add_offset を用いて NArray 等を "unpack" する.
もしも scale_factor and/or add_offset が設定されていれば na * scale_factor + add_offset を返す。そうでなければ na を返す。 coerce によって型が変化する -- 例えば、もし na が sint で scale_factor と add_offset が sfloat であれば、返り値は sfloat になる。返り値の型は NetCDFVar.unpack_type= を使って 陽に指定することもできる。
引数
戻り値
scaled_get(option=nil)
simple_get と同様だが、unpackにより属性 scale_factor と add_offset を解釈する
引数等については put の解説を参照のこと
[]
NetCDFVar#get と同様だが、サブセットを NArray#[] と同様に指定する.
NArrayでサポートされているサブセット指定方法に加えて、ステップ付 きの範囲を指定できる。これは {0..-1,2} などとする。つまり、要素 数が1のハッシュのキーに範囲(Range)、値にステップ(Integer)を指定 する。NArrayと違い、2次元以上の変数を1次元のインデックスで 指定することは出来ない。
[] =
NetCDFVar#put と同様だが、サブセットを NArray#[]= と同様に指定する.
NArrayでサポートされているサブセット指定方法に加えて、ステップ付 きの範囲を指定できる。これは {0..-1,2} などとする。つまり、要素 数が1のハッシュのキーに範囲(Range)、値にステップ(Integer)を指定 する。NArrayと違い、2次元以上の変数を1次元のインデックスで 指定することは出来ない。
get_with_miss(option=nil)
getと同様だが、データ欠損を処理する
データ欠損は標準属性 valid_range, (valid_min and/or valid_max), または missing_value により指定される。解釈の優先順位はこの順番で ある。「ユーザーズガイド」の推奨と違い、ここでは missin_value も 解釈される。もし missing_value と valid_* が同時に存在する場合、 missng_value は有効データ範囲外にあってはならない。その場合、例外 が発生する。
上記のようにもしデータ欠損(の仕方)が指定されていれば、このメソッ ドは NArrayMiss オブジェクトを返す。そうでなければ NArray を返す。
引数
戻り値
NetcdfError 以外の例外発生
対応する(利用する) C 版 NetCDF の関数
例
次の例では get を get_with_miss を置き換えている.
こうすると [] もデータ欠損を解釈するようになる (内部で
get
を呼んでるので).
file = NetCDF.open('hogehoge.nc') var = file.var('var') def var.get(*args); get_with_miss(*args); end p var.get # --> inteprets data missing if defined p var[0..-1,0] # --> inteprets data missing if defined (assumed 2D)
get_with_miss_and_scaling(option=nil)
get_with_missと同様だが、unpackによりスケーリングも行う.
欠損値処理は基本的には pack したデータを対象に行う(これは多くの コンベンション採用されている)。ただし、valid_* / missing_value の型が pack したデータの型と異なり、かつ unpackしたデータの型と 一致するとき(に限り) unpack したデータを対象とする。 これで基本的に全てのコンベンションに対応できる。
例
put_with_miss(value, option=nil)
putと同様だが、データ欠損を処理する
もしも value
が NArray なら、このメソッドは put に同
じ. もしvalue
が NArrayMiss でかつ self の属性によりデータ欠損が
定義されていれば (get_with_missを参照のこと)、value
中のデータ欠損が解釈される。即ち、value
中の欠損データは、
ある欠損値 (missing_value または _FillValue またはデータ有効範囲
外の適当な値) に置き換えられた上でファイルに書き込まれる。
value
中の非欠損データが self
における有効範囲に入って
いるかどうかはチェックされない。
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
例
次の例では put を put_with_miss を置き換えている.
こうすると []= もデータ欠損を解釈するようになる (内部で
put
を呼んでるので).
file = NetCDF.open('hogehoge.nc') var = file.var('var') def var.put(*args); put_with_miss(*args); end var.put = narray_miss # --> inteprets data missing if defined var[0..-1,0] = narray_miss # --> inteprets data missing if defined (assumed 2D)
put_with_miss_and_scaling(value, option=nil)
put_with_missと同様だが、packによりスケーリングも行う.
欠損値処理は基本的には pack したデータを対象に行う(これは多くの コンベンション採用されている)。ただし、valid_* / missing_value の型が pack したデータの型と異なり、かつ unpackしたデータの型と 一致するとき(に限り) unpack したデータを対象とする。 これで基本的に全てのコンベンションに対応できる。
例
---------------------------------------------
name
属性の名前を返す
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
name=(attribute_newname)
属性の名前を変更
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
copy(var_or_file)
属性を別の変数またはファイルにコピー。ファイルの場合はグローバル属性になる
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
delete
属性を削除
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
put(value, atttype=nil)
属性の値を設定
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
get
属性の中身を取り出す
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
atttype
属性値の型を問う
引数
戻り値
対応する(利用する) C 版 NetCDF の関数
typecode
属性値の型を問う(NArrayのtypecodeで返す)
引数
戻り値
対応する(利用する) C 版 NetCDF の関数