ParametricProportionalHazard#

final class relife.lifetime_models.ParametricProportionalHazard(baseline, coefficients=(None,))[source]#

Proportional Hazard regression.

The cumulative hazard function \(H\) is linked to the multiplier function \(g\) by the relation:

\[H(t, x) = g(\beta, x) H_0(t) = e^{\beta \cdot x} H_0(t)\]

where \(x\) is a vector of covariates, \(\beta\) is the coefficient vector of the effect of covariates, \(H_0\) is the baseline cumulative hazard function [1].

Parameters:

baselineFittableParametricLifetimeModel: Any lifetime model that can be fitted.
coefficientstuple of floats (values can be None), default is (None,): Coefficients values of the covariate effects.

Attributes:

baselineFittableParametricLifetimeModel: The regression baseline model (lifetime model).
covar_effect_CovarEffect: The regression covariate effect.
fitting_resultsFittingResults, default is None: An object containing fitting results (AIC, BIC, etc.). If the model is not fitted, the value is None.
coefficients
nb_params
params
params_names
plot: Plot function.

See also

regression.AFT: Accelerated Failure Time regression.

References

[1]

Sun, J. (2006). The statistical analysis of interval-censored failure time data (Vol. 3, No. 1). New York: springer.

Methods

`cdf`	The cumulative density function.
`chf`	The cumulative hazard function.
`dhf`	The derivate of the hazard function.
`fit`	Estimation of parameters from lifetime data.
`freeze`	Freeze regression covar.
`get_coefficients`	Returns the coefficients values.
`get_params`	Get the parameters of this model.
`get_params_names`	Parameters names.
`hf`	The hazard function.
`ichf`	Inverse cumulative hazard function.
`init_likelihood`	Initialize the lifetime likelihood used to fit the parameters.
`isf`	The inverse survival function.
`jac_cdf`	The jacobian of the cumulative density function.
`jac_chf`	The jacobian of the cumulative hazard function.
`jac_hf`	The jacobian of the hazard function.
`jac_pdf`	The jacobian of the probability density function.
`jac_sf`	The jacobian of the survival function.
`ls_integrate`	Lebesgue-Stieltjes integration.
`mean`	The mean of the distribution.
`median`	The median.
`moment`	n-th order moment.
`mrl`	The mean residual life function.
`pdf`	The probability density function.
`plot`	Plot function.
`ppf`	The percent point function.
`rvs`	Random variable sampling.
`set_params`	Set the parameters of this model.
`sf`	The survival function.
`var`	The variance of the distribution.

cdf(time, covar)#

The cumulative density function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: cdf values at each given time(s).

chf(time, covar)[source]#

The cumulative hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: chf values at each given time(s).

dhf(time, covar)[source]#

The derivate of the hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: Function values at each given time(s).

fit(time, args=None, event=None, entry=None, **kwargs)#

Estimation of parameters from lifetime data.

Parameters:

time1d array: Observed lifetime values.
argsany ndarray or tuple of ndarray, default is None: Additional arguments required by the model (e.g. covar).
event1d array of bool, default is None: Boolean indicators tagging lifetime values as right censored or complete.
entry1d array, default is None: Left truncations applied to lifetime values.
**kwargs: Extra arguments used by scipy.optimize.minimize to search for the paremeters that minimize the negative log-likelihood. covariance_method can also be passed to control the method used to estimate parameters covariance. Values can be “cs”, “2point”, “exact” or False. To skip parameters covariance estimation, set covariance_method to False, otherwise the default method associated to the model will be used. If covariance_method is “exact” the hess must be passed too.

Returns:

outthe object instance: The estimated parameters are setted inplace.

freeze(covar)#

Freeze regression covar.

Parameters:

covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

out: frozen regression: The same object but with covar stored as object data. Calling methods from the frozen regression does not need covar.

get_coefficients()#

Returns the coefficients values.

Returns:

outndarray

get_params()#

Get the parameters of this model.

Returns:

out1darray of number: Model parameters.

Notes

If parameter values are not set, they default to np.nan values.

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

hf(time, covar)[source]#

The hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: hf values at each given time(s).

ichf(cumulative_hazard_rate, covar)[source]#

Inverse cumulative hazard function.

Parameters:

cumulative_hazard_ratefloat or np.ndarray: Cumulative hazard rate value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: ichf values at each given cumulative hazard rate(s).

init_likelihood(time, args=None, event=None, entry=None, **kwargs)#

Initialize the lifetime likelihood used to fit the parameters.

fit method is the preferred way to fit model parameters. However, users can also interact with the likelihood returned by init_likelihood to study the optimization process.

This method implementation is usally composed of 3 steps:

Initialize an object to preprocess and encapsulate observation values.
Create a OptimizerConfig config instance depending on the model needs.
Instanciate and return a LifetimeLikelihood.

init_likelihood is separated from fit in order to reuse existing likelihood parametrization in case of model composition. Any parameters initialization needed by the likelihood optimizer (e.g. x0 or bounds as required in step 2.) are left to specific functions alongside concrete model implementations. These functions are invoked within init_likelihood.

Parameters:

time1d array

Observed lifetime values.

argsany ndarray or tuple of ndarray, default is None

Additional arguments required by the model (e.g. covar).

event1d array of bool, default is None

Boolean indicators tagging lifetime values as right censored or complete.

entry1d array, default is None

Left truncations applied to lifetime values.

**kwargs

Extra arguments to control the parameters optimization. It can be:

those used by scipy.optimize.minimize to search for the paremeters that minimize the negative log-likelihood.

covariance_method to control the method used to estimate parameters covariance. Values can be “cs”, “2point”, “exact” or False. To skip parameters covariance estimation, set covariance_method to False, otherwise the default method associated to the model will be used. If covariance_method is “exact” the hess must be passed too.

Returns:

outLifetimeLikelihood instance

isf(probability, covar)#

The inverse survival function.

Parameters:

probabilityfloat or np.ndarray: Probability value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: isf values at each given probability value(s).

jac_cdf(time, covar)#

The jacobian of the cumulative density function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: The derivatives with respect to each parameter. If the result is an np.ndarray, the first dimension holds the number of parameters.

jac_chf(time, covar)[source]#

The jacobian of the cumulative hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: The derivatives with respect to each parameter. If the result is an np.ndarray, the first dimension holds the number of parameters.

jac_hf(time, covar)[source]#

The jacobian of the hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: The derivatives with respect to each parameter. If the result is an np.ndarray, the first dimension holds the number of parameters.

jac_pdf(time, covar)#

The jacobian of the probability density function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: The derivatives with respect to each parameter. If the result is an np.ndarray, the first dimension holds the number of parameters.

jac_sf(time, covar)#

The jacobian of the survival function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: The derivatives with respect to each parameter. If the result is an np.ndarray, the first dimension holds the number of parameters.

ls_integrate(func, a, b, covar, *, deg=10)#

Lebesgue-Stieltjes integration.

Parameters:

funccallable (in1 ndarray , out1 ndarray): The callable must have only one ndarray object as argument and one ndarray object as output.
andarray (maximum number of dimension is 2): Lower bound(s) of integration.
bndarray (maximum number of dimension is 2): Upper bound(s) of integration. If lower bound(s) is infinite, use np.inf as value.
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).
degint, default 10: Degree of the polynomials interpolation.

Returns:

outnp.ndarray: Lebesgue-Stieltjes integral of func from a to b.

mean(covar)#

The mean of the distribution.

Parameters:

covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray

median(covar)#

The median.

Parameters:

covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray

moment(n, covar)#

n-th order moment.

Parameters:

nint: order of the moment, at least 1.
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64

mrl(time, covar)#

The mean residual life function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: Function values at each given time(s).

pdf(time, covar)#

The probability density function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: pdf values at each given time(s).

plot(fname, time, *args, ax=None, **kwargs)#

Plot function.

Parameters:

fnamestr

The function name to plot. Allowed names are sf, cdf, chf, hf, pdf.

time1d array

The timeline used for x-axis.

*args

Any additional args required to compute the function.

axplt.Axes, optional

An optional existing matplotlib.axes.

**kwargs

Extra arguments to configure the plot:

ci : bool, default is True, if False the CI is not plotted
alpha_ci :
any arguments allowed by matplotlib.plot

ppf(probability, covar)#

The percent point function.

Parameters:

probabilityfloat or np.ndarray: Probability value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: ppf values at each given probability value(s).

rvs(size, covar, *, seed=None)#

Random variable sampling.

Parameters:

sizeint or tuple (m, n) of int: Size of the generated sample.
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).
seedoptional int, np.random.BitGenerator, np.random.Generator, np.random.RandomState, default is None: If int or BitGenerator, seed for random number generator. If np.random.RandomState or np.random.Generator, use as given.

Returns:

outfloat or ndarray: The sample values.

set_params(new_params)#

Set the parameters of this model.

Parameters:

new_paramsarray-like of floats: Model parameters.

Notes

set_params definition expects an array-like of floats. At runtime, complex parameters might be setted temporarily to approximate fitted parameters covariance. This is contradictory to the given typing. At the moment, we don’t see a better solution and we believe that this is actually a limitation of what be expressed in the static typesystem.

sf(time, covar)#

The survival function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function. If ndarray, allowed shapes are (), (n,) or (m, n).
covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray: sf values at each given time(s).

var(covar)#

The variance of the distribution.

Parameters:

covarfloat or np.ndarray: Covariates values. float can only be valid if the regression has one coefficients. Otherwise it must be a ndarray of shape (nb_coef,) or (m, nb_coef).

Returns:

outnp.float64 or np.ndarray