解析 - 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`	解析の実施方法に関する自由形式の説明。
`id`、`organization_id`、`created_by`、`created_at`、`updated_at`	サーバー側で自動設定。

表形式の値そのものは、親測定と同じ 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 の任意のサブセットを指定できます。

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_...")

解析 vs. ファイル測定

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

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

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

次のステップ

測定

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

データの読み取り

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

はじめに

基本コンセプト

データ

モデル構築

パイプライン

シミュレーション

最適化

解析

解析を使うタイミング

解析レコードの構成

解析の作成

解析の一覧取得と取得

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

メタデータの更新

解析の削除

解析 vs. ファイル測定

次のステップ

測定

データの読み取り

​解析を使うタイミング

​解析レコードの構成

​解析の作成

​解析の一覧取得と取得

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

​メタデータの更新

​解析の削除

​解析 vs. ファイル測定

​次のステップ

測定

データの読み取り

解析を使うタイミング

解析レコードの構成

解析の作成

解析の一覧取得と取得

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

メタデータの更新

解析の削除

解析 vs. ファイル測定

次のステップ