.. _auto_battery_field_cell_imbalance:

*BATTERY CELL IMBALANCE*
========================

Reads a BMS SSV file and computes per-cell voltage statistics (avg, min, max, σ, outlier flag) across the full recording, then emits pack-level KPIs including voltage spread, worst-cell deviation, outlier count, and drift trend. Use this worker to characterise cell imbalance from field BMS data before further battery health analysis.

When to use
-----------

Tagged: ``analytics``, ``battery``, ``bms``, ``cell``, ``cell-voltage``, ``drift``, ``extraction``, ``field-data``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - BMS SSV file
     - ssv_file
     - file
     - —
     - ✓
     - Path to a semicolon-separated BMS recording file (SSV format) whose header row names the columns; required — the worker throws if absent or unreadable.
   * - Channel map
     - channel_map
     - mapper
     - —
     - 
     - Optional mapper that overrides automatic column resolution, mapping actual SSV column names to the canonical channels 'time' and the 'cell_voltages' family; leave empty to rely on built-in alias registry.
   * - Outlier z-score threshold
     - outlier_z_threshold
     - scalar
     - 3.0
     - 
     - Z-score threshold (dimensionless) applied to per-cell average voltages to flag outlier cells; default 3.0 — lower values flag more cells, raise to tighten the criterion.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Per-cell rows
     - per_cell_dataset
     - dataset
     - Dataset with one row per cell containing cell_id, cell_voltage_avg (V), cell_voltage_min (V), cell_voltage_max (V), cell_voltage_stdev (V), and a boolean flag_outlier indicating z-score exceedance.
   * - Imbalance KPIs
     - kpis
     - keyvalue
     - Key-value map of pack-level imbalance KPIs: cell_voltage_spread_mv (mV), max_dev_mv (mV), n_outliers (count), worst_cell_id (integer cell index), and voltage_drift_trend_mv_per_hr (mV/hr linear slope of instantaneous spread over the recording).

Disciplines
-----------

- cae.postprocessing.extraction
- data.dataset.ingest
- data.statistics
- engineering.battery

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>battery_field_cell_imbalance</code>. Schema hash: <code>6a42ea72f792</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>