Main Content

covariateSurvivalModel

Proportional hazard survival model for estimating remaining useful life

expand all in page

Description

Use covariateSurvivalModel to estimate the remaining useful life (RUL) of a component using a proportional hazard survival model. This model describes the survival probability of a test component using historical information about the life span of components and associated covariates. Covariates are environmental or explanatory variables, such as the component manufacturer or operating conditions. Covariate survival models are useful when the only data you have is the failure times and associated covariates for an ensemble of similar components, such as multiple machines manufactured to the same specifications. For more information on the survival model, see Proportional Hazard Survival Model.

To configure a covariateSurvivalModel object for a specific type of component, use fit, which estimates model coefficients using a collection of failure-time data and associated covariates. After you configure the parameters of your covariate survival model, you can then predict the remaining useful life of similar components using predictRUL. For a basic example illustrating RUL prediction, see Update RUL Prediction as Data Arrives.

If you have only life span measurements and do not have covariate information, use a reliabilitySurvivalModel.

For general information on predicting remaining useful life, see Models for Predicting Remaining Useful Life.

Creation

Syntax

mdl = covariateSurvivalModel
mdl = covariateSurvivalModel(initModel)
mdl = covariateSurvivalModel(___,Name,Value)

Description

mdl = covariateSurvivalModel creates a covariate survival model for estimating RUL and initializes the model with default settings.

example

mdl = covariateSurvivalModel(initModel) creates a covariate survival model and initializes the model parameters using an existing covariateSurvivalModel object initModel.

mdl = covariateSurvivalModel(___,Name,Value) specifies user-settable model properties using name-value pairs. For example, covariateSurvivalModel('LifeTimeUnit',"days") creates a covariate survival model with that uses days as a lifetime unit. You can specify multiple name-value pairs. Enclose each property name in quotes.

example

Input Arguments

expand all

Covariate survival model, specified as a covariateSurvivalModel object.

Properties

expand all

This property is read-only.

Baseline hazard rate of the survival model, specified as a two-column array and estimated by the fit function. The second column contains the baseline survival functions values, and the first column contains the corresponding lifetime values.

For more information on the survival model, see Proportional Hazard Survival Model.

Encoding method for the categorical features in EncodedVariables, specified as one of the following:

  • "dummy" — For a categorical feature with N categories, encode the variable using (N - 1) bits.

  • "binary" — Binary encoding

You can specify EncodingMethod:

  • Using a name-value pair when you create the model

  • Using dot notation after model creation

Flag for standardizing covariate features when calculating Cox regression parameters, specified as a logical value. When Standardize is true, numeric covariate variables are standardized such that covariate X becomes (X-mean(X))/std(X).

Standardization does not affect encoded categorical variables.

You can specify Standardize:

  • Using a name-value pair when you create the model

  • Using dot notation after model creation

Method for handling tied failure times, specified as either "breslow" or "efron". For more information on these methods, see Cox Proportional Hazards Model.

You can specify Ties:

  • Using a name-value pair when you create the model

  • Using dot notation after model creation

Numerical and display settings for Cox regression, specified as a structure created using statset('coxphfit'). You can modify the options in the structure using dot notation.

You can specify Options:

  • Using a name-value pair when you create the model

  • Using dot notation after model creation

This property is read-only.

Covariate multiplying coefficients of the survival model, specified as a scalar and estimated by the fit function. For more information on the survival model, see Proportional Hazard Survival Model.

This property is read-only.

Covariance of the covariate multiplying coefficients, specified as a positive array with size equal to the number of coefficients and estimated by the fit function.

This property is read-only.

Covariate multiplying coefficient names specified as a string array and assigned when the model is trained using the fit function.

Coefficients corresponding to numeric covariates have the same name as the corresponding data variable in DataVariables. For encoded variables, the coefficient names contain the name of the corresponding encoded variable from EncodedVariables and a representation of the encoded bit order.

Censor variable, specified as a string that contains a valid MATLAB® variable name. The censor variable is a binary variable that indicates which life-time measurements in data are not end-of-life values.

CensorVariable must not match any of the strings in DataVariables or LifeTimeVariable.

You can specify CensorVariable:

  • Using a name-value pair when you create the model

  • As an argument when you call the fit function

  • Using dot notation after model creation

Lifetime variable, specified as a string that contains a valid MATLAB variable name. For survival models, the lifetime variable contains the historical life span measurements of components.

You can specify LifeTimeVariable:

  • Using a name-value pair when you create the model

  • As an argument when you call the fit function

  • Manually using dot notation

Lifetime variable units, specified as a string.

The units of the lifetime variable do not need to be time-based. The life of the test component can be measured in terms of a usage variable, such as distance traveled (miles) or fuel consumed (gallons).

Covariate data variables, specified as a string or string array. The strings in DataVariables must be valid MATLAB variable names. Covariates are also called environmental or explanatory variables.

You can specify DataVariables:

  • Using a name-value pair when you create the model

  • As an argument when you call the fit function

  • Using dot notation after model creation

Encoded covariate variables, specified as a string or string array. The strings in EncodedVariables must be valid MATLAB variable names. 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.

To specify the method of encoding, use EncodingMethod.

You can specify EncodedVariables:

  • Using a name-value pair when you create the model

  • As an argument when you call the fit function

  • Using dot notation after model creation

The strings in EncodedVariables must be a subset of the strings in DataVariables.

Additional model information for bookkeeping purposes, specified as any data type or format. The model does not use this information.

You can specify UserData:

  • Using a name-value pair when you create the model

  • Using dot notation after model creation

Object Functions

predictRULEstimate remaining useful life for a test component
fitEstimate parameters of remaining useful life model using historical data
plotPlot survival function for covariate survival remaining useful life model

Examples

collapse all

Open Live Script

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.

mdl = covariateSurvivalModel;

Train the survival model using the training data, specifying the life time variable, data variables, and encoded variable. There is no censor variable for this training data.

fit(mdl,covariateData,"DischargeTime",["Temperature","Load","Manufacturer"],[],"Manufacturer")
Successful convergence: Norm of gradient less than OPTIONS.TolFun

Plot the baseline survival function for the model.

plot(mdl)

Figure contains an axes object. The axes object with title Survival Function Plot, xlabel Time, ylabel S(t) contains an object of type stair. This object represents Baseline Survival Function.

Open Live Script

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)

Figure contains an axes object. The axes object with title Survival Function Plot, xlabel Time, ylabel S(t) contains 2 objects of type stair. These objects represent Baseline Survival Function, Current Survival Function.

Algorithms

expand all

Extended Capabilities

Version History

Introduced in R2018a

See Also

Functions

Topics