この記事の目次
海洋データを扱うWebアプリは、正しい数値を返しながらも、間違った意味を伝えてしまうことがあります。たとえば、単位が抜け落ちている、fill valueがゼロに置き換わっている、補正済みの値に生の値側の品質フラグが付いている、補間値が実測値と見分けられない、といった場合です。
これらは、層をまたぐデータの受け渡し仕様の問題です。NetCDF、前処理、ストレージ、API、ブラウザという層をまたいでデータを渡す際に、値の意味を明文化していないと起こります。
この記事では、海洋の観測データを各工程で受け渡すための実務的な決めごとを整理します。NetCDFからブラウザ可視化まで：海洋データWebアプリの設計を踏まえ、途中で失ってはいけない情報に絞って説明します。
数値だけでは科学的なデータにならない
設計が不十分なAPIは、34.72という数値だけを送り、その意味の説明をフロントエンド、ファイル名、チーム内の記憶に委ねます。適切に設計されたAPIは、クライアントがラベルを表示し、値を検証して元データまでたどれるだけの情報を、数値と一緒に送ります。
スキーマの詳細はWebアプリごとに異なりますが、矛盾した組み合わせが生じにくい形にします。ブラウザ側が0を見て、実測値なのか、欠損なのか、変換の失敗なのかを推測しなければならない設計は避けます。
単位：表示形式の前に物理量を定義する
単位は軸ラベルに書くだけのものではなく、変数の定義そのものに含まれます。ソースの物理量をそのまま保ち、変換はすべて記録します。
各変数について次を定義します。
- コードから参照する固定名
- 画面に表示する名称
- 保存時の単位
- 表示時に選択できる単位
- 単純換算できない場合の変換方法とバージョン
- 検証に用いる物理的または運用上の有効範囲（設定する場合）
現場水温、ポテンシャル水温、保存水温が同じシステムに入り得るなら、temperatureという曖昧なキーは使わず、塩分の値をすべてPSUと呼ぶことも避けます。これは、実用塩分が無次元量であるのに対し、絶対塩分は通常g/kgで表すためです。UIの文言は分かりやすくしてかまいませんが、データ層では正確さを保ちます。
単位変換のコードを、グラフごとのコールバックへばらばらに書かないようにします。テスト済みの一つの処理で、表示する値と単位を同時に作ります。利用者が単位を切り替えられる場合も、基準となる保存値はそのまま保ち、変換を繰り返して丸め誤差が積み上がらないようにします。
欠損値：値がないことをそのまま残す
NetCDFの変数は、fill valueやmissing valueの属性を持つことがあります。これらの欠損を表す特殊値は、演算、統計、補間、JSONへの変換より前に、欠損として解釈しておきます。
安全な順序は次のとおりです。
- 変数と、そこで宣言されている欠損値の表現を読む。
- fill valueを、使用するプログラム言語で扱える欠損値へ変換する。
- 対応するQCと値の選択規則を適用する。
- 有効な入力だけから派生値を計算する。
- 文書化したスキーマに従い、欠損を
nullとして表すか項目を省略する。
JSONがNaNを扱えないからといって、欠損をゼロに置き換えてはいけません。水温ゼロ、溶存酸素ゼロ、深度ゼロ、流速ゼロは、いずれも実際にあり得る値です。置き換えた瞬間に、「値がない」という情報が「測った結果ゼロだった」に変わってしまいます。
配列の長さをそろえたプロファイルデータでは、圧力座標を数値だけで持ち、各パラメータの値はnumber | nullにします。一つのパラメータが欠けているからといって圧力の行ごと削除すると、無関係なセンサーの有効な測定値まで消えてしまいます。行とnullを残しておけば、利用する側は必要な値がそろった行を明示的に選べますし、ブラウザは値のある点だけを描画できます。
欠損となった理由にも種類があります。必要に応じて次を区別します。
- センサーでその変数を観測していなかった
- ソースにfill valueが入っていた
- 品質条件にもとづいて値を除外した
- 派生計算に必要な入力がそろわなかった
- 補間の規則にもとづいて意図的に空けた
- 通信量を減らすためにペイロードから省いた
画面上でこの6種類すべてを出し分ける必要はありません。ただし、デバッグや科学的な説明に必要な区別を、パイプライン内で消さないようにします。
QC：採用した値に対応する判定を使う
Argoのプロファイルデータには、変数ごとのQC配列、生の値、補正済みの値が含まれます。Argoデータファイルの公式ガイドでは、PARAM_QC、PARAM_ADJUSTED、データモードを説明しています。
前処理で補正済みの値を採用するなら補正済みの値側のQCを評価し、生の値へ戻すなら生の値側のQCを評価します。また、絞り込みの後も、圧力座標と関連する変数の対応は崩さないようにします。
Web向けペイロードへ元のフラグをすべて入れる必要はありませんが、少なくとも次を記録します。
- 生の値・補正済みの値など、採用した値の種類
- どのQCフラグを許容したかの規則、またはそのバージョン
- その規則を通過したかどうか
- 詳細なフィルタリング文書へのリンクまたは識別子
quality: trueのような曖昧な真偽値よりも、判定結果と規則を一緒に記録する方が適しています。真偽値だけでは、どの規則にもとづく判定なのかを後の開発者が知る手段がありません。
Argoデータの品質管理ガイド：QCフラグと補正済みデータの選び方では、補正済みの値、データモード、フラグ選択を詳しく説明しています。OceanGraphの現在の利用者向け規則はデータフィルタリングポリシー（英語）に記載されています。
識別子と座標：どの値からも元データを特定できるようにする
グラフ上の点から、元の観測値までたどれるようにします。プロファイルデータには、次のような識別情報が役立ちます。
- プラットフォームまたはWMO ID
- サイクル番号とプロファイルの識別子
- タイムゾーンを明記した観測日時
- 座標系を明記した緯度・経度
- ソースファイルまたはアーカイブキー
- 変数と鉛直レベルのインデックス
可能であれば、URLとAPI応答にはデータ更新後も変わらない識別子を使います。「17番目のプロファイル」のような配列上の位置は、絞り込みやデータ更新のたびに変わります。
日時の扱いには特に注意が必要です。UTCのISO 8601など、解釈の余地がない形でシリアライズし、現地時刻への変換は表示のときだけ行います。異なる海域の航海やセンサーをまとめるシステムでは、タイムゾーンのない日時をそのまま処理しないようにします。
経度の表し方も一つに決めます。0〜360と−180〜180が混在すると、観測点が地図の反対側に置かれたり、日付変更線をまたぐ検索が壊れたりします。
来歴：値の生成過程をたどれる情報を記録する
来歴（provenance）とは、その値がどのデータから、どの処理を経て作られたのかの記録です。公開後に人が書き足す説明文ではなく、パイプラインが生成するデータとして扱います。
最低限、次を記録します。
- ソースデータセットと、スナップショットまたは取得日時
- ソースの識別子またはファイルパス
- 処理コードのリビジョン
- 設定とQCポリシーのバージョン
- 派生変数に関わるライブラリやアルゴリズムのバージョン
- 出力データセットのバージョンと生成日時
複数の入力から作る値も、現実的な粒度で入力までたどれるようにします。すべての描画点に巨大な来歴グラフを持たせる必要はなく、プロファイル単位のソース記録で足りる場合もあります。重要なのは、管理の手間に見合う粒度で、画面上の値を作ったデータと処理規則を特定できることです。
Argoは謝辞・引用のガイドを公開しています。サービス全体の来歴ページでデータセットDOIと処理の概要を示し、個々の観測値は選択中のプロファイルから特定できるようにします。
APIデータ仕様の例
次は、前処理を経て採用した水温1点を表すAPI応答の例です。
{
"profile_id": "5904935/0280",
"observed_at": "2022-10-06T11:50:07Z",
"position": { "latitude": 23.935, "longitude": 143.876 },
"vertical": { "value": 1000.0, "unit": "dbar" },
"parameter": "potential_temperature",
"measurement": { "value": 4.18, "unit": "degC" },
"selection": {
"representation": "processed",
"qc_policy": "ocean-profile-policy-v1"
},
"provenance": {
"source_dataset": "Argo",
"source_profile": "5904935 cycle 280",
"output_version": "2026-07-31"
}
}APIのスキーマ文書では、nullを取り得る項目、許容する変数名、精度、そして鉛直座標が実測値か派生値かを定義します。
各点に大きな来歴情報を複製しないようにします。プロファイルに共通する情報は一度だけ宣言し、その下に対応する配列を並べます。意味の重複を避けた構造を基本とし、配信効率のために重複させる場合は意図を明確にします。
補間で観測の空白を消さない
この塩分断面図は、前述のWebアプリ設計記事でも使用した、読み取り専用のOceanGraph Argo処理スナップショットから作成したものです。断面図の描画には、値だけでなく、どこに値があるかを示すマスクも必要です。白い領域は塩分ゼロではないため、観測値と同じように着色してはいけません。
補間値は、観測値と観測値のあいだを推定した値です。Webアプリで使うなら、次を記録します。
- 補間を行う座標軸
- 手法
- 許容する最大間隔、外挿の規則、境界付近の扱い
- 観測値、補間値、欠損値の区別
- 規則のバージョン
利用者へ返すプロファイルデータと、画面に描く図が同じ形である必要はありません。OceanGraphはプロファイルデータの欠損をnullのまま持ち、等間隔の値が必要になった時点で、描画や解析の側が測定点の間を内挿しますが、外挿はしません。こうしておけば、描画のために作った値が測定値として扱われることはありません。
画面の見やすさを保ちながら、欠損の位置と手法の説明を残すことはできます。海洋学の時系列鉛直断面を読み解く：Argoの実例では、この図を読むときに時刻・深度方向のサンプリングが重要になる理由を説明しています。
科学データと表示設定を分ける
ブラウザ側では、色の範囲、選択中の単位、丸めたツールチップの文字列、表示中の深度範囲、レイヤーの表示・非表示といった設定も必要になります。これらは表示のための選択なので、科学データへ書き戻さないようにします。
次の二つに分けて持ちます。
- 科学データ：基準値、単位、座標、欠損状態、QC判断、来歴
- 表示設定：カラーパレット、カラースケールの上下限、丸め、ズーム、絞り込みUI
この二つを分けておけば、表示設定はいつでも元に戻せます。そのため、パレットを変えても値は変わらず、明示的な操作なしにズームが検索条件を変えることもありません。また、ツールチップに表示する値を丸めても、書き出しや比較に使う基準値の精度は保たれます。
処理の各段階で検証する
スキーマ検証で見つけられるのは構造上の問題であるため、値の意味に関する問題を見つけるには、科学的な観点からの検査も必要です。
読み込み時
- 宣言された次元と配列の形が一致している
- 座標と変数の対応が保たれている
- fill valueを欠損として解釈している
- 単位と変数の対応づけが定義済みである
- 生の値・補正済みの値の選択で、対応するQCを使っている
公開時
- 出力に、扱えない
NaNや無限大が含まれていない - すべての公開ファイルが、同一バージョンのデータセットに属している
- 必須の識別子と来歴の項目がそろっている
- 件数、深度範囲、期間がリリース記録と一致している
API応答時
- 応答が、文書化されたスキーマに適合している
- 変数名と単位が許可リストに載っている
- 検索範囲と件数上限が適用されている
- 欠損値がゼロや空文字ではなく
nullのままになっている
ブラウザ表示時
- 軸・ツールチップの単位がペイロードと一致している
- 欠損領域が塗りつぶされずに見える
- 日時、経度、鉛直方向が正しい
- 既知のプロファイルが、パイプライン側で別途描画した図と一致している
画面を複雑にせず制約を伝える
来歴の全項目をツールチップへ入れる必要はありません。情報を表示場所に応じて分けます。
- 値の近くに変数、単位、日時、識別子を置く。
- グラフから、フィルタリング規則や手法の簡潔な説明へリンクする。
- データ専用ページで、ソースと処理の詳細を示す。
- APIまたは配信ファイルのメタデータに、プログラムから読み取れる形で来歴を残す。
OceanGraphでは、データソース（英語）、データフィルタリングポリシー（英語）、制約事項（英語）に説明を分けています。画面の使いやすさを保ちながら、科学的な判断の根拠をいつでも確認できる形にしています。
データ仕様の公開前確認リスト
海洋データを扱うWeb機能を公開する前に、次を確認します。
- 表示するすべての変数を、曖昧さのない名前で区別できるか
- 単位がペイロードにあり、画面にも見えるか
- 必要な場面で、欠損、除外、補間を区別できるか
- 採用した値に対応するQC判断を使っているか
- グラフ上の値がどの観測にもとづくかを、利用者が特定できるか
- 日時を曖昧さなくシリアライズし、経度の表し方を統一しているか
- ソーススナップショット、コード、設定を特定できるか
- 既知の観測値1件が、ソースからブラウザまで一致するか
これらを確認する方法が開発者の記憶や、書かれていない慣習に依存するなら、データ仕様はまだ不完全です。
既存の海洋データアプリへこれらの取り決めを適用することが難しい場合は、下の問い合わせ導線から、設計・実装支援についてもご相談いただけます。
お問い合わせ
構築・実装支援とアノテーション業務
環境構築や設計・実装の支援、アノテーション業務の委託について、ご相談いただけます。
よくある質問
APIは元のQCフラグを返すべきですか？
画面や利用者がその詳細を必要とするなら返します。そうでなければ、採用した値の種類とバージョン付きのポリシー識別子を返し、元のフラグは処理記録に残しておきます。
すべての欠損をnullで表せますか？
多くのグラフ用ペイロードでは十分です。ただし、QCによる除外、未観測、補間の対象外という違いが解釈に影響するなら、理由コードや値の有無を示すマスクも残します。
JSONにはどの程度の精度を残すべきですか？
Webアプリの利用目的に必要な精度を保ち、丸め方を文書化します。表示する桁数を減らしても、保存してある基準値まで繰り返し丸めないようにします。
Gitのコミットハッシュだけで来歴になりますか？
いいえ。コミットだけでは、ソーススナップショット、実行設定、公開した出力のバージョンを特定できないため、来歴の一部にすぎません。
