gtool4 規約 version 4.3
2005-09-26T16:06:09+09:00 地球流体電脳倶楽部 davis プロジェクト
NetCDF 変数のうち, 構造体変数でないものを 従来型変数 と呼ぶ.
すべての従来型変数は
long_name
属性を持たなければならない.
long_name
属性には変数の記述的な名称
(文字列) を与えなければならないlong_name
は解釈系によって変数の表わしている量の名称として扱われる.
もし属性が欠けている場合は変数名が代用される.
CF standard name tableで規定されている
従来型変数は
standard_name
属性を持つことを強く推奨する.
CF standard name table は
CF 規約
の標準属性 standard_name に与える既定値を
定めたものである.
本規約では, CF 規約に従って
standard_name
属性を付与することを強く推奨する.
解釈系において変数の同定が必要な場合には,
まず
standard_name
属性を参照し,
standard_name
属性が定義されていない場合は
long_name
属性を参照し,
long_name
属性も定義されていなければ変数名を参照する,
という手続きを経ることを推奨する.
すべての従来型変数は units
属性を持たなければならない.
units
属性には変数に格納された数値の単位
(文字列) を指定しなければならないunits
属性を与えないユーザ定義の単位名は以下の規則に従わなければならない.
ユーザ定義の単位名を用いる場合にはその定義(機械可読でなくてよい)を define_* 属性に与えなければならない.
netCDF はデータ圧縮をサポートしないが, 精度の低い浮動小数点実数を短い整数型として格納することによってファイルサイズを小さくすることができる. このような処置は推奨はされないが, 広く用いられているので解釈系はこの処理をしなければならない.
解釈系は従来型変数を読み取った後に,
scale_factor
属性値があればこれを読み取った数値に乗算し, その後でもし
add_offset
属性があればこれをその結果に加算しなければならない.
生成系は
scale_factor
と add_offset
を用いた書き込みを行う前にデータの最大値と最小値が表現できることを確認しなければならない.
scale_factor
と add_offset
属性は同じ型でなければならない. その型が変数の本来意図された型であるから,
scale_factor
と add_offset
以外の属性に関する規定で変数の型という場合は,
scale_factor
または add_offset
属性の型を指す.
例1: 地表面気圧を 1hPa 単位で観測した数値を保存する場合には「観測値から 1000 を引いた数値」を格納すれば byte 型で 873hPa から 1127hPa の範囲を表現でき, float の 1/4 の記憶容量しか必要としない.
- 元のデータ
- 1007.0, 1009.0, 1012.0, 1020.0, 1016.0, ....
- CDL 表記
byte ps(some_dimension); ps:long_name = "surface pressure"; ps:add_offset = 1000.0; data: ps = 7, 9, 12, 20, 16, ....例2: 気温を通常 0.1℃ 単位で観測した値は, 「観測値を 10 倍した数値」を格納すれば short 型で -273.1℃ から 3276.7 ℃までを表現できるので, float 型の 1/2 の記憶容量しか必要としない.
- 元のデータ
- -12.7, 3.2, 22.1, 18.3, 30.4, ....
- CDL 表記
short T(some_dimension); T:long_name = "temperature"; T:scale_factor = 10.0; data: T = -127, 32, 221, 183, 304, ....
欠損値とは, 数値データの中で何らかの理由によって「値が与えられない」個所に指定すべき値である. 欠損値の表現として IEEE 754 規格の非数 (NaN) を用いるという考えは利点が多いが, 残念ながら現時点では推奨しない[注]. 以下で述べる実数値を与えることを推奨する.
浮動小数点数値のある範囲を欠損値と指定する必要がある場合,
valid_min
属性, valid_max
属性, またはその双方を指定することを推奨する.
valid_range
属性の使用は推奨されないが, 欠損値処理時に解釈しなくてはならない.
変数に valid_min
属性が存在する場合は, その属性値より小さな数値は欠損とみなされる.
変数に
valid_max
属性が存在する場合は, その属性値より大きな数値は欠損とみなされる.
数値型の2要素を持つ
valid_range
属性が存在する場合には,
第1要素 (Fortran 的添字) は
valid_min
属性,
第2要素は valid_max
属性であるとみなされる.
valid_max
属性値が valid_min
属性値より小さい場合は gtool4
規約に適合せず, 解釈は規定されない.
生成系は必要がない場合は
valid_min
,
valid_max
,
valid_range
属性を作成しないことを強く推奨する.
そうすればデータ全体にわたる数値比較と条件判定をしないで済ませることができる.
典型的な実装は, すでに欠損値範囲が定義されている入力に対してだけ,
欠損値範囲を定義することである.
もし欠損値範囲を任意に設定できるのならば,
変数の物理的意味にかかわりなく,
絶対値の十分大きな数を用いることを推奨する.
ただし, デフォルトの
fill 値は欠損値とみなすことを強く推奨する.
指定するのは
valid_min
と valid_max
のどちらか片方にとどめるべきである.
物理的に負にならない量
(たとえば温度) については
valid_min
を -6.0e36 とすることを推奨する.
それ以外の量については
valid_max
を 6.0e36 とすることを推奨する
[注].
例: 温度 (負にならない)
float T; T:valid_min = -6.0e36;
デフォルトの fill 値が欠損値ではない場合, _FillValue
属性値を指定することを推奨する. 属性値 _FillValue
は欠損値とすることを強く推奨する.
gtool4 規約に従った数値データを読み書きして数値演算を行う ― 解釈系であり生成系でもある ― ソフトウェアのことを考える. 情報が与えられないところから情報が勝手に生成されてはいけないから, 欠損値と正常値 (欠損値ではない数値) の混合した演算の結果は
とならなければならない. 複数の欠損値に異なる意味をもたせるような用法が存在してもよいが, gtool4 規約は生成系にそのような扱いを要求しない.
可搬性を IEEE 754 規格の範囲に制限することにはなるが, ソフトウェア内部での欠損値の表現として非数 (NaN) を用いることはよい考えである ― そうすればソフトウェアの内部は欠損値処理を明示的にコーディングする必要がなくなるからである. この場合は外部表現では適当な数値に変換することを推奨する.
入力の変数に
missing_value
属性が定義されていれば, その値を用いることを推奨する. 複数の入力が異なる
missing_value
を定義していた場合には,
出力の物理的性質に反しない限りで絶対値の大きなものを採用すべきである.
missing_value
属性を生成する生成系は,
missing_value
を含んだ欠損値範囲を指定しなければならない.
解釈系は
missing_value
属性を見出したが欠損値範囲の定義を見出せない場合,
情報の欠損を起こさないならば
missing_value
を含む任意の範囲を欠損値とみなしてよい.
上記の欠損値に関連する全ての属性の型は
該当するデータ変数の型と一致するものにしなければならない.
具体的に問題となるのは
スケールによる圧縮
がなされているデータである.
圧縮がなされているデータを解釈する場合には,
scale_factor
属性値および
add_offset
属性値を使用して元のデータに変換する前に欠損値であるかどうかを判定することになる.
ちなみに, 他の規約 (例えば GDT)
では欠損値に関連する属性は元のデータと同じ型を持つことを推奨している場合もある.
この場合, 元のデータに変化した後に欠損値かどうかを判定することになる.
演算を施した数値に対して欠損値の判定を行うことになるので,
valid_min
属性値や
missing_value
属性値に厳密に従うのではなく
適切な幅を持たせて判定をする必要がある.
既存の規約には, 数値が文字列として印字される場合の書式を指定する方法が規定されている. 書式は数値の精度を考慮して決定されるべきであるので, データの属性としては数値の精度を表わすものであると考えられる. 書式指定文字列は処理系に依存するので, この手段は推奨すべきものではないが, 現在のところ代替手段は定義しない.
C_format
属性はプログラム言語
C の printf
関数での書式指定文字列である. もし指定するなら, double
型の書式として適切なものを用いるべきである.
FORTRAN_format
属性はプログラム言語
Fortran の WRITE
文での書式指定である. もし指定するならば, REAL
型の書式指定子として適切なものを用いるべきである.
解釈系は印字書式を解釈することを推奨する.
(参考) GDT には time_format
属性があり, 時刻の印字書式を指定できる.
数値データは多次元の配列として格納できる. 特に必要がない限り, 次元数は最大で4とすることを推奨する. 各次元には何らかの意味をもたせてデータを配置するべきである.
例: 時空間の格子点上で数値データが与えられている場合は, 配列の次元を時間1次元および空間の3次元に対応させることを強く推奨する.
次元の添字 (番号) に対応する位置が数値で表現できるときには, 次元と同名の1次元の従来型変数に位置を格納しなければならない. これを以下では座標変数と呼ぶ. 従来型変数が持っている次元 (複数あるかもしれない) に対応する座標変数たちを, 従来型変数の座標と呼ぶ.
次元の添字に対応する「位置または領域の名称」を文字列で表現できるときには, 次元の名称に接尾辞
_label
を付加した名前の文字型変数に「位置または領域の名称」を格納することを推奨する. このような変数を文字座標と呼ぶ.
座標変数に格納される値は, 単調増加あるいは単調減少でなければならない.
従来型変数の座標となんらかの関係を持っている別の従来型変数を座標とみなして, あたかも元の従来型変数の座標であるかのように取り扱いたい場合がある. このような座標を擬似座標, 座標の指定を間接座標指定と呼ぶ.
間接座標指定を行うには CSM
では coordinates
属性を規定し, GDT
では同じ機能を持つ
coordinates
と associate
属性を規定している.
gtool4 規約の立場からは広く理解される
coordinates
という名称を用いることを推奨する.
従来型変数に
coordinates
属性がある場合,
その名称はスペースで区切られた擬似座標名のリストと解釈される.
例: 複雑な配置をもつ格子
全地球の大気の流れを予測する数値モデルでは緯度によって東西方向に格子数が異なる格子点上での計算を行うことがある. そのような計算結果は以下のように格納される.
dimensions: x = 128; // 東西方向の最大格子数 lat = 64; // 南北方向の格子数 variables: float T(lat, x); // 気温 T:long_name = "temperature"; T:coordinates = "lat lon"; T:units = "K"; T:_FillValue = -6.0e36; float lat(lat); lat:long_name = "latitude"; lat:units = "degrees_north"; float lon(lat, x); lon:long_name = "longitude"; lon:units = "degrees_east"; lon:_FillValue = -6.0e36;
座標変数が表現している方向についての性質を表現する属性がある.
座標変数が表現している方向が周期的である場合,
modulo
属性に周期を書き込むことを推奨する[注].
たとえば経度には
modulo = 360.0;
を指定すべきである.
座標変数が表現している方向が周期的であり,
現在のデータが周期的取り扱いを要求する場合,
topology
属性に文字列値
"circular
" を与えることを推奨する.
modulo
属性がありながら topology = "circular"
を指定しない場合はありうる.
たとえば地球上の東西方向に狭い範囲のデータを与えている場合には,
範囲外のデータを補間して求めてはならないことを示すために,
経度に
topology
属性を付与しないことを推奨する.
座標変数の各格子点が座標軸上のどの範囲を代表しているかを知らせることが有益な場合には,
bounds
属性を指定することを推奨する.
属性値は範囲の上限と下限を格納した従来型変数の名前である.
範囲を格納する従来型変数には座標変数の名前に
_bound
を付加した名前を付けることを推奨する.
格子がすべて密接している場合には座標 x(i)
に対応する範囲は1次元配列で表現できる.
すなわち上限は x_bound(i+1)
で, 下限は x_bound(i)
で表わすことができる.
それ以外の場合は座標 x(i)
に対応する範囲は2次元配列で表現される.
すなわち Fortran
記法では上限は x_bound(i, 1)
で,
下限は x_bound(i,
2)
で表わされる.
gtool4 規約に従う格子点データを読み取って, ある座標の方向の要素の数が少なくなるような操作 (たとえば平均操作) を行ったデータを書き出すことがある. このような操作を座標の縮約と呼ぶ.
何かの座標が縮約された変数には subgrid 属性を付与して縮約操作の種類を表わすことを推奨する. CSM との互換性のため, 同じ役割を持つ coord_op 属性も解釈すべきである.
dimension: date = UNLIMITED; variables: int date(date); date:units = "day since 1891-01-23T00:00:00"; // いわゆる日平均気温 float T(date); T:units = "K"; T:subgrid = "date: mean"; // いわゆる日最高気温 float Tmax(date); Tmax:units = "K"; Tmax:subgrid = "date: maximum"; // 午前0時の気温 float Tmidnight(date); Tmidnight:units = "K"; Tmidnight:subgrid = "date: point";
縮約された座標には old_interval 属性および old_spacing 属性を付与して, 縮約前の座標の解像度を示すことを推奨する.
(参考) 同じ次元をもっていて縮約された座標と縮約されていない座標が同じファイルの中にある場合には, 縮約された座標に expand 属性を付与して相互関係を明示することができる.
(注) 基本的に gtool4 規約では GDT よりは CSM との互換性を重視しているが, 座標の縮約は例外である. これは CSM 規約の属性命名法が名前の衝突の回避を確実にする手段をもっていないからである.
ある次元の方向の変数の平均操作について考える. デフォルトの平均操作は, 他の次元の格子番号が共通するデータの総和を計算し, 次元の方向の格子数で割ることである.
曲線直交座標系 (たとえば地球上に張られた球座標) ではこのような平均操作は誤った結果を生む. そこでは各次元に対応した重みを乗じた総和を, 次元の方向の格子数と重みの総和で割る.
座標変数に gt_calc_weight 属性が付いている場合, 属性値は変数名と解釈され, その数値が重みとして使われる. 変数を作成する際にはもとの変数名に "_weight" を付加した変数名とすることを推奨する.
本節では座標変数が時空間の次元を持つ場合に関する規約を記述する.
従来型変数が時空間を表わす座標を用いる場合は, Fortran 表記で (CDL や C では逆になる) 以下のような順序で座標を用いることを強く推奨する.
ここで鉛直方向とは重力の方向と一致するかそれに近似する方向, 東西方向とは地球または惑星の自転軸に直交する方向である. 重力や自転軸が仮定されていない場合には Fortran 表記で名前の順 (例: x, y, z) になるように座標を定義することを推奨する.
時空間方向の格子数が1つしかない場合でも, 本来多数の格子が取りうるところから1つの格子をとりだしたものであれば, 長さが1の次元を定義して位置を格納することを推奨する.
たとえば鉛直方向が1層であっても, 長さ1の鉛直座標を定義することを推奨する.
データ源が上記の順序と異なる座標の順序を用いており, 並べ替えが困難な場合には以下の手段を用いて座標を識別できるようにしておくことを強く推奨する.
暦法とは日数から月と年を定義する手続きである.
ローマ帝国に由来するユリウス暦は 16 世紀にグレゴリオ暦に改暦された. 不幸なことにユリウス暦とグレゴリオ暦の日付は不連続であり, もっと不幸なことに移行の年は地域によって異なり, 20 世紀までユリウス暦を使っていた国も存在する. このためある日付がどちらの暦によるかは自明ではない. また, 地球流体力学の実験では1年を 360 日としたり, 地球外惑星の公転周期を年のかわりに用いたりすることがある. このような事情から, 時間座標の暦法を明示することには意義がある.
時間の座標変数には calendar 属性を付与することを推奨する. 内容は GDT を参照せよ.
日本・朝鮮・中国・ 古代ギリシャなどで用いられてきた太陰太陽暦の情報交換用表記法はいまのところ標準化されていないので, ここでは表現を規定しない. 使用しないことを強く推奨する.
太陰暦であるアラビア暦は情報交換用表記にあてはめることが可能であるが, 混乱をもたらすので使用しないことを強く推奨する.
地球上で通常の経緯度とは異なる球座標を用いることがある. その場合 CSM では north_pole 属性を付与して通常の座標との対応を指示する.
gtool4 規約では構造体変数によって従来型変数の図形表現を直接的に格納できる. しかし従来型変数に図形表現を作成する際の動作を指定する機能を与えることによって, 変数が図形表現に用いられる慣習をデータとともに流通させることができる.
座標変数の
positive
属性は, その座標変数が座標軸として描画される際の方向を指示する.
属性値が
"up" または "right"
であれば, 数値が大きいほうが上または右, 属性値が
"down" または "left"
であれば, 数値が大きいほうが下または左となる.
従来型変数の gt_graph_range 属性は, その変数が描画される際の描画範囲を指示する. これは座標変数と解釈される場合も, そうでない描画対象とされる場合も有効とする. たとえば折れ線グラフの縦軸の範囲や, 等値線を描画すべき範囲などとして利用することが考えられる.
従来型変数の gt_graph_contours_levels 属性は, その変数が等値線図で描画される場合の等値線の引き方を, すべての等値線のレベルを列挙することで指示する.
従来型変数の gt_graph_contours_interval 属性は, その変数が等値線図で描画される場合の等値線の引き方を, 範囲と間隔で指定する. gt_graph_contours_levels 属性と同時に指定してもよく, 両方が指定されている場合には両方で指定される等値線が描画されるものと解釈される.
従来型変数に gt_graph_tick_all 属性が存在し, 値が "" または "0" でない場合は従来型変数が座標軸として描画される場合に必ずすべてのデータ点で tick (目盛り線)を描画すべきことを指示する. そうではなく, 従来型変数に gt_graph_tick_levels 属性がある場合, 座標軸として描画される場合に本属性値の点で tick を描画すべきことが指示される. そうではなく, 従来型変数に gt_graph_tick_interval 属性がある場合, 座標軸として描画される場合に本属性値で規定される感覚で tick を描画すべきことが指示される.
短い目盛り線と同時に長い目盛り線を描画できるために, gt_graph_smalltick_all, gt_graph_smalltick_levels, gt_graph_smalltick_interval 属性が定義されている.
変数の地図投影法を規定するために, 従来型変数の属性または大域属性として proj_coordinates 属性および proj_parameters 属性を与えることができる. 仕様については CSM を参照.
パラメタ探索実験を行う場合など, 数値などのパラメタを保存しておきたい場合がある. このような場合にはオプションでユーザ定義の属性に情報を保存することができる.
このために gtool4 規約は gt_user_anything 属性を予約する. ユーザは gt_user_ で始まる属性名には何を保存してもよい.
属性名の衝突を避けるため, 何らかの方法でユーザ名 (たとえば toyoda) を決め, それを接頭辞に含めるのがよい (たとえば gt_user_toyoda_anything).
(参考) CSM では古気候の研究のために惑星の公転軌道パラメタを保存する orbital_parameter 属性を規定している.