gtool4 規約 version 4.0beta
5. netCDF 属性リファレンス
2000/01/24 19:09
豊田英司
この文書は gtool4 規約で規定される netCDF 属性 (グローバル属性と変数の属性両方)
をその名前の順に列挙し、以下の情報を示す。
- 属性の用法の概要
- gtool4 ファイルを解釈するソフトウェア (解釈系)
は当該属性に関してどのような挙動をするべきか
- gtool4 ファイルを生成するソフトウェア (生成系)
は当該属性を生成すべきか、もし生成することが許されるならどのような内容を記入すべきか
- 使用例
- 当該属性が gtool4 規約に盛り込まれた根拠または理由
概要欄の略記号
属性の所属する場所
[大域]
属性を大域属性にすることができる。
該当: appendices, axis,
comment, Conventions, define_unit,
define_calendar, define_projection,
production, quantity_table,
source, title.
[変数]
属性を変数に付加することができる。
過半数の属性がこれに該当する。
[大域・変数]
属性を大域属性にも変数にも付属させることもできる。
該当: calendar, history, institution,
orbital_parameter, proj_coordinates, proj_parameter.
[図形]
属性を図形変数に付加することができる。
gt_object_
anything
の名前をもつ属性がこれに該当する。
属性の型・長さ
[実数]
属性は数値型でなければならない。属性の外部表現を
NF_FLOAT, NF_DOUBLE のいずれかにすることを推奨する。
該当: add_offset, appendices, north_pole, scale_factor.
[数値]
属性の外部表現を変数の外部表現と一致させなければならない。
該当: _FillValue, missing_value, old_interval, valid_max, valid_min,
valid_range
[文字]
属性は文字型でなければならない。
[1]
属性は長さ1の数値型でなければならない。
[2]
属性は長さ2の数値型でなければならない。
[不定長]
属性は数値型でなければならない。長さは規定しない。
属性の取り扱い
[必須]
生成系は必ず属性を生成しなくてはならない。解釈系は属性を解釈しなければならない。
該当: Conventions, history, long_name, source, title
[条件付必須]
生成系は規定に当てはまる場合は属性を生成しなくてはならない。解釈系は属性を解釈しなければならないが、属性が存在することに依存してはならない。
該当: positive, units
[解釈必須]
生成系は規定に当てはまる場合は属性を生成することを推奨する。解釈系は属性を解釈しなければならない。
該当: add_offset, scale_factor, valid_max, valid_min
[推奨]
生成系は規定に当てはまる場合は属性を生成することを推奨する。解釈系は属性を解釈することを推奨する。
該当: axis, bounds, C_format, calendar, coordinate, flux_direction,
FORTRAN_format, institution, missing_value, modulo, old_interval, old_spacing,
subgrid, topology
[互換]
生成系は属性を生成してもよいが、他の代替手段をも生成することを推奨する。解釈系は属性を解釈することを推奨する。
該当: coord_op, associate, production, proj_coordinates,
proj_parameter, valid_range
[参考]
生成系は属性を生成してもよい。解釈系は属性を解釈してもよい。
該当: _FillValue, appendices, comment, define_unit, define_calendar,
define_proj, expand, north_pole, orbital_parameter, time_format
[禁止]
生成系は属性を生成してはならない。
該当: signedness
属性の名前のつけかた
属性の名前は以下の規約による。
- netCDF, COARDS,
GDT, CSM
で規定されているという理由で規約に盛り込まれた属性はすべてその名前を用いる。
- それ以外の属性は接頭辞 gt_
で始まる名前を与える。
- グラフィックス関連の属性には接頭辞 gt_graph_ を用いる。
- 数値データ処理関連の属性には接頭辞 gt_calc_ を用いる。
- 接頭辞 gt_user_ は gtool
を通じて作られるユーザ定義属性のために予約されている。
概要 |
[変数] [実数] [1]
[解釈必須] |
解釈 |
数値型変数を解釈する際に add_offset
属性値を加算する。変数に scale_factor
属性が与えられている場合は scale_factor
属性値との乗算を先に行う。 |
生成 |
余計なおせっかいだが、属性値が欠損値だときっと意味がないとおもう。 |
例 |
ps:add_offset = 1000.0; |
採択理由 |
netCDF |
概要 |
[大域] [float]
[1]
[参考] |
解釈 |
GDT 規約の版数として解釈される。 |
生成 |
もし指定するならば、float
型の数値 1.3f を指定すべきである。 |
例 |
lon:appendices = 1.3f; |
採択理由 |
GDT |
概要 |
[変数] [文字]
[互換] |
解釈 |
現在の版では解釈を規定しない。 |
生成 |
現在の版では生成方法を規定しない。 |
例 |
lon:associate = "x"; |
採択理由 |
GDT |
概要 |
[大域] [文字]
[推奨] |
解釈 |
座標の単位が長さであり、しかも単位から次元の意味付けを読み取ることができない場合、座標の意味付けを知るために用いる。 |
生成 |
GDT
互換なデータを生成することが可能であり (軸が "XYZT"
とみなせる量からなっている)、軸の順序が "XYZT"
になっておらず、軸の並べ替えが大きな負担となる場合、軸の順序を示す文字列を与える。それ以外の場合与えてはならない。 |
例 |
:axis = "TYXZ"; |
採択理由 |
GDT |
概要 |
[変数] [文字] [推奨] |
解釈 |
属性値と同じ名前の変数を境界変数と呼ぶ。境界変数は
bound
属性の所属する変数より1だけ長い。境界変数の値が所属変数の方向のセルの境界位置を表わす。 |
生成 |
変数 dimension
に新しく境界変数を与える場合、その名前は "bounds_dimension"
とすることを推奨する。 |
例 |
lon:bounds = "bounds_lon"; |
採択理由 |
CSM, GDT
|
概要 |
[大域・変数] [文字]
[推奨] |
解釈 |
時間から日付表記を生成するために、まず時間の変数に
calendar
属性がある場合はそれに従い、そうではないが大域属性
calendar
がある場合にはこれに従い、それ以外の場合は値 "gregorian "
を仮定する。値 "gregorian "
はグレゴリオ暦、"julian "
はユリウス暦、"noleap "
は1年365日の暦、"360" は毎月30日で1年が360日の暦、"nkyr B.P. "
は現在から (n×1000)
年前の年の長さを用いた暦である。 |
生成 |
時間の単位をもつ変数がある場合に限り、(大域属性としてではなく)
変数にこの属性を付与することを推奨する。 |
例 |
time:calendar = "noleap"; |
採択理由 |
CSM, GDT |
概要 |
[変数] [文字]
[推奨] |
解釈 |
C
で書かれた解釈系が変数の値を印字する際に printf(3)
の書式文字列としてこの属性値を用いることを推奨する。余計なおせっかいではあるが、double
型のための書式化文字列として正当であることを確認してからのほうがよい。 |
生成 |
生成系はこの属性を付加してもしなくてもよい。もし付加するならば、プログラム言語
C の規定で定められた double
型のために正当な書式化文字列でなければならない。 |
例 |
ps:C_format = "%.3g"; |
採択理由 |
netCDF |
注 |
本属性は変数の有効数字を示す目的で作られているが、実現方法がプログラム言語
C
に依存している。有効数字または精度を表現するより適当で可搬性の高い方法を規定すべきである。 |
概要 |
[大域] [文字]
[参考] |
解釈 |
gtool4
規約は属性値の解釈を規定しない。解釈系は属性値を印字する方法を提供すべきである。 |
生成 |
生成系はこの属性を付加してもしなくてもよい。ASCII
の印字可能な文字を与えなくてはならない。 |
例 |
:comment = "experiment 1 ---
surface pressure distribution"; |
採択理由 |
GDT
|
注 |
実験パラメタのような値を格納する場合には
gt_user_anything 属性を使うことによって比較を容易にすることができる。 |
GDT
で規定されているが現在の版ではこの属性の利用については規定しない。
GDT
で規定されているが現在の版ではこの属性の利用については規定しない。
概要 |
[変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[推奨] される予定である。 |
採択理由 |
GDT, CSM |
概要 |
[変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[互換] とみなされる予定である。 |
採択理由 |
CSM |
概要 |
[大域] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[互換] とみなされる予定である。 |
採択理由 |
CSM |
概要 |
[大域] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[参考] とみなされる予定である。 |
採択理由 |
CSM |
概要 |
[大域] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[参考] とみなされる予定である。 |
採択理由 |
CSM |
概要 |
[変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[参考] とみなされる予定である。 |
採択理由 |
GDT
|
概要 |
[変数] [数値] [1]
[推奨] |
解釈 |
所属する変数の操作に関して、netCDF
ライブラリはまだ書き込まれていない部分の欠損値を指定すべきである。 |
生成 |
NF_BYTE
型以外についてはわざわざこのような面倒なものは生成しないほうがよい。 |
例 |
ps:_FillValue = -2.0e30; |
採択理由 |
netCDF |
概要 |
[変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[推奨] とみなされる予定である。 |
採択理由 |
CSM |
概要 |
[変数] [文字]
[推奨] |
解釈 |
Fortran
で書かれた解釈系が変数の値を印字する際に WRITE
文または PRINT
文の書式文字列としてこの属性値を用いることを推奨する。余計なおせっかいではあるが、実数型のための書式化文字列として正当であることを確認してからのほうがよい。 |
生成 |
生成系はこの属性を付加してもしなくてもよい。もし付加するならば、プログラム言語
Fortran で定められた実数型のために正当な書式化文字列でなければならない。 |
例 |
ps:FORTRAN_format = "(g10.3)"; |
採択理由 |
netCDF |
注 |
本属性は変数の有効数字を示す目的で作られているが、実現方法がプログラム言語
Fortran に依存している。有効数字または精度を表現するより適当で可搬性の高い方法を規定すべきである。 |
概要 |
[変数] [数値] [2] [推奨] |
解釈 |
所属する変数の数値を描画する際にはこの属性値2つの範囲を描画対象とすべきである。 |
生成 |
欠損値をいれてはいけない。 |
例 |
ps:gt_graph_range = -950.0, 1050.0; |
概要 |
[変数] [数値] [不定長] [推奨] |
解釈 |
所属する変数の数値を用いて等値線図を描画する際にはこの属性値の等値線を描画すべきである。 |
生成 |
欠損値をいれてはいけない。左のほうが小さい数値を入れなくてはいけない。 |
例 |
ps:contour_levels = 996.0, 1000.0, 1004.0,
1008.0, 1012.0, 1016.0, 1020.0; |
この名前はユーザの自由な利用のために予約されている。gtool4
規約に従う解釈系はこれらの属性の有無および値を検索する手段を提供すべきである。gtool4
規約に従う生成系はこれらの属性を生成してもよい。
概要 |
[大域] [文字] [必須] |
解釈 |
現在 gtool4
規約には「過去の版」が存在しないため、gtool4
規約の現在の版 (gtool4.0beta)
を参照する解釈系はこの属性を特に解釈しなくてよい。将来
gtool4
規約に属性の解釈の変更を伴う改定が行われた後に開発される解釈系はこの属性をバージョン番号として参照するであろう。 |
生成 |
生成系は属性値 "4.0beta"
を付与しなければならない。 |
例 |
:appendices = "4.0beta"; |
概要 |
[大域] [文字] [必須] |
解釈 |
属性値を改行文字 "\n"
によって区切って表示する。それ以上の解析ができることを期待しないほうがよい。 |
生成 |
既存属性値のあとに日時、スペースひとつ、ユーザ名、">
"、コマンドライン、改行文字を追加しなければならない。日時は
JIS X 0301
の「暦日付の完全形式及び地方時の時刻の完全形式の拡張形式」により、地方時と協定世界時の差を付加することを推奨する。ユーザ名は
UNIX システムでは whoami(1)
コマンドの出力と同等のものとする。 |
例 |
:history = "2000-01-19T18:03:39+09:00
akahori> gt3togt4 gtool.in"; |
採択理由 |
netCDF |
概要 |
[大域] [文字]
[推奨] |
解釈 |
所属する変数の記述的名称。たとえば作図プログラムはこの名称をラベルとして表示すべきである。 |
生成 |
何がしかの意味のある文字列を付与しなければならない。 |
例 |
:institution = "toyoda";
:institution = "toyoda@gfd-dennou.org";
:institution = "GFD-Dennou Club"; |
採択理由 |
GDT |
概要 |
[変数] [文字] [必須] |
解釈 |
所属する変数の記述的名称。たとえば作図プログラムはこの名称をラベルとして表示すべきである。 |
生成 |
何がしかの意味のある文字列を付与しなければならない。 |
例 |
ps:long_name = "surface
pressure"; |
採択理由 |
netCDF,
必須の根拠は CSM |
概要 |
[変数] [数値] [1]
[推奨] |
解釈 |
数値型変数を解釈する際に特別の扱いはなされない。 |
生成 |
valid_range, valid_min, valid_max
属性で定義される欠損値を指定しなければならない。 |
例 |
ps:missing_value = -2.0e20; |
採択理由 |
netCDF |
概要 |
[変数] [数値] [1] [推奨] |
解釈 |
変数が座標として解釈される場合 modulo
属性値が周期と解釈される。 |
生成 |
欠損値を指定してはならない。 |
例 |
lon:modulo = 360.0; |
採択理由 |
GDT
|
概要 |
[変数] [実数]
[2]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[参考] とみなされる予定である。 |
採択理由 |
GDT
|
概要 |
[変数] [数値]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[推奨] とみなされる予定である。 |
採択理由 |
GDT
|
概要 |
[変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[推奨] とみなされる予定である。 |
採択理由 |
GDT
|
概要 |
[大域・変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[推奨] とみなされる予定である。 |
採択理由 |
CSM
|
概要 |
[変数] [文字]
[条件付必須] |
解釈 |
変数が縦軸または横軸として描画される場合の方向を決定する。属性値が
"up" ならば数値の大きいほうが上または右、"down"
ならば数値の大きいほうが下または左となる。 |
生成 |
変数が鉛直座標とみなされる可能性がある場合は適切な値を生成しなければならない。 |
例 |
lon:positive = "up"; |
採択理由 |
COARDS, GDT,
CSM. 左右方向に関する解釈は gtool4
独自のものである。 |
概要 |
[大域] [文字] [互換] |
解釈 |
source
属性がない場合、そのかわりに「データがどのように作られたか」を示す文字列と解釈される。 |
生成 |
与える場合は source 属性と同一の文字列を与える。 |
例 |
lon:production = "GFD-Dennou Club AGCM 5.3"; |
採択理由 |
GDT |
概要 |
[大域・変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[互換] とみなされる予定である。 |
採択理由 |
CSM
|
概要 |
[大域・変数] [文字]
|
注 |
現在の版では解釈・生成を規定しない。将来は
[互換] とみなされる予定である。 |
採択理由 |
CSM
|
GDT
で規定されているが現在の版ではこの属性の利用については規定しない。
GDT
で規定されているが現在の版ではこの属性の利用については規定しない。
概要 |
[変数] [実数] [1]
[解釈必須] |
解釈 |
数値型変数を解釈する際に scale_factor
属性値を乗算する。変数に add_offset
属性が与えられている場合は乗算を先に行う。 |
生成 |
scale_factor 属性をみだりに付加しないことを勧めるが、データ格納効率に関する要求が認められるので禁止はしない。 |
例 |
ps:scale_factor = 100.0; |
採択理由 |
netCDF |
概要 |
[変数] [禁止] |
解釈 |
NF_BYTE 型変数を解釈する際に 128 から 255
までの数値を負数と解釈するか否かを指定するものであるらしいが、属性値の解釈は規定しない。 |
生成 |
この属性を付与することを禁止する。 |
禁止理由 |
netCDF |
概要 |
[大域] [文字]
[必須] |
解釈 |
「データがどのように作られたか」を示す文字列と解釈される。 |
生成 |
数値モデルのバージョンや観測手段などを示す文字列を格納することが推奨される。 |
例 |
lon:source = "GFD-Dennou Club AGCM 5.3"; |
採択理由 |
CSM
|
概要 |
[変数] [文字] |
注 |
現在の版では解釈・生成について規定しない。将来の版では
[推奨] とみなされる予定である。 |
採択理由 |
GDT
|
概要 |
[大域] [文字] [必須] |
解釈 |
所属するファイル (データセット)
の単純な名称。たとえば実験設定や (同じデータが分割されている場合は)
順番などを意味するも文字列であることが期待される。 |
生成 |
何がしかの意味のある文字列を付与しなければならない。 |
例 |
:title = "control"; |
採択理由 |
netCDF,
必須の根拠は CSM |
概要 |
[変数] [文字] [推奨] |
解釈 |
属性値が "circular"
である場合、変数が座標として解釈される場合に周期的座標であることを示す。modulo
属性値が周期と解釈される。 |
生成 |
経度に相当する座標変数には付与するべきである。 |
例 |
lon:topology = "circular"; |
採択理由 |
GDT
|
GDT
で規定されているが現在の版ではこの属性の利用については規定しない。将来の版では
[参考] とみなされる予定である。
概要 |
[変数] [文字]
[条件付必須] |
解釈 |
所属する変数の単位を表わす。解釈系は
udunits 規約または JIS
X 0124
の第一形式に従う単位の表記を正しく解釈できるべきである。 |
生成 |
SI
単位を付与できるデータに関しては、生成系は JIS
X 0124
の第一形式に従う単位表記を生成しなければならない。 |
例 |
ps:units = "hPa"; |
採択理由 |
netCDF |
概要 |
[変数] [数値] [1]
[解釈必須] |
解釈 |
所属する変数の数値がこの属性値より小さくなった場合、処理系は当該数値を欠損値とみなさなくてはならない。処理系は欠損値の演算から正常な数値を発生させてはならない。欠損値の関与する演算結果は欠損値であるが、どの値になるかは規定しない。すべての欠損値を内部的に
IEEE
浮動小数点表現の非数に置換した後演算を行うという実装は
gtool4 規約に適合している。 |
生成 |
このような面倒なものは特に理由がなければ生成しないほうがよい。IEEE
浮動小数点表現を使うことができるのならば、非数を用いるほうがよい。もし指定しなければならないのならば、絶対値のできる限り大きな負の数値を指定すべきである。変数に
valid_range
属性が付与されている場合はこの属性を生成してはならない。 |
例 |
ps:valid_min = -1.0e30; |
採択理由 |
netCDF |
概要 |
[変数] [数値] [1]
[解釈必須] |
解釈 |
所属する変数の数値がこの属性値より大きくなった場合、処理系は当該数値を欠損値とみなさなくてはならない。 |
生成 |
もし指定しなければならないのならば、絶対値のできる限り大きな正の数値を指定すべきである。valid_min
属性値より小さい値を与えてはならない。変数に
valid_range
属性が付与されている場合はこの属性を生成してはならない。 |
例 |
ps:valid_max = 1.0e30; |
採択理由 |
netCDF |
概要 |
[変数] [数値] [2]
[互換] |
解釈 |
所属する変数の数値がこの属性値2つの範囲の外になった場合、処理系は当該数値を欠損値とみなさなくてはならない。 |
生成 |
valid_range よりも valid_min および
valid_max
属性を指定することを推奨する。もし指定しなければならないのならば、できる限り絶対値の大きな正負の数値を指定すべきである。第1要素より第2要素の数値が大きくなくてはならない。変数に
valid_min 属性または valid_max
属性が付与されている場合はこの属性を生成してはならない。 |
例 |
ps:valid_range = -1.0e30, 1.0e30; |
採択理由 |
netCDF |