ParametricLifetimeModel

class relife.model.ParametricLifetimeModel

Base class to create a parametric lifetime model

A parametric lifetime model is an LifetimeModel having parameters that can be estimated, i.e. it has a fit method.

Methods

cdf	Cumulative distribution function.
chf	Cumulative hazard function.
compose_with	Compose with new ParametricModel instance(s).
copy	Copy current instance.
fit	Estimation of lifetime model parameters with respect to lifetime data.
hf	Hazard function.
ichf	Inverse cumulative hazard function.
init_params	Initialization of the parameters
isf	Inverse survival function.
ls_integrate	Lebesgue-Stieltjes integration.
mean	Mean.
median	Median
moment	n-th order moment
mrl	Mean residual life.
new_params	Change local parameters structure.
pdf	Probability density function.
ppf	Percent point function.
rvs	Random variable sampling.
sf	Survival function.
var	Variance.

Attributes

nb_params	Number of parameters.
params	Parameters values.
params_bounds	Bounds of the parameters
params_names	Parameters names.
plot	Plot
fitting_results

cdf(time, *args)

Cumulative distribution function.

Parameters:

timefloat or ndarray, shape (n, ) or (m, n)

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Cumulative distribution function values at each given time.

abstract chf(time, *args)

Cumulative hazard function.

Parameters:

timefloat or ndarray, shape (n, ) or (m, n)

Elapsed time.

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Cumulative hazard values at each given time.

compose_with(**kwcomponents)

Compose with new ParametricModel instance(s).

This method must be seen as standard function composition exept that objects are not functions but group of functions (as object encapsulates functions). When you compose your ParametricModel instance with new one(s), the followings happen :

• each new parameters are added to the current Parameters instance

• each new ParametricModel instance is accessible as a standard attribute

Like so, you can request new ParametricModel components in current ParametricModel instance while setting and getting all parameters. This is usefull when ParametricModel can be seen as a nested function (see Regression).

Parameters:

**kwcomponentsvariadic named ParametricModel instance

Instance names (keys) are followed by the instances themself (values).

Notes

If one wants to pass a dict of key-value, make sure to unpack the dict with ** operator or you will get a nasty TypeError.

copy()

Copy current instance.

Returns:

An independant copied instance.

fit(time, event=None, entry=None, departure=None, model_args=(), inplace=False, **kwargs)

Estimation of lifetime model parameters with respect to lifetime data.

Parameters:

timendarray (1d or 2d)

Observed lifetime values.

eventndarray of boolean values (1d), default is None

Boolean indicators tagging lifetime values as right censored or complete.

entryndarray of float (1d), default is None

Left truncations applied to lifetime values.

departurendarray of float (1d), default is None

Right truncations applied to lifetime values.

model_argstuple of ndarray, default is None

Other arguments needed by the lifetime model.

inplaceboolean, default is True

If true, parameters of the lifetime model will be replaced by estimated parameters.

**kwargs

Extra arguments used by scipy.minimize. Default values are:

• method : “L-BFGS-B”

• contraints : ()

• tol : None

• callback : None

• options : None

• bounds : self.params_bounds

• x0 : self.init_params

Returns:

ndarray of float

Estimated parameters.

Notes

Supported lifetime observations format is either 1d-array or 2d-array. 2d-array is more advanced format that allows to pass other information as left-censored or interval-censored values. In this case, event is not needed as 2d-array encodes right-censored values by itself.

abstract hf(time, *args)

Hazard function.

The hazard function of the distribution

Parameters:

timefloat or ndarray, shape (n, ) or (m, n)

Elapsed time.

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Hazard values at each given time.

ichf(cumulative_hazard_rate, *args)

Inverse cumulative hazard function.

Parameters:

Cumulative hazard ratefloat or ndarray, shape (n, ) or (m, n)

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Inverse cumulative hazard values, i.e. time.

abstract init_params(lifetime_data, *args)

Initialization of the parameters

Initialize parameters values with respect to lifetime data.

Parameters:

lifetime_dataLifetimeData object

lalal.

argstuple of numpy arrays

lala.

isf(probability, *args)

Inverse survival function.

Parameters:

probabilityfloat or ndarray, shape (n, ) or (m, n)

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Complement quantile corresponding to probability.

ls_integrate(func, a, b, *args, deg=100)

Lebesgue-Stieltjes integration.

The Lebesgue-Stieljes intregration of a function with respect to the lifetime model taking into account the probability density function and jumps

The Lebesgue-Stieltjes integral is:

\[\int_a^b g(x) \mathrm{d}F(x) = \int_a^b g(x) f(x)\mathrm{d}x + \sum_i g(a_i) w_i\]

where:

• \(F\) is the cumulative distribution function,

• \(f\) the probability density function of the lifetime model,

• \(a_i\) and \(w_i\) are the points and weights of the jumps.

Parameters:

funccallable (in1 ndarray, out1 ndarray)

The callable must have only one ndarray object as argument and returns one ndarray object

andarray (max dim of 2)

Lower bound(s) of integration.

bndarray (max dim of 2)

Upper bound(s) of integration. If lower bound(s) is infinite, use np.inf as value.

argsndarray (max dim of 2)

Other arguments needed by the lifetime model (eg. covariates)

degint, default 100

Degree of the polynomials interpolation

Returns:

2d ndarray

Lebesgue-Stieltjes integral of func with respect to cdf from a to b.

Notes

ls_integrate operations rely on arguments number of dimensions passed in a, b, *args or any other variable referenced in func. Because func callable is not easy to inspect, either one must specify the maximum number of dimensions used (0, 1 or 2), or ls_integrate converts all these objects to 2d-array. Currently, the second option is prefered. That’s why, returns are always 2d-array.

mean(*args)

Mean.

Parameters:

*argsvariadic arguments required by the function

Returns:

ndarray of shape (0,)

Mean value.

median(*args)

Median

Parameters:

*argsvariadic arguments required by the function

Returns:

ndarray of shape (0,)

Median value.

moment(n, *args)

n-th order moment

Parameters:

norder of the moment, at least 1.

*argsvariadic arguments required by the function

Returns:

ndarray of shape (0, )

n-th order moment.

mrl(time, *args)

Mean residual life.

Parameters:

timefloat or ndarray, shape (n, ) or (m, n)

Elapsed time.

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Mean residual life values.

property nb_params

Number of parameters.

Returns:

int

Number of parameters.

new_params(**kwparams)

Change local parameters structure.

This method only affects local parameters. ParametricModel components are not affected. This is usefull when one wants to change model parameters for any reason. For instance Regression models use new_params to change number of regression coefficients depending on the number of covariates that are passed to the fit method.

Parameters:

**kwparamsvariadic named floats corresponding to new parameters

Float names (keys) are followed by float instances (values).

Notes

If one wants to pass a dict of key-value, make sure to unpack the dict with ** operator or you will get a nasty TypeError.

property params

Parameters values.

Returns:

ndarray

Parameters values of the model

Notes

If parameter values are not set, they are encoded as np.nan value.

Parameters can be by manually setting`params` through its setter, fitting the model if fit exists or by specifying all parameters values when the model object is initialized.

abstract property params_bounds

Bounds of the parameters

Returns:

Bounds

The lower and upper bounds for the parameters.

property params_names

Parameters names.

Returns:

list of str

Parameters names

Notes

Parameters values can be requested (a.k.a. get) by their name at instance level.

abstract pdf(time, *args)

Probability density function.

Parameters:

timefloat or ndarray, shape (n, ) or (m, n)

Elapsed time.

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

The probability density function evaluated at each given time.

property plot

Plot

ppf(probability, *args)

Percent point function.

Parameters:

probabilityfloat or ndarray, shape (n, ) or (m, n)

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Quantile corresponding to probability.

rvs(*args, size=1, seed=None)

Random variable sampling.

Parameters:

*argsvariadic arguments required by the function

sizeint, default 1

Sized of the generated sample.

seedint, default None

Random seed.

Returns:

ndarray of shape (size, )

Sample of random lifetimes.

abstract sf(time, *args)

Survival function.

Parameters:

timefloat or ndarray, shape (n, ) or (m, n)

Elapsed time.

*argsvariadic arguments required by the function

Returns:

ndarray of shape (), (n, ) or (m, n)

Survival function values at each given time.

var(*args)

Variance.

Parameters:

*argsvariadic arguments required by the function

Returns:

ndarray of shape (0,)

Variance value.