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

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 変数の型 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 の関数

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

メソッドインデックス

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

クラス NetCDF

定数

クラスメソッド

NetCDF.nc4?

このライブラリが NetCDF version 4 を使うようになっていれば (リンクされてる NetCDF ライブラリがver 4なら)true を, そうでなければ (NetCDF 3なら) false を返す。

NetCDF.creation_format=(cmode)

(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). NetCDF.create で作られるファイルのフォーマットを指定する. 初期設定は "classic".

引数

NetCDF.creation_format

(このメソッドは NetCDF-4 が使われてるときのみ使用可能:そうでなければ 例外が発生する). NetCDF.create で作られるファイルのフォーマットの現在の設定を返す.

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にする。既にそうなら何もせず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 の関数

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

クラス 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 の関数

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

ndimsのエリアス

ntype

vartypeの別名

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の別名(alias)

simple_put(value, option=nil)

値を入れる

引数

戻り値

対応する(利用する) 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の別名(alias)

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次元のインデックスで 指定することは出来ない。

"numru/netcdf_miss" を require することで追加されるインスタンスメソッド

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_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_with_miss_and_scaling(value, option=nil)

put_with_missと同様だが、packによりスケーリングも行う.

欠損値処理は基本的には pack したデータを対象に行う(これは多くの コンベンション採用されている)。ただし、valid_* / missing_value の型が pack したデータの型と異なり、かつ unpackしたデータの型と 一致するとき(に限り) unpack したデータを対象とする。 これで基本的に全てのコンベンションに対応できる。

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

クラス 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

属性の中身を取り出す

引数

戻り値

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

atttype

属性値の型を問う

引数

戻り値

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

typecode

属性値の型を問う(NArrayのtypecodeで返す)

引数

戻り値

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