> ## 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.

# データフォーマット

> バッテリーサイクリングデータの認識される時系列列、単位、電流符号規約、EIS 列、数量フォーマットのリファレンスです

Ionworks Studio はバッテリーサイクリングデータに標準化されたフォーマットを使用します。このページは、認識される列、数値の数量フォーマット、Ionworks がアップロード時に前提とする符号規約のリファレンスです。

生のサイクラーファイルをこのフォーマットに変換する方法については、[データの準備](/ja/data/preparing-data)を参照してください。アップロードワークフローについては、[データのアップロード](/ja/data/uploading)を参照してください。

## 時系列の列

時系列 DataFrame には、サイクリング実験からの高解像度測定が含まれます。データには任意の列を含められますが、以下の列は自動ステップラベリングシステムで **認識** されます。

| 列                          | 型     | 説明                          |
| -------------------------- | ----- | --------------------------- |
| `Time [s]`                 | float | 累積時間（秒）（サイクルごとにリセットしない）     |
| `Voltage [V]`              | float | セル電圧                        |
| `Current [A]`              | float | 電流（正 = 放電、負 = 充電）           |
| `Cycle count`              | int   | 累積サイクル番号（0 始まり）             |
| `Step count`               | int   | すべてのサイクルにわたる累積ステップ番号（0 始まり） |
| `Temperature [degC]`       | float | セル温度                        |
| `Cycle from cycler`        | int   | サイクラーが報告するサイクル番号            |
| `Step from cycler`         | int   | サイクラーが報告するステップ番号            |
| `Discharge capacity [A.h]` | float | 累積放電容量                      |
| `Charge capacity [A.h]`    | float | 累積充電容量                      |
| `Discharge energy [W.h]`   | float | 累積放電エネルギー                   |
| `Charge energy [W.h]`      | float | 累積充電エネルギー                   |

<Note>
  **時間はサイクルにわたって累積でなければなりません。** サイクラーが各サイクルの開始時に時間をゼロにリセットする場合は、処理中に累積時間に変換してください。[データの準備 — 時間が累積でない](/ja/data/preparing-data#time-not-cumulative)を参照してください。
</Note>

### カスタム列

時系列データには任意の追加列を追加できます。カスタム列は保存され可視化に利用できますが、自動ステップラベリングシステムでは使用されません。

## 電流符号規約

Ionworks は一貫した符号規約を使用します:

* **正の電流 = 放電**
* **負の電流 = 充電**

バリデータは、反対の規約を使っていると思われるデータや、規約を判定できない（すべての値が同じ符号の）データを拒否します。サイクラーが異なる規約を使用している場合は、変換ヘルパーについて[データの準備 — 符号規約](/ja/data/preparing-data#incorrect-current-sign-convention)を参照してください。

## EIS とインピーダンスデータ

測定に電気化学インピーダンス分光（EIS）データが含まれる場合、以下の列が認識されます:

| 列                | 型     | 説明                     |
| ---------------- | ----- | ---------------------- |
| `Frequency [Hz]` | float | 励起周波数                  |
| `Z_Re [Ohm]`     | float | インピーダンスの実部             |
| `Z_Im [Ohm]`     | float | インピーダンスの虚部（容量性挙動では通常負） |
| `Z_Mod [Ohm]`    | float | インピーダンスの大きさ            |
| `Z_Phase [deg]`  | float | インピーダンスの位相角            |

<Note>
  **符号規約:** `Z_Im [Ohm]` はインピーダンス虚部の生の値を格納し、容量性挙動では通常負です。Ionworks Studio のナイキストプロットはこの値を自動的に反転し、標準的な電気化学規約に従って `-Z_Im [Ohm]` を y 軸に表示します。ファイルリーダー（BioLogic、Gamry など）はこの変換を自動的に処理します。
</Note>

### 直交 / 極座標からの導出

データに `Z_Mod [Ohm]` と `Z_Phase [deg]` が含まれていて `Z_Re [Ohm]` または `Z_Im [Ohm]` が欠落している場合、Ionworks は欠落する成分を自動的に導出します:

* `Z_Re = Z_Mod * cos(Z_Phase * π/180)`
* `Z_Im = Z_Mod * sin(Z_Phase * π/180)`

つまり、インピーダンスデータは直交形式（`Z_Re`、`Z_Im`）でも極座標形式（`Z_Mod`、`Z_Phase`）でもアップロードでき、Ionworks は解析用に 4 つの列すべてを確実に利用できるようにします。既存の列は決して上書きされません。

## 数量フォーマット

単位を持つすべての数値は `{"value": <number>, "unit": "<unit>"}` 形式を使用します。例:

```json theme={null}
{"value": 2.0, "unit": "A.h"}
```

このフォーマットは、セル仕様の定格（`capacity`、`voltage_min` など）、セルインスタンスの `measured_properties`、プロパティ測定に適用されます。単位を持たないプレーン文字列や数値も適切な箇所では受け入れられます。

### 単位記法

単位は **PyBaMM 記法** で保存されます: `.` 区切りのアトムと、オプションの符号付き整数指数で構成され、`*`、`/`、`**` は使用しません。例:

| 量      | PyBaMM 記法                               |
| ------ | --------------------------------------- |
| 容量     | `A.h`                                   |
| 面積負荷量  | `mg.cm-2`                               |
| 比エネルギー | `W.h.kg-1`                              |
| 濃度     | `mol.m-3`                               |
| 導電率    | `S.m-1`                                 |
| 単一単位   | `V`、`A`、`s`、`degC`、`ohm`、`mm`、`percent` |

**Pint 形式の文字列も入力時に受け付けられ**、保存時に PyBaMM 記法へ正規化されます。送信時には以下のペアは等価です:

| Pint 入力    | 保存形式       |
| ---------- | ---------- |
| `A*h`      | `A.h`      |
| `mg/cm**2` | `mg.cm-2`  |
| `W*h/kg`   | `W.h.kg-1` |
| `mol/m**3` | `mol.m-3`  |
| `S/m`      | `S.m-1`    |

つまり、Pint 構文を使った既存のペイロードは引き続き動作しますが、API から返される値は PyBaMM 記法になります。新しいコードでは PyBaMM 記法を優先することで、送信した内容と読み出した内容が一致します。

```python theme={null}
# どちらも受け付けられ、保存される単位はいずれも "A.h" になります。
client.cell_spec.update(
    cell_spec.id,
    ratings={"capacity": {"value": 2.0, "unit": "A.h"}},
)
client.cell_spec.update(
    cell_spec.id,
    ratings={"capacity": {"value": 2.0, "unit": "A*h"}},
)
```

## ステップサマリー

ステップサマリーには、実験の各ステップに対する集約メトリクスが含まれます。効率的なフィルタリングとサイクルレベル解析を可能にします。

<Tip>
  自分でステップサマリーを提供しない場合、アップロード時に時系列データから **自動生成** されます。
</Tip>

自動生成されるステップサマリーには、`step_type`（Rest、CC charge、CC discharge、CV などとして推論）、`duration_s`、電圧統計（`start_voltage_v`、`end_voltage_v`、`mean_voltage_v`）、電流統計、各ステップの容量・エネルギーの合計などの列が含まれます。

## 次のステップ

<CardGroup cols={2}>
  <Card title="データの準備" icon="file-import" href="/ja/data/preparing-data">
    ionworksdata ライブラリでサイクラーファイルをこのフォーマットに変換します。
  </Card>

  <Card title="データのアップロード" icon="upload" href="/ja/data/uploading">
    整形済みデータをセル仕様、インスタンス、測定としてアップロードします。
  </Card>

  <Card title="測定" icon="flask" href="/ja/data/measurements">
    3 つの測定タイプとそのフィールド。
  </Card>

  <Card title="データの可視化" icon="chart-line" href="/ja/data/visualizing">
    インタラクティブビューアでアップロードしたデータを探索します。
  </Card>
</CardGroup>