gtool4 規約 version 4.0beta10

3. 従来型変数

2000-05-25T18:39:33+09:00 豊田英司

従来型変数全般にあてはまる規約

NetCDF 変数のうち、構造体変数でないものを従来型変数と呼ぶ。

すべての従来型変数は long_name 属性を持たなければならない。

long_name 属性には変数の記述的な名称 (文字列) を与えなければならない
もし生成系が必要な情報を入手できない場合は変数名と同じ名前をつけてもよい
long_name は解釈系によって変数の表わしている量の名称として扱われる。もし属性が欠けている場合は変数名が代用される

単位

すべての従来型変数は units 属性を持たなければならない。

units 属性には変数に格納された数値の単位 (文字列) を指定しなければならない
ただし単位に関する情報が得られない場合は units 属性を与えない
できるだけ SI に準拠した単位を用い、付属書の書式で表現することを推奨する
無次元数値を格納する場合は '1' を与えなければならない
スケーリングによって得られた無次元数値には単位があるものとみなしてもよい。この場合にはユーザ定義の単位を用いる。次節参照

ユーザ定義の単位

ユーザ定義の単位名は以下の規則に従わなければならない。

udunits にすでに登録されたものであってはならない。
下線と英小文字だけから構成されなければならない。

ユーザ定義の単位名を用いる場合にはその定義（機械可読でなくてよい）を define_units 属性に与えなければならない。

スケールによる圧縮

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 を含む任意の範囲を欠損値とみなしてよい。

数値の印字書式の指定

既存の規約には、数値が文字列として印字される場合の書式を指定する方法が規定されている。書式は数値の精度を考慮して決定されるべきであるので、データの属性としては数値の精度を表わすものであると考えられる。書式指定文字列は処理系に依存するので、この手段は推奨すべきものではないが、現在のところ代替手段は定義しない。

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 属性が付いている場合、属性値は変数名と解釈され、その数値が重みとして使われる。

時空間座標に関する規約

本節では座標変数が時空間の次元を持つ場合に関する規約を記述する。

時空間座標の識別

従来型変数が時空間を表わす座標を用いる場合は、Fortran 表記で (CDL や C では逆になる) 以下のような順序で座標を用いることを強く推奨する。

最初に水平方向、もし東西にあたるものがあれば東西方向
次に水平方向の第2次元、もし南北にあたるものがあれば南北方向
次に鉛直方向
次に時間
時空間以外の座標がある場合には最後

ここで鉛直方向とは重力の方向と一致するかそれに近似する方向、東西方向とは地球または惑星の自転軸に直交する方向である。重力や自転軸が仮定されていない場合には Fortran 表記で名前の順 (例: x, y, z) になるように座標を定義することを推奨する。

時空間方向の格子数が1つしかない場合でも、本来多数の格子が取りうるところから1つの格子をとりだしたものであれば、長さが1の次元を定義して位置を格納することを推奨する。

たとえば鉛直方向が1層であっても、長さ1の鉛直座標を定義することを推奨する。

データ源が上記の順序と異なる座標の順序を用いており、並べ替えが困難な場合には以下の手段を用いて座標を識別できるようにしておくことを強く推奨する。

水平方向座標の units 属性に "degree_east", "degree_north" を指定する
鉛直座標の positive 属性に "up" または "down" を指定する
時間座標の units 属性に時間の単位を指定する
大域属性 axis に軸の順序を記述する

暦法

暦法とは日数から月と年を定義する手続きである。

ローマ帝国に由来するユリウス暦は 16 世紀にグレゴリオ暦に改暦された。不幸なことにユリウス暦とグレゴリオ暦の日付は不連続であり、もっと不幸なことに移行の年は地域によって異なり、20 世紀までユリウス暦を使っていた国も存在する。このためある日付がどちらの暦によるかは自明ではない。また、地球流体力学の実験では1年を 360 日としたり、地球外惑星の公転周期を年のかわりに用いたりすることがある。このような事情から、時間座標の暦法を明示することには意義がある。

時間の座標変数には calendar 属性を付与することを推奨する。内容は GDT を参照せよ。

日本・朝鮮・中国・古代ギリシャなどで用いられてきた太陰太陽暦の情報交換用表記法はいまのところ標準化されていないので、ここでは表現を規定しない。使用しないことを強く推奨する。

太陰暦であるアラビア暦は情報交換用表記にあてはめることが可能であるが、混乱をもたらすので使用しないことを強く推奨する。

回転座標 (互換)

地球上で通常の経緯度とは異なる球座標を用いることがある。その場合 CSM では north_pole 属性を付与して通常の座標との対応を指示する。

図形表現に関するヒント

gtool4 規約では構造体変数によって従来型変数の図形表現を直接的に格納できる。しかし従来型変数に図形表現を作成する際の動作を指定する機能を与えることによって、変数が図形表現に用いられる慣習をデータとともに流通させることができる。

座標変数の positive 属性は、その座標変数が座標軸として描画される際の方向を指示する。属性値が "up" または "right" であれば、数値が大きいほうが上または右、属性値が "down" または "left" であれば、数値が大きいほうが下または左となる。

従来型変数の gt_graph_range 属性は、その変数が描画される際の描画範囲を指示する。これは座標変数と解釈される場合も、そうでない描画対象とされる場合も有効とする。たとえば折れ線グラフの縦軸の範囲や、等値線を描画すべき範囲などとして利用することが考えられる。

従来型変数の gt_graph_contour_levels 属性は、その変数が等値線図で描画される場合の等値線の引き方を、すべての等値線のレベルを列挙することで指示する。

従来型変数の gt_graph_contour_spacing 属性は、その変数が等値線図で描画される場合の等値線の引き方を、範囲と間隔で指定する。gt_graph_contour_levels 属性と同時に指定してもよく、両方が指定されている場合には両方で指定される等値線が描画されるものと解釈される。

細い等値線と太い等値線を同時に指定できるように、gt_graph_thickcontour_levels 属性と gt_graph_thickcontour_spacing 属性が定義されている。これらは線が太くなるということを除いて gt_graph_contour_levels や gt_graph_contour_spacing と同等の効力をもつ。

従来型変数に gt_graph_tick_all 属性が存在し、値が "" または "0" でない場合は従来型変数が座標軸として描画される場合に必ずすべてのデータ点で tick を描画すべきことを指示する。

従来型変数に gt_graph_tick_byvalue 属性がある場合、座標軸として描画される場合に本属性値の点で tick を描画すべきことが指示される。

従来型変数に gt_graph_tick_interval 属性がある場合、座標軸として描画される場合に本属性値で規定される感覚で tick を描画すべきことが指示される。

地図投影 (互換)

変数の地図投影法を規定するために、従来型変数の属性または大域属性として proj_coordinates 属性および proj_parameter 属性を与えることができる。仕様については CSM を参照。

パラメタの保存

パラメタ探索実験を行う場合など、数値などのパラメタを保存しておきたい場合がある。このような場合にはオプションでユーザ定義の属性に情報を保存することができる。

このために gtool4 規約は gt_user_anything 属性を予約する。ユーザは gt_user_ で始まる属性名には何を保存してもよい。

属性名の衝突を避けるため、何らかの方法でユーザ名 (たとえば toyoda) を決め、それを接頭辞に含めるのがよい (たとえば gt_user_toyoda_anything)。

(参考) CSM では古気候の研究のために惑星の公転軌道パラメタを保存する orbital_parameter 属性を規定している。