解析 - Ionworks Studio

解析 (analysis) は、1 つのセル測定から抽出した特徴量を記録するレコードです。例えば、EIS スイープにフィットさせた ECM パラメータ、RPT から導出した LLI/LAM 劣化ポイント、HPPC パルスから計算した DCIR 値などが該当します。各解析は 1 つの親測定に紐づく 1 行と、抽出値を保持する parquet ファイルで構成されます。後処理ステップの出力を、その元となった測定と一緒に永続化しておきたい場合に解析を使用してください。フィッティング、可視化、レポーティングなど、下流のツールが抽出器を再実行することなく後から結果を参照できます。

解析を使うタイミング

派生した表形式の結果に対して、以下のいずれかに該当する場合は解析が適しています:

結果が正確に 1 つの測定（「真実の情報源」となる測定）に属する。
生ファイル添付（ファイル測定）ではなく、構造化された列として保持したい。
時間とともに異なる抽出器から生成される可能性がある — analysis_type は自由形式なので、スキーマ変更なしに新しい種類を追加できます。

代表的な例:

`analysis_type`	抽出元	代表的な列
`ecm_from_eis`	EIS 時系列測定	`R0`、`R1`、`C1` など、単位は `Ohm`、`F`
`lam_lli_from_rpt`	RPT 時系列測定	`LAM_pe`、`LAM_ne`、`LLI`、単位は `%`
`dcir_from_hppc`	HPPC 時系列測定	各 SOC における `dcir_charge`、`dcir_discharge`

analysis_type は自由形式の文字列です — バックエンドは空でない任意の値を受け入れるため、新しい抽出器を追加してもマイグレーションやクライアントリリースは不要です。ecm_from_eis、lam_lli_from_rpt、dcir_from_hppc は、Studio UI がデフォルトで提示する参考リストです。

解析レコードの構成

すべての解析レコードは次のフィールドを持ちます:

フィールド	説明
`measurement_id`	この解析の派生元となる親セル測定の ID。
`name`	ユーザーが指定する解析名。
`analysis_type`	解析の種類（自由形式の文字列、例: `"ecm_from_eis"`）。
`columns`	UI でのヘッダープレビュー用の `{name, unit, dtype?}` 仕様のリスト。
`metadata`	自由形式の JSON オブジェクト — 元となる RPT/サイクルの識別子、抽出器のパラメータ、ソルバー設定など。
`notes`	解析の実施方法に関する自由形式の説明。
`source_pipeline_id`	任意。この解析を生成したパイプラインランの ID。
`source_simple_pipeline_id`	任意。この解析を生成したシンプルパイプラインの ID。
`source_analysis_id`	任意。この解析の計算元となった別の解析の ID。
`source_label`	任意。来歴を示す自由形式のメモ。
`id`、`organization_id`、`created_by`、`created_at`、`updated_at`	サーバー側で自動設定。

1 つの解析で設定できる source_*_id フィールドは 1 つまで です。1 つの解析は、上流の Ionworks レコードを 1 つだけ持つか、まったく持たないかのいずれかです。source_label は独立しており、単独で設定できます。これらのフィールドの使い方については解析のプロベナンスを追跡するを参照してください。表形式の値そのものは、親測定と同じ measurement-data バケットに保存された parquet ファイルに格納されます。ダウンロード用の署名付き URL はオンデマンドで発行されます。解析は Python API クライアントで管理し、client.analysis として公開されています。create() は DataFrame を直接受け取り、クライアント側で parquet にシリアライズしてアップロードします。

解析の作成

from ionworks import Ionworks, AnalysisType
import polars as pl

client = Ionworks()

df = pl.DataFrame({"R0": [0.012], "R1": [0.008], "C1": [1.4]})

analysis = client.analysis.create(
    measurement_id="msmt_abc123",
    name="ECM fit at 25 °C, 50% SOC",
    analysis_type=AnalysisType.ECM_FROM_EIS,  # または文字列 "ecm_from_eis"
    data=df,
    columns=[
        {"name": "R0", "unit": "Ohm"},
        {"name": "R1", "unit": "Ohm"},
        {"name": "C1", "unit": "F"},
    ],
    metadata={"soc_pct": 50, "temperature_degc": 25, "fit_rms": 0.0021},
    notes="Fitted with Randles model, 1e-3 to 1e5 Hz sweep",
)
print(analysis.id)

analysis_type はフリーフォームです。任意の文字列、または AnalysisType StrEnum のメンバー（ECM_FROM_EIS、LAM_LLI_FROM_RPT、DCIR_FROM_HPPC）のいずれかを渡してください。

解析の一覧取得と取得

measurement_id または project_id のいずれか一方を指定します。単一の測定から派生した解析を一覧表示するには measurement_id で、プロジェクト内のすべての測定にまたがる解析を一覧表示するには project_id でフィルタリングします。両方を指定した場合、またはどちらも指定しない場合はエラーになります。

# 単一の測定に紐づくすべての解析
for a in client.analysis.list(measurement_id="msmt_abc123"):
    print(a.id, a.analysis_type, a.name)

# プロジェクト全体の解析（limit の上限は 100）
page = client.analysis.list(project_id="proj_xyz", limit=100, offset=0)
print(page.total)

# 単一の解析レコード
analysis = client.analysis.get("ana_...")

抽出データのダウンロード

parquet ファイルはインラインでは返されません。get_data() は署名付き URL を取得し、parquet を直接読み込んで設定されたバックエンドの DataFrame を返します。

df = client.analysis.get_data("ana_...")
print(df.head())

生の parquet を自分でダウンロードしたい場合は get_download_url() を使用します。署名付き URL の有効期限は 5 分です。

url = client.analysis.get_download_url("ana_...")  # 有効期間は 5 分

メタデータの更新

update() は行レベルのフィールドのみを更新します — parquet は置き換え ません。name、analysis_type、columns、metadata、notes、 source_pipeline_id、source_simple_pipeline_id、source_analysis_id、 source_label の任意のサブセットを指定できます。ソースフィールドについては解析のプロベナンスを追跡するを参照してください。

client.analysis.update("ana_...", {
    "name": "ECM fit at 25 °C, 50% SOC (v2)",
    "metadata": {"soc_pct": 50, "temperature_degc": 25, "fit_rms": 0.0018},
})

parquet 自体を置き換えたい場合は、解析を削除して再作成してください。

解析の削除

行と parquet ファイルを削除します。

client.analysis.delete("ana_...")

Studio で解析を閲覧する

測定の詳細ページには、その測定から派生したすべての解析を一覧表示する 解析 (Analyses) セクションがあります。各項目には解析名、analysis_type、作成日時が表示されます。解析名をクリックすると、解析詳細ページと抽出特徴量テーブルが開きます。

Studio で解析を表示する

すべての解析には Ionworks Studio 上の詳細ページがあり、parquet データをインタラクティブなプロットとして描画するとともに、メタデータ、列、ノートを表示します。親測定の解析一覧から開くか、URL がわかっていれば直接遷移できます。

パンくずリスト

ヘッダーには解析の完全な系譜が表示され、任意の親要素まで遡ることができます: セル仕様 → セルインスタンス → 測定 → 解析 各セグメントはリンクです。何らかの理由で系譜の取得に失敗した場合は、測定への単一リンクにフォールバックし、ページ自体は問題なく表示されます。

データプレビュープロット

右側のパネルには、parquet の 2 つの数値列を互いにプロットします。プロット上部の X 軸 と Y 軸 のドロップダウンで、JavaScript の数値として安全に表現できる値を持つ任意の列の組を選択できます。数値以外の列（文字列、真偽値）と、JavaScript の安全整数範囲を超える整数列（int64 のままとなる大きな ID やタイムスタンプ）は選択できません。

軸ラベルには、解析の columns 仕様で宣言した name [unit] 形式が使われます。create() 時に意味のある unit 値を設定しておいてください。
選択した X 列が単調非減少である場合、トレースは lines+markers として描画され、それ以外の場合は markers のみで描画されます — ECM パラメータスイープのような散布図的な出力に有用です。
初回ロード時、軸は最初の 2 つの数値列にデフォルト設定されます。

行数の上限

プレビューはブラウザーの応答性を保つために上限が設けられています:

テーブルは parquet の最初の 100 行 を表示します。
プロットは最大でも最初の 10,000 行 をマテリアライズします。
プロット下のキャプションには実際の行数が表示され、ファイルがプロットの上限を超える場合はプロットが切り詰められている旨が示されます。

データセット全体を扱いたい場合は、ヘッダーの Download parquet ボタン（毎回新しい署名付き URL を発行します）を使うか、Python からデータを取得してください:

df = client.analysis.get_data("ana_...")

元の測定へのリンク

左カラムの View source measurement ボタンからは、親測定の詳細ビューへ直接遷移できます — パンくずリストの測定セグメントと同じリンク先です。このクロスリンクにより、フィットした ECM パラメータや劣化ポイントを抽出元の測定まで簡単にたどることができ、どの測定にすでに解析が付随しているかを一目で把握できます。

解析のプロベナンスを追跡する

解析の measurement_id は、その解析がどの測定から抽出されたかを示します。source_* フィールドはそれとは別の問いに答えます: どの計算処理がその解析を生成したか? — パイプランラン、シンプルパイプライン、または連鎖元となった別の解析、加えて Ionworks 上のリンク可能なレコードではないプロベナンスのための自由形式の source_label です。

フィールド	説明
`source_pipeline_id`	この解析を出力したパイプラインラン。
`source_simple_pipeline_id`	この解析を生成したシンプルパイプライン。
`source_analysis_id`	この解析の計算元となった上流の解析。
`source_label`	自由形式のメモ（例: `"より厳しい制約で ECM を再フィット"`）。

1 つの解析で設定できる source_*_id フィールドは 1 つまでであり、参照される行が存在しない場合、リクエストは拒否されます。ただしこのチェックは行の存在のみを確認し、あなたがその行を閲覧できるかどうかは検証しません — そのため、あなたからは通常見えないレコードの ID をソースとして設定すること自体は成功し、後でリンクを辿ろうとしたときにのみ未解決として表示されます。source_label は独立しており、ソースが別の Ionworks レコードでない場合は単独で設定してください。作成時に設定するには、解析を作成した後に client.analysis.update() に渡すか、REST API を直接使う場合は POST /analyses の Form(...) フィールドとして含めます:

analysis = client.analysis.create(
    measurement_id="msmt_abc123",
    name="ECM fit at 25 °C, 50% SOC",
    analysis_type="ecm_from_eis",
    data=df,
    columns=[{"name": "R0", "unit": "Ohm"}],
)

# どのパイプラインで生成されたかを記録する
client.analysis.update(analysis.id, {
    "source_pipeline_id": "pipe_xyz789",
    "source_label": "より厳しい制約で ECM を再フィット",
})

Studio では、解析の詳細ページに既存の「View source measurement」ボタンと並んで Source 行が表示されます。ソースが、あなたがアクセスできるパイプラインまたは別の解析に解決される場合、ラベルはその詳細ページへのリンクになります。材料ページのデータセットも同じモデルを使用しているため、Studio から離れることなく、カーブ → それを生成したフィット → そのフィットの元となった解析、と辿ることができます。

解析 vs. ファイル測定

いずれも測定にデータを紐づけますが、用途が異なります:

	解析	ファイル測定
親	1 つのセル測定	セルインスタンスに直接
データ形式	列と単位が宣言された parquet 表	任意のファイル（画像、PDF、numpy 配列）
用途	抽出された特徴量、フィットパラメータ、劣化ポイント	SEM 写真、X 線 CT、解体解析ドキュメント

既存の測定から派生した構造化された表形式データが出力である場合は解析を、セル自体に紐づく独立したアーティファクトが対象の場合はファイル測定を選択してください。

次のステップ

測定

時系列、プロパティ、ファイルの各測定タイプ — すべての解析の親となります。

データの読み取り

測定とその解析を一覧表示・フィルター・取得します。

はじめに

クイックスタート

基本コンセプト

運用

データ

モデル構築

パイプライン

シミュレーション

最適化

解析

解析を使うタイミング

解析レコードの構成

解析の作成

解析の一覧取得と取得

抽出データのダウンロード

メタデータの更新

解析の削除

Studio で解析を閲覧する

Studio で解析を表示する

パンくずリスト

データプレビュープロット

行数の上限

元の測定へのリンク

解析のプロベナンスを追跡する

解析 vs. ファイル測定

次のステップ

測定

データの読み取り

​解析を使うタイミング

​解析レコードの構成

​解析の作成

​解析の一覧取得と取得

​抽出データのダウンロード

​メタデータの更新

​解析の削除

​Studio で解析を閲覧する

​Studio で解析を表示する

​パンくずリスト

​データプレビュープロット

​行数の上限

​元の測定へのリンク

​解析のプロベナンスを追跡する

​解析 vs. ファイル測定

​次のステップ

測定

データの読み取り

解析を使うタイミング

解析レコードの構成

解析の作成

解析の一覧取得と取得

抽出データのダウンロード

メタデータの更新

解析の削除

Studio で解析を閲覧する

Studio で解析を表示する

パンくずリスト

データプレビュープロット

行数の上限

元の測定へのリンク

解析のプロベナンスを追跡する

解析 vs. ファイル測定

次のステップ