Skip to content

generate

The dispatcher. Takes a model name and forwards the remaining keyword arguments to that model's generator unchanged.

See Choosing a model for which name to pass, and the Generators page for each generator's own signature.

interface

Interface module to unify access to all survival data generators.

Example: >>> from gen_surv import generate >>> df = generate(model="cphm", n=100, model_cens="uniform", cens_par=1.0, beta=0.5, covariate_range=2.0)

generate 

generate(model: ModelType, **kwargs: object) -> DataFrame

Generate survival data from a specific model.

Parameters:

Name Type Description Default
model ModelType

Name of the generator to run. Must be one of cphm, cmm, tdcm, thmm, aft_ln, aft_weibull, aft_log_logistic, competing_risks, competing_risks_weibull, mixture_cure, piecewise_exponential or recurrent_events.

 required
**kwargs object

Arguments forwarded to the chosen generator. These vary by model.

  • cphm: n, model_cens, cens_par, beta, covariate_range
  • cmm: n, model_cens, cens_par, beta, covariate_range, rate
  • tdcm: n, dist, corr, dist_par, model_cens, cens_par, beta, lam
  • thmm: n, model_cens, cens_par, beta, covariate_range, rate
  • aft_ln: n, beta, sigma, model_cens, cens_par, seed
  • aft_weibull: n, beta, shape, scale, model_cens, cens_par, seed
  • aft_log_logistic: n, beta, shape, scale, model_cens, cens_par, seed
  • competing_risks: n, n_risks, baseline_hazards, betas, covariate_dist, etc.
  • competing_risks_weibull: n, n_risks, shape_params, scale_params, betas, etc.
  • mixture_cure: n, cure_fraction, baseline_hazard, betas_survival, betas_cure, etc.
  • piecewise_exponential: n, breakpoints, hazard_rates, betas, etc.
  • recurrent_events: n, process, baseline, baseline_params, betas, stratum_effects, followup_time, etc.
 {}

Returns:

Type Description
DataFrame

Simulated survival data with columns specific to the chosen model. All models include time/duration and status columns.

Raises:

Type Description
ChoiceError

If an unknown model name is provided.

Examples:

>>> from gen_surv import generate
>>> df = generate(model="cphm", n=100, beta=0.5, covariate_range=2.0,
...               model_cens="uniform", cens_par=1.0)
>>> df.head()
Source code in gen_surv/interface.py 
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def generate(model: ModelType, **kwargs: object) -> pd.DataFrame:
    """Generate survival data from a specific model.

    Parameters
    ----------
    model : ModelType
        Name of the generator to run. Must be one of ``cphm``, ``cmm``,
        ``tdcm``, ``thmm``, ``aft_ln``, ``aft_weibull``, ``aft_log_logistic``,
        ``competing_risks``, ``competing_risks_weibull``, ``mixture_cure``,
        ``piecewise_exponential`` or ``recurrent_events``.
    **kwargs
        Arguments forwarded to the chosen generator. These vary by model.

        - cphm: n, model_cens, cens_par, beta, covariate_range
        - cmm: n, model_cens, cens_par, beta, covariate_range, rate
        - tdcm: n, dist, corr, dist_par, model_cens, cens_par, beta, lam
        - thmm: n, model_cens, cens_par, beta, covariate_range, rate
        - aft_ln: n, beta, sigma, model_cens, cens_par, seed
        - aft_weibull: n, beta, shape, scale, model_cens, cens_par, seed
        - aft_log_logistic: n, beta, shape, scale, model_cens, cens_par, seed
        - competing_risks: n, n_risks, baseline_hazards, betas, covariate_dist, etc.
        - competing_risks_weibull: n, n_risks, shape_params, scale_params, betas, etc.
        - mixture_cure: n, cure_fraction, baseline_hazard, betas_survival,
          betas_cure, etc.
        - piecewise_exponential: n, breakpoints, hazard_rates, betas, etc.
        - recurrent_events: n, process, baseline, baseline_params, betas,
          stratum_effects, followup_time, etc.

    Returns
    -------
    pd.DataFrame
        Simulated survival data with columns specific to the chosen model.
        All models include time/duration and status columns.

    Raises
    ------
    ChoiceError
        If an unknown model name is provided.

    Examples
    --------
    >>> from gen_surv import generate
    >>> df = generate(model="cphm", n=100, beta=0.5, covariate_range=2.0,
    ...               model_cens="uniform", cens_par=1.0)
    >>> df.head()
    """
    ensure_in_choices(model, "model", _model_map.keys())
    try:
        return _model_map[model](**kwargs)
    except ValidationError as exc:
        exc.args = (f"{exc} (while validating inputs for model '{model}')",)
        raise exc