> ## 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.
# データのアップロード
> Python API で Ionworks Studio にセル仕様、インスタンス、測定をアップロードします
Ionworks Studio へのデータアップロードは、3 段階の階層に従います: セル仕様（セルの設計図）を作成し、セルインスタンス（特定の物理セル）を作成し、そのインスタンスに対する測定をアップロードします。
インストールと認証については [Python API クライアント](/ja/api-client) ページを参照してください。データを読み取るには [データの読み取り](/ja/data/reading) を参照してください。
## アップロードワークフロー
仕様はセルの材料、電気的定格、構成要素を定義します。
仕様にリンクされた特定の物理セルです。
時系列、プロパティ、ファイル測定をインスタンスに添付します。
### ステップ 1: セル仕様を作成または取得する
```python theme={null}
cell_spec = client.cell_spec.create_or_get(
{
"name": "NCM622/Graphite Coin Cell",
"form_factor": "R2032",
"manufacturer": "Custom Cells",
"ratings": {
"capacity": {"value": 0.002, "unit": "A.h"},
"voltage_min": {"value": 2.5, "unit": "V"},
"voltage_max": {"value": 4.2, "unit": "V"},
},
"cathode": {
"properties": {"loading": {"value": 12.3, "unit": "mg.cm-2"}},
"material": {"name": "NCM622", "manufacturer": "BASF"},
},
"anode": {
"properties": {"loading": {"value": 6.5, "unit": "mg.cm-2"}},
"material": {"name": "Graphite", "manufacturer": "Customcells"},
},
}
)
```
セル仕様フィールドの全セットは[セル](/ja/core-concepts/cells)を参照してください。
### ステップ 2: セルインスタンスを作成または取得する
```python theme={null}
cell_instance = client.cell_instance.create_or_get(
cell_spec.id,
{
"name": "NCM622-GR-001",
"batch": "BATCH-2024-001",
"date_manufactured": "2024-01-20",
"measured_properties": {
"cathode": {"loading": {"value": 12.1, "unit": "mg.cm-2"}},
"anode": {"loading": {"value": 6.4, "unit": "mg.cm-2"}},
},
},
)
```
セルインスタンスのフィールド:
| フィールド | 説明 |
| --------------------- | --------------------------------- |
| `name` | このセルの一意の識別子 |
| `batch` | バッチまたはロット番号 |
| `date_manufactured` | 製造日（任意） |
| `measured_properties` | 仕様と異なるこのセル固有の測定値（実測容量、電極ローディングなど） |
### ステップ 3: 時系列付きで測定をアップロードする
```python theme={null}
import pandas as pd
time_series = pd.DataFrame(
{
"Time [s]": [0, 1, 2, 3, 4, 5],
"Voltage [V]": [3.0, 3.2, 3.5, 3.8, 4.0, 4.2],
"Current [A]": [-0.002, -0.002, -0.002, -0.002, -0.002, -0.002],
"Step count": [0, 0, 0, 1, 1, 1],
"Cycle count": [0, 0, 0, 0, 0, 0],
"Step from cycler": [1, 1, 1, 2, 2, 2],
"Cycle from cycler": [0, 0, 0, 0, 0, 0],
}
)
measurement_data = {
"measurement": {
"name": "Formation Cycle 1",
"protocol": {
"name": "CC-CV charge at C/10 to 4.2V",
"ambient_temperature_degc": 25,
},
"test_setup": {
"cycler": "Biologic VMP3",
"operator": "Jane Smith",
},
"notes": "Formation cycle - first charge",
},
"time_series": time_series,
}
bundle = client.cell_measurement.create(cell_instance.id, measurement_data)
print(f"Created measurement: {bundle.name}")
print(f"Steps created: {bundle.steps_created}")
```
**プロパティ** および **ファイル** 測定タイプ（およびそれらが受け入れるフィールド）については[測定](/ja/data/measurements)を参照してください。
## アップロード検証
データが Ionworks Studio に送信される前に、Python クライアントはマシン上で時系列を検証します。常時オンのチェックは、最も一般的な処理ミスをキャッチします:
* 正の電流が放電（電圧低下）に対応している。充電は負の電流を使用する。
* 時間が 0 から始まり、単調非減少である。
* `Step count` が存在し、0 から始まり、1 ずつ増加する。
* 累積列（容量、エネルギー）が各ステップの先頭でリセットされる。
これらのいずれかが失敗すると、`create` と `create_or_get` は `MeasurementValidationError` を発生させ、アップロードは開始されません。それぞれの失敗を修正する方法は下記の[トラブルシューティング](#トラブルシューティング)を参照してください。
### 検証失敗の確認
`MeasurementValidationError.errors` は `ValidationIssue` レコードのリストです。各 issue は安定した `code`（`IssueCode` 列挙）、`severity`（`"error"` または `"warning"`）、人間可読の `message`、ステップインデックス、列名、観測値、閾値などの詳細を含む構造化された `payload` 辞書を持ちます。
`message` を解析するのではなく `code` で分岐します。文言はリリース間で変わる可能性がありますが、チェック識別子は安定しています。
```python theme={null}
from ionworks import IssueCode, MeasurementValidationError
try:
client.cell_measurement.create(cell_instance.id, measurement_data)
except MeasurementValidationError as e:
for issue in e.errors:
print(f"[{issue.severity}] {issue.code}: {issue.message}")
print(" details:", issue.payload)
if e.has_code(IssueCode.CURRENT_SIGN_REVERSED):
# Auto-fixable: positive current was charge, not discharge.
# Use ionworksdata.transform.set_positive_current_for_discharge(df)
# before re-uploading.
...
```
### 厳格な検証
**すべてのアップロードで `validate_strict=True` を渡すことをお勧めします。** 厳格チェックは、データ処理中に発生した微妙なバグ（例えば、記録されていない大きな時間ギャップ、誤った `groupby` や `partition_by` 呼び出しで行が並び替えられた時系列など）を、データが Ionworks Studio に到達して下流のシミュレーションやフィットを汚染する前にキャッチします。
```python theme={null}
bundle = client.cell_measurement.create(
cell_instance.id,
measurement_data,
validate_strict=True,
)
```
厳格モードは常時オンのものに加えて以下のチェックを追加します:
* 各ステップに少なくとも 2 つのデータポイントが含まれる
* `Cycle count` が各ステップ内で一定である
* 連続する時間サンプル間のギャップが 5 時間を超えない
* 連続する行間で電圧が連続している（`voltage_window` が必要）
* 同じ方向の連続ステップ 2 つが満充電または満放電を行わない（`rated_capacity` と `measurement_detail` の `steps` データフレームが必要）
* 単一ステップが定格容量の 500 % を超えない — 発生時にエラーではなく `UserWarning` を発する（`rated_capacity` と `steps` が必要）
* 報告される累積容量・エネルギー列が、電流（および電力）の台形積分とすべての行で 10 % 以内で一致する — 常時オンチェックを通過してしまうラベル付け誤り `Discharge`/`Charge`、欠落サンプル、符号規約のバグをキャッチします
### より豊富なチェックのためにセルコンテキストを提供する
電圧連続性チェックとステップ容量チェックには、セルの定格電圧ウィンドウと容量が必要です。キーワード引数として渡します:
```python theme={null}
bundle = client.cell_measurement.create(
cell_instance.id,
measurement_data,
validate_strict=True,
rated_capacity=0.002, # A.h — nominal capacity of the cell
voltage_window=(2.5, 4.2), # (V_min, V_max) from the cell spec
)
```
すでにセル仕様オブジェクトを持っている場合は、これらの値を直接読み取れます:
```python theme={null}
ratings = cell_spec.ratings
rated_capacity = ratings["capacity"]["value"]
voltage_window = (
ratings["voltage_min"]["value"],
ratings["voltage_max"]["value"],
)
```
両方の引数は任意です。`voltage_window` を省略すると電圧連続性チェックのみがスキップされます。`rated_capacity` を省略すると連続フルステップとステップごとの容量チェックのみがスキップされます。その他の厳格モードチェックはすべて実行されます。
連続フルステップとステップごとの容量チェックには、`measurement_detail` の `steps` キーの下に事前計算されたステップサマリーも必要です。提供しない場合、Ionworks Studio はアップロード後にサーバー側でステップサマリーを生成しますが、これら 2 つのクライアント側チェックはスキップされます。
`create_or_get` も同じ `rated_capacity` と `voltage_window` 引数を受け入れ、`create` に転送します。
### 厳格チェックを 1 つだけ緩和する
特定の厳格チェックがデータセットで既知の偽陽性である場合（例えば、5 時間の時間ギャップ閾値を超える正当な数日間の休止期間など）、厳格モードを完全に無効にするのではなく、`skip_checks` で **そのチェックのみ** を緩和してください。これによりその他のすべてのガードレールは維持されます（最小権限の検証）。
```python theme={null}
bundle = client.cell_measurement.create(
cell_instance.id,
measurement_data,
validate_strict=True,
skip_checks={"time_gaps"}, # everything else still enforced
)
```
有効な名前（`ionworks.validators.STRICT_CHECK_NAMES` としても公開されています）:
* `minimum_points_per_step`
* `cycle_constant_within_step`
* `time_gaps`
* `voltage_continuity`
* `consecutive_same_direction_full_steps`
* `step_capacity_within_rated`
* `capacity_energy_from_current_power`
未知の名前は `ValueError` を発生させます。複数のチェックに同時に該当する文書化された理由がない限り、厳格モードを一括で無効にしないでください。
### EIS 測定の検証
サイクリング用のチェックは
[電気化学インピーダンス分光法 (EIS)](/ja/data/format#eis-and-impedance-data)
データには適用されません。EIS スペクトルには `Time [s]` や `Step count` は存在せず、周波数に対するインピーダンスサンプルのみが含まれます。測定辞書に `data_type` ヒントを追加してクライアントに EIS 測定であることを伝えると、バリデーターは EIS 専用のチェックセットに切り替わります。
```python theme={null}
measurement_data = {
"measurement": {
"name": "EIS at 25°C, 50% SOC",
"data_type": "eis",
"protocol": {
"ambient_temperature_degc": 25,
},
},
"time_series": eis_df, # columns: Frequency [Hz], Z_Re [Ohm], Z_Im [Ohm]
}
bundle = client.cell_measurement.create(
cell_instance.id,
measurement_data,
validate_strict=True,
rated_capacity=0.002, # A.h — インピーダンス大きさチェックを有効化
)
```
以下のチェックが実行されます:
* **構造カラム**（常時オン）— フレームには `Frequency [Hz]`、`Z_Re [Ohm]`、`Z_Im [Ohm]` が含まれている必要があります。
* **`eis_zim_sign`**（厳格モードのみ）— 容量性帯域が主に正の値になっているスペクトルにフラグを立てます。Ionworks の規約では、`Z_Im [Ohm]` は容量性アーク全体で**負**です（[EIS とインピーダンスデータ](/ja/data/format#eis-and-impedance-data) を参照）。修正のヒントは `Z_Im = -Z_Im` です。
* **`eis_impedance_magnitude`**（厳格モードのみ）— `min(Z_Re)` を容量から推定された値の 100× の広い帯域と比較することで、桁違いの単位エラー（Ω 対 mΩ 対 kΩ）を捕捉します。`rated_capacity` が必要で、指定されない場合はスキップされます。
両方のヒューリスティックチェックは桁違いの問題（完全に反転した符号や 1000× の単位エラー）でのみ発火するため、妥当なスペクトルが誤って弾かれることはありません。他の厳格チェックと同様に、個別のチェックをスキップできます:
```python theme={null}
bundle = client.cell_measurement.create(
cell_instance.id,
measurement_data,
validate_strict=True,
skip_checks={"eis_zim_sign"},
)
```
## `create_or_get` による冪等なアップロード
3 つの create メソッドにはすべて `create_or_get` バリアントがあり、アップロードスクリプトを安全に再実行可能にします。同じ名前のリソースがすでに存在する場合、クライアントはエラーを発生させずに取得して返します。
```python theme={null}
# cell_spec: data only
spec = client.cell_spec.create_or_get(data)
# cell_instance: requires cell_spec_id
instance = client.cell_instance.create_or_get(cell_spec_id, data)
# cell_measurement: requires cell_instance_id
measurement = client.cell_measurement.create_or_get(cell_instance_id, data)
```
## 重複の処理
`create_or_get` ではなく `create()` を呼び出して同じ名前のリソースがすでに存在する場合、API は `detail` フィールドに既存リソースの ID を含めて `409 Conflict` を返します:
```json theme={null}
{
"error_code": "CONFLICT",
"message": "Cell specification with this name already exists",
"detail": {
"resource_type": "cell_specification",
"resource_name": "My Cell Spec",
"existing_id": "abc-123"
}
}
```
`existing_id` を使うと、独自の create-or-get ロジックを実装したい場合に別途ルックアップせずに既存レコードを取得できます。
## インライン時系列のサイズ制限
インラインで渡される時系列（例: パイプライン設定内）は **1,000 行** で上限が設定されています。それより大きなデータセットは、まず測定としてアップロードする必要があります。エラークラス、回避策、`db:` 参照形式については[データの読み取り — インラインサイズ制限](/ja/data/reading#inline-time-series-size-limit)を参照してください。
## 自動ペイロード圧縮
Python クライアントは、API に送信する前に 512 KB を超えるリクエストペイロードを gzip で自動的に圧縮します。これは透過的に行われ、設定は不要です。大きなシリアライズされたモデルやデータセットでは、アップロードサイズを大幅に削減できます。
## トラブルシューティング
### 連続する行間で大きな時間ギャップがある
**問題:** `validate_strict=True` でアップロードする際に、次のようなエラーが発生する:
> Time gap of 6.12 h between rows 4201 and 4202 exceeds the maximum allowed
> gap of 5.0 h.
**解決策:** 連続する 2 つの時間サンプル間で 5 時間を超えるギャップは、ほぼ常に処理中に行が削除されたことを意味します。例えば、長い休止期間がファイル内の経過時間として記録されていたが、中間の行が削除された場合などです。その後、容量積分が欠落区間を電流が流れたかのように計算してしまい、過大な値が報告されます。
フィルタリングなしで生のサイクラーファイルを再度読み込み、時間軸が連続していることを確認してください。ワークフローで意図的にデータを間引く場合は、セクション全体を削除するのではなく一様にダウンサンプリングするか、ギャップで記録を別々の測定に分割してください。
### 電圧連続性チェックの失敗
**問題:** `validate_strict=True` と `voltage_window` を指定してアップロードする際に、次のようなエラーが発生する:
> Voltage continuity check failed: 318/3599 (8.8%) of consecutive row pairs
> have a voltage jump greater than 80% of the rated voltage window.
**解決策:** Ionworks はすべての連続する行ペア間の絶対電圧変化を確認します。ペアの 5 % 超が定格電圧ウィンドウ（`V_max - V_min`）の 80 % を超える場合、時系列はほぼ確実に時系列順になっていません。典型的には、`partition_by("Cycle_raw")` のようなグループ化操作によって異なるサイクルのパルス行と休止行がインターリーブされていることが原因です。
アップロード前に DataFrame を `Time [s]` でソートし、自然な行順序を破る変換を避けてください:
```python theme={null}
import polars as pl
time_series = time_series.sort("Time [s]")
```
### 同方向の連続フル容量ステップ
**問題:** `validate_strict=True`、`steps` データフレーム、`rated_capacity` を指定してアップロードする際に、次のようなエラーが発生する:
> Consecutive full-capacity discharge steps detected: step 12 and step 15
> each delivered more than 200% of the rated capacity.
**解決策:** ここでの「連続」とは、シーケンス内で最も近い同方向のステップ 2 つを意味します。つまり、ステップ 12 と 15 の間に充電ステップがあっても連続する放電です。単一の測定は単一のセルでの 1 つの連続したテストを表すべきなので、背中合わせの 2 つのフル容量放電（または充電）は、ファイルが複数の独立した実験を結合して組み立てられたことを意味することが多いです（例: 異なる C レートでの複数の CC 放電を縫い合わせたもの）。ソースデータをアップロード前に別々の測定に分割し直してください。
正当に長い単一の実験に 3 つ以上のフル充電または放電が連続して含まれる場合（まれですが可能性はあります）、`measurement_detail` から事前計算された `steps` エントリを削除するか `rated_capacity` を省略してこの特定のチェックをスキップし、Ionworks Studio がサーバー側でステップサマリーを再生成するようにします。
### ステップ容量が定格容量を超える
**問題:** `validate_strict=True`、`steps` データフレーム、`rated_capacity` を指定してアップロードする際に、次のような `UserWarning` が発生する:
> 3 step(s) exceed 500% of the rated capacity. First: step 47 has
> 'Discharge capacity \[A.h]' = 0.031 A.h.
**解決策:** これはソフトな警告です（アップロードは続行されます）が、ステップ境界に問題があるか、記録されていない時間ギャップにわたって容量積分が膨張している可能性を示しています。フラグの立ったステップを確認し、それが単一の充電または放電を表していることを確認し、`Step count` 列のギャップを再確認してください。基本的な時間ギャップやステップ境界の問題を修正すると、通常は警告が消えます。
### 容量・エネルギー列が電流・電力積分と一致しない
**問題:** `validate_strict=True` でアップロードする際に、次のようなエラーが発生する:
> Column 'Discharge capacity \[A.h]' disagrees with the running integral of
> 'max(I, 0)' over time by up to 47.3% (exceeds 10% tolerance). Worst row
> 8421: reported = 0.0019 A.h, integrated = 0.0010 A.h.
このチェックは、報告される各累積列を、プラットフォームが累積列を報告する方法を反映したステップごとのリセットを含む、時間に対する電流（容量）または電力（エネルギー）の台形積分と比較します。Ionworks の符号規約（正の電流 = 放電）では:
* `Discharge capacity [A.h]` ≈ `∫ max(I, 0) dt / 3600`
* `Charge capacity [A.h]` ≈ `∫ max(-I, 0) dt / 3600`
* `Discharge energy [W.h]` ≈ `∫ max(P, 0) dt / 3600`
* `Charge energy [W.h]` ≈ `∫ max(-P, 0) dt / 3600`
電力は `Power [W]` が存在すればそれを使用し、それ以外の場合は `Voltage [V] * Current [A]` として計算されます。対応する issue コードは `DISCHARGE_CAPACITY_INTEGRAL_MISMATCH`、`CHARGE_CAPACITY_INTEGRAL_MISMATCH`、`DISCHARGE_ENERGY_INTEGRAL_MISMATCH`、`CHARGE_ENERGY_INTEGRAL_MISMATCH` です。各 issue の `payload` には、最悪の行インデックス、その行での報告値と積分値、最大累積スケール、相対誤差が含まれます。
**解決策:** 不一致は通常、`Discharge` / `Charge` ラベルの入れ替わり、電流符号規約の誤り、または信頼できないソース列のいずれかに起因します。これら 3 つはいずれも
[データの準備 — 充電と放電の累積列の入れ替わり](/ja/data/preparing-data#swapped-charge-and-discharge-cumulative-columns)
とその上の[符号規約のトラブルシューティング](/ja/data/preparing-data#incorrect-current-sign-convention)にある変換レシピでカバーされています。そちらでデータを修正してから再アップロードしてください。
不一致がむしろデータセットの既知の特性であり、下流解析に影響しないことを確認した場合は、`skip_checks={"capacity_energy_from_current_power"}` でこのチェックだけを緩和してください。
## 次のステップ
3 つの測定タイプ — 時系列、プロパティ、ファイル — の詳細。
測定データを一覧、フィルタリング、ページング、取得します。
アップロード前にサイクラーファイルを Ionworks フォーマットに読み込みます。
認識される列、数量フォーマット、符号規約。