ParametricProportionalHazard#

final class assetlife.lifetime_models.ParametricProportionalHazard(baseline, coefficients=())[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.

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

`apply_condition`	Return a model with age replacement, left truncation, or both.
`cdf`	The cumulative distribution function.
`chf`	The cumulative hazard function.
`dhf`	The derivative of the hazard function.
`fit`
`freeze`	Return a model with additional arguments stored.
`get_coefficients`	Returns the coefficients values.
`get_params`	Get the parameters of this model.
`hf`	The hazard function.
`ichf`	Inverse cumulative hazard function.
`init_likelihood`	Initialize the lifetime likelihood used to fit the parameters.
`is_fitted`	Whether fitting results are set.
`is_parametrized`	Whether at least one parameter value is set.
`isf`	The inverse survival function.
`jac_cdf`	The Jacobian of the cumulative distribution 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`	The n-th order moment.
`mrl`	The mean residual life function.
`pdf`	The probability density function.
`plot`	Plot function.
`ppf`	The percent point function, inverse of the CDF.
`rvs`	Random variate sampling.
`set_params`	Set the parameters of this model.
`sf`	The survival function.
`var`	The variance of the distribution.

apply_condition(*, ar=None, a0=None)#

Return a model with age replacement, left truncation, or both.

Parameters:

arfloat or ndarray, optional: Age replacement threshold.
a0float or ndarray, optional: Initial age for left truncation.

Returns:

outParametricLifetimeModel: Conditioned lifetime model.

property args_shape#: Shape of additional model arguments.

cdf(time, *covar)#

The cumulative distribution function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function.
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.
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 derivative of the hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function.
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).

freeze(*args)#: Return a model with additional arguments stored.

get_coefficients()#

Returns the coefficients values.

Returns:

outndarray

get_params()#

Get the parameters of this model.

Returns:

out1darray of floats: Model parameters.

Notes

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

hf(time, *covar)[source]#

The hazard function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function.
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.
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 usually composed of 3 steps:

Initialize an object to store and preprocess lifetime values.
Create a FitConfig instance depending on the model needs.
Instantiate 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 or 2d array

Observed lifetime values. 1d array can handle complete and right censored lifetimes with event. To add left censored or interval censored lifetimes, use 2d array.

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 parameters 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

is_fitted()#: Whether fitting results are set.

is_parametrized()#: Whether at least one parameter value is set.

isf(probability, *covar)#

The inverse survival function.

Parameters:

probabilityfloat or np.ndarray: Probability value(s) at which to compute the function.
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 distribution function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function.
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.
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.
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.
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.
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, *density_args, func_args=(), deg=10)#

Lebesgue-Stieltjes integration.

Parameters:

funcCallable: Function to integrate with respect to the lifetime distribution.
afloat or ndarray: Lower bound of the integration.
bfloat or ndarray: Upper bound of the integration.
*density_args: Additional arguments required by the lifetime model.
func_argstuple, default=(): Additional arguments required by func.
degint, default=10: Number of sample points and weights for the quadrature.

Returns:

outnp.ndarray: Lebesgue-Stieltjes integration 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, *args)#

The n-th order moment.

Parameters:

nint: Order of the moment, at least 1.
*args: Any additional args.

Returns:

outnp.float64 or np.ndarray

mrl(time, *args)#

The mean residual life function.

Parameters:

timefloat or np.ndarray: Elapsed time value(s) at which to compute the function.
*args: Any additional args.

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.
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 the model has fitting_results
alpha_ci :
any arguments allowed by matplotlib.plot

ppf(probability, *covar)#

The percent point function, inverse of the CDF.

Parameters:

probabilityfloat or np.ndarray: Probability value(s) at which to compute the function.
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=None, *covar, seed=None)#

Random variate 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: Sample values.

set_params(new_params)#

Set the parameters of this model.

Parameters:

new_params1d array-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 can 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.
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