API

This section provides comprehensive details about the exposed ReLife API. ReLife is structured into different modules, each with a clear and specific role. We divided the API documentation close to the same logic.

Lifetime models

Parametric lifetime models

Lifetime models are objects whose exposed interface can answer basic probility functions of the survival analysis. In object-oriented programming, one must not see them as a group of probability functions solely : it also encapsulates data like parameters, other nested models, etc.

Lifetime models are imported like this :

from relife.lifetime_model import <model_constructor>

Here is an exhaustive list of all lifetime model constructors that can be used in Relife :

Lifetime distributions

Exponential	Exponential lifetime distribution.
Weibull	Weibull lifetime distribution.
Gompertz	Gompertz lifetime distribution.
Gamma	Gamma lifetime distribution.
LogLogistic	Log-logistic probability distribution.

Here is a quick example that instanciates a Weibull distribution and computes the survival function.

>>> import numpy as np
>>> from relife.lifetime_model import Weibull
>>> weibull = Weibull(3.47, 0.01) # shape = 3.47, rate = 0.01
# sf is np.float64, ie. a scalar
>>> sf = weibull.sf(10.)
# sf is np.array of shape (2,), 2 points for 1 asset
>>> sf_1d = weibull.sf(np.array([10., 20.]))
# sf is np.array of (2, 3), 3 points for 2 assets
>>> sf_2d = weibull.sf(np.array([[10., 20., 30.], [30., 40., 50.]]))

Lifetime regression

ProportionalHazard	Proportional Hazard regression.
AcceleratedFailureTime	Accelerated failure time regression.

Here is a quick example that instanciates a ProportionalHazard regression from the same Weibull distribution (see above). The regression has 3 coefficients.

>>> import numpy as np
>>> from relife.lifetime_model import Weibull
>>> from relife.lifetime_model import ProportionalHazard

>>> weibull = Weibull(3.47, 0.01) # shape = 3.47, rate = 0.01
# 3 coefficients
>>> regression = ProportionalHazard(weibull, coefficients=(0.2, 0.01, 0.4))

# 1 value per covar
>>> covar = np.array([3., 59., 9.3])
# sf is np.float64, ie. a scalar
>>> sf = regression.sf(10., covar)

# 2 values per covar, meaning two assets
>>> covar_2d = np.array([[3., 59., 9.3], [2., 64., 5.6]])
# sf is np.array of shape (2, 1), 1 point for 2 assets
>>> sf_2d = regression.sf(10., covar_2d)

Note that the example above uses Numpy broadcasting. It is a core functionnality of ReLife. For more explanations and pratical examples about broadcasting in ReLife, please read Broadcasting in ReLife.

Conditional lifetime models

LeftTruncatedModel	Left truncated model.
AgeReplacementModel	Age replacement model.

>>> import numpy as np
>>> from relife.lifetime_model import LeftTruncatedModel, Weibull
>>> from relife.lifetime_model import ProportionalHazard

>>> left_truncated_weibull = LeftTruncated(Weibull(3.47, 0.01))

# sf is np.float64, ie. a scalar
>>> sf = left_truncated_weibull.sf(10., a0=20.)

Frozen parametric lifetime models

Frozen lifetime models share the same properties as lifetime models, but any additional arguments to time are frozen. This means that the values of these arguments are stored within the model and cannot be set as arguments in a method request. These models are important in ReLife because other objects expect frozen-like lifetime models: any lifetime model that has only time as a method argument. It is specifically the case of policy objects. To freeze a lifetime model, just call .freeze(*args) on the model instance where *args are required additional arguments of the model.

Note

LifetimeDistribution objects can’t be frozen as time is the only variable needed for these objects.

Frozen lifetime regression

FrozenLifetimeRegression	Frozen lifetime regression.
FrozenLeftTruncatedModel	Frozen left truncated model.
FrozenAgeReplacementModel	Frozen age replacement model.

Non parametric lifetime models

KaplanMeier	Kaplan-Meier estimator.
NelsonAalen	Nelson-Aalen estimator.
ECDF	Empirical Cumulative Distribution Function.
Turnbull	Turnbull estimator.

Built-in dataset

load_circuit_breaker	Load circuit breaker dataset containing observed lifetimes and left truncations values
load_insulator_string	Load insulator string dataset containing observed lifetimes, left truncations values and covariates
load_power_transformer	Load power transformer dataset containing observed lifetimes and left truncations values.

Stochastic processes

RenewalProcess	Renewal process.
RenewalRewardProcess	Renewal reward process.
NonHomogeneousPoissonProcess	Non-homogeneous Poisson process.

Economy

RunToFailureReward	Run-to-failure reward.
AgeReplacementReward	Age replacement reward.

Maintenance policies

AgeReplacementPolicy	Age replacement policy.
OneCycleAgeReplacementPolicy	One-cyle age replacement policy.
RunToFailurePolicy	Run-to-failure renewal policy.
OneCycleRunToFailurePolicy	One cyle run-to-failure policy.
NonHomogeneousPoissonAgeReplacementPolicy	Age replacement policy for non-Homogeneous Poisson process.

Routines

is_frozen
is_lifetime_model
is_stochastic_process

Base classes

Warning

The interfaces presented below might interest you only if you want to understand how ReLife is implemented (contributions, suggestions, spotted errors, etc.) Otherwise, you can skip this part of the API

Parametric models

ParametricModel	Base class to create a parametric_model core.
ParametricLifetimeModel	Base class for lifetime model.
FrozenParametricLifetimeModel
NonParametricLifetimeModel

Policies

BaseAgeReplacementPolicy
BaseOneCycleAgeReplacementPolicy