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 は以下の４つのクラスから構成される。

• クラス NetCDF -- ファイルのクラス

  一つのNetCDFクラスのオブジェクトは一つの NetCDF ファイルに対応する

• クラス NetCDFDim -- 次元のクラス

  C 版 NetCDF では、次元は、ファイルのIDと次元IDという２変数の組で表されるが、 Ruby 版では一つの NetCDFDim オブジェクトで代表される

• クラス NetCDFVar -- 変数のクラス

  C 版 NetCDF では、変数は、ファイルのIDと変数IDという２変数の組で表されるが、 Ruby 版では一つの NetCDFVar オブジェクトで代表される

• クラス NetCDFAtt -- 属性のクラス

  C 版 NetCDF では、属性は、ファイルのIDと変数IDと属性名の組で表されるが、 Ruby 版では一つの NetCDFAtt オブジェクトで代表される

エラー処理

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

セキュリティ

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

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

マニュアルの見方

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

機能の解説

引数

• 引数1の名 (そのクラスまたは取り得る値): 説明
• 引数2の名 (そのクラスまたは取り得る値): 説明
• ...

戻り値

• 戻り値の説明

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

• NetCDF ver 3 の関数名。括弧がない場合、その関数と同等の機能を有 することを示す。直接的な対応がない場合、括弧内に依存する関数を挙げる。

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

目次

• クラス NetCDF

  クラスメソッド

  • NetCDF.open ファイルオープン（クラスメソッド）mode="w" でファイルが存在しなければ新規作成
  • NetCDF.new NetCDF.openメソッドのエイリアスである
  • NetCDF.create NetCDFファイルを作る（クラスメソッド)

  インスタンスメソッド

  • close ファイルクローズ
  • ndims ファイル中の次元の数を返す
  • nvars ファイル中の変数の数を返す
  • natts ファイル中のグローバル属性の数を返す
  • unlimited ファイル中のunlimited dimensionを返す
  • path ファイルのパス. open/create時のfilename引数の中身を返す.
  • redef define modeにする。既にそうなら何もしない。
  • enddef data mode に入る。既にそうなら何もしない。
  • sync メモリー中のバッファーをディスク上に反映してファイルを同期させる
  • def_dim dimensionを定義
  • put_att グローバル属性を設定
  • def_var 変数を定義
  • var ファイルに既存の変数をオープン
  • dim 既存の次元をオープン
  • att 既存のグローバル属性をオープン
  • fill= fillmodeの変更。(NetCDF のデフォルトは FILL である。)
  • each_dim 次元に関するイテレータ.
  • each_var 変数に関するイテレータ.
  • each_att グローバル属性に関するイテレータ.
  • dim_names ファイル中の全次元の名前を配列に入れて返す。
  • var_names ファイル中の全変数の名前を配列に入れて返す。
  • att_names ファイル中の全グローバル属性の名前を配列に入れて返す。

• クラス NetCDFDim

  クラスメソッド

  インスタンスメソッド

  • length 次元の長さを返す
  • name= 名前をつけかえる
  • name 名前を返す
  • unlimited? 無制限次元かどうか？

• クラス NetCDFVar

  クラスメソッド

  インスタンスメソッド

  • dim その変数における dim_num 番目(0から数える)の次元を問合わせる。
  • dims その変数の全次元を配列にいれて返す
  • each_att 変数中の全属性(NetCDFAtt)に関するイテレータ
  • dim_names 変数中の全次元の名前を配列に入れて返す。
  • att_names 変数中の全属性の名前を配列に入れて返す。
  • name 変数の名前を返す
  • name= 名前を付け替える
  • ndims 次元の数を問う
  • ntype
  • vartype 変数値の型を問う
  • natts 属性の数を問う
  • file その変数が属するファイルを問合わせる
  • att 名前を指定した属性を返す
  • put_att 属性を設定
  • put 値を入れる
  • get 値を取り出す

• クラス NetCDFAtt

  クラスメソッド

  インスタンスメソッド

  • name 属性の名前を返す
  • name= 属性の名前を変更
  • copy 属性を別の変数またはファイルにコピー。ファイルの場合はグローバル属性になる
  • delete 属性を削除
  • put 属性の値を設定
  • get 属性の中身を取り出す
  • atttype 属性の種類を問う

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

クラス NetCDF

クラスメソッド

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

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

引数

• filename (String): ファイル名
• mode (String) : 入出力モード "r"(読み取り), "w"(書き込み可)
• share (true or false) : sharedモードにするか (書き込み中のファ イルに他のプロセスからの読み込みがあり得る場合に true とする。C版ユー ザーズガイド第5章の nc_open の項を参照のこと)

戻り値

• NetCDFクラスのオブジェクト

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

• nc_open, nc_create

NetCDF.new

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

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

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

引数

• filename (String) : ファイル名
• noclobber (true or false) : 上書きするかしないか
• share (true or false) : sharedにするか

戻り値

• NetCDFクラスのオブジェクト

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

• nc_create

インスタンスメソッド

close

ファイルクローズ

引数

• なし

戻り値

• nil

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

• nc_close

ndims

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

引数

• なし

戻り値

• Integer

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

• nc_inq_ndims

nvars

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

引数

• なし

戻り値

• Integer

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

• nc_inq_nvars

natts

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

引数

• なし

戻り値

• Integer

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

• nc_inq_natts

unlimited

ファイル中のunlimited dimensionを返す

引数

• なし

戻り値

• 存在するときNetCDFDimクラスのオブジェクト。ないときはnil

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

• nc_inq_unlimdim

path

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

引数

• なし

戻り値

• String

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

• なし

redef

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

引数

• なし

戻り値

• nil

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

• nc_redef

enddef

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

引数

• なし

戻り値

• nil

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

• nc_enddef

sync

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

引数

• なし

戻り値

• nil

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

• nc_sync

def_dim(dimension_name, length)

dimensionを定義

引数

• dimension_name (String) : 定義するdimensionの名前
• length (Integer) : dimensionの長さ。無制限次元は 0。

戻り値

• 定義された次元 (NetCDFDimオブジェクト)

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

• nc_def_dim

put_att(attribute_name, value, atttype=nil)

グローバル属性を設定

引数

• attribute_name (String) : グローバル属性の名前
• value (Numeric, String, Array of Numeric, or NArray) : 設定する値
• atttype(nil or String) : 属性値のタイプ. nil, "string", "byte", "sint", "int", "sfloat", "float"のいずれか (nil以外はそ れぞれ 1,1,2,4,4,8バイト) nilはお任せ(変数から判断)

戻り値

• 設定された属性 (NetCDFAttオブジェクト)

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

• nc_put_att_<type>

def_var(variable_name, vartype, dimensions)

変数を定義

引数

• variable_name (String) : 定義するvariableの名前
• vartype (String) : 変数のタイプ ("byte", "sint", "sint", "int", "sfloat", "float" のいずれか)
• dimensions (Array) : variableの次元。NetCDFDim の Array。最も 「速く回る」次元から「遅く回る」次元の順に。その長さが変数の rank となる。

戻り値

• 定義した変数(NetCDFVarオブジェクト)

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

• nc_def_var

var(var_name)

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

引数

• var_name (String) : オープンする変数名

戻り値

• 存在すれば NetCDFVar クラスのオブジェクト。存在しなければnil。

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

• nc_inq_varid

dim(dimension_name)

既存の次元をオープン

引数

• dimension_name (String) : オープンする次元名

戻り値

• 存在すれば NetCDFDimクラスのオブジェクト。存在しなければnil

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

• nc_inq_dimid

att(attribute_name)

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

引数

• attribute_name (String) : オープンするグローバル属性名

戻り値

• 存在すれば NetCDFAttクラスのオブジェクト。存在しなければnil

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

• (nc_inq_attidを検査に利用)

fill=(filemode)

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

引数

• fillmode (true for FILL or false for NOFILL)

戻り値

• nil

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

• nc_set_fill

each_dim{ ... }

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

引数

• { ... } : イテレーター用ブロック。do endブロックでもよい。

戻り値

• self

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

• (nc_inq_ndimsを利用)

each_var{ ... }

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

引数

• { ... } : イテレーター用ブロック。do endブロックでもよい。

戻り値

• self

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

• (nc_inq_nvarsを利用)

each_att{ ... }

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

引数

• { ... } : イテレーター用ブロック。do endブロックでもよい。

戻り値

• self

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

• (nc_inq_natts, nc_inq_attnameを利用)

dim_names

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

引数

• なし

戻り値

• String の Array

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

• (nc_inq_ndims, nc_inq_dimnameを利用)

var_names

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

引数

• なし

戻り値

• String の Array

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

• (nc_inq_nvars, nc_inq_varnameを利用)

att_names

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

• なし

戻り値

• String の Array

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

• (nc_inq_natts, nc_inq_attnameを利用)

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

クラス NetCDFDim

クラスメソッド

インスタンスメソッド

length

次元の長さを返す

引数

• なし

戻り値

• Integer

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

• nc_inq_dimlen

name=(dimension_newname)

名前をつけかえる

引数

• dimension_newname (String) : 新しい名前

戻り値

• nil

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

• nc_rename_dim

name

名前を返す

引数

• なし

戻り値

• String

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

• nc_inq_dimname

unlimited?

無制限次元かどうか？

引数

• なし

戻り値

• true or false

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

• (nc_inq_unlimdim を利用)

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

クラス NetCDFVar

クラスメソッド

インスタンスメソッド

dim(dim_num)

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

引数

• dim_num (Fixnum) : 0,1,2,...。最も速く回る次元が0。

戻り値

• NetCDFDimオブジェクト

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

• (nc_inq_vardimid利用)

dims

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

引数

• なし

戻り値

• NetCDFDimオブジェクトのArray

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

• nc_inq_vardimid

each_att{ ... }

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

引数

• { ... } : 繰り返すブロック

戻り値

• self

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

• (nc_inq_natts, nc_inq_attnameを利用)

dim_names

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

引数

• なし

戻り値

• String の Array

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

• (nc_inq_varndims, nc_inq_vardimid, nc_inq_dimname を利用)

att_names

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

引数

• なし

戻り値

• String の Array

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

• (nc_inq_natts, nc_inq_attnameを利用)

name

変数の名前を返す

引数

• なし

戻り値

• String

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

• nc_inq_varname

name=(variable_newname)

名前を付け替える

引数

• variable_newname (String) : 新しい名前

戻り値

• nil

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

• nc_rename_var

ndims

次元の数を問う

引数

• なし

戻り値

• Integer

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

• nc_inq_varndims

ntype

vartype

変数値の型を問う

引数

• なし

戻り値

• String ("string","byte","sint","int","sfloat", or "float")

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

• nc_inq_vartype

natts

属性の数を問う

引数

• なし

戻り値

• Integer

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

• nc_inq_varnatts

file

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

引数

• なし

戻り値

• NetCDFクラスのオブジェクト

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

• なし

att(attribute_name)

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

引数

• attribute_name (String) : 取り出す属性名

戻り値

• NetCDFAttオブジェクト. 存在しなければnil

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

• (nc_inq_attidを検査に利用)

put_att(attribute_name, value, atttype=nil)

属性を設定

引数

• attribute_name (String) : attribute名
• value (Numeric, String, Array of Numeric, or NArray) : 設定する値
• atttype : 属性の型 (nilまたは
• nil, "string","byte","sint","int","sfloat","float" (nil以外はそれぞれ 1,1,2,4,4,8バイト)) nilはお任せ(変数から判断)

戻り値

• NetCDFAttのオブジェクト

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

• nc_put_att_<type>

put(value, option=nil)

値を入れる

引数

• value : 入れる値 (Numeric,Array(Numericの1次元配列)、NArray)

• 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番目にあた るスカラー値

戻り値

• nil

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

• nc_put_var_<type>, nc_put_vars_<type>, nc_put_var1_<type>

get(option=nil)

値を取り出す

引数

• option (Hash) : 変数の一部分を指定するためのオプション引数。仕 様は put に同じ。

戻り値

• NArrayクラスのオブジェクト

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

• nc_get_var_<type>, nc_get_vars_<type>, nc_get_var1_<type>

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

クラス NetCDFAtt

クラスメソッド

インスタンスメソッド

name

属性の名前を返す

引数

• なし

戻り値

• String

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

• なし

name=(attribute_newname)

属性の名前を変更

引数

• attribute_newname (String) : 新しい名前

戻り値

• nil

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

• nc_rename_att

copy(var_or_file)

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

引数

• var_or_file (NetCDFVar or NetCDF)

戻り値

• コピーして作られた属性 (NetCDFAtt)

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

• nc_copy_att

delete

属性を削除

引数

• なし

戻り値

• nil

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

• nc_del_att

put(value, atttype=nil)

属性の値を設定

引数

• value (Numeric, String, Array of Numeric, or NArray) : 入れる値
• atttype (nil or String) : valueのタイプ(nilまたは"string","byte","sint","int","sfloat","float" (それぞれ,1,1,2,4,4,8バイト))

戻り値

• nil

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

• nc_put_att_<type>

get

属性の中身を取り出す

引数

• なし

戻り値

• 文字列またはNArrayオブジェクト (注意: スカラーの場合も長さ1の

NArrayになる)

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

atttype

属性の種類を問う

引数

• なし

戻り値

• "string","byte","sint","int","sfloat","float"

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

• nc_inq_atttype