covariateSurvivalModel

Proportional hazard survival model for estimating remaining useful life

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.

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.

Input Arguments

initModel — Covariate survival model

covariateSurvivalModel object

Covariate survival model, specified as a covariateSurvivalModel object.

Properties

BaselineCumulativeHazard — Baseline hazard rate function

Read-only: two-column array

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.

EncodingMethod — Encoding method

"dummy" (default) | "binary"

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

Standardize — Flag for standardizing covariate features

false (default) | true

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

Ties — Method for handling tied failure times

"breslow" (default) | "efron"

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

Options — Numerical and display settings

structure

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

ParameterValues — Covariate multiplying coefficients

Read-only: vector

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.

ParameterCovariance — Covariance of covariate multiplying coefficients

Read-only: array

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.

ParameterNames — Covariate multiplying coefficient names

Read-only: string array

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.

CensorVariable — Censor variable

"" (default) | string

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

LifeTimeVariable — Lifetime variable

"" (default) | string

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

LifeTimeUnit — Lifetime variable units

"" (default) | string

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

DataVariables — Covariate data variable

"" (default) | string | string array

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

EncodedVariables — Encoded covariate variables

"" (default) | string | string array

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.

UserData — Additional model information

[] (default) | any data type or format

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

predictRUL	Estimate remaining useful life for a test component
fit	Estimate parameters of remaining useful life model using historical data
plot	Plot survival function for covariate survival remaining useful life model

Examples

Train 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.

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)

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)

Algorithms

Proportional Hazard Survival Model

The covariateSurvivalModel object implements the following proportional hazard survival model:

$$h\left(X,t\right)=h_0\left(t\right)e^{b^{T}X}$$

where:

• X is a vector covariate values.

• b is a vector of covariate multiplying coefficients. These coefficients correspond to the ParameterValues property of the model.

• h₀(t) is the baseline hazard rate function, which corresponds to the BaselineCumulativeHazard property of the model.

• h(X,t) is the hazard rate at time t for X.

To find the parameters of this model, the fit function uses the coxphfit function.

For more information on proportional hazard models, see Cox Proportional Hazards Model.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The predictRUL command supports code generation with MATLAB Coder™ for this RUL model type. Before generating code that uses this model, you must save the model using saveRULModelForCoder. For an example, see Generate Code for Predicting Remaining Useful Life.

• For a covariateSurvivalModel, you cannot generate code for predictRUL using covariate data specified as string or character-vector values in table or timetable form. Instead, convert the string or character-vector data to a different data type, or delete the data from the table.

• In addition to the read-only properties, you cannot change the following properties of survival models at run time:

  • LifeTimeVariable

  • LifeTimeUnit

  • DataVariables

  • CensorVariable

  • EncodedVariables (covariateSurvivalModel only)

  • EncodingMethod (covariateSurvivalModel only)

• See predictRUL for additional limitations on code generation.

Version History

Introduced in R2018a