matlab-extract-battery-features

# Battery Feature Extraction


## When to Use

- Any task involving battery test data feature extraction: cycling degradation trending, SOH estimation, RUL prediction, capacity fade analysis
- Differential curve analysis (IC dQ/dV, DV dV/dQ, DT dT/dV) for electrode degradation diagnosis
- Single-segment measurement statistics from partial or full charge/discharge data
- Batch processing of multiple battery cycling test files

## When NOT to Use

- The task has no battery test data context (no cycling or differential-curve data)
- The primary goal is battery simulation, equivalent circuit modeling, or Simulink battery plant models
- The task is general signal processing, machine learning model training, or visualization without feature extraction
- The data is not from electrochemical battery tests (e.g., fuel cells, supercapacitors, or generic sensor data)

This skill covers the 5 released PMT battery feature extraction functions. These functions work natively with MATLAB tables and vectors, handle segmentation and peak detection internally, and are performance-optimized. Prefer these PMT functions over manual feature computation (e.g., hand-coded cumtrapz loops, manual peak finding). Override only if the user explicitly requests otherwise.

---

## API Overview

The Predictive Maintenance Toolbox provides **5 public functions** for battery feature extraction:

```
                        Battery Cycling Test Data
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
              Full Pipeline               Individual Functions
                    │                           │
             batteryTest-                       ├── batteryMeasurementFeatures
             DataParser                         ├── batteryDifferentialCurves
                 +                              └── batteryDifferentialCurveFeatures
             batteryTest-
             Feature-
             Extractor
                 │
                 ▼
             Feature table
```

| Function | Input | Output | Use When | Available From |
|----------|-------|--------|----------|----------------|
| `batteryTestDataParser` | Raw cycling table | Parser object (segmented data) | You have multi-cycle data needing segmentation | R2024b |
| `batteryTestFeatureExtractor` | Options | Extractor object | Full pipeline: parser → all cycling features | R2024b |
| `batteryMeasurementFeatures` | V, I, T, t vectors | Statistical + cumulative feature table | Any single-phase segment (partial or full charge/discharge) | R2026a |
| `batteryDifferentialCurves` | V, I, T, t vectors | dQ/dV, dV/dQ, dT/dV tables | Constant-current segment only (CC charge or CC discharge) | R2026a |
| `batteryDifferentialCurveFeatures` | Curve + x-axis | Peak feature table | Extracting features from differential curves | R2026a |

---

## Interaction Model: Stop or Proceed

Do not stop and ask before every extraction. Most decisions have a deterministic rule — apply it,
extract, and **report what you did** so the user can correct it. Only stop when a decision is
genuinely ambiguous *and* guessing it wrong would fail silently (plausible-but-wrong features).

**STOP and ask the user first** — but only when one of these is true:

1. **Two or more time-column candidates of the same type** (e.g. two numeric elapsed-time columns) —
   no rule can choose between them.
2. **Raw unnamed numeric matrix** — column roles must be inferred, not read from names.
3. **`checkCyclingProtocol` finds neither phase consistent** — no phase can be recommended.
4. **Anomalous cycles detected** — never silently exclude them (see CyclingPhase Selection, step 5).
5. **A required variable cannot be mapped** — a needed column is missing or its role is unclear.

**Otherwise PROCEED, then REPORT.** Apply the deterministic rules — datetime/duration beats numeric
time; use `checkCyclingProtocol`'s `RecommendedPhase`; set `DT=true` iff temperature is present; set
`CC=true` whenever IC/DV/DT is requested — write and run the extraction, then present in one turn:

- the column mappings used (noting any alternatives considered and why the chosen one won),
- the CyclingPhase and the consistency reason for it,
- any goal-vs-data tension, if present (see CyclingPhase Selection, step 4 — a report line, not a stop),
- the resulting feature table, followed by the "what next?" offer.

Close the report with an explicit undo invitation, e.g. *"If any mapping or the phase choice looks
wrong, tell me and I'll re-run."* This preserves the safety net without a blocking question.

---

## Full Pipeline: Cycling Test Feature Extraction

For multi-cycle battery test data (the most common workflow):

```matlab
% Step 1: Parse and segment the raw cycling data
parser = batteryTestDataParser(tbl, ...
    CurrentVariable="Current_A", ...
    VoltageVariable="Voltage_V", ...
    TimeVariable="Time", ...
    CycleIndexVariable="Cycle", ...
    StepIndexVariable="Step", ...
    TemperatureVariable="Temperature_C", ...
    ExcludedCycles=[], ...
    Tolerance=5e-5, ...
    NumInterpolatedPoints=1000, ...
    WindowSize=10);

% Step 2: Create extractor with desired feature categories
extractor = batteryTestFeatureExtractor( ...
    CyclingPhase="Charge", ...  % 'Charge', 'Discharge', or 'Both'
    Statistics=true, ...         % Voltage/current/temp statistics
    CycleCumulative=true, ...   % Capacity, energy, duration
    CC=true, ...                 % Constant-current segment features
    CV=true, ...                 % Constant-voltage segment features
    CCCV=true, ...               % CC+CV combined features
    IC=true, ...                 % Incremental capacity curve features
    DV=false, ...                % Differential voltage curve features
    DT=false);                   % Differential temperature curve features

% Step 3: Extract features
featureTable = extract(extractor, parser);
```

### CyclingPhase Selection

Features a