pymkm.sftable.core

Core classes for survival fraction (SF) table generation.

This module defines:

  • SFTableParameters: A dataclass storing all parameters required to compute survival fraction curves using MKM, SMK, or OSMK models.

  • SFTable: A computation manager that integrates MKTable results with biological model parameters to produce survival fraction outputs.

The module supports OSMK 2021 and OSMK 2023 models.

class pymkm.sftable.core.SFTable(parameters: SFTableParameters)[source]

Bases: object

compute(*, ion: str | int, energy: float | None = None, let: float | None = None, force_recompute: bool | None = True, model: Literal['classic', 'stochastic'] | None = None, apply_oxygen_effect: bool = False) → None

Compute survival fraction curve(s) based on microdosimetric inputs.

This function stores the results in self.table as a list of result dictionaries.

Parameters:

  • ion (Union[str, int]) – Ion name, symbol, or atomic number.

  • energy (Optional[float]) – Kinetic energy per nucleon [MeV/u]. Interpolated if not provided.

  • let (Optional[float]) – Linear energy transfer [MeV/cm]. Interpolated if not provided.

  • force_recompute (Optional[bool]) – If True, recomputes results even if cached data exist.

  • model (Literal["classic", "stochastic"], optional) – Microdosimetric model to use: “classic” or “stochastic”.

  • apply_oxygen_effect (Optional[bool]) – Whether to apply OSMK model. Ignored if model != “stochastic”.

Returns:

None. Results are stored in self.table.

Raises:

ValueError – If inputs are inconsistent, or if required parameters are missing.

display(results: list)[source]

Display the computed survival fraction results in a tabular format.

Parameters:

results (list[dict]) – List of dictionaries with keys ‘params’, ‘calculation_info’, and ‘data’.

Raises:

ValueError – If no results are provided.

plot(*, verbose: bool | None = False, let: float | None = None)

Plot survival fraction curves stored in self.table.

Parameters:

  • verbose (Optional[bool]) – If True, displays model parameters on the plot.

  • let (Optional[float]) – LET value [MeV/cm] to filter the curves to plot. If None, all results are shown.

Raises:

ValueError – If no results are available or no match is found for the specified LET.

summary()[source]

Print a detailed summary of the current survival model configuration.

Displays LQ parameters and OSMK-related settings if applicable.

class pymkm.sftable.core.SFTableParameters(mktable: ~pymkm.mktable.core.MKTable, alpha0: float | None = None, beta0: float | None = None, dose_grid: ~numpy.ndarray = <factory>, alphaL: float | None = None, alphaS: float | None = None, zR: float | None = None, gamma: float | None = None, Rm: float | None = None, f_rd_max: float | None = None, f_z0_max: float | None = None, Rmax: float | None = None, K: float = 3.0, pO2: float | None = None)[source]

Bases: object

Configuration container for computing survival fraction (SF) curves using MKM, SMK, or OSMK models.

Parameters:

  • mktable (pymkm.mktable.core.MKTable) – Precomputed MKTable containing specific energy values.

  • alpha0 (Optional[float]) – Total linear coefficient α₀ in the LQ model [Gy⁻¹]. Required unless both alphaL and alphaS are provided.

  • beta0 (Optional[float]) – Quadratic coefficient β₀ in the LQ model [Gy⁻²]. If not provided, it is retrieved from mktable.parameters.

  • dose_grid (Optional[np.ndarray]) – Dose grid [Gy] over which to compute survival fractions. Defaults to np.arange(0, 15.5, 0.5).

  • alphaL (Optional[float]) – Linear coefficient for lethal lesions [Gy⁻¹] (OSMK 2021/2023).

  • alphaS (Optional[float]) – Linear coefficient for sublethal lesions [Gy⁻¹] (OSMK 2021/2023).

  • zR (Optional[float]) – Radiation quality–dependent oxygen parameter [Gy] (OSMK 2021 only).

  • gamma (Optional[float]) – Exponent for R_max(zd) expression (OSMK 2021 only).

  • Rm (Optional[float]) – Minimum value of R_max (OSMK 2021 only).

  • f_rd_max (Optional[float]) – Maximum domain radius scaling factor under hypoxia (OSMK 2023 only).

  • f_z0_max (Optional[float]) – Maximum saturation parameter scaling factor under hypoxia (OSMK 2023 only).

  • Rmax (Optional[float]) – Maximum radioresistance at pO₂ = 0 mmHg (OSMK 2023 only).

  • K (Optional[float]) – Oxygen pressure [mmHg] at which R(pO₂) = (1 + Rmax)/2. Default is 3.0 (Inaniwa 2021).

  • pO2 (Optional[float]) – Oxygen partial pressure [mmHg] at which to evaluate the oxygen effect. Enables OSMK mode if set.

K: float = 3.0
Rm: float | None = None
Rmax: float | None = None
alpha0: float | None = None
alphaL: float | None = None
alphaS: float | None = None
beta0: float | None = None
dose_grid: ndarray
f_rd_max: float | None = None
f_z0_max: float | None = None
classmethod from_dict(config: dict) → SFTableParameters[source]

Create an SFTableParameters instance from a dictionary.

Unrecognized keys in the dictionary will trigger a warning.

Parameters:

config (dict) – Dictionary of parameters with keys matching the dataclass fields.

Returns:

A populated SFTableParameters instance.

Return type:

SFTableParameters

Raises:

ValueError – If unknown keys are present in the configuration dictionary.

gamma: float | None = None
mktable: MKTable
pO2: float | None = None
zR: float | None = None