Types

Type aliases and protocols used in the lymph package.

exception lymph.types.DataWarning

Bases: UserWarning

Warnings related to potential data issues.

class lymph.types.HasSetParams(*args, **kwargs)

Bases: Protocol

Protocol for classes that have a set_params method.

class lymph.types.HasGetParams(*args, **kwargs)

Bases: Protocol

Protocol for classes that have a get_params method.

lymph.types.GraphDictType

Type alias for a graph dictionary.

A dictionary of this form specifies the structure of the underlying graph. Example:

>>> graph_dict = {
...     ("tumor", "T"): ["I", "II", "III"],
...     ("lnl", "I"): ["II"],
...     ("lnl", "II"): ["III"],
...     ("lnl", "III"): [],
... }

lymph.types.ParamsType

Type alias for how parameters are passed around.

This is e.g. the type that the Model.get_params() method returns.

alias of Iterable[float] | dict[str, float]

lymph.types.InvolvementIndicator

Type alias for how to encode lymphatic involvement for a single lymph node level.

The choices "micro", "macro", and "notmacro" are only relevant for the trinary models.

alias of Literal[False, 0, ‘healthy’, True, 1, ‘involved’, ‘micro’, ‘macro’, ‘notmacro’]

lymph.types.PatternType

Type alias for an involvement pattern.

An involvement pattern is a dictionary with keys for the lymph node levels and values for the involvement of the respective lymph nodes. The values are either True, False, or None, which means that the involvement is unknown.

TODO: Document the new possibilities to specify trinary involvment. See matrix.compute_encoding()

>>> pattern = {"I": True, "II": False, "III": None}

lymph.types.DiagnosisType

Type alias for a diagnosis, which is an involvement pattern per diagnostic modality.

>>> diagnosis = {
...     "CT": {"I": True, "II": False, "III": None},
...     "MRI": {"I": True, "II": True, "III": None},
... }

class lymph.types.Model

Bases: ABC

Abstract base class for models.

This class provides a scaffold for the methods that any model for lymphatic tumor progression should implement.

abstract get_params(as_dict: bool = True, as_flat: bool = True) → Iterable[float] | dict[str, float]

Return the parameters of the model.

The parameters are returned as a dictionary if as_dict is True, and as an iterable of floats otherwise. The argument as_flat determines whether the returned dict is flat or nested. This is helpful, because a model may call the get_params method of other instances, which can be fused to get a flat dictionary.

get_num_dims(mode: Literal['HMM', 'BN'] = 'HMM') → int

Return the number of dimensions of the parameter space.

A hidden Markov model (mode="HMM") typically has more parameters than a Bayesian network (mode="BN"), because it we need parameters for the distributions over diagnosis times. Your can read more about that in the lymph.diagnosis_times module.

abstract set_params(*args: float, **kwargs: float) → tuple[float]

Set the parameters of the model.

The parameters may be passed as positional or keyword arguments. The positional arguments are used up one by one by the set_params methods the model calls. Keyword arguments override the positional arguments.

abstract state_dist(t_stage: str, mode: Literal['HMM', 'BN'] = 'HMM') → ndarray

Return the prior state distribution of the model.

The state distribution is the probability of the model being in any of the possible hidden states.

obs_dist(given_state_dist: ndarray | None = None, t_stage: str = 'early', mode: Literal['HMM', 'BN'] = 'HMM') → ndarray

Return the distribution over observational states.

If given_state_dist is None, it will first compute the state_dist() using the arguments t_stage and mode (which are otherwise ignored). Then it multiplies the distribution over (hidden) states with the specificity and sensitivity values stored in the model (see modalities.Composite()) and marginalizes over the hidden states.

abstract load_patient_data(patient_data: DataFrame) → None

Load patient data in LyProX format into the model.

abstract likelihood(given_params: Iterable[float] | dict[str, float] | None = None, log: bool = True) → float

Return the likelihood of the model given the parameters.

The likelihood is returned in log space if log is True, and in linear space otherwise. The parameters may be passed as positional or keyword arguments. They are then passed to the set_params() method first.

abstract posterior_state_dist(given_params: Iterable[float] | dict[str, float] | None = None, given_state_dist: ndarray | None = None, given_diagnosis: dict[str, dict[str, Literal[False, 0, 'healthy', True, 1, 'involved', 'micro', 'macro', 'notmacro'] | None]] | None = None) → ndarray

Return the posterior state distribution using the given_diagnosis.

The posterior state distribution is the probability of the model being in a certain state given the diagnosis. The given_params are passed to the set_params() method. Alternatively to parameters, one may also pass a given_state_dist, which is effectively the precomputed prior from calling state_dist().

marginalize(involvement: dict[str, dict[str, Literal[False, 0, 'healthy', True, 1, 'involved', 'micro', 'macro', 'notmacro'] | None]] | None = None, given_state_dist: ndarray | None = None, t_stage: str = 'early', mode: Literal['HMM', 'BN'] = 'HMM') → float

Marginalize given_state_dist over matching involvement patterns.

Any state that matches the provided involvement pattern is marginalized over. For this, the matrix.compute_encoding() function is used.

If given_state_dist is None, it will be computed by calling state_dist() with the given t_stage and mode. These arguments are ignored if given_state_dist is provided.

abstract risk(involvement: dict[str, Literal[False, 0, 'healthy', True, 1, 'involved', 'micro', 'macro', 'notmacro'] | None] | None = None, given_params: Iterable[float] | dict[str, float] | None = None, given_state_dist: ndarray | None = None, given_diagnosis: dict[str, dict[str, Literal[False, 0, 'healthy', True, 1, 'involved', 'micro', 'macro', 'notmacro'] | None]] | None = None) → float

Return the risk of involvement, given params/state_dist and diagnosis.