8.1 属性の規約

Put your logo here!

8.1 属性の規約

アンダースコア(‘_’)で始まる名前はNetCDFライブラリ専用です。NetCDFファイルを処理する一般的なアプリケーションは標準的な属性の規約を仮定しており、よほどの理由が無い限り、これらの規約に従いましょう。以下に、有用であることが証明済みの、推奨される標準的な属性の名前や意味が表記されています。これらの中には数値データを仮定しているものもあり(例えば、units, valid_range, scale_factor)、文字データ用には使うべきではない属性がいくつかあることに注意して下さい。

units 変数データの単位を指定する文字列。Unidataは自由に取得できるルーチンライブラリを開発・提供しています。これを使えば文字列と単位指定のバイナリ形式との間の変換やバイナリ形式で様々な有用な操作を行なうことができます。このライブラリはいくつかのNetCDFアプリケーションで使われています。推奨される単位構文を使用すれば、整合単位で表現されたデータを、算術演算用に一般的な単位に自動的に変換することが可能です。詳しくは、Appendix A「単位」(p.117)参照。

long_name 長い記述的な名前。プロットのラベルなどに使える。変数にlong_name属性が割り当てられていなければ、変数名をデフォルトとして使用しましょう。

valid_min この変数の有効値の最小値を示すスカラー

valid_max この変数の有効値の最大値を示すスカラー

valid_range
この変数の有効値の最小値と最大値を示す２つの数値のベクトル。valid_minとvalid_max属性の値を指定することと等価です。これらの変数はどれも有効範囲(valid range)を定義している。valid_minまたはvalid_maxのどちらか一方でも定義されていたら、valid_range属性を定義してはいけません。

一般的なアプリケーションは有効範囲外の値は欠損として扱うのが望ましいです。各valid_range, valid_minそしてvalid_max属性の型はその変数の型と一致してしてなければなりません。(ただし、byteデータ型は除く：これらは意図する範囲を符号付整数型によって指定できます。)

valid_min, valid_max, valid_rangeのいずれも定義されていない場合には、一般的なアプリケーションは有効範囲を次の方法で定義するのが良いです。データがバイト型で_FillValueが明示されていない場合、有効範囲はすべての可能な値を含みます。それ以外の場合には、有効範囲から(明示された、もしくはデフォルト指定の)_FillValueを下記の要領で除外します。_FillValueが正の値の場合には、それが有効な最大値とし、正で無い場合には有効な最小値として定義します。整数型については、_FillValueとこの有効な最大値または最小値の差を1とします。浮動小数点型については、丸め誤差を念頭に置き、この差を表現可能な最小値(最も下位のビットで１)の2倍に設定します。

scale_factor ある変数についてこの属性が与えられていれば、データにアクセスするアプリケーションによってデータが読み込まれた後に、データはこの係数と掛け合せられます。

add_offset
ある変数についてこの属性が与えられている場合、データはそれにアクセスするアプリケーションによって読み込まれた後にこの数が加えられます。もし、scale_factorとadd_offsetの両方の属性が与えられている場合には、データはまずスケールされ、その後でオフセットが加えられます。scale_factorとadd_offsetを同時に使うことによって、簡単なデータ圧縮を行なうことができ、これによって、NetCDFファイル内に低解像度の浮動小数点データを小さい整数として格納することができます。スケールされたデータが書き込まれた場合、アプリケーションはまず、オフセットを差し引き、その後にスケールファクターで割ります。

scale_factorとadd_offsetが圧縮に使われる際には、関連する変数(圧縮データを格納している)の型は通常、byte型かshort型です。一方で、解凍されたデータはfloat型やdouble型となります。scale_factorとadd_offset属性は両方とも解凍されたデータの持つ型(float型やdouble型)でなければなりません。

_FillValue
_FillValue属性は、変数に割り当てられているディスクスペースをあらかじめ埋めるために使用されるフィル値を指定します。このようにあらかじめスペースを埋める動作は、nc_set_fillを使ってノーフィルモード(nofill mode)が設定されていない限り行なわれます。詳細については、5.12節「書き込みのフィルモードを設定する: NF_SET_FILL」(p.43)を参照して下さい。書き込まれた事のない値を読み取った時にフィル値が返されます。_FillValueが定義されていれば、それはスカラーで、変数と同じ型を取ります。デフォルトのフィル値が変数の型に合致していれば、変数について_FillValue属性をいちいち定義する必要はありません。しかし、byte型データにデフォルトのフィル値を使用することはお勧めできません。この変数の属性の値を変更する際には、その値がそれ以降の書き込みに対してのみ有効である点に注意してください。それ以前にフィル値が書き込まれたデータは変更されません。

一般のアプリケーションはしばしば、未定義の値または欠損値を表現するために値を書き込む必要があります。フィル値はこれに対して適切な値を提供します。それは、フィル値が通常、有効範囲外の値を取るために、一般のアプリケーションでは欠損値として扱われるからです。フィル値を有効範囲内に設定することはできますが、薦められません。

より詳しい説明については、7.16節「フィル値」(p.82)を参照して下さい。

missing_value この属性はライブラリや規約に従った一般のアプリケーションによって特別扱いされるわけではありませんが、しばしば有用な情報であるので特定のアプリケーションで使われることがあります。missing_value属性はスカラーでもベクトルでも良く、欠損データを示す値を含んでいます。一般のアプリケーションが、これらの値を欠損値として取り扱えるように、これらの値は有効範囲外にあるべきです。

signedness 使用価値の無くなった属性です。元はbyte値が符号付か符号無しのどちらで扱われるべきか指定するために作られました。現在ではこの目的のために、valid_minとvalid_maxの属性を使用できます。例えば、byte変数に非負の値のみ格納したい場合には、valid_min = 0とvalid_max = 255とを使えます。NetCDFライブラリはこの属性を無視します。

C_format この変数の値をプリントするCアプリケーションが使用するべきフォーマットを与える文字配列です。例えば、ある変数が有効数字3桁の精度しかないことが明らかであれば、C_format属性を"%.3g"と定義するのが適当です。ncdumpユーティリティプログラムは、これが定義されている変数に対してはこの属性を使います。このフォーマットはscale_factor及びadd_offset等のスケーリングする属性のある無しに関わらず、スケールされた(内部)型と値に適用されます。

title グローバル属性で、データセットの中身を簡潔に説明する文字配列。

history 検査履歴のためにグローバル属性。これは文字配列で、ファイルを修正したプログラムの各呼び出しに対して一列割り振られています。性質の良い一般のNetCDFアプリケーションは、アクセスする際に日付・時刻・ユーザー名・プログラム名・コマンドの引数を含む一行を追加します。

Conventions
存在する場合には、‘Conventions’はグローバル属性であり、データセットが従う規約の名前を示す文字配列です。ある分野に固有な規約の集合体を記述した文書の貯蔵場所のディレクトリの相対的なディレクトリ名として解釈される文字列の形式を取ります。これによって、規約の階層構造が可能になり、規約の記述や例を、それを定義した機関やグループが保持する場所を与えています。規約のディレクトリ名は現在ではホストマシンftp.unidata.ucar.edu.上のpub/NetCDF/Conventions/ディレクトリから相対的に解釈される。代わりに、規約を記述した文書が維持されているWWWサイトを指定するために、完全なURL指定子を使用しても構いません。

例えば、NUWGというグループが、ある分野に固有のデータ構造の次元名・変数名・必要な属性・NetCDF表現に対する規約について合意したとします。NUWGは合意された規約を記述した文書をConventionsディレクトリのサブディレクトリNUWG/に保管しておくことができます。これらの規約に従ったデータセットは"NUWG"という値を持ったグローバルConventions属性を含むことになります。

後にこのグループが、NUWGデータの特定の部分集合(例えば時系列等)について新たに規約を追加することに決めた場合、その追加される規約の記述はNUWG/Time_series/サブディレクトリに保管されます。これらの追加された規約に従ったデータセットは"NUWG/Time_series"の値を持つグローバルConventions属性を使い、NUWG規約と追加されたNUWG時系列規約にも従ったことを示します。

units	変数データの単位を指定する文字列。Unidataは自由に取得できるルーチンライブラリを開発・提供しています。これを使えば文字列と単位指定のバイナリ形式との間の変換やバイナリ形式で様々な有用な操作を行なうことができます。このライブラリはいくつかのNetCDFアプリケーションで使われています。推奨される単位構文を使用すれば、整合単位で表現されたデータを、算術演算用に一般的な単位に自動的に変換することが可能です。詳しくは、Appendix A「単位」(p.117)参照。
long_name	長い記述的な名前。プロットのラベルなどに使える。変数にlong_name属性が割り当てられていなければ、変数名をデフォルトとして使用しましょう。
valid_min	この変数の有効値の最小値を示すスカラー
valid_max	この変数の有効値の最大値を示すスカラー
valid_range	この変数の有効値の最小値と最大値を示す２つの数値のベクトル。valid_minとvalid_max属性の値を指定することと等価です。これらの変数はどれも有効範囲(valid range)を定義している。valid_minまたはvalid_maxのどちらか一方でも定義されていたら、valid_range属性を定義してはいけません。一般的なアプリケーションは有効範囲外の値は欠損として扱うのが望ましいです。各valid_range, valid_minそしてvalid_max属性の型はその変数の型と一致してしてなければなりません。(ただし、byteデータ型は除く：これらは意図する範囲を符号付整数型によって指定できます。) valid_min, valid_max, valid_rangeのいずれも定義されていない場合には、一般的なアプリケーションは有効範囲を次の方法で定義するのが良いです。データがバイト型で_FillValueが明示されていない場合、有効範囲はすべての可能な値を含みます。それ以外の場合には、有効範囲から(明示された、もしくはデフォルト指定の)_FillValueを下記の要領で除外します。_FillValueが正の値の場合には、それが有効な最大値とし、正で無い場合には有効な最小値として定義します。整数型については、_FillValueとこの有効な最大値または最小値の差を1とします。浮動小数点型については、丸め誤差を念頭に置き、この差を表現可能な最小値(最も下位のビットで１)の2倍に設定します。
scale_factor	ある変数についてこの属性が与えられていれば、データにアクセスするアプリケーションによってデータが読み込まれた後に、データはこの係数と掛け合せられます。
add_offset	ある変数についてこの属性が与えられている場合、データはそれにアクセスするアプリケーションによって読み込まれた後にこの数が加えられます。もし、scale_factorとadd_offsetの両方の属性が与えられている場合には、データはまずスケールされ、その後でオフセットが加えられます。scale_factorとadd_offsetを同時に使うことによって、簡単なデータ圧縮を行なうことができ、これによって、NetCDFファイル内に低解像度の浮動小数点データを小さい整数として格納することができます。スケールされたデータが書き込まれた場合、アプリケーションはまず、オフセットを差し引き、その後にスケールファクターで割ります。 scale_factorとadd_offsetが圧縮に使われる際には、関連する変数(圧縮データを格納している)の型は通常、byte型かshort型です。一方で、解凍されたデータはfloat型やdouble型となります。scale_factorとadd_offset属性は両方とも解凍されたデータの持つ型(float型やdouble型)でなければなりません。
_FillValue	_FillValue属性は、変数に割り当てられているディスクスペースをあらかじめ埋めるために使用されるフィル値を指定します。このようにあらかじめスペースを埋める動作は、nc_set_fillを使ってノーフィルモード(nofill mode)が設定されていない限り行なわれます。詳細については、5.12節「書き込みのフィルモードを設定する: NF_SET_FILL」(p.43)を参照して下さい。書き込まれた事のない値を読み取った時にフィル値が返されます。_FillValueが定義されていれば、それはスカラーで、変数と同じ型を取ります。デフォルトのフィル値が変数の型に合致していれば、変数について_FillValue属性をいちいち定義する必要はありません。しかし、byte型データにデフォルトのフィル値を使用することはお勧めできません。この変数の属性の値を変更する際には、その値がそれ以降の書き込みに対してのみ有効である点に注意してください。それ以前にフィル値が書き込まれたデータは変更されません。一般のアプリケーションはしばしば、未定義の値または欠損値を表現するために値を書き込む必要があります。フィル値はこれに対して適切な値を提供します。それは、フィル値が通常、有効範囲外の値を取るために、一般のアプリケーションでは欠損値として扱われるからです。フィル値を有効範囲内に設定することはできますが、薦められません。より詳しい説明については、7.16節「フィル値」(p.82)を参照して下さい。
missing_value	この属性はライブラリや規約に従った一般のアプリケーションによって特別扱いされるわけではありませんが、しばしば有用な情報であるので特定のアプリケーションで使われることがあります。missing_value属性はスカラーでもベクトルでも良く、欠損データを示す値を含んでいます。一般のアプリケーションが、これらの値を欠損値として取り扱えるように、これらの値は有効範囲外にあるべきです。
signedness	使用価値の無くなった属性です。元はbyte値が符号付か符号無しのどちらで扱われるべきか指定するために作られました。現在ではこの目的のために、valid_minとvalid_maxの属性を使用できます。例えば、byte変数に非負の値のみ格納したい場合には、valid_min = 0とvalid_max = 255とを使えます。NetCDFライブラリはこの属性を無視します。
C_format	この変数の値をプリントするCアプリケーションが使用するべきフォーマットを与える文字配列です。例えば、ある変数が有効数字3桁の精度しかないことが明らかであれば、C_format属性を"%.3g"と定義するのが適当です。ncdumpユーティリティプログラムは、これが定義されている変数に対してはこの属性を使います。このフォーマットはscale_factor及びadd_offset等のスケーリングする属性のある無しに関わらず、スケールされた(内部)型と値に適用されます。
title	グローバル属性で、データセットの中身を簡潔に説明する文字配列。
history	検査履歴のためにグローバル属性。これは文字配列で、ファイルを修正したプログラムの各呼び出しに対して一列割り振られています。性質の良い一般のNetCDFアプリケーションは、アクセスする際に日付・時刻・ユーザー名・プログラム名・コマンドの引数を含む一行を追加します。
Conventions	存在する場合には、‘Conventions’はグローバル属性であり、データセットが従う規約の名前を示す文字配列です。ある分野に固有な規約の集合体を記述した文書の貯蔵場所のディレクトリの相対的なディレクトリ名として解釈される文字列の形式を取ります。これによって、規約の階層構造が可能になり、規約の記述や例を、それを定義した機関やグループが保持する場所を与えています。規約のディレクトリ名は現在ではホストマシンftp.unidata.ucar.edu.上のpub/NetCDF/Conventions/ディレクトリから相対的に解釈される。代わりに、規約を記述した文書が維持されているWWWサイトを指定するために、完全なURL指定子を使用しても構いません。
	例えば、NUWGというグループが、ある分野に固有のデータ構造の次元名・変数名・必要な属性・NetCDF表現に対する規約について合意したとします。NUWGは合意された規約を記述した文書をConventionsディレクトリのサブディレクトリNUWG/に保管しておくことができます。これらの規約に従ったデータセットは"NUWG"という値を持ったグローバルConventions属性を含むことになります。
	後にこのグループが、NUWGデータの特定の部分集合(例えば時系列等)について新たに規約を追加することに決めた場合、その追加される規約の記述はNUWG/Time_series/サブディレクトリに保管されます。これらの追加された規約に従ったデータセットは"NUWG/Time_series"の値を持つグローバルConventions属性を使い、NUWG規約と追加されたNUWG時系列規約にも従ったことを示します。

Quadralay Corporation
http://www.webworks.com
Voice: (512) 719-3399
Fax: (512) 719-3606
sales@webworks.com