leaspy.models.summary#

Model inspection objects for programmatic access to model metadata.

This module provides Summary and Info, returned by model.summary() and model.info() respectively, along with the TypedDict schemas for training and dataset metadata.

Both classes auto-print when their return value is discarded (e.g. model.summary()) and stay silent when stored in a variable (e.g. s = model.summary()). See AutoPrintMixin for details.

Classes#

`VisitsPerSubject`	Per-subject visit distribution statistics.
`DatasetInfo`	Statistics of the training dataset, computed during `fit()`.
`TrainingInfo`	Metadata about the training process, captured during `fit()`.
`AutoPrintMixin`	Mixin that auto-prints when the object is discarded.
`Info`	Model configuration and training context (no parameter values).
`Summary`	Structured summary of a Leaspy model including parameter values.

Functions#

`get_axis_labels`(axis_name, size[, feature_names])	Resolve human-readable labels for a parameter axis.
`get_number_of_parameters`(model)	Calculate the number of free parameters of the model.
`compute_bic`(nll, num_params, n_subjects)	Calculate the Bayesian Information Criterion (BIC).
`compute_aic`(nll, num_params, n_subjects)	Calculate the Akaike Information Criterion (AIC).
`compute_icl`(bic, model)	Calculate the Integrated Completed Likelihood (ICL) for a mixture model.

Module Contents#

class VisitsPerSubject[source]#

Bases: TypedDict

Per-subject visit distribution statistics.

median: float#

min: int#

max: int#

iqr: float#

class DatasetInfo[source]#

Bases: TypedDict

Statistics of the training dataset, computed during fit().

n_subjects: int#

n_scores: int#

n_visits: int#

n_observations: int#

visits_per_subject: VisitsPerSubject#

n_events: int#

class TrainingInfo[source]#

Bases: TypedDict

Metadata about the training process, captured during fit().

algorithm: str#

seed: int#

n_iter: int#

n_burn_in_iter: int#

converged: bool#

duration: str#

get_axis_labels(axis_name, size, feature_names=None)[source]#

Resolve human-readable labels for a parameter axis.

Parameters:

axis_namestr or None: Semantic axis name ("feature", "source", "cluster", "basis").
sizeint: Number of elements along the axis.
feature_nameslist[str], optional: Feature names used when axis_name is "feature".

Returns:

list[str] or None: Labels for the axis, or None if no meaningful labels are available.

Parameters:

axis_name (Optional[str])
size (int)
feature_names (Optional[list[str]])

Return type:

Optional[list[str]]

class AutoPrintMixin[source]#

Mixin that auto-prints when the object is discarded.

Relies on CPython reference counting: when the return value of e.g. model.summary() is not assigned, the object is immediately garbage-collected, triggering __del__ which prints it.

When stored (s = model.summary()), any public attribute access sets _printed = True, suppressing the __del__ output.

Subclasses must define a _printed: bool field (via dataclass) and a __str__ method.

get_number_of_parameters(model)[source]#

Calculate the number of free parameters of the model.

Uses the theoretical formula: P = 3F + (F-1)*S + S*K + 4K where F = features, S = sources, K = clusters.

Parameters:

model: A fitted Leaspy model instance.

Returns:

int: Number of free parameters.

Parameters:

model (BaseModel)

Return type:

int

compute_bic(nll, num_params, n_subjects)[source]#

Calculate the Bayesian Information Criterion (BIC).

BIC = 2 * nll + P * log(N)

Parameters:

nllfloat: Negative log-likelihood (nll_attach).
num_paramsint: Number of free parameters.
n_subjectsint: Number of subjects used for model fitting.

Returns:

float or None: The computed BIC, or None if inputs are invalid.

Parameters:

nll (float)
num_params (int)
n_subjects (int)

Return type:

Optional[float]

compute_aic(nll, num_params, n_subjects)[source]#

Calculate the Akaike Information Criterion (AIC).

AIC = 2 * nll + 2 * P

Parameters:

nllfloat: Negative log-likelihood (nll_attach).
num_paramsint: Number of free parameters.
n_subjectsint: Number of subjects used for model fitting (not used in AIC but included for consistency).

Returns:

float or None: The computed AIC, or None if inputs are invalid.

Parameters:

nll (float)
num_params (int)
n_subjects (int)

Return type:

Optional[float]

compute_icl(bic, model)[source]#

Calculate the Integrated Completed Likelihood (ICL) for a mixture model.

ICL = BIC - sum_i sum_k pi_ik * log(pi_ik)

where pi_ik is the posterior probability that individual i belongs to cluster k (classification responsibility). The entropy term penalises poorly-separated clusters on top of the BIC complexity penalty, so models with crisp cluster assignments are preferred.

Returns None for non-mixture models (i.e. when model.n_clusters is not set), or when bic itself is None.

Parameters:

bicfloat or None: Pre-computed BIC value for this model.
modelBaseModel: A fitted Leaspy model. Mixture-specific fields are read from model.state (per-individual tau, xi, sources) and from model.parameters (cluster priors tau_mean, tau_std, xi_mean, xi_std, sources_mean, probs).

Returns:

float or None: The computed ICL, or None if not applicable.

Parameters:

bic (Optional[float])
model (BaseModel)

Return type:

Optional[float]

class Info[source]#

Bases: AutoPrintMixin

Model configuration and training context (no parameter values).

Returned by model.info(). Auto-prints when discarded; provides programmatic access when stored in a variable.

Examples

>>> model.info()              # prints info
>>> i = model.info()          # store for programmatic access
>>> i.n_subjects              # 150
>>> i.help()                  # list available attributes

name: str#

model_type: str#

dimension: int | None = None#

features: list[str] | None = None#

source_dimension: int | None = None#

n_clusters: int | None = None#

obs_models: list[str] | None = None#

n_total_params: int | None = None#

latent_variables: dict#

training_info: TrainingInfo#

hyperparameters: dict#

dataset_info: DatasetInfo#

leaspy_version: str | None = None#

classmethod from_model(model)[source]#

Build an Info from a model instance.

Works on un-fitted models too: parameter counts and DAG-derived fields are simply omitted when the model state isn’t available yet.

Parameters:: model (BaseModel)
Return type:: Info

property algorithm: str | None#

Algorithm name used for training.

Return type:: Optional[str]

property seed: int | None#

Random seed used for training.

Return type:: Optional[int]

property n_iter: int | None#

Number of iterations.

Return type:: Optional[int]

property n_burn_in_iter: int | None#

Number of burn-in (memory-less) iterations.

Return type:: Optional[int]

property converged: bool | None#

Whether training converged.

Return type:: Optional[bool]

property duration: str | None#

Training duration.

Return type:: Optional[str]

property hyperparameter: dict#

Model hyperparameters (e.g. source_dimension, obs_model).

Return type:: dict

property latent_variable_distributions: dict#

Latent variable prior distributions, grouped by population/individual.

Return type:: dict

property n_subjects: int | None#

Number of subjects in the training dataset.

Return type:: Optional[int]

property n_visits: int | None#

Total number of visits.

Return type:: Optional[int]

property n_scores: int | None#

Number of scored features.

Return type:: Optional[int]

property n_observations: int | None#

Total number of observed data points.

Return type:: Optional[int]

property visits_per_subject: VisitsPerSubject | None#

Per-subject visit distribution statistics.

Return type:: Optional[VisitsPerSubject]

property n_events: int | None#

Number of observed events (joint models only).

Return type:: Optional[int]

help()[source]#

Print available attributes and their meanings.

Return type:: None

class Summary[source]#

Bases: AutoPrintMixin

Structured summary of a Leaspy model including parameter values.

Returned by model.summary(). Auto-prints when discarded; provides programmatic access when stored in a variable.

Examples

>>> model.summary()           # prints the formatted summary
>>> s = model.summary()       # store for programmatic access
>>> s.algorithm               # 'mcmc_saem'
>>> s.get_param('tau_std')    # tensor([10.5])
>>> s.help()                  # list available attributes

name: str#

model_type: str#

dimension: int | None = None#

features: list[str] | None = None#

source_dimension: int | None = None#

n_clusters: int | None = None#

obs_models: list[str] | None = None#

n_total_params: int | None = None#

nll: float | None = None#

bic: float | None = None#

aic: float | None = None#

icl: float | None = None#

training_info: TrainingInfo#

dataset_info: DatasetInfo#

parameters: dict[str, dict[str, Any]]#

derived_parameters: dict[str, Any]#

leaspy_version: str | None = None#

classmethod from_model(model)[source]#

Build a Summary from a model instance.

Parameters:: model (BaseModel)
Return type:: Summary

property sources: list[str] | None#

Source names (e.g. ['s0', 's1']) or None.

Return type:: Optional[list[str]]

property clusters: list[str] | None#

Cluster names (e.g. ['c0', 'c1']) or None.

Return type:: Optional[list[str]]

property algorithm: str | None#

Algorithm name used for training.

Return type:: Optional[str]

property seed: int | None#

Random seed used for training.

Return type:: Optional[int]

property n_iter: int | None#

Number of iterations.

Return type:: Optional[int]

property converged: bool | None#

Whether training converged.

Return type:: Optional[bool]

property n_subjects: int | None#

Number of subjects in the training dataset.

Return type:: Optional[int]

property n_visits: int | None#

Total number of visits.

Return type:: Optional[int]

property n_observations: int | None#

Total number of observations.

Return type:: Optional[int]

get_param(name)[source]#

Get a parameter value by name, searching fitted and derived parameters.

Parameters:

namestr: Parameter name (e.g. 'betas_mean', 'tau_std', 'v0', 'p0').

Returns:

value: The parameter value (typically a torch.Tensor), or None.

Parameters:

name (str)

Return type:

Optional[Any]

help()[source]#

Print available attributes and their meanings.

Return type:: None