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 Union[Iterable[float], dict[str, float]]

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.DiagnoseType

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

>>> diagnose = {
...     "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.diagnose_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 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 risk(involvement: dict[str, bool | str | NAType | None] | None = None, given_params: Iterable[float] | dict[str, float] | None = None, given_state_dist: ndarray | None = None, given_diagnoses: dict[str, dict[str, bool | str | NAType | None]] | None = None) → float | ndarray

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