pymkm.sftable¶

Survival fraction table generation for MKM, SMK, and OSMK models.

This subpackage provides tools for computing and visualizing survival fraction (SF) curves based on microdosimetric quantities from an MKTable.

After running compute(), the results are stored in self.table as a list of result dictionaries:

SFTable.table = [
    {
        "params": {
            "ion": "12C",
            "energy": 160.0,
            "let": 28.3,
            "model": "stochastic",
            "osmk_version": "2023"
        },
        "calculation_info": "computed",
        "data": pd.DataFrame({
            "dose": [...],                 # [Gy]
            "survival_fraction": [...]     # dimensionless
        })
    },
    ...
]

Models supported¶

MKM (classic): Linear-quadratic model with saturation correction.
SMK (stochastic): Extension of MKM using dose-averaged microdosimetric inputs.
OSMK (oxygen-aware SMK): Includes hypoxia corrections using 2021 or 2023 formulations
by Inaniwa et al., (Phys. Med. Biol., 2021) and Inaniwa & Kanematsu, (JRR, 2023).

Modules¶

core: Defines SFTableParameters and SFTable for configuring and managing SF table generation.
compute: Provides compute(), the main routine for calculating survival curves from LET and energy data.
plot: Contains plotting utilities for visualizing survival curves across doses, energies, or ions.

Usage¶

The sftable module is typically used after computing an MKTable:

from pymkm.sftable.core import SFTableParameters, SFTable

params = SFTableParameters(mktable=mktable, alpha0=0.1, beta0=0.05)
sftable = SFTable(params)
sftable.compute(ion="C")
sftable.plot()

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

Bases: object

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.

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¶

pymkm.sftable¶

Models supported¶

Modules¶

Usage¶

Submodules¶