Claudeで曲線フィッティングと残差確認を行う手順 — モデル式は人が決める

測定データへの曲線フィッティングは、Claude APIのコード実行ツールで回せます。CSVをアップロードし、モデル式と初期値を指定すれば、パラメータ推定値と残差プロットがサンドボックスの中で出てきます。

ただし、どの式を当てるかを決めるのは実験者です。Claudeに任せるのは「指定した式を当てて、数値と図を出す」ところまでにします。残差の形から式の妥当性を読む作業と、推定値を報告に使うかどうかの判断は、人の側に残します。

コード実行ツールにフィッティングを任せられる範囲

コード実行ツールとは、Claudeがサンドボックス化されたコンテナでBashコマンドとファイル操作を実行できるサーバーサイドのツールです。PythonとBashがここで動き、実行はAPIが代行します。自分で実行結果をtool_resultとして返す必要はありません。

曲線フィッティングで効くのは、プリインストールされたライブラリです。

• データ処理と統計: pandas、numpy、scipy、scikit-learn、statsmodels
• 作図: matplotlib、seaborn
• 数式処理: sympy、mpmath

scipy.optimize.curve_fitもmatplotlibも、追加インストールなしで使えます。コンテナにはインターネット接続がなく、実行時に別のパッケージを入れることはできません。lmfitのようなライブラリを使いたい場合は、このツールでは前提にできません。

実行環境の制約も先に押さえておきます。

時間の上限もあります。1回のツール呼び出しが最大実行時間を超えるとexecution_time_exceededエラーが返ります。プログラム的ツール呼び出し(programmatic tool calling)を使う場合は、REPLのセルごとに90秒の壁時計制限が掛かります。長い反復計算を1回の呼び出しに詰め込むと、この上限に当たりえます。

CSVを渡してフィッティングを走らせる

手順は3つです。Files APIでCSVをアップロードし、メッセージにcontainer_uploadブロックで参照し、コード実行ツールをtoolsに入れます。

Pythonのコードは次のとおりです。公式の「Upload and analyze files」の例をフィッティング用に組み替えた形です。

import anthropic
from pathlib import Path
 
client = anthropic.Anthropic()
file_object = client.files.upload(file=Path("data.csv"))
 
prompt = """添付の data.csv(列: t, y, sigma)に、
y = a * exp(-k * t) + c を scipy.optimize.curve_fit で当ててください。
初期値は p0=[2.0, 0.5, 0.1]、sigma は y の標準偏差として
absolute_sigma=True を指定します。
推定値と標準誤差、残差プロット、pcov の条件数を出してください。"""
 
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": prompt},
            {"type": "container_upload", "file_id": file_object.id},
        ],
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.to_json())

アップロードできる形式にはCSV、Excel(.xlsx / .xls)、JSON、XML、画像、テキストファイルが含まれます。測定器がExcelで吐くデータもそのまま渡せます。

プロンプトで人が決める項目を固定する

曲線フィッティングは、式・初期値・誤差の扱いを変えるだけで推定値が動きます。Claudeに「いい感じに当てて」と頼むと、これらをClaudeが選びます。実験者が決めるべき項目を、プロンプトに書いて固定します。

誤差の扱いは特に差が出ます。curve_fitのabsolute_sigmaがFalse(既定)のとき、sigmaは相対的な大きさだけが意味を持ちます。共分散行列pcovは、カイ二乗が自由度と釣り合うようにsigma全体を定数倍した前提で計算されます。測定器の仕様から標準偏差が分かっているならTrueを指定し、pcovにその絶対値を反映させます。

どちらを選んだかは、出力された標準誤差の意味を左右します。プロンプトに書かずに任せると、Claudeがどちらで計算したかを、後から追わなければなりません。

返ってきた結果を実験者が検証する

出力で見るのは、推定値の表より先に残差です。

curve_fitのドキュメントは、モデル式が過剰にパラメータを持つと、共分散行列が信頼できなくなると述べています。簡易な確認方法として、np.linalg.cond(pcov)で条件数を計算する方法が載っています。プロンプトで条件数を出させておくと、この確認が毎回の出力に組み込まれます。

また、pcovは式のパラメータ付近の線形近似にもとづいて導かれます。この近似が当てはまらない場合、標準誤差は不確かさの良い指標にならないことがあります。信頼区間を厳密に求めたいときは、ブートストラップなどの別の手法を人が選んで指示します。

Claudeの数値を手元で再計算する

コード実行は、Claudeが書いたコードの出力を返します。数値が正しいかどうかは、別の経路で確かめます。確実なのは、Claudeに「実行したPythonコードの全文を出力して」と頼み、そのコードを手元の環境で動かすことです。

手元で動かして比べるコードの例は次のとおりです。式や引数が、依頼したものと一致しているかが分かります。

import numpy as np
import pandas as pd
from scipy.optimize import curve_fit
 
df = pd.read_csv("data.csv")
 
def model(t, a, k, c):
    return a * np.exp(-k * t) + c
 
popt, pcov = curve_fit(
    model, df["t"], df["y"],
    p0=[2.0, 0.5, 0.1],
    sigma=df["sigma"], absolute_sigma=True,
)
perr = np.sqrt(np.diag(pcov))
resid = df["y"] - model(df["t"], *popt)
chi2 = np.sum((resid / df["sigma"]) ** 2)
dof = len(df) - len(popt)
 
print("popt:", popt)
print("perr:", perr)
print("chi2/dof:", chi2 / dof)
print("cond(pcov):", np.linalg.cond(pcov))

chi2/dofが1から大きく外れる場合は、式か、sigmaの見積もりのどちらかに問題があります。どちらが原因かは、残差プロットの形と合わせて判断します。出力されたpoptが手元の値と小数点以下で食い違うときは、scipyのバージョン差か、Claudeが依頼と異なる引数を使っています。コード全文を見れば切り分けられます。

数値の突き合わせの考え方は、論文の統計値を生データと照合する手順と共通です。Claudeの出力を信じる前に、同じ入力から自分で再計算します。

残差プロットをファイルで受け取る

残差プロットは画像ファイルとして受け取るのが便利です。ただし、ファイルが返ってくるには条件があります。bashコマンドの実行ごとに、空の$OUTPUT_DIRディレクトリが作られます。コマンド終了時にその直下にあるファイルだけが取得され、結果のcontentリストにfile_idとして入ります。

別の場所に書いたファイルはコンテナに残るだけで、返ってきません。依頼文には、次のように書き足します。

python /tmp/fit.py && cp /tmp/residuals.png "$OUTPUT_DIR/" \
  && ls "$OUTPUT_DIR"

lsを同じコマンドに入れておくと、取得対象に入ったかどうかが出力で確認できます。Claude自身はcontentリストを見ません。ファイルが消える理由と対処は、$OUTPUT_DIRの罠に詳しくあります。

受け取ったfile_idは、Files APIのclient.files.download()で取得します。コード実行が作ったファイルは、明示的に削除するまで残ります。

失敗したときと費用の目安

エラーは、結果のerror_codeで見分けます。

curve_fitが収束しないときは、Python側のエラーになります。ドキュメントによれば、最小二乗の最小化に失敗するとRuntimeErrorが出ます。共分散が推定できないときはOptimizeWarningです。この2つはstderrに出るので、依頼文に「警告も含めて出力をそのまま報告して」と書いておきます。収束しないときは、p0を見直すか、method='trf'とboundsの組み合わせを試す判断も人が行います。

費用は、web_search_20260209やweb_fetch_20260209以降を同じリクエストに入れない場合、実行時間で課金されます。1組織あたり月1,550時間までは無料で、超過分はコンテナ1つにつき1時間0.05ドルです。実行時間の最小は5分で、ファイルをリクエストに含めると、ツールを呼ばなくても課金対象になります。ファイルがコンテナに事前配置されるためです。条件の詳細はコード実行ツールが無料になる条件で整理しています。

同じコンテナで式を変えて再依頼する

式を変えて当て直すたびにCSVを再アップロードする必要はありません。前のレスポンスのコンテナIDを次のリクエストに渡すと、作成済みのファイルが残った状態で続けられます。code_execution_20260120以降とプログラム的ツール呼び出しを併用すれば、Pythonインタープリターの変数も保持されます。

コンテナは、約5分操作がないとチェックポイントされ、作成から30日以内ならそのIDで復元できます。30日を過ぎたコンテナを参照するとエラーになるため、containerパラメーターなしで再送します。測定の再解析が数週間後になる場合は、コンテナではなく、手元に保存したdata.csvとコード全文が頼りになります。

計算の自動化と判断の分担

測定データの解析は、数値を出すところと意味を読むところに分かれます。コード実行は前者を速くします。後者は、実験条件を知っている人にしかできません。

分担の早見表は次のとおりです。

数値を再計算で確かめる、という点では、コード実行で拘束時間の判定を検算する手順も同じ型です。ルールや式は人が与え、Claudeには計算を任せる構成になっています。