gtool4 規約 version 4.2
2004-08-10T12:09:17+09:00 石渡正樹
この規約は、gtool4 規約準拠 netCDF データセットの形を規定し、その生成法と解釈を与える。この規約は netCDF データセットの自己記述性を高め、種々の環境で使用する際の可搬性、信頼性を高めることを目的とする。
以下で netCDF ファイル とは、netCDF ユーザーズガイドで netCDF データセットと呼ばれているものを指す[注]。
本規約は netCDF ファイルを生成するソフトウェアまたは人間 (以下では生成系と呼ぶ) に対する規定と、netCDF ファイルを解釈するソフトウェアまたは人間 (以下では解釈系と呼ぶ) に対する規定からなる。
生成系が本規約に適合するとは、生成系に関する必須規定を遵守することである。生成系は必須規定に違反する動作をできないようにしたほうがよいが、ユーザが明示的にオプション操作をした場合に (たとえばコマンドラインスイッチ) 違反を許容してもよいし、ユーザの入力が必須規定に違反する場合に警告メッセージを表示してもよい。
データセットが本規約に適合するとは、生成系に関する生成規定に反することなく同じデータセットを生成できることである。
解釈系が本規約に適合するとは、解釈系に関する必須規定を遵守することである。解釈系に関する必須規定には gtool4 規約に不適合なデータセットの解釈も含まれているので、すべての gtool4 適合データセットを解釈できるだけでは十分でない。たとえば、一般に解釈系は必須属性が存在することを仮定してはならない。
何かを「しなければならない」という表現は必須規定を表わす。
何かを「してはならない」という表現は「その動作をしないようにしなければならない」という意味の必須規定である。
何かを「することを推奨する」という表現は推奨規定を表わす。
何かを「してもよい」という表現は参考規定を表わす。節見出しや段落の先頭に表記されている (参考) は節や段落全体が参考規定であることを示す。
何かを「するべきである」という表現は、参考規定の中で遵守することが強く期待されている規定に付与されている。
生成系は新たに作成する netCDF データセットに ".nc" で終わるファイル名を与えなければならない[注]。
ファイル名は末尾の ".nc" を除いて 8文字以内にとどめることを推奨する。8文字以内にとどめることができない場合には、32 文字以内にとどめることを強く推奨する。ファイル名は数字、英小文字、そして下線で構成することを強く推奨する。
ファイル名に英小文字を使用することができない環境では、英大文字を代わりに用いることができる。
変数名は netCDF ライブラリに許容される変数名でなければならない[注]。
混乱を防ぐため、英大文字と英小文字の相違を無視すると同一になってしまう2つの名前 (たとえば "T" と "t") を持った変数を作らないことを強く推奨する。
gtool4 規約は (図形情報などの) オブジェクト指向なデータ構造を格納することを想定して[注]新しく構造体変数を導入する。
構造体変数の変数本体には意味のある情報を格納せず、構造体の成分にあたる情報を属性値として格納する。
従来の netCDF 規約では、変数本体に主要なデータ（たいていは数値型）を格納し、属性に補助的な説明を格納する。このような従来の使い方をする変数を構造体変数と区別するために従来型変数と呼ぶ。
注: gtool4 規約に従う netCDF ファイルは、構造体変数を削除すれば既存の規約でほとんど理解可能になるように設計されている。逆に、既存の規約で作成された netCDF ファイルは、従来型変数だけを含むように見える。
従来型変数については第3章で、構造体変数については第4章で記述されている。
生成系は以下の大域属性 Conventions
を与えねばならない。
:Conventions = "http://www.gfd-dennou.org/arch/gtool4/conventions/";
また、生成系は以下の大域属性
gt_version
を与えねばならない。
:gt_version = "4.2";
解釈系は、少なくとも Conventions
属性値が "gtool"
を含む場合には（そうでない場合も可能な限り）、 gtool4
規約に準拠した動作をしなければならない。
(参考) GDT
規約への互換性を考慮する場合、大域属性 appendices
を与えてもよい[注]。もし与えるならば、float
型で数値 1.3 (またはあなたが参照した最新の GDT 規約版数) とする。
:appendices = 1.3f;
生成系はすべてのファイルに大域属性 title
を与えねばならない。
大域属性 title
には表題すなわちファイルに含まれる数値データの短い説明を与えるべきである。数値モデルのランの名称や観測・実験番号などが考えられる。
やむをえず title 属性を機械的に生成するには、所属するデータ変数の long_name を列挙したものを付与することが考えられる。
解釈系は大域属性 title
が存在することに依存してはならない。表題を出力するソフトウェアは
title
が欠けている場合にはファイル名で代用すべきである。
(参考) 生成系は副題を gt_subtitle
属性に与えてもよい。
解釈系が表題と副題を別個に取り扱う機能を持たない場合、表題は
title
と gt_subtitle
を空白をはさんで連結したものとすることを推奨する。
例
:title = "aqua-planet patch experiment"; :gt_subtitle = "A4";
(参考) ファイルの長い記述的な説明は大域属性 comment に格納するのがよい。
例
:title = "ISLSCP Initiative 1"; :gt_subtitle = "1987-1988"; :comment = "Global Data Sets for Land-Atmosphere Models"; :source = "ISLSCP Initiative 1"; :institution = "USA NASA Goddard DAAC";
生成系はすべてのファイルに source 属性を与えねばならない。また、生成系は institution 属性を与えることが推奨される。
source 属性には数値データが最初に netCDF 形式で作成されたときの観測手段、データアーカイブ名、またはソフトウェア名が記入されるべきである。
機械的に source 属性を生成するには、もし source 属性が何らかの手段で与えられていればそれを保存し、存在しなければソフトウェアの名称を与えるようにすることが考えられる。
例1: 観測値の netCDF 化 (測器名称)
:source = "report of JMA-80";例2: データアーカイブの編集
:source = "ECMWF Objective Analysis";例3: 数値予報モデルによるデータ
:source = "GFD-Dennou Club AGCM 5.3";
institution 属性にはファイルの最終変更を行った者の名称が記入されるべきである。データがある機関の事業として供給されるならば、その機関の名称が記入されるべきである。また個人の作業としてファイルが作成されるならば、その個人の実名やログイン名が記入されるべきである。
(参考) 機械的に institution 属性を生成するには、特に指示がない限り作業者のログイン名と (可能ならば) 作業を行った機械の名前を記録することが考えられる。
解釈系は source 属性が存在することを仮定してはならない。
GDT 規約への互換性を考慮する場合、source 属性と同じ値を production 属性としても与えておくことを推奨する。
生成系は大域属性 history
を作成しなければならない。
生成系が 1 つの netCDF ファイルの情報を加工して netCDF ファイルを生成する場合には既存の
history属性値に文字列を追加したものを新しいhistory属性値としなければならない。生成系が netCDF ファイルによらないで netCDF ファイルを生成する場合には、既存の history 属性値は空文字列であるとみなされる。
生成系が複数の 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";
となる。
(参考) gtool 規約の将来の版では、より信頼できる[注]履歴保存法として、木構造履歴
gt_history_branchを用いることを推奨する予定である。木構造履歴の詳細は今のところ規定しない。