fit

Estimate parameters of remaining useful life model using historical data

Syntax

fit(mdl,data)

fit(mdl,data,lifeTimeVariable)

fit(mdl,data,lifeTimeVariable,dataVariables)

fit(mdl,data,lifeTimeVariable,dataVariables,censorVariable)

fit(mdl,data,lifeTimeVariable,dataVariables,censorVariable,encodedVariables)

Description

The fit function estimates the parameters of a remaining useful life (RUL) prediction model using historical data regarding the health of an ensemble of similar components, such as multiple machines manufactured to the same specifications. Depending on the type of model, you specify the historical health data as a collection of lifespan measurements or degradation profiles. Once you estimate the parameters of your model, you can then predict the remaining useful life of similar components using the predictRUL function.

Using fit, you can configure the parameters for the following types of estimation models:

• Degradation models

• Survival models

• Similarity models

For a basic example illustrating RUL prediction, see Update RUL Prediction as Data Arrives.

For general information on predicting remaining useful life using these models, see RUL Estimation Using RUL Estimator Models.

fit(mdl,data) fits the parameters of the remaining useful life model mdl using the historical data in data. This syntax applies only when data does not contain table or timetable data.

fit(mdl,data,lifeTimeVariable) fits the parameters of mdl using the time variable lifeTimeVariable and sets the LifeTimeVariable property of mdl. This syntax applies only when data contains:

• Nontabular data

• Tabular data, and mdl does not use data variables

fit(mdl,data,lifeTimeVariable,dataVariables) fits the parameters of mdl using the data variables in dataVariables and sets the DataVariables property of mdl.

fit(mdl,data,lifeTimeVariable,dataVariables,censorVariable) specifies the censor variable for a survival model and sets the CensorVariable property of mdl. The censor variable indicates which life-time measurements in data are not end-of-life values. This syntax applies only when mdl is a survival model and data contains tabular data.

fit(mdl,data,lifeTimeVariable,dataVariables,censorVariable,encodedVariables) specifies the encoded variables for a covariate survival model and sets the EncodedVariables property of mdl. Encoded variables are usually nonnumeric categorical features that fit converts to numeric vectors before fitting. This syntax applies only when mdl is a covariateSurvivalModel object and data contains tabular data.

Examples

Train Linear Degradation Model

Load training data.

load('linTrainVectors.mat')

The training data is a cell array of column vectors. Each column vector is a degradation feature profile for a component.

Create a linear degradation model with default settings.

mdl = linearDegradationModel;

Train the degradation model using the training data.

fit(mdl,linTrainVectors)

Train Reliability Survival Model

Load training data.

load('reliabilityData.mat')

This data is a column vector of duration objects representing battery discharge times.

Create a reliability survival model with default settings.

mdl = reliabilitySurvivalModel;

Train the survival model using the training data.

fit(mdl,reliabilityData,"hours")

Train Hash Similarity Model Using Tabular Data

Load training data.

load('hashTrainTables.mat')

The training data is a cell array of tables. Each table is a degradation feature profile for a component. Each profile consists of life time measurements in the "Time" variable and corresponding degradation feature measurements in the "Condition" variable.

Create a hash similarity model that uses the following values as hashed features:

mdl = hashSimilarityModel('Method',@(x) [mean(x),std(x),kurtosis(x),median(x)]);

Train the similarity model using the training data. Specify the names of the life time and data variables.

fit(mdl,hashTrainTables,"Time","Condition")

Predict RUL Using Covariate Survival Model

Load training data.

load('covariateData.mat')

This data contains battery discharge times and related covariate information. The covariate variables are:

• Temperature

• Load

• Manufacturer

The manufacturer information is a categorical variable that must be encoded.

Create a covariate survival model, and train it using the training data.

mdl = covariateSurvivalModel('LifeTimeVariable',"DischargeTime",'LifeTimeUnit',"hours",...
   'DataVariables',["Temperature","Load","Manufacturer"],'EncodedVariables',"Manufacturer");
fit(mdl,covariateData)

Successful convergence: Norm of gradient less than OPTIONS.TolFun

Suppose you have a battery pack manufactured by maker B that has run for 30 hours. Create a test data table that contains the usage time, DischargeTime, and the measured ambient temperature, TestAmbientTemperature, and current drawn, TestBatteryLoad.

TestBatteryLoad = 25;
TestAmbientTemperature = 60; 
DischargeTime = hours(30);
TestData = timetable(TestAmbientTemperature,TestBatteryLoad,"B",'RowTimes',hours(30));
TestData.Properties.VariableNames = {'Temperature','Load','Manufacturer'};
TestData.Properties.DimensionNames{1} = 'DischargeTime';

Predict the RUL for the battery.

estRUL = predictRUL(mdl,TestData)

estRUL = duration
   38.332 hr

Plot the survival function for the covariate data of the battery.

plot(mdl,TestData)

Input Arguments

mdl — Remaining useful life prediction model

degradation model | survival model | similarity model

Remaining useful life prediction model, specified as one of these models. fit updates the parameters of this model using the historical data in data.

RUL Model Groups	Prediction Model
Degradation models	linearDegradationModel
	exponentialDegradationModel
Survival models	reliabilitySurvivalModel
	covariateSurvivalModel
Similarity models	hashSimilarityModel
	pairwiseSimilarityModel
	residualSimilarityModel

For more information on the different model types and when to use them, see Models for Predicting Remaining Useful Life.

data — Historical data

column vector | array | table | timetable | cell array

Historical data regarding the health of an ensemble of similar components, such as their degradation profiles or life spans, specified as an array or table of component life times, or a cell array of degradation profiles.

If your historical data is stored in an ensemble datastore object, you must first convert it to a table before estimating your model parameters. For more information, see Data Ensembles for Condition Monitoring and Predictive Maintenance.

The format of data depends on the type of RUL model you specify in mdl.

Degradation Model

If mdl is a linearDegradationModel or exponentialDegradationModel, specify data as a cell array of component degradation profiles. Each element of the cell array contains the degradation feature profile across the lifetime of a single component. There can be only one degradation feature for your model. You can specify data as a cell array of:

• Two-column arrays, where each row contains the usage time in the first column and the corresponding feature measurement in the second column. In this case, the usage time column must contain numeric values; that is, it cannot use, for example, duration or timedate values.

• table objects. Select the variable from the table that contains the feature degradation profile using dataVariables, and select the usage time variable, if present, using lifeTimeVariable.

• timetable objects. Select the variable from the table that contains the feature degradation profile using dataVariables, and select the usage time variable using lifeTimeVariable.

Survival Model

For survival models, data contains the life span measurements for multiple components. Also, for covariate survival models, data contains corresponding time-independent covariates, such as the component provider or working regimes. Specify data as one of the following:

• Column vector of life span measurements — This case applies only when mdl is a reliabilitySurvivalModel.

• Array — The first column contains the life span measurements, and the remaining columns contain the covariate values. This case applies only when mdl is a covariateSurvivalModel.

• table or timetable — In this case, select the variable from the table that contains the life span measurements using lifeTimeVariable. For covariate survival models, select the covariate variables using dataVariables. For reliability survival models, fit ignores dataVariables.

By default, fit assumes that all life span measurements are end-of-life values. To indicate that a life span measurement is not an end-of-life value, use censoring. To do so, specify data as a table or timetable that contains a censor variable. The censor variable is a binary variable that is 1 when the corresponding life span measurement is not an end-of-life value. Select the censor variable using censorVariable.

Similarity Model

If mdl is a hashSimilarityModel, pairwiseSimilarityModel, or residualSimilarityModel, specify data as a cell array of degradation profiles. Each element of the cell array contains degradation feature profiles across the lifetime a single component. For similarity models, you can specify multiple degradation features, where each feature is a health indicator for the component. You can specify data as a cell array of:

• N-by-(M_i+1) arrays, where N is the number of feature measurements (at different usage times) and M_i is the number of features. The first column contains the usage times and the remaining columns contain the corresponding measurements for degradation features.

• table objects. Select the variables from the table that contain the feature degradation profiles using dataVariables, and select the corresponding usage time variable, if present, using lifeTimeVariable.

• timetable objects. Select the variables from the table that contain the feature degradation profiles using dataVariables, and select the corresponding usage time variable using lifeTimeVariable.

fit assumes that all the degradation profiles represent run-to-failure data; that is, the data starts when the component is in a healthy state and end when the component is close to failure or maintenance.

lifeTimeVariable — Life time variable

"" (default) | string

Life time variable, specified as a string. If data is a:

• table, then lifeTimeVariable must match one of the variable names in the table.

• timetable, then lifeTimeVariable one of the variable names in the table or the dimension name of the time variable , data.Properties.DimensionNames{1}.

table or timetable, then lifeTimeVariable must match one of the variable names in the table. If there is no life time variable in the table or if data is nontabular, then you can omit lifeTimeVariable.

lifeTimeVariable must be "" or a valid MATLAB^® variable name, and must not match any of the strings in dataVariables.

fit stores lifeTimeVariable in the LifeTimeVariable property of the model.

dataVariables — Feature data variables

"" (default) | string | string array

Feature data variables, specified as a string or string array. If data is a:

• Degradation model, then dataVariables must be a string

• Similarity model or covariate survival model, then dataVariables must be a string array

• Reliability survival model, then fit ignores dataVariables

If data is:

• A table or timetable, then the strings in dataVariables must match variable names in the table.

• Nontabular, then dataVariables must be "" or contain the same number of strings as there are data columns in data. The strings in dataVariables must be valid MATLAB variable names.

fit stores dataVariables in the DataVariables property of the model.

censorVariable — Censor variable

"" (default) | string

Censor variable for survival models, specified as a string. The censor variable is a binary variable that indicates which life time measurements in data are not end-of-life values. To use censoring, data must be a table or timetable.

If you specify censorVariable, the string must match one of the variable names in data and must not match any of the strings in dataVariables or lifeTimeVariable.

fit stores censorVariable in the CensorVariable property of the model.

encodedVariables — Encoded variables

"" (default) | string | string array

Encoded variables for covariate survival models, specified as a string or string array. Encoded variables are usually nonnumeric categorical features that fit converts to numeric vectors before fitting. You can also designate logical or numeric values that take values from a small set to be encoded.

The strings in encodedVariables must be a subset of the strings in dataVariables.

fit stores encodedVariables in the EncodedVariables property of the model.

Version History

Introduced in R2018a