> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 材料とプロパティデータセット
> 電極、電解液、その他の材料を管理し、OCP、拡散係数、導電率カーブなどの測定プロパティデータセットを添付します
## 材料とは
**材料 (Material)** は、[セル仕様](/ja/core-concepts/cells)で使用される物理材料を記述する再利用可能なレコードです。例えば、NMC811 正極粉末、グラファイト負極、LP57 電解液などです。
材料と、それをラップする**セルコンポーネント**（負極、正極、電解液、セパレータ、ケース）は、**プロジェクトにスコープされます**。セル仕様を通じて材料やコンポーネントを作成すると、同じ組織内の 2 つのプロジェクトは、名前、製造元、製品 ID がまったく同じ「同一の」材料であっても、それぞれ独自のコピーを保持します。これにより、編集内容、プロパティデータセット、セルからの参照はプロジェクトごとにきれいに分離されます。同じ材料を別のプロジェクトでも使いたい場合は、そのプロジェクトに一致する材料を新しく作成することになります。
セル仕様を経由せず直接作成された材料やコンポーネントはプロジェクトを持たず、組織全体で共有されたままになります。プロジェクトごとのスコープが導入される前から存在する古い材料も、組織全体で共有されている場合があります。これらの共有レコードを編集すると、それを参照するすべての仕様に影響します。
各材料には任意の数の **プロパティデータセット** を添付できます。プロパティデータセットは、1 つ以上の物理プロパティを 1 つ以上の独立変数の関数として表す表形式の測定（CSV または parquet）です。例えば、電解質導電率対濃度や、負極 OCP 対化学量論などです。プロパティデータセットは親材料と同じプロジェクトに属します。
プロパティデータセットはデータとして保存されます。ルックアップテーブルをパラメータ化モデルに直接埋め込む[パラメータ補間子](/ja/build/interpolants)とは別物です。プロパティデータセットを使って生の測定を整理・共有し、シミュレーションで使用する準備ができたら補間子に変換してください。
## 材料の使いどころ
材料は次のような場合に使用します:
* 複数のセル（例: 複数のセル構成における同じ電解液）にまたがって使用される材料のプロパティに関する単一の信頼できる情報源を維持したい。
* 測定された材料と並べて、生の測定（OCP、拡散係数、導電率、輸率、…）を保存したい。
* 同じプロパティの複数のデータセットを比較したい — 例えば、異なる温度や異なる研究室で測定された OCP カーブ。
* 来歴を追跡したい: 誰が、いつ、どの生ファイルからデータセットをアップロードしたか。
## UI で材料を管理する
各プロジェクトには左側のナビゲーションに **Materials** セクションがあります。そこで次のことが可能です:
* **材料を作成する** — 名前を付け、任意で製造元と製品 ID を指定します。
* **材料を開く** — プロパティデータセットとメタデータを表示します。
* 行アクションメニューから材料を **編集または削除** します。
セル仕様エディタから作成された材料は、そのセル仕様のプロジェクトを引き継ぎます。そのため、通常はプロジェクトを明示的に選ぶ必要はなく、材料はそれを使用するセルと同じプロジェクトに作成されます。
### プロパティデータセットのアップロード
材料の詳細ページから **Upload property dataset** をクリックして:
1. **ファイルを選択する** — CSV または parquet。CSV はヘッダー行を含むことも省略することもできます。ファイルを選択するとデータセット名はファイル名から自動入力されます。別の名前にしたい場合は編集してください。
2. **データセット名を確認する** — ステップ 1 でファイル名から自動入力されます。別の名前にしたい場合は変更してください（例: `Conductivity at 25 °C`）。
3. **列を宣言する** — ファイル内で検出されたすべての列が順番に表示されます。各列について次を提供します:
* **Name** — 処理済みデータセットに格納される表示名（例: `c_e`）。送信前に表示されているすべての列に名前を付ける必要があります。インポートしたくない列はその行を削除するか、名前を付けて後で無視してください。末尾の空の列（Excel の「末尾のカンマ」アーティファクトでよくあります）は自動的にトリムされます。
* **Unit** — 物理単位（例: `mol/L`、`S/m`）。無次元量の場合は空白のままにします。
* **Source column** — 値の取得元となるアップロードファイル内の列。ヘッダーなし CSV では位置です。ヘッダー付きのファイルでは名前で選択できます。
4. **送信。** ファイルが解析され、すべての値が浮動小数点数に強制変換され（数値でないセルは NaN になります）、処理済み parquet と元の生ファイルの両方が保存されます。
アップロード後、データセットは材料のプロパティリストに、行数と列ごとの NaN カウントとともに表示され、解析の問題を素早く発見できます。
### データセットのプロット
データセットをクリックすると **plot ダイアログ** が開きます。可能なこと:
* データセットから x と y の列を選択します。凡例には各 y 列が単位付きで表示されるため（例: `kappa (S/m)`）、デュアル軸のプロットも読みやすくなります。
* ズームとパン: プロットは大きなデータセットでも反応性を保つように、表示範囲の点を動的にダウンサンプリングして再取得します。
* アクションメニューから処理済み parquet または元の生ファイルをダウンロードします。
### データセットの編集
データセットの **Edit** アクションでは次が可能です:
* データセットの名前を変更します。
* 列名と単位を再宣言します。列が変更されると、保存された元のファイルから新しい仕様で parquet が再構築されます。再アップロードは不要です。
* 同じデータセット ID とメタデータを保持したままデータファイルを完全に置き換えます。データセットを参照する他のレコードはリンクされたままです。
データを変更する編集ごとにデータセットの `data_version` がインクリメントされるため、下流のコンシューマーはキャッシュされた結果が古くなったことを検出できます。
## 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`。 |
各列仕様はオブジェクトです:
```json theme={null}
{
"name": "c_e",
"unit": "mol.L-1",
"source_column_index": 0
}
```
`source_column_index` はアップロードファイル内の列の 0 始まりの位置です。ファイルにヘッダー行がある場合でも必須です。名前は位置で照合された後、提供した `name` にリネームされます。
`curl` でのアップロード例:
```bash theme={null}
curl -X POST "$IONWORKS_URL/material_property_datasets" \
-H "Authorization: Bearer $IONWORKS_API_KEY" \
-F "file=@conductivity.csv" \
-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` を含みます。
### 材料のデータセット一覧
```bash theme={null}
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 として取得する
```bash theme={null}
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 オブジェクトとして返します:
```json theme={null}
{
"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}` | データセットと保存されたファイルを削除します。 |
## 関連項目
* [セル](/ja/core-concepts/cells) — 材料はセル仕様の負極、正極、電解液、セパレーター構成要素から参照されます。
* [パラメータ補間子](/ja/build/interpolants) — 測定されたプロパティデータをパラメータ化モデル内のルックアップテーブルパラメータに変換します。
* [マテリアルデータセットからの電解液輸送](/ja/pipelines/direct-entries) — プロパティデータセットから濃度依存の電解液輸送パラメータを構築し、パイプラインに投入します。
* [データの概要](/ja/data/overview) — Ionworks Studio で実験データがどのように整理されるか。