uncertainty-and-units

不確かさと単位

対象範囲

計算に物理単位が含まれる場合、または報告する数値に不確かさが必要な場合は、常にこのスキルを使用してください。具体的には、次のような場合です。

• 単位間の変換。波長から光子エネルギー、質量から物質量、エネルギーから温度など、物理的な文脈が必要な変換も含みます。
• 相関のある入力を含む場合と含まない場合の、測定モデルを通じた不確かさの伝播。
• 校正証明書、仕様、繰り返し性データに基づくGUM不確かさ予算の作成。
• 包含係数の選択と、k = 2 が妥当かどうかの判断。
• 結果を四捨五入して記述し、読者に ± の意味が伝わるようにすること。
• 相関を捨てずに、曲線フィットからパラメーターの不確かさを取り出すこと。
• 既存の解析コードを確認し、気づかれにくい単位や不確かさの欠陥を見つけること。
• 次元的に整合する答えが物理的にも可能かどうかを確認すること。すなわち、桁の大きさ、無次元群、それらが示す条件を確認します。

このスキルは、計量学とそれを実装する2つのライブラリを対象とします。統計的推論、モデル選択、研究計画は対象外です。statistical-analysis、statistical-power、experimental-design を参照してください。

最新リリースとインストール

2026-07-26 確認済み：

• pint 0.25.3、2026-03-19 リリース。Python 3.11 以降が必要です。
• uncertainties 3.2.3、2025-04-21 リリース。Python 3.8 以降が必要です。
• NumPy 2.5.1 と SciPy 1.18.0。どちらも Python 3.12 以降が必要です。
• SciPy 1.18.0 の scipy.constants は CODATA 2022 を使用します。SciPy 1.11 以前は CODATA 2018 を使用しており、推奨値のいくつかは両者で異なります。

uv venv --python 3.13
source .venv/bin/activate
uv pip install "pint==0.25.3" "uncertainties==3.2.3" "numpy==2.5.1" "scipy==1.18.0"

pint-pandas と pint-xarray は、単位対応の列や配列を追加するもので、別途インストールが必要です。

必ず守る作業手順

1. 入力時に単位を付け、出力時にのみ単位を取り除きます。 関数の境界で ureg.wraps または m_as("unit") を使って変換し、計算の途中では決して変換しません。
2. 計算の前に測定モデルを明示的に記述します。 推定値がゼロの補正も含めてください。モデルから補正を省くと、その不確かさも予算から漏れます。
3. すべての入力に次の4項目を指定します。 推定値、標準不確かさ、不確かさの根拠となる分布、自由度です。
4. Type Bの記述は適切な除数で換算します。 証明書に記載された拡張不確かさは記載の k で割り、矩形分布の限界値は sqrt(3) で割ります。
5. 合成する前に相関を特定します。 同じ標準器に対して校正された入力、同じ計器で測定された入力、同じフィットから得られた入力には相関があります。
6. 感度係数を計算し、生の不確かさではなく c_i * u(x_i) に基づいて予算を確認します。
7. 線形化が妥当か確認します。 GUMフレームワークと並行してモンテカルロ法を実行し、JCGM 101の条項8に基づく比較を適用します。比較に失敗した場合は、モンテカルロ法の結果を報告します。
8. 慣例ではなく、有効自由度から k を選びます。
9. まず不確かさを丸め、その後、同じ小数位まで値を丸めます。
10. ± が何を表すかを明記します。 標準不確かさか拡張不確かさか、k、包含確率、手法を記載します。
11. 報告前に値の大きさが妥当か確認します。 次元的に整合する結果でも、物理的に不可能な場合があります。既知のスケールまたは無次元群と比較し、その条件でも依拠したすべての仮定が成り立つことを確認してください。

このスキルで防ぐべき誤り

以下はいずれもエラーを起こさず、もっともらしい数値を返します。

不明なスケールで単位を取り除く

length = (12.7 * ureg.mm).magnitude          # 12.7 -- of what?
length = (12.7 * ureg.mm).m_as("m")          # 0.0127 metres, stated

.magnitude は、その量がたまたま保持している単位での値を返します。値を取り出すたびに、その時点で単位を指定してください。

オフセット温度の計算

Q(20, "degC") + Q(5, "degC")     # OffsetUnitCalculusError -- correctly refused
Q(20, "degC") + Q(5, "delta_degC")   # 25 degree_Celsius
Q(25, "degC") - Q(20, "degC")        # 5 delta_degree_Celsius

摂氏と華氏は間隔尺度です。温度の不確かさは常に差であり、delta_ 単位を使います。20 ± 0.5 degC を華氏に変換すると、68 degF ± 0.9 delta_degF となります。この1行では、異なる2種類の変換を行っています。

掛け算で加算できる対数単位

Q(10, "dBm") + Q(10, "dBm")   # 0.0001 kilogram**2 * meter**4 / second**6

これは 20 mW でも 13 dBm でもなく、10 mW × 10 mW です。べき乗は行いません。計算を行う前に、線形単位に変換してください。

往復変換で失われる相関

x = ufloat(1.0, 0.1)
x - x                                     # 0.0+/-0
x - ufloat(x.nominal_value, x.std_dev)    # 0.00+/-0.14

公称値と標準偏差から変数を再構築すると、独立した変数になります。2つの浮動小数点数を経由するシリアライズでも同じことが起こります。相関した集合を再構築するには、correlated_values(values, covariance_matrix) を使用してください。

共分散行列が気づかれないまま再スケーリングされる

popt, pcov = curve_fit(f, x, y, sigma=sigma)                        # default
popt, pcov = curve_fit(f, x, y, sigma=sigma, absolute_sigma=True)

デフォルトでは pcov が縮約カイ二乗で再スケーリングされるため、パラメーターの不確かさに適合度が反映され、sigma を指定しない場合と同じ結果になります。合成した直線フィットの例では、2つの結果は [0.0364, 0.2154] と [0.0477, 0.2820] となり、31% の差があります。sigma に実際の標準不確かさを指定する場合は、必ず absolute_sigma=True を渡してください。

確認されていない線形化

x = 1.0 ± 0.5 に対する y = x² では、GUM フレームワークによると、y = 1.0、u_c = 1.0、95% 区間は [-0.96, 2.96] です。二乗値であるにもかかわらず、区間の大部分が負です。モンテカルロ法では、平均値は 1.25、u_c は 1.06、最短の 95% 区間は [0, 3.32] となります。線形伝播ライブラリを使っても、このようなことが起きたとは分かりません。

同梱のローカル CLI

すべてのヘルパーはオフラインで動作し、URL とシンボリックリンクを拒否し、入力に上限を設け、プライベートな権限で出力をアトミックに書き込み、--force を指定しない限り上書きを拒否します。

python skills/uncertainty-and-units/scripts/propagate_uncertainty.py --help
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --help
python skills/uncertainty-and-units/scripts/format_result.py --help
python skills/uncertainty-and-units/scripts/convert_units.py --help
python skills/uncertainty-and-units/scripts/audit_units.py --help
python skills/uncertainty-and-units/scripts/check_plausibility.py --help

propagate_uncertainty.py

同じモデルに対して両方の伝播方法を実行し、JCGM 101 第8条の検証テストを適用します。

python skills/uncertainty-and-units/scripts/propagate_uncertainty.py \
  --expression "m / (pi * (d / 2) ** 2 * h)" \
  --variable "m=250.0,0.05" \
  --variable "d=20.0,0.02,rectangular" \
  --variable "h=40.0,0.05,rectangular" \
  --measurand density --unit "g/cm3" --format markdown

各 --variable は name=value,standard_uncertainty[,distribution[,dof]] の形式です。分布には normal、rectangular、triangular、arcsine、exact を指定でき、モンテカルロサンプリングにのみ使用されます。相関は --correlation "a,b=0.9" で指定します。長期的に使用するモデルには、同じ内容を記述した JSON の --spec ファイルを使用できます。

式は抽象構文木として解析され、+ - * / ** と固定リストの関数を明示的に走査して簡約されます。コンパイルも実行もされません。

レポートには、推定値、u_c、感度係数、パーセント表示の予算、有効自由度、k、U、両方のモンテカルロ包含区間、および線形化した結果を報告できるかどうかの判定が表示されます。

uncertainty_budget.py

証明書やデータシートで使われる形式で示された成分を組み合わせます。

python skills/uncertainty-and-units/scripts/uncertainty_budget.py --template > budget.json
python skills/uncertainty-and-units/scripts/uncertainty_budget.py --spec budget.json --format markdown

各成分では、除数を決める distribution を指定します。expanded は coverage_factor、rectangular は sqrt(3)、triangular は sqrt(6)、arcsine は sqrt(2)、normal は 1 で除算します。さらに、任意で sensitivity、dof、relative: true を指定できます。このツールは u_c、Welch-Satterthwaite の有効自由度、t 分布から求めた k、U を計算します。また、タイプ A の成分に自由度が指定されていない場合、nu_eff が小さく k = 2 が不適切な場合、1つの成分が支配的な場合、タイプ B の成分に指定された normal が除数未適用の拡張不確かさである可能性が高い場合に警告します。

format_result.py

python skills/uncertainty-and-units/scripts/format_result.py \
  --value 12.34567 --uncertainty 0.02345 --unit mm \
  --coverage-factor 2.26 --coverage-probability 0.95

12.346 ± 0.023 mm、12.346(23) mm、科学表記と LaTeX 形式、および数値に添える必要がある文を返します。不確かさが 1 または 2 で始まるのに有効数字を1桁に指定した場合や、不確かさが推定値を上回る場合は警告します。

convert_units.py

python skills/uncertainty-and-units/scripts/convert_units.py \
  --value 532 --unit nm --to eV --context spectroscopy --uncertainty 0.5

python skills/uncertainty-and-units/scripts/convert_units.py \
  --value 1.0 --unit g --to mol --context chemistry --context-parameter "mw=180.156 g/mol"

変換時の局所導関数を使って不確かさを引き継ぎます。コンテキスト変換は比例ではなく逆数の関係になるため、これは重要です。変換にコンテキストが必要な場合は、エラーメッセージにその名前を表示し、オフセット単位と対数単位にはフラグを付けます。--list-contexts を使うと、レジストリで定義されている内容を確認できます。

audit_units.py

既存の解析コードを静的にレビューします。解析は行いますが、インポートも実行もしません。

python skills/uncertainty-and-units/scripts/audit_units.py \
  --input analysis.py --format markdown --fail-on medium

ルール	重大度	検出内容
UNIT001	中	1 つのモジュールに 2 つ目の UnitRegistry がある — レジストリ間の ValueError
UNIT002	中	オフセット温度単位がある一方で、delta_ 単位がどこにもない
UNIT003	高	先行する .to(...) または .m_as(...) のない .magnitude
UNIT004	中	+ が乗算になる対数単位
UNC001	高	absolute_sigma のない curve_fit
UNC002	中	ddof のない np.std／np.var
UNC003	中	uncertainties を使用するモジュール内の math または numpy の関数
UNC004	高	.nominal_value と .std_dev から再構築された ufloat
CONST001	低	CODATA 定数との差が 0.1% 以内のリテラル

検出結果が --fail-on（デフォルトは high）を満たすと、終了ステータスは 1 になります。これにより、pre-commit または CI のチェックとして使用できます。

ルールはヒューリスティックであるため、誤検出はディレクティブコメントで抑制できます。コメントを検出箇所の行末に置くとその行を、単独の行に置くと次の行を対象にします。

value = quantity.magnitude  # audit-units: ignore UNIT003 -- already converted upstream

# audit-units: ignore UNC003 -- the argument here is a plain float array
scaled = np.log10(counts)

# audit-units: ignore-file CONST001 はモジュール全体を対象とし、ルール名を指定しない場合はすべてのルールを抑制します。抑制は非表示にされず、レポートに集計されるため、すべての検出を無効にしたファイルもその旨が示されます。

check_plausibility.py

次元の整合性は、物理的にあり得ることを意味しません。幅 2 m のセルも、毛細管内のレイノルズ数 4e7 も、すべての単位チェックに合格します。このツールは、無次元群、特性スケール、厳選された大きさの範囲を用いて、一連の物理量を検証し、数値を報告する前に各式の次元を確認します。

python skills/uncertainty-and-units/scripts/check_plausibility.py \
  --quantity "density=1060 kg/m**3" --quantity "velocity=0.5 mm/s" \
  --quantity "length=8 um" --quantity "viscosity=3.5 mPa*s" \
  --group reynolds --format markdown
# Re = 0.001211 -- laminar (circular pipe, length = diameter)

python skills/uncertainty-and-units/scripts/check_plausibility.py \
  --quantity "diameter=2 m" --band "eukaryotic_cell_diameter=diameter"
# implausible: 4.3 decades outside the 5-100 um range

--group は 14 個の無次元群のいずれかを評価し、システムがどの状態領域にあるかを示します。--scale は拡散時間、デバイ長、ストークス沈降速度などの特性スケールを計算します。--band は指定された物理量を観測範囲と比較します。--list は、各式に必要な入力値とともにカタログ全体を出力します。

物理定数（k_B、N_A、R_gas、g_earth など）は、指定しなくてもすべての式で利用でき、リテラルとして記述するのではなく実行時に scipy.constants から読み込まれるため、SciPy に同梱される CODATA リリースに追従します。

重要なのは次元チェックです。動粘度を必要とする式に、動粘性ではなく粘性係数を渡した場合 — どちらも「粘度」と呼ばれ、どちらも水の物性値として表に載っていて、ρ 倍異なります — は、数値を計算する前に拒否されます。

error: viscosity must have dimensionality [mass] / ([length] * [time]),
       but m²/s is [length] ** 2 / [time]

判定結果が --fail-on（デフォルトは implausible）を満たすと、終了ステータスは 1 になります（範囲から 1 桁以内の値は questionable です）。しきい値は境界が厳密でない慣例であり、相関式のフィッティングに用いられた形状を前提とします。それぞれの場合に使用する特性長については、references/plausibility-scales.md を参照してください。

伝播方法の選択

状況	方法
線形またはほぼ線形のモデル、入力値がおおむね正規分布、大きな自由度	GUM フレームワークのみ
入力値の ±2u の範囲で非線形性がある	両方を実行し、8 項のテストを適用
いずれかの入力値の相対不確かさが約 20% を超える	モンテカルロ
長方形分布、またはそれ以外の非正規分布の成分が支配的	モンテカルロ
出力に下限がある（分散、濃度、二乗量）	モンテカルロ
出力分布が非対称	モンテカルロ、最短の包含区間
相関のある入力値	どちらでもよいが、標準不確かさだけでなく共分散行列を指定

長方形分布の寄与が支配的なモデルは、完全に線形であっても 8 項のテストに合格しません。フレームワークの k = 1.96 では、ほぼ台形の出力に対して過剰な包含範囲となるためです。推定値と u_c は依然として正しく、区間だけが広すぎます。

定数

定数を記憶だけで入力しないでください。2019年のSI再定義により、c、h、e、k、 およびN_Aは厳密に定義され、相対標準不確かさはゼロです。それ以外はすべて CODATAの改訂ごとに変動する測定値です。

import scipy.constants as constants

constants.value("electron mass")        # 9.1093837139e-31
constants.unit("electron mass")         # kg
constants.precision("electron mass")    # 3.07e-10, relative standard uncertainty
constants.precision("Planck constant")  # 0.0, exact by definition

precisionは相対標準不確かさを返します。絶対標準不確かさを得るには、値を掛けてください。

参考ファイル

• references/gum-methodology.md — タイプA評価とタイプB評価、分布の除数、 伝播則、ウェルチ・サタスウェイト法、フレームワークが適用できない場合、モンテカルロ 手順、および第8条の検証テスト。
• references/pint-recipes.md — レジストリ、オフセット単位と対数単位、コンテキスト、 wrapsとcheckによる境界の適用、NumPyとの相互運用、カスタム単位、 書式指定。
• references/uncertainties-recipes.md — 変数の同一性と相関、 correlated_values、umathとunumpy、書式指定、フィット共分散行列、および パッケージの制限。
• references/domain-conversions.md — エネルギー階層、分光法、濃度、 圧力、放射線と磁気、質量分析、対数量、および次元は同じでも意味が異なる量の 組み合わせ。
• references/reporting-rules.md — 丸め、表記法、結果に必ず添える文、 図におけるSD、SEM、CIの使い分け、不検出、および適合性判定ルール。
• references/plausibility-scales.md — 特性長の選び方、各無次元数が制約する モデリング上の仮定、特性スケール、観測された大きさの範囲とその出典、および すべてのしきい値に関する注意事項。

日付付きの情報源

2026-07-26に確認：

• JCGM 100:2008、測定データの評価 — 測定における不確かさの表現ガイド
• JCGM 101:2008、補足1 — モンテカルロ法による分布の伝播
• NIST Technical Note 1297
• CODATA国際推奨値
• PyPIのPint — 0.25.3、リリース日2026-03-19。
• Pintのドキュメント。非乗法単位 およびコンテキストを含みます。
• PyPIのuncertainties — 3.2.3、リリース日 2025-04-21。
• uncertaintiesのドキュメント
• scipy.constantsのリファレンス

関連スキル

• astropy：単位・物理量、座標、FITS I/O、表形式データなど、Astropy APIを必要とする天文学・天体物理学のワークフロー向けのPythonコアライブラリ。