Parametric Recurrence Model

class surpyval.recurrent.parametric.parametric_recurrence.ParametricRecurrenceModel

Bases: RecurrenceSimulationMixin, LikelihoodInferenceMixin

A class for holding the parameters, data, and usefult methods for a fitted parametric recurrence model. This is the result of the fit calls from the counting distributions.

When fitted by maximum likelihood the model also carries the likelihood- inference behaviour (log_likelihood, aic, bic, standard_errors) from LikelihoodInferenceMixin. Models built by from_params or fitted by how="MSE" carry no likelihood, so those methods raise.

Example

>>> from surpyval import Exponential
>>> from surpyval.recurrent import HPP
>>> import numpy as np
>>> np.random.seed(1)
>>> x = Exponential.random(10, 1e-3).cumsum()
>>> model = HPP.fit(x)

cif(x)

Compute the cumulative incidence function (CIF) based on the fitted model. No need to pass parameters as it uses the parameters of the fitted model.

Parameters: x (array_like) – Values at which to compute the CIF.
Returns: Computed cumulative intensity function values.
Return type: array_like

count_terminated_simulation(events, items=1, seed=None)

Simulate count-terminated recurrence data based on the fitted model.

Parameters

events (int) – Number of events to simulate.
items (int, optional) – Number of items (or sequences) to simulate. Default is 1.
seed (int or numpy.random.Generator, optional) – Seed for a reproducible simulation. When None (default) the numpy global RNG is used.

Returns

An NonParametricCounting model built from the simulated data.

Return type

NonParametricCounting

count_terminated_simulation_data(events, items=1, seed=None)

Simulate count-terminated recurrence data and return the raw events.

Unlike count_terminated_simulation() (which returns the fitted NonParametricCounting MCF), this returns the simulated event data itself, ready to be refitted or inspected via .x/.i/.c/ .n.

Parameters

events (int) – Number of events to simulate per sequence.
items (int, optional) – Number of items (or sequences) to simulate. Default is 1.
seed (int or numpy.random.Generator, optional) – Seed for a reproducible simulation.

Returns

The simulated recurrence data in xicn format.

Return type

RecurrentEventData

Notes

Count termination is a failure-terminated (Type II) scheme: each item is observed until its events + 1-th event, so its observation window is the random time of that last event and every event is exact (c = 0). Parametric fits handle this correctly – the interarrival/intensity likelihood ends at the last observed event and the MLE is consistent. The nonparametric MCF, however, is only reliable up to roughly events recurrences: beyond that the at-risk set is depleted and the curve is biased (which is why count_terminated_simulation() trims to mcf_hat < events). For a fixed-window observation scheme, use time_terminated_simulation_data(), which right-censors each item at T.

covariance(): Approximate parameter covariance matrix, ordered to match parameter_names. Computed as the inverse of the numerical Hessian of the negative log-likelihood at the MLE.

iif(x)

Compute the intensity function based on the fitted model. No need to pass parameters as it uses the parameters of the fitted model.

Parameters: x (array_like) – Values at which to compute the intensity.
Returns: Computed instantaneous intensity functions values.
Return type: array_like

mcf(x)

The mean cumulative function (MCF). For these counting processes the MCF equals the cumulative intensity, so this is a closed-form alias for cif() (overriding the simulation-based estimate in the mixin).

Parameters: x (array_like) – Values at which to compute the MCF.
Returns: The MCF evaluated at x.
Return type: array_like

plot(ax=None)

Compute the inverse of the cumulative incidence function (CIF) based on the fitted model, if it’s defined for the distribution.

Parameters: ax (matplotlib axes, optional) – An axes object to draw the plot on. Creates a new one if not provided.
Returns: An axes object with the plot.
Return type: matplotlib axes

standard_errors(): Standard errors of the fitted parameters (the square roots of the diagonal of covariance()), ordered to match parameter_names. Entries are NaN where the variance is non-positive, which typically indicates a boundary optimum.

time_terminated_simulation(T, items=1, tol=1e-08, max_events=10000, seed=None)

Simulate time-terminated recurrence data based on the fitted model.

Parameters

T (float) – Time termination value.
items (int, optional) – Number of items (or sequences) to simulate. Default is 1.
tol (float, optional) – Interarrival times below this value end the sequence early; a tiny increment indicates the cumulative time has stalled below T (a possible asymptote). Default is 1e-8.
max_events (int, optional) – Hard cap on the number of events simulated per sequence. This is the backstop that guarantees termination for sequences whose cumulative time cannot reach T. Default is 10000.
seed (int or numpy.random.Generator, optional) – Seed for a reproducible simulation. When None (default) the numpy global RNG is used.

Returns

An NonParametricCounting model built from the simulated data.

Return type

NonParametricCounting

Warning

A sequence is terminated early and right-censored at its last event if an interarrival time falls below tol or it reaches max_events before T. A warning is raised in either case.

time_terminated_simulation_data(T, items=1, tol=1e-08, max_events=10000, seed=None)

Simulate time-terminated recurrence data and return the raw events.

Unlike time_terminated_simulation() (which returns the fitted NonParametricCounting MCF), this returns the simulated event data itself, ready to be refitted or inspected via .x/.i/.c/ .n. Each sequence is right-censored at T.

Parameters

T (float) – Time termination value.
items (int, optional) – Number of items (or sequences) to simulate. Default is 1.
tol (float, optional) – Interarrival times below this value end the sequence early. Default is 1e-8.
max_events (int, optional) – Hard per-sequence event cap that guarantees termination. Default is 10000.
seed (int or numpy.random.Generator, optional) – Seed for a reproducible simulation.

Returns

The simulated recurrence data in xicn format.

Return type

RecurrentEventData