gtool4 規約 version 4.0beta4

2. 用語と全般的規定

2000-02-02T21:15:+09:00 豊田英司


適用範囲

この規約は、gtool4 規約準拠 netCDF データセットの形を規定し、その生成法と解釈を与える。この規約は netCDF データセットの自己記述性を高め、種々の環境で使用する際の可搬性、信頼性を高めることを目的とする。

用語の定義

生成系
gtool4 規約に従う netCDF ファイルを生成するソフトウェアまたは人間。
解釈系
gtool4 規約に従う netCDF ファイルを解釈するソフトウェアまたは人間。
netCDF ファイル
NetCDF ユーザーズガイドの「netCDF データセット」と同義とする。NetCDF ファイルには次元、大域属性、変数を定義できる。変数には属性を定義できる。属性と変数には外部表現の型がある。
外部表現型
変数または属性が netCDF ファイルの内部でどのように表現されているかを示す型。
変数
特に断りなく用いた場合には netCDF 変数を指す。変数は文字型または数値型の多次元配列である。
図形変数
図形オブジェクトの属性を格納するために作られた変数。これは gtool4 独自の概念である。図形変数に関する規定は 4 章にまとめられている。
数値変数
図形変数以外の変数。変数の内容は多くの場合多次元数値データである。これは gtool4 独自の概念である。数値変数に関する規定は 3 章にまとめられている。
座標変数
次元名と一致する数値変数。
次元
特に断りなく用いた場合には netCDF 次元を指す。物理的次元とは別。無次元量は物理的次元を持たない量であり、これを変数として表現する際には多次元配列であるかもしれないので netCDF 次元の有無とは関係ない。

本規約への適合性

何かを「しなければならない」という表現は必須規定を表わす。

何かを「してはならない」という表現は「その動作をしないようにしなければならない」という意味の必須規定である。

何かを「することを推奨する」という表現は推奨規定を表わす。

何かを「してもよい」という表現は参考規定を表わす。節見出しや段落の先頭に表記されている (参考) は節や段落全体が参考規定であることを示す。

何かを「するべきである」という表現は、参考規定の中で遵守することが強く期待されている規定に付与されている。

生成系が本規約に適合するとは、生成系に関する必須規定を遵守することである。生成系は必須規定に違反する動作をできないように作るべきであるが、ユーザが明示的にオプション操作をした場合に (たとえばコマンドラインスイッチ) 違反を許容してもよいし、ユーザの入力が必須規定に違反する場合に警告メッセージを表示してもよい。

データセットが本規約に適合するとは、生成系に関する必須規定を遵守して生成することが可能であることである。

解釈系が本規約に適合するとは、解釈系に関する必須規定を遵守することである。一般に解釈系は生成系に関する必須規定が遵守されていることを仮定してはならない。


ファイル名

生成系は ".nc" で終わるファイル名を作成しなければならない[注]

ファイル名は末尾の ".nc" を除いて 8文字以内にとどめることを推奨する。8文字以内にとどめることができない場合には、32 文字以内にとどめることを強く推奨する。ファイル名は数字、英小文字、そして下線で構成することを強く推奨する。

ファイル名に英小文字を使用することができない環境では、英大文字を代わりに用いることができる。

変数名

変数名は netCDF ライブラリに許容される変数名でなければならない[注]

混乱を防ぐため、英大文字と英小文字の相違を無視すると同一になってしまう2つの名前 (たとえば "T" と "t") を持った変数を作らないことを強く推奨する。

大域属性

規約情報

生成系は以下の大域属性 Conventions を与えねばならない。

:Conventions = "http://www.gfd-dennou.org/arch/gtool4/conventions/";

生成系が以下の大域属性 gt_version を与えることを推奨する。

:gt_version = "4.0beta4";

解釈系は、少なくとも Conventions 属性値が "gtool" を含む場合には、 gtool4 規約に準拠した動作をしなければならない。 しかし、一般に大域属性 Conventions の有無または値に依存した動作をすべきではない。

(参考) GDT 規約への互換性を考慮する場合、大域属性 appendices を与えてもよい[注]。もし与えるならば、float 型で数値 1.3 (または最新の GDT 規約版数) とする。

:appendices = 1.3f;

表題

生成系はすべてのファイルに大域属性 title を与えねばならない。

大域属性 title にはファイルに含まれる数値データの短い説明を与えるべきである。数値モデルのランの名称や観測・実験番号などが考えられる。

title 属性を機械的に生成するには、所属するデータ変数の long_name を列挙したものを付与することが考えられる。

解釈系は大域属性 title が存在することに依存してはならない。表題を出力するソフトウェアは title が欠けている場合にはファイル名で代用すべきである。

(参考) ファイルの長い記述的な説明は大域属性 comment に格納するのがよい。

作成者情報

生成系はすべてのファイルに source 属性を与えねばならない。また、生成系は institution 属性を与えることが推奨される。

source 属性には数値データが最初に netCDF 形式で作成されたときの観測手段、データアーカイブ名、またはソフトウェア名が記入されるべきである。

この属性を機械的に生成するには、もし source 属性が何らかの手段で与えられていればそれを保存し、存在しなければソフトウェアの名称を与えるようにすることが考えられる。

institution 属性にはファイルの最終変更を行った者の名称が記入されるべきである。データがある機関の事業として供給されるならば、その機関の名称が記入されるべきである。また個人の作業としてファイルが作成されるならば、その個人の実名やログイン名が記入されるべきである。

この属性を機械的に生成するには、特に指示がない限り作業者のログイン名と (可能ならば) 作業を行った機械の名前を記録することが考えられる。

解釈系は source 属性が存在することを仮定してはならない。

GDT 規約への互換性を考慮する場合、source 属性値を production 属性としても与えておくことを推奨する。

編集履歴

生成系は大域属性 history を作成しなければならない。

生成系が 1 つの netCDF ファイルの情報を加工して netCDF ファイルを生成する場合には既存の  history  属性値に文字列を追加したものを新しい history 属性値としなければならない。

生成系が netCDF ファイルによらないで netCDF ファイルを生成する場合には、既存の属性値は空文字列であるとみなされる。

生成系が複数の netCDF ファイルの情報から netCDF ファイルを生成する場合には、どれかひとつの既存の history 属性値を既存の属性値とみなす。どれが選ばれるべきかは実装依存とする。

履歴に追加すべき文字列は、日時、スペース、ユーザ名、"> ", コマンドライン、改行である。必要な情報が取得できない場合は空文字列でよい。

たとえば既存の history が

:history = "1999-12-21T01:20:20+0900 toyoda> agcm5.exe\n";

となっているデータファイルを "gtset ofs=+1000" というコマンドで編集した場合は

:history = "1999-12-21T10:23:41+09:00 toyoda> agcm5.exe\n",
    "2000-01-20T14:21:20+09:00 toyoda> gtset ofs=+1000\n";

となる。

より信頼できる[注]履歴保存法として、木構造履歴 gt_history_branch を用いることを推奨する予定である。

木構造履歴の詳細は今のところ規定しない。