gtool4 規約

netCDF 属性一覧

2000-01-19 豊田英司

凡例

この文書は gtool4 規約で規定される netCDF 属性 (グローバル属性と変数の属性両方) をその名前の順に列挙し、以下の情報を示す。

概要欄の略記号

属性の利用個所

[変数]
属性を変数に付加することができる。
[大域]
属性を大域属性にすることができる。
[大域・変数]
属性を大域属性にも変数に付属させることもできる。

属性の型・長さ

[整数]
属性は数値型でなければならない。属性の外部表現を NF_BYTE, NF_SHORT, NF_INT のいずれかにすることを推奨する。
[実数]
属性は数値型でなければならない。属性の外部表現を NF_FLOAT, NF_DOUBLE のいずれかにすることを推奨する。
[数値]
属性の外部表現を変数の外部表現と一致させなければならない。
[文字]
属性は文字型でなければならない。
[1]
属性は長さ1の数値型でなければならない。
[2]
属性は長さ2の数値型でなければならない。
[不定長]
属性は数値型でなければならない。

属性の取り扱い

[必須]
生成系は属性を生成しなくてはならない。解釈系は規定に当てはまる場合属性を解釈しなければならない。
[推奨]
生成系は属性を生成することを推奨する。解釈系は用途に応じて属性を解釈することを推奨する。
[ないほうがよい]
生成系は属性を生成しないことを推奨する。
[禁止]
生成系は属性を生成してはならない。

属性の名前のつけかた

属性の名前は以下の規約による。

  1. netCDF, COARDS, GDT, CSM で規定されているという理由で規約に盛り込まれた属性はすべてその名前を用いる。
  2. それ以外の属性は接頭辞 gt_ で始まる名前を与える。
  3. グラフィックス関連の属性には接頭辞 gt_graph_ を用いる。
  4. 数値データ処理関連の属性には接頭辞 gt_calc_ を用いる。
  5. 接頭辞 gt_user_ は gtool を通じて作られるユーザ定義属性のために予約されている。

add_offset

概要 [変数] [実数] [1] [ないほうがよい]
解釈 数値型変数を解釈する際に add_offset 属性値を加算する。変数に scale_factor 属性が与えられている場合は scale_factor 属性値との乗算を先に行う。
生成 add_offset 属性をみだりに付加しないことを勧めるが、データ格納効率に関する要求が認められるので禁止はしない。
例 p:add_offset = 1000.0;
採択理由 netCDF

appendices

概要 [大域] [文字] [必須]
解釈 現在 gtool4 規約には「過去の版」が存在しないため、gtool4 規約の現在の版 (gtool4.0beta) を参照する解釈系はこの属性を特に解釈しなくてよい。将来 gtool4 規約に属性の解釈の変更を伴う改定が行われた後に開発される解釈系はこの属性をバージョン番号として参照するであろう。
生成 生成系は属性値 "4.0beta" を付与しなければならない。
例 :appendices = "4.0beta";
採択理由 GDT

associate

GDT で規定されているが仕様未調査のため現在の版では言及しない。

axis

概要 [大域] [文字] [ないほうがよい]
解釈 Conventions 属性から GDT であることが判明している場合、軸の方向の意味付けを知るために用いる。
生成 GDT 互換なデータを生成することが可能であり (軸が "XYZT" とみなせる量からなっている)、軸の順序が "XYZT" になっておらず、軸の並べ替えが大きな負担となる場合、軸の順序を示す文字列を与える。それ以外の場合与えてはならない。
例 :axis = "TYXZ";
採択理由 GDT

bounds

概要 [変数] [文字]
解釈 属性値と同じ名前の変数を境界変数と呼ぶ。境界変数は bound 属性の所属する変数より1だけ長い。境界変数の値が所属変数の方向のセルの境界位置を表わす。
生成 変数 dimension に新しく境界変数を与える場合、その名前は "bounds_dimension" とすることを推奨する。
例 lon:bounds = "bounds_lon";
採択理由 CSM (GDT の同名の属性とは非互換)

calendar

概要 [大域・変数] [文字] [推奨]
解釈 時間から日付表記を生成するために、まず時間の変数に calendar 属性がある場合はそれに従い、そうではないが大域属性 calendar がある場合にはこれに従い、それ以外の場合は値 "gregorian" を仮定する。値 "gregorian" はグレゴリオ暦、"julian" はユリウス暦、"noleap" は1年365日の暦、"nkyr B.P." は現在から (n×1000) 年前の年の長さを用いた暦である。
生成 時間に関する変数がある場合には変数にこの属性を付与することを推奨する。
例 time:calendar = "noleap";
採択理由 CSM, GDT

C_format

概要 [変数] [文字]
解釈 C で書かれた解釈系が変数の値を印字する際に printf(3) の書式文字列としてこの属性値を用いることを推奨する。余計なおせっかいではあるが、double 型のための書式化文字列として正当であることを確認してからのほうがよい。
生成 生成系はこの属性を付加してもしなくてもよい。もし付加するならば、プログラム言語 C の規定で定められた double 型のために正当な書式化文字列でなければならない。
例 p:C_format = "%.3g";
採択理由 netCDF
注 本属性は変数の有効数字を示す目的で作られているが、実現方法がプログラム言語 C に依存している。有効数字または精度を表現するより適当で可搬性の高い方法を規定すべきである。

comment

GDT で規定されているが仕様未調査のため現在の版では言及しない。

component

GDT で規定されているが仕様未調査のため現在の版では言及しない。

compress

GDT で規定されているが仕様未調査のため現在の版では言及しない。

Conventions

概要 [大域] [文字] [必須]
解釈 属性値に "gtool" が含まれていれば、gtool4 規約に従って解釈してよいことを示す。"gtool" は属性値の先頭にあるとは限らない。
生成 属性値を "http://www.gfd-dennou.org/arch/gtool4/conventions/" としなければならない。
例 :Conventions = "http://www.gfd-dennou.org/arch/gtool4/conventions/";
採択理由 netCDF

coordinates

GDT, CSM で規定されているが仕様未調査のため現在の版では言及しない。

coord_op

CSM で規定されているが仕様未調査のため現在の版では言及しない。

define_unit

CSM で規定されているが仕様未調査のため現在の版では言及しない。

define_calendar

CSM で規定されているが仕様未調査のため現在の版では言及しない。

define_projection

CSM で規定されているが仕様未調査のため現在の版では言及しない。

expand

GDT で規定されているが仕様未調査のため現在の版では言及しない。

_FillValue

概要 [変数] [数値] [1]
解釈 所属する変数の操作に関して、netCDF ライブラリはまだ書き込まれていない部分の読み取りに際してこの属性値を
生成 NF_BYTE 型以外についてはわざわざこのような面倒なものは生成しないほうがよい。
例 p:_FillValue = -2.0e30;
採択理由 netCDF

flux_direction

CSM で規定されているが仕様未調査のため現在の版では言及しない。

FORTRAN_format

概要 [変数] [文字]
解釈 Fortran で書かれた解釈系が変数の値を印字する際に WRITE 文または PRINT 文の書式文字列としてこの属性値を用いることを推奨する。余計なおせっかいではあるが、実数型のための書式化文字列として正当であることを確認してからのほうがよい。
生成 生成系はこの属性を付加してもしなくてもよい。もし付加するならば、プログラム言語 Fortran で定められた実数型のために正当な書式化文字列でなければならない。
例 p:FORTRAN_format = "(g10.3)";
採択理由 netCDF
注 本属性は変数の有効数字を示す目的で作られているが、実現方法がプログラム言語 Fortran に依存している。有効数字または精度を表現するより適当で可搬性の高い方法を規定すべきである。

history

概要 [大域] [文字] [必須]
解釈 属性値を改行文字 "\n" によって区切って表示する。それ以上の解析ができることを期待しないほうがよい。
生成 既存属性値のあとに日時、スペースひとつ、ユーザ名、"> "、コマンドライン、改行文字を追加しなければならない。日時は JISX0301 の「暦日付及び地方時の時刻の拡張形式」により、地方時と協定世界時の差を付加することを推奨する。ユーザ名は UNIX システムでは whoami(1) コマンドの出力と同等のものとする。
例 :history = "2000-01-19T18:03:39+0900 akahori> gt3togt4 gtool.in";
採択理由 netCDF

institution

GDT で規定されているが仕様未調査のため現在の版では言及しない。

long_name

概要 [変数] [文字] [必須]
解釈 所属する変数の記述的名称。たとえば作図プログラムはこの名称をラベルとして表示すべきである。
生成 何がしかの意味のある文字列を付与しなければならない。
例 p:long_name = "surface pressure";
採択理由 netCDF, 必須の根拠は CSM 

missing_value

概要 [変数] [数値] [1] [ないほうがよい]
解釈 数値型変数を解釈する際に特別の扱いはなされない。 
生成 valid_range, valid_min, valid_max 属性で定義される欠損値を指定しなければならない。
例 p:missing_value = -2.0e20;
採択理由 netCDF

modulo

GDT で規定されているが仕様未調査のため現在の版では言及しない。

north_pole

GDT で規定されているが仕様未調査のため現在の版では言及しない。

old_interval

GDT で規定されているが仕様未調査のため現在の版では言及しない。

old_spacing

GDT で規定されているが仕様未調査のため現在の版では言及しない。

orbital_parameter

CSM で規定されているが仕様未調査のため現在の版では言及しない。

positive

COARDS, GDT, CSM で規定されているが仕様未調査のため現在の版では言及しない。

production

GDT で規定されているが仕様未調査のため現在の版では言及しない。

proj_coordinate

GDT で規定されているが仕様未調査のため現在の版では言及しない。

proj_parameters

CSM で規定されているが仕様未調査のため現在の版では言及しない。

quantity

CSM で規定されているが仕様未調査のため現在の版では言及しない。

quantity_table

GDT で規定されているが仕様未調査のため現在の版では言及しない。

scale_factor

概要 [変数] [実数] [1] [ないほうがよい]
解釈 数値型変数を解釈する際に scale_factor 属性値を乗算する。変数に add_offset 属性が与えられている場合は乗算を先に行う。
生成 scale_factor 属性をみだりに付加しないことを勧めるが、データ格納効率に関する要求が認められるので禁止はしない。
例 p:scale_factor = 100.0;
採択理由 netCDF

signedness

概要 [変数] [禁止]
解釈 NF_BYTE 型変数を解釈する際に 128 から 255 までの数値を負数と解釈するか否かを指定するものであるらしいが、属性値は規定しない。
生成 この属性を付与することを禁止する。
禁止理由 netCDF

source

CSM で規定されているが仕様未調査のため現在の版では言及しない。

subgrid

GDT で規定されているが仕様未調査のため現在の版では言及しない。

title

概要 [大域] [文字] [必須]
解釈 所属するファイル (データセット) の単純な名称。たとえば実験設定や (同じデータが分割されている場合は) 順番などを意味するも文字列であることが期待される。
生成 何がしかの意味のある文字列を付与しなければならない。
例 :title = "control";
採択理由 netCDF, 必須の根拠は CSM 

topology

GDT で規定されているが仕様未調査のため現在の版では言及しない。

time_format

GDT で規定されているが仕様未調査のため現在の版では言及しない。

units

概要 [変数] [文字] [推奨]
解釈 所属する変数の単位を表わす。解釈系は udunits 規約または JISX0124 の第一形式に従う単位の表記を正しく解釈できるべきである。
生成 SI 単位を付与できるデータに関しては、生成系は JISX0124 の第一形式に従う単位表記を生成しなければならない。
例 p:units = "hPa";
採択理由 netCDF

valid_min

概要 [変数] [数値] [1] [ないほうがよい]
解釈 所属する変数の数値がこの属性値より小さくなった場合、処理系は当該数値を欠損値とみなさなくてはならない。処理系は欠損値の演算から正常な数値を発生させてはならない。欠損値の関与する演算結果は欠損値であるが、どの値になるかは規定しない。すべての欠損値を内部的に IEEE 浮動小数点表現の非数に置換した後演算を行うという実装は gtool4 規約に適合している。　
生成 このような面倒なものは生成しないほうがよい。IEEE 浮動小数点表現を使うことができるのならば、非数を用いるほうがよい。もし指定しなければならないのならば、絶対値のできる限り大きな負の数値を指定すべきである。変数に valid_range 属性が付与されている場合はこの属性を生成してはならない。
例 p:valid_min = -1.0e30;
採択理由 netCDF

valid_max

概要 [変数] [数値] [1] [ないほうがよい]
解釈 所属する変数の数値がこの属性値より大きくなった場合、処理系は当該数値を欠損値とみなさなくてはならない。　
生成 このような面倒なものは生成しないほうがよい。IEEE 浮動小数点表現を使うことができるのならば、非数を用いるほうがよい。もし指定しなければならないのならば、絶対値のできる限り大きな正の数値を指定すべきである。変数に valid_range 属性が付与されている場合はこの属性を生成してはならない。
例 p:valid_max = 1.0e30;
採択理由 netCDF

valid_range

概要 [変数] [数値] [2] [ないほうがよい]
解釈 所属する変数の数値がこの属性値2つの範囲の外になった場合、処理系は当該数値を欠損値とみなさなくてはならない。　
生成 このような面倒なものは生成しないほうがよい。IEEE 浮動小数点表現を使うことができるのならば、非数を用いるほうがよい。もし指定しなければならないのならば、できる限り絶対値の大きな正負の数値を指定すべきである。変数に valid_min 属性または valid_max 属性が付与されている場合はこの属性を生成してはならない。
例 p:valid_range = -1.0e30, 1.0e30;
採択理由 netCDF

gt_graph_range

概要 [変数] [数値] [2] [推奨]
解釈 所属する変数の数値を描画する際にはこの属性値2つの範囲を描画対象とすべきである。
生成 欠損値をいれてはいけない。
例 p:gt_graph_range = -950.0, 1050.0;

gt_graph_contour_levels

概要 [変数] [数値] [不定長] [推奨]
解釈 所属する変数の数値を用いて等値線図を描画する際にはこの属性値の等値線を描画すべきである。
生成 欠損値をいれてはいけない。左のほうが小さい数値を入れなくてはいけない。
例 p:contour_levels = 996.0, 1000.0, 1004.0, 1008.0, 1012.0, 1016.0, 1020.0;

gt_graph_contour_spacing

gt_graph_thickcontour_levels

gt_user_anystring

この名前はユーザの自由な利用のために予約されている。gtool4 規約に従う解釈系はこれらの属性の有無および値を検索する手段を提供すべきである。gtool4 規約に従う生成系はこれらの属性を生成してもよい。