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 オブジェクトで代表される

データ型

本ライブラリーでは全ての 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 クラスと同じセキュリティー対応をしていてる。

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

マニュアルの見方

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

機能の解説

引数

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

戻り値

• 戻り値の説明

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

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

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

目次

• クラス NetCDF

  クラスメソッド

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

  インスタンスメソッド

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

• クラス NetCDFDim

  クラスメソッド

  インスタンスメソッド

  • length 次元の長さを返す
  • length_ul0 length と同じだが、無制限次元に関しゼロを返す
  • name= 名前をつけかえる
  • name 名前を返す
  • unlimited? 無制限次元かどうか？

• クラス NetCDFVar

  クラスメソッド

  • NetCDFVar.new NetCDF.open と NetCDF#Var を組み合わせて一行で済ます(使わなくて良い).

  インスタンスメソッド

  • dim その変数における dim_num 番目(0から数える)の次元を問合わせる。
  • dims その変数の全次元を配列にいれて返す
  • shape_ul0 変数の形を返す. 但し無制限次元の長さはゼロ.
  • shape_current 変数の現在の形を返す.
  • each_att 変数中の全属性(NetCDFAtt)に関するイテレータ
  • dim_names 変数中の全次元の名前を配列に入れて返す。
  • att_names 変数中の全属性の名前を配列に入れて返す。
  • name 変数の名前を返す
  • name= 名前を付け替える
  • ndims 次元の数を問う
  • ntype vartype の別名
  • vartype 変数値の型を問う
  • natts 属性の数を問う
  • file その変数が属するファイルを問合わせる
  • att 名前を指定した属性を返す
  • put_att 属性を設定
  • put 値を入れる
  • scaled_put put と同様だが、属性 scale_factor と add_offset を解釈する
  • get 値を取り出す
  • scaled_get get と同様だが、属性 scale_factor と add_offset を解釈する

• クラス 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 mode を使うか

戻り値

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

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

• nc_create

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

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

引数

• tmpdir (String) : テンポラリーファイルを置くディレクトリー名。 デフォルトは環境変数で指定されたディレクトリー（TMPDIR,TMP,or TEMP）または '.'。セキュアーモードでは '.' のみがデフォルトとな る。
• share (true or false) : shared mode を使うか

戻り値

• 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 の関数

• なし

uri

path のエリアス

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) : 属性の型. "char"(="string"),"byte", "sint","int","sfloat", "float" (それ ぞれ,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) : 変数のタイプ ("char", "byte", "sint", "sint", "int", "sfloat", "float" のいずれか)
• dimensions (Array) : variableの次元。NetCDFDim の Array。最も 「速く回る」次元から「遅く回る」次元の順に。その長さが変数の rank となる。

戻り値

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

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

• nc_def_var

def_var_with_dim(variable_name, vartype, shape_ul0, dimnames)

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

引数

• variable_name (String) : 定義するvariableの名前
• vartype (String) : 変数のタイプ ("char", "byte", "sint", "sint", "int", "sfloat", "float" のいずれか)
• shape_ul0 (Array of Integer) : 変数の形、即ち、各次元の長さ。無 制限次元はゼロで表す。長さが変数の rank となる。
• dimnames (Array of String) : 各次元の名前. 長さ(=>rank) は shape_ul0 と等しくなければならない。

戻り値

• 定義した変数(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

length_ul0

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

クラスメソッド

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

NetCDF.open と NetCDF#Var を組み合わせて一行で済ます(使わなくて良い).

引数

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

戻り値

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

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

• (nc_open, nc_create, nc_inq_varid 等を利用する)

インスタンスメソッド

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

shape_ul0

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

引数

• なし

戻り値

• Array. [0次元目の長さ, 1次元目の長さ,.. ]

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

• (nc_inq_vardimid, nc_inq_unlimdim 等を利用)

shape_current

変数の現在の形を返す.

引数

• なし

戻り値

• Array. [0次元目の長さ, 1次元目の長さ,.. ]

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

vartype

変数値の型を問う

引数

• なし

戻り値

• String ("char","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 or String) : 属性の型. "char"(="string"),"byte", "sint","int","sfloat", "float" (それ ぞれ,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>

scaled_put(value, option=nil)

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

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

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

get(option=nil)

値を取り出す

引数

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

戻り値

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

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

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

scaled_get(option=nil)

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

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

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

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

クラス 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) : 属性の型. "char"(="string"),"byte", "sint","int","sfloat", "float" (それ ぞれ,1,1,2,4,4,8 バイト)) または nil (つまりお任せ)

戻り値

• nil

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

• nc_put_att_<type>

get

属性の中身を取り出す

引数

• なし

戻り値

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

NArrayになる)

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

atttype

属性の種類を問う

引数

• なし

戻り値

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

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

• nc_inq_atttype