Types#
Type aliases and protocols used in the lymph package.
- exception lymph.types.DataWarning[source]#
Bases:
UserWarning
Warnings related to potential data issues.
- class lymph.types.HasSetParams(*args, **kwargs)[source]#
Bases:
Protocol
Protocol for classes that have a
set_params
method.
- class lymph.types.HasGetParams(*args, **kwargs)[source]#
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.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[source]#
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] [source]#
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 argumentas_flat
determines whether the returned dict is flat or nested. This is helpful, because a model may call theget_params
method of other instances, which can be fused to get a flat dictionary.
- get_num_dims(mode: Literal['HMM', 'BN'] = 'HMM') int [source]#
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 thelymph.diagnosis_times
module.
- abstract set_params(*args: float, **kwargs: float) tuple[float] [source]#
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 [source]#
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 [source]#
Return the distribution over observational states.
If
given_state_dist
isNone
, it will first compute thestate_dist()
using the argumentst_stage
andmode
(which are otherwise ignored). Then it multiplies the distribution over (hidden) states with the specificity and sensitivity values stored in the model (seemodalities.Composite()
) and marginalizes over the hidden states.
- abstract load_patient_data(patient_data: DataFrame) None [source]#
Load patient data in LyProX format into the model.
- abstract likelihood(given_params: Iterable[float] | dict[str, float] | None = None, log: bool = True) float [source]#
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 theset_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 [source]#
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 theset_params()
method. Alternatively to parameters, one may also pass agiven_state_dist
, which is effectively the precomputed prior from callingstate_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 [source]#
Marginalize
given_state_dist
over matchinginvolvement
patterns.Any state that matches the provided
involvement
pattern is marginalized over. For this, thematrix.compute_encoding()
function is used.If
given_state_dist
isNone
, it will be computed by callingstate_dist()
with the givent_stage
andmode
. These arguments are ignored ifgiven_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 [source]#
Return the risk of
involvement
, given params/state_dist and diagnosis.