> ## 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. # データの準備 > ionworksdata ライブラリで、サイクラーファイル、BDF、EIS データを Ionworks フォーマットに読み込みます アップロードの前に、サイクラーからの生データを [Ionworks データフォーマット](/ja/data/format)に変換する必要があります。[`ionworksdata`](https://data.docs.ionworks.com/) ライブラリは、一般的なバッテリーサイクラーのファイルを読み取り、形式を自動検出し、単位、タイムスタンプ、列名を正規化します。 ```bash theme={null} pip install ionworksdata ``` ## サポートされるサイクラー `ionworksdata` は可能な限りファイル形式を自動検出し、標準列を持つ polars DataFrame を生成します。 | サイクラー | ファイル種別 | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- | | Arbin | `.csv`、`.xlsx`、`.res` | | BaSyTec | `.csv` | | BioLogic | `.mpt`、`.mpr`、`.txt` | | Maccor | `.txt`、`.csv`、`.xls`、`.xlsx` | | Neware | `.csv`、`.xls`、`.xlsx`（マルチシート対応、CSV では Latin-1 へ自動フォールバック） | | Novonix | `.csv` | | Repower | `.csv` | | 汎用 CSV | `.csv`（認識される列ヘッダーまたはカスタムマッピングを持つ任意の CSV） | | 汎用 Parquet | `.parquet`（認識される列ヘッダーまたはカスタムマッピングを持つ任意の parquet ファイル） | | BDF ([Battery Data Format](https://battery-data-alliance.github.io/battery-data-format/)) | `.bdf`、`.bdf.gz`、`.bdf.parquet`、`.csv` | ```python theme={null} import ionworksdata as iwd df = iwd.read.time_series("my_test.mpt", "biologic") ``` ## カスタム列マッピング CSV が非標準の列名を使用している場合は、`extra_column_mappings` で標準名にマップします。明示的にマップした列については、リーダーは自動検出をスキップし、値はリスケールなしでそのまま使用されます。 ```python theme={null} import ionworksdata as iwd df = iwd.read.time_series( "my_data.csv", "csv", extra_column_mappings={ "vCell": "Voltage [V]", "iCell": "Current [A]", "t": "Time [s]", "Tcell": "Temperature [degC]", }, ) ``` 部分的なマッピングも機能します。マップしない標準列は引き続き自動検出されます: ```python theme={null} df = iwd.read.time_series( "my_data.csv", "csv", extra_column_mappings={"vCell": "Voltage [V]"}, ) ``` カスタムのテストセットアップや独自仕様のサイクラーから来た CSV では `extra_column_mappings` を使用してください。マップされた値はそのまま保持され、単位変換やスケーリングは適用されません。このパラメータを使う前に、データが期待される標準単位（V、A、s、°C）になっていることを確認してください。 ## 汎用 parquet ファイル [BDF 仕様](#battery-data-format-bdf)に従わない parquet ファイルには、汎用 parquet リーダーを使用します。これは CSV リーダーの列検出戦略をミラーし、電圧、電流、時間、温度の一般的なエイリアスを認識しますが、parquet は強く型付けされていて列名が曖昧でないため、テキスト解析関連の処理はスキップします。区切り文字、エンコーディング、引用符の処理は不要です。 すでに parquet にエクスポートされたサイクラーデータ（例: 社内パイプラインや他のツールからのもの）を [Ionworks データフォーマット](/ja/data/format)に正規化したい場合に使用してください。 すべての `.parquet` ファイルは自動検出されます。リーダーを明示的に指定することもできます: ```python theme={null} import ionworksdata as iwd # Auto-detected by extension df = iwd.read.time_series("cell.parquet") # Or call the reader directly df = iwd.read.parquet("cell.parquet") ``` ファイルが非標準の列名を使用している場合は、CSV リーダーと同じように `extra_column_mappings` を渡します: ```python theme={null} df = iwd.read.parquet( "cell.parquet", extra_column_mappings={ "vCell": "Voltage [V]", "iCell": "Current [A]", "t": "Time [s]", }, ) ``` BDF の parquet ファイル（`.bdf.parquet`）は引き続き BDF リーダーにルーティングされます。汎用 parquet リーダーは BDF でない `.parquet` ファイルのフォールバックとしてのみ使用されます。 ## Battery Data Format (BDF) `ionworksdata` は Battery Data Alliance が定義する [Battery Data Format (BDF)](https://battery-data-alliance.github.io/battery-data-format/) のファイルを読み書きできます。CSV、gzip 圧縮 CSV、parquet のすべてのバリアントがサポートされます。ファイルはヘッダーまたは拡張子（`.bdf`、`.bdf.gz`、`.bdf.parquet`）で自動検出されます。 ```python theme={null} import ionworksdata as iwd # Read df = iwd.read.bdf("cell.bdf") df = iwd.read.time_series("cell.bdf.parquet") # via the generic entrypoint # Write iwd.write.bdf(df, "out.bdf") # CSV with preferred labels iwd.write.bdf(df, "out.bdf.gz") # gzipped CSV iwd.write.bdf(df, "out.bdf.parquet") # parquet iwd.write.bdf(df, "out.bdf", use_machine_readable_names=True) ``` BDF は電流の符号規約を強制しません。リーダーは読み込み時に電流を Ionworks の規約（**正 = 放電**）に正規化するため、反対の IEC 規約に従うサードパーティの BDF ファイルは自動的に反転されます。ライターは入力 DataFrame の規約をそのまま出力します。放電が正の出力を保証する必要がある場合は、まず `transform.set_positive_current_for_discharge` でデータを通してください。 ## EIS とインピーダンスデータ | 計測機 | ファイル種別 | | -------- | ------------------------------------- | | BioLogic | `.mpt`、`.mpr`、`.txt`（インピーダンス列を含むファイル） | | Gamry | `.dta`（ZCURVE テーブル） | インピーダンスデータは `Frequency [Hz]`、`Z_Re [Ohm]`、`Z_Im [Ohm]`、`Z_Mod [Ohm]`、`Z_Phase [deg]` 列に読み込まれます。 ```python theme={null} import ionworksdata as iwd df = iwd.read.gamry("eis_measurement.dta") ``` 完全な列仕様と符号規約は[データフォーマット](/ja/data/format#eis-and-impedance-data)ページを参照してください。 ## トラブルシューティング ### 不正な電流符号規約 **問題:** 測定データをアップロードする際に、次のようなエラーが発生する: > Current sign convention error: positive current appears to be charge, not > discharge. **解決策:** Ionworks は **正の電流 = 放電**、**負の電流 = 充電** を想定しています。サイクラーが反対の規約を使用している場合は、アップロード前にデータを変換します: ```python theme={null} import ionworksdata as iwd data = iwd.transform.set_positive_current_for_discharge(data) ``` ### 曖昧な電流符号規約 **問題:** 測定データをアップロードする際に、次のようなエラーが発生する: > Current sign convention error: the sign convention is ambiguous. これは、すべての電流値が同じ符号を持っており、正が充電か放電かをバリデータが判定できない場合に発生します。 **解決策:** 同じ変換を使用します。電圧応答解析（両方の符号規約で OCV-R 等価回路モデルを当てはめる）を用いて、すべての電流が同じ符号を共有していても充電と放電の方向を推論します: ```python theme={null} import ionworksdata as iwd data = iwd.transform.set_positive_current_for_discharge(data) ``` 自動アプローチでデータに対してうまく動作しない（例えば平坦な電圧プロファイル）場合は、サイクラーのステップ種別列に基づいて符号を手動で適用できます: ```python theme={null} import polars as pl # Replace "Step type" and "charge" with your cycler's column name # and step-type label (e.g. "CC_Charge", "Charge", "C", etc.) data = data.with_columns( pl.when(pl.col("Step type") == "charge") .then(-pl.col("Current [A]").abs()) .otherwise(pl.col("Current [A]").abs()) .alias("Current [A]") ) ``` ### 符号なし（大きさのみ）の電流 **問題:** 測定データをアップロードする際に、次のようなエラーが発生する: > Current sign convention error: the current appears to be unsigned > (magnitude-only) but contains both charge and discharge steps. Sign it using > the cycler mode column via > `ionworksdata.transform.set_positive_current_for_discharge(data)` before > validation. これは、休止以外のすべての電流サンプルが正であるにもかかわらず、データに充電ステップと放電ステップの両方が明らかに含まれている場合に発生します。これは、電流を大きさとして記録し、方向は `Current [A]` の符号ではなく別のモード列でエンコードするサイクラーの特徴です。この問題は[曖昧な符号規約](#曖昧な電流符号規約)とは異なり、サイクラー自身の充電/放電ラベルから電流を符号付け直すという具体的で決定論的な修正方法があります。 **解決策:** `set_positive_current_for_discharge` を実行します。休止以外の電流がすべて正で、かつ充電ステップと放電ステップの両方が存在することを検出した場合、電圧応答ヒューリスティックにフォールバックする代わりに、サイクラーのモード列を使って充電ステップのサンプルの符号を反転します: ```python theme={null} import ionworksdata as iwd data = iwd.transform.set_positive_current_for_discharge(data) ``` issue コードは `CURRENT_SIGN_UNSIGNED` です。プロンプトなしで自動修正を適用したい場合は、これに明示的に分岐してください: ```python theme={null} from ionworks import IssueCode, MeasurementValidationError import ionworksdata as iwd try: client.cell_measurement.create(cell_instance.id, data) except MeasurementValidationError as e: if e.has_code(IssueCode.CURRENT_SIGN_UNSIGNED): data = iwd.transform.set_positive_current_for_discharge(data) client.cell_measurement.create(cell_instance.id, data) else: raise ``` ### 充電と放電の累積列が入れ替わっている **問題:** `validate_strict=True` でアップロードする際に、次のようなエラーが発生する: > Column 'Discharge capacity \[A.h]' disagrees with the running integral of > 'max(I, 0)' over time by up to 96.4% (exceeds 10% tolerance). …そして、報告されている `Discharge capacity [A.h]` が充電半波を追跡しているように見え、`Charge capacity [A.h]` でも同じく反転した挙動が見られる。これは一部のハーフセル出力や、2 つの累積列を逆にラベル付けするサイクラー設定で発生します。 **解決策:** `fix_swapped_charge_discharge_columns` を使用して、各列を電流（およびエネルギーの場合は電力）の台形積分と比較し、入れ替えた割り当てが許容範囲内で、そのままの割り当てが許容範囲外の場合にペアの名前を変更します。 ```python theme={null} import ionworksdata as iwd # Required prerequisite — without a known sign convention, "Discharge" vs # "Charge" has no ground-truth meaning to compare against. data = iwd.transform.set_positive_current_for_discharge(data) # Inspects "Discharge/Charge capacity [A.h]" and, when present, # "Discharge/Charge energy [W.h]". Returns `data` unchanged when no swap # is warranted. data = iwd.transform.fix_swapped_charge_discharge_columns(data) ``` 変換には `Time [s]`、`Step count`、`Current [A]` の列が必要で、エネルギーペアには `Power [W]`（または `Power [W]` がない場合は `Voltage [V] * Current [A]`）を使用します。デフォルトの `tolerance` は相対誤差 10 % です。データに対してより厳しい/緩い閾値が必要な場合は、別の値を渡してください: ```python theme={null} data = iwd.transform.fix_swapped_charge_discharge_columns(data, tolerance=0.05) ``` この関数は、正の電流が放電に対応しない場合はラベルの入れ替えを拒否します。既知の符号規約がなければどちらの列がどちらかを判別する手段がなく、入れ替えは本物の符号規約バグをマスクしてしまうためです。最初に `set_positive_current_for_discharge` を実行してください。 ### 時間が累積でない **問題:** 各サイクルで時間が 0 にリセットされる。 **解決策:** 累積時間オフセットを追跡します: ```python theme={null} cumulative_time_offset = 0.0 for cycle_num, cycle_df in df.group_by("Cycle from cycler"): cycle_df = cycle_df.with_columns( (pl.col("Time [s]") + cumulative_time_offset).alias("Time [s]") ) cumulative_time_offset = cycle_df["Time [s]"].max() ``` ### ステップカウントが累積でない **問題:** 各サイクルでステップカウントがリセットされる。 **解決策:** サイクル間でステップカウントオフセットを追跡します: ```python theme={null} step_offset = 0 for cycle_num, cycle_df in df.group_by("Cycle count"): cycle_df = cycle_df.with_columns( (pl.col("Step from cycler") + step_offset).alias("Step count") ) step_offset = cycle_df["Step count"].max() + 1 ``` ### 容量列の欠落 **問題:** 容量の計算に失敗する。 **解決策:** 容量を計算する前に `Time [s]`、`Current [A]`、`Voltage [V]` の列があることを確認してください。 ### UTF-8 でない CSV ファイル（例: Neware） **問題:** Neware の CSV ファイルの読み込みがエンコーディングエラーで失敗する。 **解決策:** Neware リーダーは UTF-8 デコードが失敗した場合に自動的に Latin-1 にフォールバックするため、ほとんどの場合アクションは不要です: ```python theme={null} import ionworksdata as iwd df = iwd.read.time_series("neware_data.csv", "neware") ``` エンコーディングを明示的に制御するには: ```python theme={null} df = iwd.read.time_series( "neware_data.csv", "neware", options={"file_encoding": "latin-1"}, ) ``` ## 次のステップ 認識される列、単位、符号規約の完全なリファレンスです。 準備したデータをセル仕様、インスタンス、測定としてアップロードします。 `read`、`write`、`transform`、`steps`、`load` の完全なリファレンスです。 問題を報告したり、ソースを閲覧したりできます。