matlab-extract-battery-features

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

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 IC/DV/DT will silently produce no features. Always set CC=true when enabling IC, DV, or DT.

---

Individual Functions

batteryMeasurementFeatures — Statistics and Cumulative

Extracts statistical and cumulative features from any single-phase segment — works on partial or full charge/discharge data (CC, CV, or mixed CC+CV). Only requirement: current must not change sign within the segment.

featureTable = batteryMeasurementFeatures(V, I, T, t, ...
    NoiseTolerance=1e-4);

% T and t are optional:
featureTable = batteryMeasurementFeatures(V, I);          % stats only
featureTable = batteryMeasurementFeatures(V, I, [], t);   % stats + cumulative (no temp)
featureTable = batteryMeasurementFeatures(V, I, T, t);    % all features

Output features:

• Voltage: max, min, mean, std, skewness, kurtosis
• Current: max, min, mean, std, skewness, kurtosis
• Temperature (if provided): max, min, mean, std
• Cumulative (if time provided): capacity (Ah), energy (Wh), duration, start voltage

batteryDifferentialCurves — IC, DV, DT Curves

Computes differential curves from a constant-current (CC) segment — charge or discharge. Requires current to be approximately constant (95% of samples must have dI/dt < tolerance). Does NOT work on CV or mixed CC+CV segments.

[dQdV, dVdQ, dTdV] = batteryDifferentialCurves(V, I, T, t, ...
    NoiseTolerance=1e-4, ...
    PreSmoothingMethod="none", ...          % "none","movmean","sgolay", etc.
    PreSmoothingWindowSize=10, ...
    PostSmoothingMethod="gaussian", ...     % default: "gaussian"
    PostSmoothingWindowSize=10, ...
    NumInterpolatedPoints=1000, ...
    InterpolationMethod="linear");

Output tables:

• dQdV — columns: IC, interpolatedVoltage, interpolatedTime
• dVdQ — columns: DV, interpolatedTime, interpolatedVoltage
• dTdV — columns: DT, interpolatedVoltage, interpolatedTemperature (empty if T not provided)

batteryDifferentialCurveFeatures — Peak Features from Curves

Extracts peak-based features from a differential curve:

% From table output of batteryDifferentialCurves:
features = batteryDifferentialCurveFeatures(dQdV);

% Or from raw vectors:
features = batteryDifferentialCurveFeatures(curveValues, xAxisValues);

Output features per peak: value, width, location (x-axis), prominence, area, left/right slopes, total area under curve, statistical features.

---

Mappings, Phase, and Next Steps

Stop After Extraction — Offer Next Steps

Once the feature table is extracted and displayed, stop and present available next steps to the user. Do not autonomously proceed to visualization, feature ranking, or script saving. Example:

Feature extraction complete — 70 features across 5 cycles.

What would you like to do next?

• Visualize: Plot feature trends over cycles (e.g., capacity fade, IC peak shift)
• Rank features: Identify most discriminative features for your analysis goal
• Export: Save the feature table to a .mat or .csv file
• Refine: Adjust feature categories, CyclingPhase, or smoothing parameters

Only execute a next step when the user explicitly requests it. This applies even if the original prompt contains phrasing like "show me" or "plot" — extract first, present the table, then offer to visualize.

Column Mapping: Ambiguity Resolution

When inspecting data columns, multiple columns may be plausible candidates for a single variable (e.g., both Test_Time and DateTime could be TimeVariable). Apply the deterministic rule when one exists; only stop when it doesn't (see Interaction Model: Stop or Proceed):

1. Prefer datetime/duration over numeric elapsed time. If one candidate is datetime/duration type and another is numeric seconds, the datetime column wins — this is a rule, not a judgment call, so apply it and report it rather than asking. In your report, note the alternative you considered (e.g., "I found both Test_Time (numeric) and DateTime (datetime type) — used DateTime as it is a proper datetime column").
2. Stop only when the rule can't decide. If two candidates share the same type (e.g. two numeric elapsed-time columns) so no rule can pick, ask the user which to use. Likewise if a required variable has no clear column.
3. When you proceed, report the mappings, CyclingPhase, and DT decision after extracting — with an undo invitation. When you stop (per the Interaction Model), present the proposed mappings first. Example report/proposal block:

Column mappings used:

• CurrentVariable → "Current"
• VoltageVariable → "Voltage"
• TimeVariable → "DateTime" (also saw numeric Test_Time; chose the datetime column)
• CycleIndexVariable → "Cycle_Index"
• StepIndexVariable → "Step_Index"
• TemperatureVariable → "Temperature"

If any mapping or the phase choice looks wrong, tell me and I'll re-run.

Unnamed Data (Matrices Without Column Names)

When cycling data arrives as a raw numeric matrix (no column names), infer column roles from value characteristics, then confirm with the user before proceeding:

• Current alternates sign (charge/discharge)
• Voltage stays within cell limits (monotonic within a phase)
• Time is monotonically increasing
• Cycle and step indices are integer-valued and repeat across cycles

Present the inferred mapping and ask the user to confirm before extracting.

For cycling test analysis

Inspect first, don't interrogate. Load the data and read its column names and types yourself rather than asking the user to describe them. Map the columns by rule, run checkCyclingProtocol for the phase choice, and select feature categories from the user's stated goal via the Feature Selection Guide below. Only ask the user when a STOP condition applies (Interaction Model) — e.g. the format is a raw unnamed matrix, or a time/required column is genuinely ambiguous. If the goal itself is unclear (no SOH/RUL/diagnosis stated), ask what they want to learn — that drives feature selection.

---

Feature Selection Guide

For SOH / Capacity Estimation

• Primary: CycleCumulative (capacity, energy), IC peak features (track electrode degradation)
• Supporting: Statistics (voltage mean shift), CC duration (charging time increase)
• Why IC: Peak positions shift and heights decrease as electrodes degrade — most physically meaningful

For RUL / End-of-Life Prediction

• Primary: IC + CycleCumulative trending over cycles
• Supporting: CCCV energy ratio (CC/CV balance shifts as internal resistance grows)

For Fast Charging Optimization

• Primary: CV features (CV duration increase = lithium plating risk)
• Supporting: DT features (thermal signature of plating), Statistics (temperature rise)

---

Common Pitfalls

1. Mixing charge and discharge data. Both functions require single-phase data (current must not change sign). batteryMeasurementFeatures accepts any partial or full charge/discharge segment (CC, CV, or mixed). batteryDifferentialCurves is stricter — requires constant-current data specifically.

2. Time format. Time must be datetime or duration, NOT numeric seconds. Convert: t = seconds(numericTime) or t = datetime(numericTime, 'ConvertFrom', 'posixtime').

3. Over-smoothing IC/DV curves. Large PostSmoothingWindowSize destroys degradation-sensitive peaks. Start with default (10), increase only if data is very noisy. Validate visually.

4. Extracting all features blindly. 165+ features with <50 cycles = overfitting risk. Use the feature selection guide above to pick physically meaningful subsets.

5. Wrong units. Current in Amps (not mA), voltage in Volts, time in seconds-based duration. Capacity is computed as Ah internally using cumtrapz(I, t)/3600.

6. Missing temperature for DT curves. batteryDifferentialCurves returns empty dTdV if T is not provided. Set DT=true when temperature data is present; set DT=false when it is not.

7. When to use individual functions vs full pipeline. batteryTestFeatureExtractor + batteryTestDataParser is for multi-cycle data. For individual segments (partial charge, single discharge phase, etc.), use batteryMeasurementFeatures or batteryDifferentialCurves directly — they don't require full cycling data.

8. CCCV requires both CC and CV. If either CC=false or CV=false, CCCV features cannot be computed. The extractor handles this automatically.

9. IC/DV/DT require CC=true. Differential curve features (IC, DV, DT) are computed from the CC segments identified by the parser. Setting IC=true with CC=false silently produces no IC features. Always enable CC=true when using IC, DV, or DT.

---

Typical Workflows

Before running any workflow: Apply the Interaction Model (Stop or Proceed). If no STOP condition holds, run the extraction and report the mappings, CyclingPhase, and feature configuration afterward; if one does, present the proposal and wait for confirmation first.

Workflow 1: Track degradation across cycles

% Check protocol consistency first (run with the MATLAB current folder set to the
% skill's scripts/ directory via the MCP project_path — do not use addpath)
result = checkCyclingProtocol(cyclingData, ...
    CurrentVariable="I", VoltageVariable="V", ...
    TimeVariable="t", CycleIndexVariable="Cycle", ...
    StepIndexVariable="Step");

% Parse multi-cycle data (exclude anomalous cycles if user confirmed)
parser = batteryTestDataParser(cyclingData, ...
    CurrentVariable="I", VoltageVariable="V", ...
    TimeVariable="t", CycleIndexVariable="Cycle", ...
    StepIndexVariable="Step", ...
    ExcludedCycles=result.AnomalousCycles);

% Extract IC + capacity features per cycle
% Note: CC=true is required for IC/DV/DT to work
extractor = batteryTestFeatureExtractor( ...
    CyclingPhase="Charge", IC=true, CycleCumulative=true, ...
    Statistics=false, CC=true, CV=false, CCCV=false);
features = extract(extractor, parser);

% features is a table: 1 row per cycle, columns = feature values
% Use for trending, anomaly detection, or RUL model training

Workflow 2: Partial charge segment analysis

% batteryMeasurementFeatures works on ANY single-phase segment:
% partial charge, partial discharge, CC, CV, or mixed CC+CV
V = partialChargeData.Voltage;
I = partialChargeData.Current;
T = partialChargeData.Temperature;
t = partialChargeData.Time;
stats = batteryMeasurementFeatures(V, I, T, t);

% For differential curves, data MUST be constant-current:
idx = data.Mode == "CC";
[dQdV, ~, ~] = batteryDifferentialCurves(V(idx), I(idx), T(idx), t(idx), ...
    PostSmoothingMethod="gaussian", PostSmoothingWindowSize=15);
icFeatures = batteryDifferentialCurveFeatures(dQdV);

(For the full function list with availability and selection guidance, see the API Overview table near the top of this skill.)

---

Copyright 2026 The MathWorks, Inc.

---