batteryTestDataParser
Convert data produced by battery lab testing into a format that is compatible with analysis and feature extraction
Since R2024b
Description
batteryTestDataParser
encapsulates measurement and operational
data from battery cycler testing. The object contains properties that identify critical
variables for battery data parsing and feature extraction.
Creating a batteryTestDataParser
object is the first step in extracting
predefined sets of operation-focused features using batteryTestFeatureExtractor
and extract
. You
can also extract your own customized features by using segmentData
to
add cycle and step information to the data that the parser encapsulates. For more information
on using these items together, see Characterize Battery Health Using Cycler-Based Test Data.
Creation
Syntax
Description
encapsulates the data bdp
= batteryDataParser(data
,CurrentVariable
=cv,VoltageVariable
=vv,TimeVariable
=tt,CycleIndexVariable
=civ,StepIndexVariable
=siv)data
in a
batteryTestDataParser
object bdp
and configures
bdp
with the data variable names specified by the remaining
arguments.
The variable properties in this syntax must be set before you can use any of the
object functions such as segmentData
or extract features using batteryTestFeatureExtractor
. Alternatively, you can use the simpler
construction syntax of the form bdp = batteryTestDataParser(data)
, and
then use dot notation to assign the variable names. For example, use the following set of
commands to achieve the same results as the previous
syntax.
bdp = batteryTestDataParser(data) bdp.CurrentVariable = cv bdp.VoltageVariable = vv bdp.TimeVariable = tt bdp.CycleIndexVariable = civ bdp.StepIndexVariable = siv
specifies additional object properties using name-value arguments. For example,
bdp
= batteryDataParser(___,Name=Value)Tolerance=0.001
sets the variance threshold for identifying cycling
modes.
As with the required properties in the first syntax, you can also set these properties
using dot notation. For example, set Tolerance
using
bd.Tolerance = 0.001
.
Input Arguments
data
— Unsegmented battery data
table | timetable
Unsegmented battery data, specified as a table or timetable. Each column contains
a variable name and the values corresponding to that variable. The following table
describes the variables in data
that batteryTestDataParser
has corresponding variable-name properties for and
uses. Other data
variables are ignored.
Variable Type | Data Description |
---|---|
Current | Current value, specified as numeric value in amperes. |
Voltage | Voltage value, specified as a numeric value in volts. |
Time | Time value, specified as a datetime or duration value. |
Cycle Index | Cycle Index, specified as an integer. The cycle index represents the complete sequence of phases, including charging, discharging, and resting phases, that a battery undergoes during a single cycle of its testing protocol. The value increments with each completed cycle. |
Step Index | Step index, specified as an integer that identifies a specific operation within a battery cell test. Each step index corresponds to a distinct set of operational parameters and conditions. |
Temperature (Optional) | Temperature, specified as a numeric value in degrees Celsius. |
Properties
CurrentVariable
— Variable name for current values
string
Variable name for current values, specified as a string that is identical to the
corresponding column name in data
. This property is required for
follow-on processing.
VoltageVariable
— Variable name for voltage values
string
Variable name for voltage values, specified as a string that is identical to the
corresponding column name in data
. This property is required for
follow-on processing.
TimeVariable
— Variable name for time values
string
Variable name for current values, specified as a string that is identical to the
corresponding column name in data
. This property is required when
data
is a table. When data
is a timetable,
the software uses the rowTimes
property of the timetable for the
variable name "DateTime"
and the time values.
CycleIndexVariable
— Variable name for cycle index values
string
Variable name for current values, specified as a string that is identical to the
corresponding column name in data
. This property is required for
follow-on processing.
StepIndexVariable
— Variable name for step index values
string
Variable name for current values, specified as a string that is identical to the
corresponding column name in data
. This property is required for
follow-on processing.
TemperatureVariable
— Variable name for temperature value
string
Variable name for current values, specified as a string that is identical to the
corresponding column name in data
. This variable is optional for
follow-on processing.
ExcludedCycles
— cycle indices
integer vector
Cycles to exclude, specified as a vector of cycle indices. The values in this vector should correspond to a subset of the existing cycle indices. Values that fall outside this range are ignored.
Tolerance
— Variance threshold for identifying cycling modes
5e-05 (default) | numeric value
Threshold for allowable variance for accurately identifying cycling modes, specified as a numeric value.
NumInterpolatedPoints
— Number of interpolation points to use in curve calculation
1000 (default) | positive integer
Number of interpolation points to use in the curve calculations, specified as an integer.
WindowSize
— Window size for filtering differential curves
10 (default) | positive integer
Number of interpolation points to use in the curve calculations, specified as an integer.
IsSegmented
— Data segmentation flag
false
| true
This property is read-only.
Data segmentation flag, specified as false
before segmentation
and true
after applying segmentData
to bdp
.
If you reset any variable names after segmenting the data, the software resets
IsSegmented
to false
.
isTemperatureAvailable
— Temperature availability flag
false
| true
This property is read-only.
Temperature availability flag, specified as false
or
true
. This property is set to true
if
TemperatureVariable
has been set.
Object Functions
segmentData | Classify and organize raw battery measurement data by identifying cycling phase, cycling mode, and data validity |
computeDifferentialCurves | Compute incremental capacity, differential voltage, and differential temperature curves that can be used to analyze battery behavior under constant-current conditions |
Examples
Create Battery Test Data Parser and Extract Features
Load the data cleanData10
, which contains cleaned battery data through the tenth test cycle. It is known that Cycle 0 contains incorrectly collected data. Display the first five lines.
This example data represents only a small portion of battery life, at the beginning of the cycling test.
load clean_bat_data cleanData10 head(cleanData10,5)
Data_Point DateTime Step_Index Cycle_Index Current Voltage Charge_Capacity Discharge_Capacity Charge_Energy Discharge_Energy dV/dt Internal_Resistance Temperature __________ ____________________ __________ ___________ _______ _______ _______________ __________________ _____________ ________________ ___________ ___________________ ___________ 1 13-May-2017 03:21:40 0 0 0 3.3018 0 0 0 0 -1.5259e-05 0.022012 30.457 2 13-May-2017 03:21:40 0 0 0 3.3018 0 0 0 0 -1.5259e-05 0.022012 30.457 3 13-May-2017 03:21:50 0 0 0 3.3018 0 0 0 0 -2.6703e-05 0.022012 30.445 4 13-May-2017 03:22:00 0 0 0 3.3018 0 0 0 0 -1.5259e-05 0.022012 30.501 5 13-May-2017 03:22:10 0 0 0 3.3018 0 0 0 0 -8.5831e-06 0.022012 30.501
The table includes current, voltage, and temperature measurements, as well as indices for step and cycle index. The table also includes other measurements, such as Internal_Resistance
.
Create Battery Test Data Parser
Create the batteryTestDataParser
object bdp
. Use dot notation to assign variable names in the table to properties. In this example, the battery cycle is temperature controlled to a roughly constant value, and can be excluded from the analysis. Therefore, do not set the TemperatureVariable
property name.
bdp = batteryTestDataParser(cleanData10); bdp.CurrentVariable = "Current"; bdp.VoltageVariable = "Voltage"; bdp.TimeVariable = "DateTime"; bdp.CycleIndexVariable = "Cycle_Index"; bdp.StepIndexVariable = "Step_Index"
bdp = BatteryTestDataParser with properties: CurrentVariable: "Current" VoltageVariable: "Voltage" TimeVariable: "DateTime" CycleIndexVariable: "Cycle_Index" StepIndexVariable: "Step_Index" TemperatureVariable: "" ExcludedCycles: [1x0 double] Tolerance: 5.0000e-05 NumInterpolatedPoints: 1000 WindowSize: 10 IsSegmented: 0 IsTemperatureAvailable: 0
bdp
contains the properties that you set, and ignores other table columns.
Exclude Known Erroneous Cycle Data
Exclude Cycle-0 data from processing by setting the ExcludedCycles
property to 0.
bdp.ExcludedCycles = 0;
Segment Data
Segment the data so that it can be analyzed by cycle and step.
bdpseg = segmentData(bdp); head(bdpseg,5)
Data_Point DateTime Step_Index Cycle_Index Current Voltage Charge_Capacity Discharge_Capacity Charge_Energy Discharge_Energy dV/dt Internal_Resistance Temperature CyclingModes CyclingPhases IsValid __________ ____________________ __________ ___________ _______ _______ _______________ __________________ _____________ ________________ ___________ ___________________ ___________ ____________ _____________ _______ 1 13-May-2017 03:21:40 0 0 0 3.3018 0 0 0 0 -1.5259e-05 0.022012 30.457 Undefined Undefined false 2 13-May-2017 03:21:40 0 0 0 3.3018 0 0 0 0 -1.5259e-05 0.022012 30.457 Undefined Undefined false 3 13-May-2017 03:21:50 0 0 0 3.3018 0 0 0 0 -2.6703e-05 0.022012 30.445 Undefined Undefined false 4 13-May-2017 03:22:00 0 0 0 3.3018 0 0 0 0 -1.5259e-05 0.022012 30.501 Undefined Undefined false 5 13-May-2017 03:22:10 0 0 0 3.3018 0 0 0 0 -8.5831e-06 0.022012 30.501 Undefined Undefined false
The software adds columns for Step_Index
, Cycle_Index
, and IsValid
. Because the data begins with Cycle 0 and you are excluding this cycle, IsValid
is set to false
for this data. The data table encapsulated by bdp
also contains these new columns.
Create Battery Test Feature Extractor
Create a batteryTestFeatureExtractor
object bft
.
bft = batteryTestFeatureExtractor()
bft = BatteryTestFeatureExtractor with properties: CyclingPhase: "Charge" Statistics: 1 CycleCumulative: 1 CC: 1 CV: 1 CCCV: 1 IC: 1 DV: 0 DT: 0
Using dot notation, specify that both charge and discharge cycles be used for features. Accept the default settings for the feature set selections.
bft.CyclingPhase = "Both";
Extract Features
Use extract
to extract the specified features into the feature table ft
.
ft = extract(bft,bdp);
Display the first five rows of ft
.
head(ft,5)
Cycle_Index Charge_cumulativeCapacity Charge_cumulativeEnergy Charge_duration Charge_startVoltage Charge_Voltage_max Charge_Voltage_min Charge_Voltage_mean Charge_Voltage_std Charge_Voltage_skewness Charge_Voltage_kurtosis Charge_Current_max Charge_Current_min Charge_Current_mean Charge_Current_std Charge_Current_skewness Charge_Current_kurtosis Charge_Step5_IC_peak Charge_Step5_IC_peakWidth Charge_Step5_IC_peakLocation Charge_Step5_IC_peakProminence Charge_Step5_IC_peaksArea Charge_Step5_IC_peakLeftSlope Charge_Step5_IC_peakRightSlope Charge_Step5_IC_area Charge_Step5_IC_max Charge_Step5_IC_min Charge_Step5_IC_mean Charge_Step5_IC_std Charge_Step5_IC_skewness Charge_Step5_IC_kurtosis Charge_Step5_CC_duration Charge_Step5_CC_currentMedian Charge_Step5_CC_slope Charge_Step5_CC_energy Charge_Step5_CC_skewness Charge_Step5_CC_kurtosis Charge_Step6_IC_peak Charge_Step6_IC_peakWidth Charge_Step6_IC_peakLocation Charge_Step6_IC_peakProminence Charge_Step6_IC_peaksArea Charge_Step6_IC_peakLeftSlope Charge_Step6_IC_peakRightSlope Charge_Step6_IC_area Charge_Step6_IC_max Charge_Step6_IC_min Charge_Step6_IC_mean Charge_Step6_IC_std Charge_Step6_IC_skewness Charge_Step6_IC_kurtosis Charge_Step6_CC_duration Charge_Step6_CC_currentMedian Charge_Step6_CC_energy Charge_Step6_CC_skewness Charge_Step6_CC_kurtosis Charge_Step9_IC_peak Charge_Step9_IC_peakWidth Charge_Step9_IC_peakLocation Charge_Step9_IC_peakProminence Charge_Step9_IC_peaksArea Charge_Step9_IC_peakLeftSlope Charge_Step9_IC_peakRightSlope Charge_Step9_IC_area Charge_Step9_IC_max Charge_Step9_IC_min Charge_Step9_IC_mean Charge_Step9_IC_std Charge_Step9_IC_skewness Charge_Step9_IC_kurtosis Charge_Step9_CC_duration Charge_Step9_CC_currentMedian Charge_Step9_CC_energy Charge_Step9_CC_skewness Charge_Step9_CC_kurtosis Charge_Step9_CV_duration Charge_Step9_CV_voltageMedian Charge_Step9_CV_slope Charge_Step9_CV_energy Charge_Step9_CV_skewness Charge_Step9_CV_kurtosis Charge_Step9_CCCV_energyRatio Charge_Step9_CCCV_energyDifference Charge_Step5_CC_tInv Discharge_cumulativeCapacity Discharge_cumulativeEnergy Discharge_duration Discharge_startVoltage Discharge_Voltage_max Discharge_Voltage_min Discharge_Voltage_mean Discharge_Voltage_std Discharge_Voltage_skewness Discharge_Voltage_kurtosis Discharge_Current_max Discharge_Current_min Discharge_Current_mean Discharge_Current_std Discharge_Current_skewness Discharge_Current_kurtosis Discharge_Step10_IC_peak Discharge_Step10_IC_peakWidth Discharge_Step10_IC_peakLocation Discharge_Step10_IC_peakProminence Discharge_Step10_IC_peaksArea Discharge_Step10_IC_peakLeftSlope Discharge_Step10_IC_peakRightSlope Discharge_Step10_IC_area Discharge_Step10_IC_max Discharge_Step10_IC_min Discharge_Step10_IC_mean Discharge_Step10_IC_std Discharge_Step10_IC_skewness Discharge_Step10_IC_kurtosis Discharge_Step10_CC_duration Discharge_Step10_CC_currentMedian Discharge_Step10_CC_slope Discharge_Step10_CC_energy Discharge_Step10_CC_skewness Discharge_Step10_CC_kurtosis Discharge_Step10_CC_tInv Discharge_Step10_CV_duration Discharge_Step10_CV_voltageMedian Discharge_Step10_CV_slope Discharge_Step10_CV_energy Discharge_Step10_CV_skewness Discharge_Step10_CV_kurtosis Discharge_Step10_CCCV_energyRatio Discharge_Step10_CCCV_energyDifference ___________ _________________________ _______________________ _______________ ___________________ __________________ __________________ ___________________ __________________ _______________________ _______________________ __________________ __________________ ___________________ __________________ _______________________ _______________________ ____________________ _________________________ ____________________________ ______________________________ _________________________ _____________________________ ______________________________ ____________________ ___________________ ___________________ ____________________ ___________________ ________________________ ________________________ ________________________ _____________________________ _____________________ ______________________ ________________________ ________________________ ____________________ _________________________ ____________________________ ______________________________ _________________________ _____________________________ ______________________________ ____________________ ___________________ ___________________ ____________________ ___________________ ________________________ ________________________ ________________________ _____________________________ ______________________ ________________________ ________________________ ____________________ _________________________ ____________________________ ______________________________ _________________________ _____________________________ ______________________________ ____________________ ___________________ ___________________ ____________________ ___________________ ________________________ ________________________ ________________________ _____________________________ ______________________ ________________________ ________________________ ________________________ _____________________________ _____________________ ______________________ ________________________ ________________________ _____________________________ __________________________________ ____________________ ____________________________ __________________________ __________________ ______________________ _____________________ _____________________ ______________________ _____________________ __________________________ __________________________ _____________________ _____________________ ______________________ _____________________ __________________________ __________________________ ________________________ _____________________________ ________________________________ __________________________________ _____________________________ _________________________________ __________________________________ ________________________ _______________________ _______________________ ________________________ _______________________ ____________________________ ____________________________ ____________________________ _________________________________ _________________________ __________________________ ____________________________ ____________________________ ________________________ ____________________________ _________________________________ _________________________ __________________________ ____________________________ ____________________________ _________________________________ ______________________________________ 1 1.0912 3.8091 1837.2 3.2889 3.6004 3.2889 3.5127 0.076284 -0.26567 2.0059 6.6013 0.064569 2.1754 2.3511 0.94798 2.3503 5.4806 0.028983 3.53 0.48663 0.15111 14.045 -17.479 0.47486 5.4806 0.20359 1.8284 1.8936 0.91305 2.2617 260.48 6.5999 NaN 1.6668 -1.1606 3.3064 6.0466 0.0015526 3.4968 0.031648 NaN NaN NaN 0.28551 37.411 3.3344 6.5201 5.7697 4.0684 19.896 289.56 3.96 1.1145 0.23118 1.8814 2.7514 0.041081 3.4178 2.2495 0.093172 86.649 -40.036 0.17691 2.7514 0.14988 0.83718 0.82946 1.1874 2.968 579.99 1.1 0.61058 1.401 4.4162 610.01 3.6002 -0.00073938 0.11516 1.8343 5.892 5.3022 0.49542 NaN 1.0858 3.3053 1186.2 3.3297 3.3297 1.9996 2.7518 0.46306 -0.69494 1.7957 -0.021996 -4.4004 -3.6203 1.6577 1.6544 3.741 6.7975 0.11988 3.1491 6.6874 0.53131 40.006 -124.84 1.0703 6.7975 -0.014311 0.80703 1.5432 2.3837 7.7647 875.8 -4.4 0.00030465 3.2745 -1.363 3.6784 760.95 300.43 1.9999 0.00093293 0.016935 -2.3131 9.8519 193.36 3.2575 2 1.1011 3.8354 1846.4 3.1837 3.6004 3.1837 3.5029 0.088036 -0.73117 3.6177 6.6015 0.05476 2.2175 2.3674 0.90434 2.2705 5.5806 0.0057399 3.5324 0.27875 0.022226 55.087 -31.76 0.44216 5.5806 0.13184 1.2509 1.678 1.5393 3.9561 242.78 6.6003 0.013906 1.5463 -0.96454 2.5803 6.2122 0.0023982 3.495 0.063827 0.010988 25.474 -9.7076 0.28528 37.379 3.5681 6.7183 5.8188 4.0179 19.36 289.6 3.96 1.1142 0.3299 1.9009 2.8966 0.041309 3.4156 2.3838 0.097776 101.48 -38.962 0.18304 2.8966 0.14602 0.86161 0.88746 1.2188 3.0379 600 1.1 0.6313 1.5064 4.9068 590 3.6002 -0.00069836 0.10311 2.1156 7.6634 6.1227 0.52819 0.7253 1.0876 3.3111 1191.7 3.3199 3.3199 1.9996 2.7293 0.46952 -0.62182 1.679 -0.022033 -4.4006 -3.5379 1.7243 1.4985 3.249 6.7984 0.11951 3.1457 6.6764 0.54736 38.573 -127.79 1.0721 6.7984 -0.019335 0.81345 1.5523 2.374 7.7118 877.32 -4.4 0.00030269 3.2804 -1.3602 3.6885 761.05 304.33 1.9999 0.00088585 0.016846 -2.3857 10.332 194.73 3.2635 3 1.1268 3.9237 1851.9 3.0906 3.6004 3.0906 3.4951 0.099424 -1.171 5.1736 6.6013 0.051631 2.3933 2.4829 0.78503 1.9785 5.543 0.023424 3.5319 0.46554 0.11941 7.7787 -24.902 0.52472 5.543 0.091083 1.1408 1.7 1.6561 4.2318 287.82 6.5999 0.016691 1.8347 -1.0243 2.7645 6.2728 0.0015434 3.4902 0.020799 NaN NaN NaN 0.28518 37.805 3.6316 6.7985 5.8824 4.0208 19.379 289.61 3.96 1.1141 0.3022 1.9029 3.0041 0.040571 3.4171 2.4841 0.10175 88.355 -51.569 0.18597 3.0041 0.13535 0.87385 0.90858 1.2478 3.1188 609.99 1.1 0.64142 1.6531 5.6046 580 3.6002 -0.00073569 0.097314 1.6633 5.2229 6.5913 0.54411 6.0581 1.0972 3.3433 1198.5 3.4424 3.4424 1.9996 2.7497 0.47889 -0.6258 1.7303 -0.022201 -4.4005 -3.5499 1.7126 1.5172 3.3065 6.7829 0.12166 3.1522 6.7482 0.53042 40.973 -120.47 1.0818 6.7829 -0.021383 0.75001 1.5018 2.5311 8.5461 885.19 -4.4 0.00030422 3.3127 -1.3307 3.7906 760.88 303.26 1.9999 0.00094755 0.016758 -2.4133 9.9184 197.68 3.296 4 1.1285 3.9265 1854 3.0425 3.6004 3.0425 3.4886 0.10833 -1.4374 6.0532 6.6018 0.053802 2.4518 2.4836 0.73677 1.9175 5.5386 0.018892 3.5263 0.40434 0.098235 22.395 -12.47 0.51326 5.5386 0.077485 1.0178 1.6221 1.8529 4.987 281.47 6.6 0.017771 1.7912 -0.8937 2.4507 6.2692 0.0034412 3.4926 0.077164 0.011037 6.021 -29.907 0.28448 37.957 3.8414 6.8738 5.9451 3.9968 19.115 289.63 3.96 1.114 0.43977 1.9856 3.0445 0.040016 3.4159 2.5082 0.099078 94.507 -46.675 0.1861 3.0445 0.13527 0.88531 0.92738 1.2342 3.0851 610 1.1 0.64157 1.5256 4.9396 575.01 3.6002 -0.00071665 0.094806 1.8886 6.4618 6.7672 0.54677 8.4167 1.097 3.3423 1197.7 3.4182 3.4182 1.9996 2.735 0.481 -0.57359 1.6517 -0.022873 -4.4004 -3.5176 1.739 1.4618 3.1404 6.7829 0.121 3.1502 6.7368 0.53385 41.007 -125.91 1.0815 6.7829 -0.0073165 0.76354 1.5115 2.4976 8.3636 884.95 -4.4 0.00029715 3.3115 -1.2773 3.5595 765.91 302.74 2 0.00085562 0.016897 -2.5036 11.241 195.99 3.2946 5 1.1089 3.8666 1840.9 3.2517 3.6004 3.2517 3.5057 0.080206 -0.28465 2.2471 6.6012 0.054041 2.2484 2.3956 0.88864 2.2173 5.5227 0.023587 3.5334 0.42688 0.11951 3.4916 -35.718 0.50984 5.5227 0.17263 1.6987 1.9009 1.0187 2.4386 279.64 6.6 NaN 1.7887 -1.0714 3.0945 6.347 0.0021218 3.4908 0.04628 0.011198 16.809 -20.958 0.28503 37.672 3.6557 6.8669 5.902 3.9845 19.021 289.6 3.96 1.1139 0.31689 1.8507 3.0711 0.039906 3.4177 2.5572 0.10124 74.786 -56.712 0.18762 3.0711 0.14183 0.87892 0.93035 1.2626 3.1556 615 1.1 0.64671 1.6549 5.3183 575.01 3.6002 -0.00070527 0.09545 2.0023 7.0948 6.7754 0.55126 NaN 1.0899 3.3189 1191.5 3.319 3.319 1.9957 2.7191 0.47534 -0.57212 1.6031 -0.022711 -4.4004 -3.5032 1.7484 1.4358 3.0653 6.7769 0.12188 3.1521 6.6506 0.5366 40.214 -122.29 1.0744 6.7769 -0.013659 0.81197 1.5549 2.3806 7.7339 879.13 -4.4 0.00030022 3.2881 -1.3286 3.5449 760.85 302.39 1.9999 0.00089706 0.017049 -2.309 9.7528 192.86 3.271
The feature table starts at Cycle 1.
Plot the charge voltage kurtosis.
plot(ft.Cycle_Index,ft.Charge_Voltage_kurtosis)
title("Charge Voltage Kurtosis by Cycle")
Version History
Introduced in R2024b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)