---

name: matlab-extract-battery-features description: > Extract battery features for degradation analysis and health monitoring in MATLAB. Covers cycling test features, differential curves (IC/DV/DT), and measurement statistics. Use when working with battery cycling data, SOH estimation, RUL prediction, or any battery test data analysis in MATLAB. Triggers on battery* functions such as batteryTestDataParser, batteryTestFeatureExtractor, batteryMeasurementFeatures, batteryDifferentialCurves. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

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):

% 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 are only meaningful for degradation trending when extracted from phases with a consistent protocol (same C-rate, same voltage limits) across all cycles.

Agent should:

1. After determining column mappings, run checkCyclingProtocol to assess protocol consistency. This helper ships with the skill at scripts/checkCyclingProtocol.m. Make it callable by setting the MATLAB current folder to that scripts/ directory (pass its absolute path as the MCP tool's project_path) — do not call addpath. Reference the user's data by absolute path.

   result = checkCyclingProtocol(data, ...
       CurrentVariable="<mapped>", VoltageVariable="<mapped>", ...
       TimeVariable="<mapped>", CycleIndexVariable="<mapped>", ...
       StepIndexVariable="<mapped>", TemperatureVariable="<mapped>");
   

   checkCyclingProtocol interface:

   • Input: data (table of cycling data) plus the Name-Value column mappings above. TemperatureVariable is optional (default "", disabled).
   • Output: a struct result with fields:
     • RecommendedPhase — "Charge", "Discharge", or "Both" (the proposed CyclingPhase)
     • ChargeConsistent / DischargeConsistent — logical; whether each phase has a stable repeating protocol across cycles
     • AnomalousCycles — cycle indices with non-standard step sequences (candidates for ExcludedCycles)
     • MajorityCycles — cycle indices matching the dominant protocol
     • NumCycles — number of cycles in the data
     • StepTable — per-step reference protocol (phase, CC/CV/rest %, median current, voltage range, duration)
   • The function also prints a human-readable protocol summary to stdout.

2. Use the output to propose CyclingPhase based solely on protocol consistency — justify your choice by citing the repeating C-rate and voltage limits shown in the reference protocol table.

3. Do NOT mention the user's analysis goal (SOH, RUL, degradation, health tracking, etc.) as part of the CyclingPhase justification. The choice is purely about which phase has a fixed, repeating protocol — the analysis goal is irrelevant to this decision.

4. Surface any goal-vs-data tension — but do not let it change the phase choice. The phase you chose above is final and consistency-driven. Separately, if the consistent phase is not the one conventionally associated with the user's stated goal (charge-side IC / dQ-dV for SOH and lithium-inventory loss; discharge for delivered-capacity fade), say so explicitly instead of silently extracting from the phase the data happens to support:

   You asked about <goal>, which conventionally leans on <charge/discharge>-side features (e.g. IC peak shifts for SOH). In your data, though, the <charge/discharge> protocol varies across cycles, so those features would not trend on a fixed baseline. Only the <other> protocol is consistent, so I'm extracting from there. Here's what the consistent phase can still tell you about <goal>: <what it can/can't deliver>.

   This is a communication step, not a phase-selection input. Never pick the inconsistent phase just because the goal would normally prefer it — report the tension and proceed with the consistent phase (or ask the user whether they can supply data with a stable protocol on the phase they need).

5. If anomalous cycles are detected, inform the user and ask whether to exclude them:

   The protocol check found N anomalous cycles (X.X%) with non-standard step sequences: [list or first 10]. These cycles likely have data collection issues (missing steps). Would you like to exclude them? If yes, I'll set ExcludedCycles=[...] on the parser.

   Only add ExcludedCycles after the user confirms. Do not silently exclude them.

6. Report the CyclingPhase choice (and any tension from step 4) alongside the NV-pair mappings — in the after-extraction report if you proceeded, or in the confirmation if a STOP condition applied.

If protocol consistency cannot be determined from the data (neither phase is consistent), this is a STOP condition — ask the user which phase has a fixed protocol before extracting.

Feature Categories (165+ features total)

| Category | Property | Features | Tracks | |----------|----------|----------|--------| | Statistics | Statistics=true | max, min, mean, std, skewness, kurtosis of V, I, T | General degradation trends | | CycleCumulative | CycleCumulative=true | Capacity (Ah), energy (Wh), duration, start voltage | Capacity fade, energy efficiency | | CC | CC=true | CC duration, median current, slope, energy, skewness, kurtosis | CC phase degradation | | CV | CV=true | CV duration, median voltage, slope, energy, skewness, kurtosis | CV phase degradation | | CCCV | CCCV=true | Energy ratio (CC/CV), energy difference | Phase balance shift | | IC | IC=true | Peak value, width, location, prominence, area, slopes | Electrode degradation mechanisms | | DV | DV=true | Peak features from dV/dQ curve | Electrode capacity balance | | DT | DT=true | Peak features from dT/dV curve | Thermal degradation signatures |

Dependency: IC, DV, and DT require CC=true. These differential curve features are computed from CC segments identified by the parser. If CC=false, no CC segments are identified and