Baseline hazards

The families a generator can sample from, and the protocol any object must satisfy to be used as one. See the baseline hazards guide for how to pass them.

baseline

Baseline hazard families.

A survival time is drawn by inverting the cumulative hazard: draw :math:E \sim \mathrm{Exponential}(1) and solve :math:H_0(t) = E / e^{\eta} for :math:t. Every generator in this package that samples a continuous time does exactly that, differing only in which :math:H_0 it uses.

This module makes that the explicit contract. A baseline hazard is anything implementing :class:BaselineHazard, so a simulator written against the protocol works with any shape, rather than growing a separate entry point per family.

All implementations are frozen dataclasses that validate their parameters on construction, and every method accepts either a scalar or a NumPy array.

Examples:

>>> from gen_surv.baseline import WeibullBaseline
>>> baseline = WeibullBaseline(shape=2.0, scale=1.5)
>>> value = baseline.cumulative_hazard(3.0)
>>> round(baseline.inverse_cumulative_hazard(value), 10)
3.0

BaselineHazard

Bases: Protocol

The interface a baseline hazard must provide to be sampled from.

Three methods, of which the last two are the ones sampling needs: :meth:cumulative_hazard to evaluate :math:H_0(t), and :meth:inverse_cumulative_hazard to solve :math:H_0(t) = v for :math:t. They must be mutual inverses wherever :math:H_0 is finite and strictly increasing.

hazard

hazard(t: TimeLike) -> TimeLike

Instantaneous hazard :math:h_0(t).

Source code in gen_surv/baseline.py

def hazard(self, t: TimeLike) -> TimeLike:
    """Instantaneous hazard :math:`h_0(t)`."""
    ...

cumulative_hazard

cumulative_hazard(t: TimeLike) -> TimeLike

Integrated hazard :math:H_0(t) = \int_0^t h_0(u)\,du.

Source code in gen_surv/baseline.py

def cumulative_hazard(self, t: TimeLike) -> TimeLike:
    """Integrated hazard :math:`H_0(t) = \\int_0^t h_0(u)\\,du`."""
    ...

inverse_cumulative_hazard

inverse_cumulative_hazard(value: TimeLike) -> TimeLike

Time at which the cumulative hazard reaches value.

Returns inf where the cumulative hazard never reaches it, which is a real property of some families rather than an error.

Source code in gen_surv/baseline.py

def inverse_cumulative_hazard(self, value: TimeLike) -> TimeLike:
    """Time at which the cumulative hazard reaches ``value``.

    Returns ``inf`` where the cumulative hazard never reaches it, which is a
    real property of some families rather than an error.
    """
    ...

ExponentialBaseline dataclass

ExponentialBaseline(rate: float = 1.0)

Constant hazard: :math:h_0(t) = \lambda.

The memoryless case. Waiting times are exponential, so on a multi-event process it makes no difference whether the clock runs forward or resets.

Parameters:

Name	Type	Description	Default
rate	float	The constant hazard, positive.	1.0

WeibullBaseline dataclass

WeibullBaseline(shape: float = 1.0, scale: float = 1.0)

Monotone hazard: :math:H_0(t) = (t/\sigma)^{\rho}.

Falling for shape < 1, constant at 1, rising above it.

Parameters:

Name	Type	Description	Default
shape	float	The Weibull shape :math:\rho, positive.	1.0
scale	float	The Weibull scale :math:\sigma, positive.	1.0

GompertzBaseline dataclass

GompertzBaseline(rate: float = 1.0, shape: float = 0.1)

Exponentially changing hazard: :math:h_0(t) = a e^{bt}.

A negative shape is allowed and gives a declining hazard whose total is finite, :math:a/|b|. Beyond that total the inverse is inf: the event never happens, which is the point of the family rather than a failure.

Parameters:

Name	Type	Description	Default
rate	float	The hazard at time zero, :math:a, positive.	1.0
shape	float	The exponential rate of change, :math:b. Non-zero; negative for a declining hazard. Use :class:ExponentialBaseline for b = 0.	0.1

total_hazard property

total_hazard: float

The limit of :math:H_0(t), finite only for a declining hazard.

LogLogisticBaseline dataclass

LogLogisticBaseline(shape: float = 1.0, scale: float = 1.0)

Unimodal hazard: :math:H_0(t) = \log(1 + (t/\sigma)^{\rho}).

The hazard rises to a peak and then decays, which no other family here does. Not a proportional-hazards family in its own right, but a perfectly good baseline to scale by a linear predictor.

Parameters:

Name	Type	Description	Default
shape	float	The shape :math:\rho, positive.	1.0
scale	float	The scale :math:\sigma, positive.	1.0

PiecewiseConstantBaseline dataclass

PiecewiseConstantBaseline(
    breakpoints: Sequence[float] = (),
    hazard_rates: Sequence[float] = (1.0,),
)

Constant within intervals, jumping between them.

There is always one more rate than there are breakpoints: k breakpoints cut the timeline into k + 1 pieces, the last one open-ended.

Parameters:

Name	Type	Description	Default
breakpoints	Sequence[float]	Strictly increasing positive times at which the hazard changes.	()
hazard_rates	Sequence[float]	One positive rate per interval, len(breakpoints) + 1 of them.	(1.0,)