材料とプロパティデータセット

材料とは

材料 (Material) は、セル仕様で使用される物理材料を記述する再利用可能なレコードです。例えば、NMC811 正極粉末、グラファイト負極、LP57 電解液などです。材料と、それをラップするセルコンポーネント（負極、正極、電解液、セパレータ、ケース）は、常にプロジェクトにスコープされます。すべての材料とコンポーネントはちょうど 1 つのプロジェクトに属し、セル仕様は自プロジェクト内の材料とコンポーネントのみを参照します。同じ組織内の 2 つのプロジェクトは、名前、製造元、製品 ID がまったく同じ「同一の」材料であっても、それぞれ独自のコピーを保持します。これにより、プロパティデータセットとセルからの参照はプロジェクトごとにきれいに分離されます。同じ材料を別のプロジェクトでも使いたい場合は、そのプロジェクトに一致する材料を新しく作成することになります。

プロジェクトごとのスコープが導入される前から存在していた古い材料は、すべてプロジェクトごとのコピーに分割されました。また、共有の「System」材料ライブラリ（Graphite、NMC、LFP など）はセル仕様の作成時に直接参照されなくなり、代わりにライブラリ定義があなた自身のプロジェクトにクローンされます。アプリのどこにもプロジェクトをまたがる材料共有は存在しません。

材料の一覧取得・作成には project_id が必須ですが、ID を指定した単一の材料の取得・更新・削除は組織単位で認可されます — その組織内の材料にアクセスできるプロジェクトメンバーであれば、別のプロジェクトに属する材料であっても ID を指定して参照・変更できます。

各材料には任意の数の プロパティデータセット を添付できます。プロパティデータセットは、1 つ以上の物理プロパティを 1 つ以上の独立変数の関数として表す表形式の測定（CSV または parquet）です。例えば、電解質導電率対濃度や、負極 OCP 対化学量論などです。プロパティデータセットは親材料と同じプロジェクトに属します。

プロパティデータセットはデータとして保存されます。ルックアップテーブルをパラメータ化モデルに直接埋め込むパラメータ補間子とは別物です。プロパティデータセットを使って生の測定を整理・共有し、シミュレーションで使用する準備ができたら補間子に変換してください。

材料の使いどころ

材料は次のような場合に使用します:

複数のセル（例: 複数のセル構成における同じ電解液）にまたがって使用される材料のプロパティに関する単一の信頼できる情報源を維持したい。
測定された材料と並べて、生の測定（OCP、拡散係数、導電率、輸率、…）を保存したい。
同じプロパティの複数のデータセットを比較したい — 例えば、異なる温度や異なる研究室で測定された OCP カーブ。
来歴を追跡したい: 誰が、いつ、どの生ファイルからデータセットをアップロードしたか。

UI で材料を管理する

各プロジェクトには左側のナビゲーションに Materials セクションがあります。そこで次のことが可能です:

材料を作成する — 名前を付け、任意で製造元と製品 ID を指定します。
材料を開く — プロパティデータセットとメタデータを表示します。
行アクションメニューから材料を 編集または削除 します。

セル仕様エディタから作成された材料は、そのセル仕様のプロジェクトを引き継ぎます。そのため、通常はプロジェクトを明示的に選ぶ必要はなく、材料はそれを使用するセルと同じプロジェクトに作成されます。

プロパティデータセットのアップロード

材料の詳細ページから Upload property dataset をクリックして:

ファイルを選択する — CSV または parquet。CSV はヘッダー行を含むことも省略することもできます。ファイルを選択するとデータセット名はファイル名から自動入力されます。別の名前にしたい場合は編集してください。
データセット名を確認する — ステップ 1 でファイル名から自動入力されます。別の名前にしたい場合は変更してください（例: Conductivity at 25 °C）。
列を宣言する — ファイル内で検出されたすべての列が順番に表示されます。各列について次を提供します:
- Name — 処理済みデータセットに格納される表示名（例: c_e）。送信前に表示されているすべての列に名前を付ける必要があります。インポートしたくない列はその行を削除するか、名前を付けて後で無視してください。末尾の空の列（Excel の「末尾のカンマ」アーティファクトでよくあります）は自動的にトリムされます。
- Unit — 物理単位（例: mol/L、S/m）。無次元量の場合は空白のままにします。
- Source column — 値の取得元となるアップロードファイル内の列。ヘッダーなし CSV では位置です。ヘッダー付きのファイルでは名前で選択できます。
送信。 ファイルが解析され、すべての値が浮動小数点数に強制変換され（数値でないセルは NaN になります）、処理済み parquet と元の生ファイルの両方が保存されます。

アップロード後、データセットは材料のプロパティリストに、行数と列ごとの NaN カウントとともに表示され、解析の問題を素早く発見できます。

データセットのプロット

データセットをクリックすると plot ダイアログ が開きます。可能なこと:

データセットから x と y の列を選択します。凡例には各 y 列が単位付きで表示されるため（例: kappa (S/m)）、デュアル軸のプロットも読みやすくなります。
ズームとパン: プロットは大きなデータセットでも反応性を保つように、表示範囲の点を動的にダウンサンプリングして再取得します。
アクションメニューから処理済み parquet または元の生ファイルをダウンロードします。

データセットの編集

データセットの Edit アクションでは次が可能です:

データセットの名前を変更します。
列名と単位を再宣言します。列が変更されると、保存された元のファイルから新しい仕様で parquet が再構築されます。再アップロードは不要です。
同じデータセット ID とメタデータを保持したままデータファイルを完全に置き換えます。データセットを参照する他のレコードはリンクされたままです。

データを変更する編集ごとにデータセットの data_version がインクリメントされるため、下流のコンシューマーはキャッシュされた結果が古くなったことを検出できます。

データセットのプロベナンスを追跡する

すべてのプロパティデータセットにはどこから来たかを記録できます。これにより、プロット上のカーブを、それを生成したパイプライン、フィット、または解析まで辿ることができます。あるいは、デジタル化した論文、実験ノート、ベンダーシートまで遡ることもできます。プロベナンスは 4 つの任意フィールドで表現されます:

フィールド	説明
`source_pipeline_id`	このデータセットを出力したパイプラインラン。
`source_simple_pipeline_id`	このデータセットを生成したシンプルパイプライン。
`source_analysis_id`	このデータセットの派生元となった解析。
`source_label`	自由形式のメモ（例: `"Smith et al. 2023, Fig. 3"` や `"手動でアップロード"`）。

1 つのデータセットで設定できる source_*_id フィールドは 1 つまで です。1 つのデータセットは、上流の Ionworks レコードを 1 つだけ持つか、まったく持たないかのいずれかです。参照される行が存在しない場合、リクエストは拒否されます。ただしこのチェックは行の存在のみを確認し、あなたがその行を閲覧できるかどうかは検証しません — そのため、あなたからは通常見えないレコードの ID をソースとして設定すること自体は成功し、後でリンクを辿ろうとしたときにのみ未解決として表示されます。source_label は独立しており、単独で設定できます。ソースがリンク可能な Ionworks レコードでない場合はこちらを使ってください。材料のデータセットグリッドの Source 列は、source_label が設定されていればそれを表示し、設定されていなければソースの種類を表示します。ソースが Studio で参照可能なパイプラインまたは解析に解決される場合は、ラベルがそのソースの詳細ページへのリンクになります。

UI でアップロードまたは編集時にソースを設定する

Upload property dataset ダイアログと Edit ダイアログには Source セクションがあります:

ソースの種類 を選びます — Pipeline、Simple pipeline、Analysis のいずれか、あるいは「リンク可能なソースなし」の場合は空欄のままにします。
対応する ID を貼り付けます。種類を切り替えると、先に入力していた ID はクリアされ、複数のソースが同時に設定されることを防ぎます。
任意で ソースラベル を追加します — Source 列とデータセット詳細ビューに表示される、短い自由形式のメモです。

REST API でソースを設定する

データセットを作成または更新するときに、ソースフィールドの任意のサブセットを渡します。次の例は、あるパイプラインランで生成されたことを記録し、自由形式のラベルを追加しています:

curl -X POST "$IONWORKS_URL/material_property_datasets" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  -F "[email protected]" \
  -F "material_id=$MATERIAL_ID" \
  -F "project_id=$PROJECT_ID" \
  -F "name=Conductivity at 25 °C" \
  -F 'columns=[{"name":"c_e","unit":"mol.L-1","source_column_index":0},{"name":"kappa","unit":"S.m-1","source_column_index":1}]' \
  -F "source_pipeline_id=$PIPELINE_ID" \
  -F "source_label=Fitted from 25 °C EIS sweep"

既存のデータセットのプロベナンスを変更またはクリアするには、更新したいフィールドを PATCH します。ソース ID やラベルをクリアするには null を送信します:

curl -X PATCH "$IONWORKS_URL/material_property_datasets/$DATASET_ID" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_pipeline_id": null, "source_analysis_id": "'$ANALYSIS_ID'"}'

Python クライアントおよび REST API から返される MaterialPropertyDataset レコードはいずれも同じ 4 つのフィールドを公開しているため、データセットが現れる任意の場所からプロベナンスを読み取れます:

dataset = client.material_property_dataset.get("mpd_def456")
print(dataset.source_pipeline_id, dataset.source_analysis_id, dataset.source_label)

Python クライアント

Python API クライアントは材料とそのプロパティデータセットを 2 つのサブクライアントとして公開します:

client.material — 材料の一覧取得と取得。
client.material_property_dataset — プロパティデータセットの一覧取得、取得、ダウンロード。

いずれのクライアントも読み取り専用です。材料やデータセットを作成・変更するには、UI または REST API を使用してください。

材料の一覧取得と取得

from ionworks import Ionworks

client = Ionworks()

# 現在の組織内の材料を、すべてのプロジェクトを横断して一覧取得
materials = client.material.list(limit=50)
for m in materials:
    print(m.id, m.name, m.manufacturer, m.product_id, m.project_id)

# ID で単一の材料を取得
material = client.material.get("mat_abc123")

各材料は project_id を持ちます。list() に project_id を渡すと、各材料に返される property_count もそのプロジェクトにスコープされます。

材料のプロパティデータセット一覧

datasets = client.material_property_dataset.list(
    material_id="mat_abc123",
    project_id="proj_xyz789",  # オプション: このプロジェクトのデータセットのみ
    limit=100,
)
for d in datasets:
    print(d.id, d.name, d.data_version, [c.name for c in d.columns])

各 MaterialPropertyDataset は、columns（name、unit、source_column_index を持つ ColumnSpec レコードのリスト）、編集ごとにインクリメントされる data_version、および列ごとの nan_counts を公開します。

データセット値のダウンロード

get_data() はデータセット全体をダウンロードし、設定された DataFrame バックエンドの DataFrame として返します:

dataset = client.material_property_dataset.get("mpd_def456")
print(dataset.name, dataset.data_version)

# 列名を物理単位にマッピング。例: {"c_e": "mol/L", "kappa": "S/m"}
units = {col.name: col.unit for col in dataset.columns}

# すべての行を DataFrame として取得
df = client.material_property_dataset.get_data("mpd_def456")
df.head()

REST API

材料プロパティデータセットは /material_property_datasets の下で管理されます。材料そのものは /materials の下で管理されます。

データセットのアップロード

POST /material_property_datasets は multipart フォームを受け入れます:

フィールド	説明
`file`	アップロードする CSV または parquet ファイル。
`material_id`	親材料の ID。
`project_id`	このデータセットがスコープされるプロジェクトの ID。
`name`	人間可読のデータセット名。
`columns`	列仕様の JSON 配列（下記参照）。
`no_header`	CSV にヘッダー行がない場合は `true`。デフォルトは `false`。
`source_pipeline_id`	任意。このデータセットを生成したパイプラインランの ID。
`source_simple_pipeline_id`	任意。このデータセットを生成したシンプルパイプラインの ID。
`source_analysis_id`	任意。このデータセットの派生元となった解析の ID。
`source_label`	任意。来歴を示す自由形式のメモ（例: 論文の参照や手動アップロードの説明）。

1 つのデータセットで設定できる source_*_id フィールドは 1 つまで です。プロベナンスが Ionworks 上のリンク可能なレコードではない場合（例: 「Smith et al. 2023 から手動でデジタル化」など）は、source_label だけを設定してください。詳しくはデータセットのプロベナンスを追跡するを参照してください。各列仕様はオブジェクトです:

{
  "name": "c_e",
  "unit": "mol.L-1",
  "source_column_index": 0
}

source_column_index はアップロードファイル内の列の 0 始まりの位置です。ファイルにヘッダー行がある場合でも必須です。名前は位置で照合された後、提供した name にリネームされます。 curl でのアップロード例:

curl -X POST "$IONWORKS_URL/material_property_datasets" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  -F "[email protected]" \
  -F "material_id=$MATERIAL_ID" \
  -F "project_id=$PROJECT_ID" \
  -F "name=Conductivity at 25 °C" \
  -F 'columns=[
    {"name": "c_e", "unit": "mol.L-1", "source_column_index": 0},
    {"name": "kappa", "unit": "S.m-1", "source_column_index": 1}
  ]'

レスポンスは新しいデータセットレコードで、id、storage_path、data_version、列ごとの nan_counts を含みます。

材料のデータセット一覧

curl "$IONWORKS_URL/material_property_datasets?material_id=$MATERIAL_ID&project_id=$PROJECT_ID&limit=100&offset=0" \
  -H "Authorization: Bearer $IONWORKS_API_KEY"

データセットレコードのページ分割されたリストを返します。

データセット値を JSON として取得する

curl "$IONWORKS_URL/material_property_datasets/$DATASET_ID/data?max_points=500&x_col=c_e&x_min=0&x_max=2" \
  -H "Authorization: Bearer $IONWORKS_API_KEY"

データセットを列指向の JSON オブジェクトとして返します:

{
  "c_e": [0.5, 1.0, 1.5, 2.0],
  "kappa": [0.42, 0.71, 0.89, 0.95]
}

max_points は均一にダウンサンプリングするため、大きなデータセットでもプロットの反応性が保たれます。x_col、x_min、x_max はある列の範囲にレスポンスを制限します。チャートのズームに便利です。

元のファイルのダウンロード

GET /material_property_datasets/{id}/file を使ってファイル用の短命の署名付き URL にリダイレクトするか、GET /material_property_datasets/{id}/download-url で URL を JSON として受け取れます（ブラウザから開きたい場合に便利）。?kind=parquet（デフォルト）で処理済み parquet を、?kind=original でアップロードした生ファイルをダウンロードできます。

メタデータの更新、ファイルの置き換え、削除

エンドポイント	説明
`PATCH /material_property_datasets/{id}`	データセットの名前を変更したり列を再宣言したりします。列が変わると、保存された元のファイルから parquet が再構築されます。
`PATCH /material_property_datasets/{id}/file`	データファイルを置き換えます。同じリクエストで任意に `name`、`columns`、`no_header` も更新できます。
`DELETE /material_property_datasets/{id}`	データセットと保存されたファイルを削除します。

はじめに

クイックスタート

基本コンセプト

運用

データ

モデル構築

パイプライン

シミュレーション

最適化

材料とプロパティデータセット

材料とは

材料の使いどころ

UI で材料を管理する

プロパティデータセットのアップロード

データセットのプロット

データセットの編集

データセットのプロベナンスを追跡する

UI でアップロードまたは編集時にソースを設定する

REST API でソースを設定する

Python クライアント

材料の一覧取得と取得

材料のプロパティデータセット一覧

データセット値のダウンロード

REST API

データセットのアップロード

材料のデータセット一覧

データセット値を JSON として取得する

元のファイルのダウンロード

メタデータの更新、ファイルの置き換え、削除

関連項目

​材料とは

​材料の使いどころ

​UI で材料を管理する

​プロパティデータセットのアップロード

​データセットのプロット

​データセットの編集

​データセットのプロベナンスを追跡する

​UI でアップロードまたは編集時にソースを設定する

​REST API でソースを設定する

​Python クライアント

​材料の一覧取得と取得

​材料のプロパティデータセット一覧

​データセット値のダウンロード

​REST API

​データセットのアップロード

​材料のデータセット一覧

​データセット値を JSON として取得する

​元のファイルのダウンロード

​メタデータの更新、ファイルの置き換え、削除

​関連項目

材料とは

材料の使いどころ

UI で材料を管理する

プロパティデータセットのアップロード

データセットのプロット

データセットの編集

データセットのプロベナンスを追跡する

UI でアップロードまたは編集時にソースを設定する

REST API でソースを設定する

Python クライアント

材料の一覧取得と取得

材料のプロパティデータセット一覧

データセット値のダウンロード

REST API

データセットのアップロード

材料のデータセット一覧

データセット値を JSON として取得する

元のファイルのダウンロード

メタデータの更新、ファイルの置き換え、削除

関連項目