pymkm.mktable.core

Core classes for MKM and SMK microdosimetric table generation.

This module defines: - MKTableParameters: configuration container for geometry, models, and computation settings - MKTable: main interface for generating, storing, and exporting microdosimetric tables

Supports both classic MKM and stochastic SMK models, with optional OSMK 2023 corrections for hypoxia. Each MKTable instance manages the full computation pipeline per ion type, including saving, loading, displaying, and exporting results.

class pymkm.mktable.core.MKTable(parameters: MKTableParameters, sp_table_set: StoppingPowerTableSet | None = None)[source]

Bases: object

Main handler for microdosimetric table generation using MKM or SMK.

This class manages the physical model, geometry, table computation, result storage, and export functionalities.

compute(ions: List[str | int] | None = None, energy: float | List[float] | ndarray | None = None, parallel: bool = True, integration_method: str = 'trapz') → None

Compute per-ion microdosimetric tables using MKM or SMK model.

For each ion:

  • Retrieves energy–LET grid

  • Computes specific energy and dose-averaged quantities

  • Applies saturation correction and optional OSMK

  • Aggregates into a structured table

Parameters:

  • self (MKTable) – MKTable instance.

  • ions (list[str or int], optional) – Ion identifiers to compute. If None, all available ions are used.

  • energy (float or list or np.ndarray, optional) – Custom energy grid for resampling (if any).

  • parallel (bool) – Whether to enable multiprocessing.

  • integration_method (str) – Integration scheme (‘trapz’, ‘simps’, ‘quad’).

Raises:

RuntimeError – If MKTable is not initialized.

display(preview_rows: int = 5)[source]

Print a formatted preview of the computed tables for all ions.

Shows metadata, model parameters, and head/tail of each ion’s table.

Parameters:

preview_rows (int) – Number of rows to display from start and end of each table.

Raises:

ValueError – If no tables have been computed.

get_table(ion: str | int) → DataFrame[source]

Retrieve computed table for a specific ion.

Parameters:

ion (str or int) – Ion identifier (name, symbol, or atomic number).

Returns:

Microdosimetric table as a DataFrame.

Return type:

pandas.DataFrame

Raises:

ValueError – If results are not available or ion is not found.

load(filename: str | Path)[source]

Load previously saved MKTable results from a pickle file.

Parameters:

filename (str or Path) – Path to the .pkl file containing saved table data.

Raises:

FileNotFoundError – If the specified file does not exist.

property model_version: str

Get the active model version as a string label.

Returns:

‘stochastic’ if SMK is enabled, otherwise ‘classic’ (MKM).

Return type:

str

plot(ions: List[str | int] | None = None, *, x: str = 'energy', y: str = 'z_bar_star_domain', verbose: bool = False, ax: Axes | None = None, show: bool | None = True)

Plot microdosimetric quantities from the MKTable.

Parameters:

  • ions (list[str or int], optional) – List of ions to plot. If None, all computed ions are used.

  • x (str) – x-axis variable (‘energy’ or ‘let’).

  • y (str) – y-axis variable (‘z_bar_star_domain’, ‘z_bar_domain’, ‘z_bar_nucleus’).

  • verbose (bool) – Show model configuration in the plot.

  • ax (Optional[matplotlib.axes.Axes]) – Matplotlib Axes object to draw on. If None, a new figure is created.

  • show (Optional[bool]) – If True, displays the plot. Set False when embedding or scripting.

Raises:

  • RuntimeError – If table is empty.

  • ValueError – If x or y are invalid.

save(filename: str | Path | None = None)[source]

Save the computed MKTable results to a pickle file.

Parameters:

filename (str or Path, optional) – Optional output file path. If None, uses default name.

Raises:

ValueError – If no results have been computed.

summary(verbose: bool = False)[source]

Print a summary of the current MKTable configuration.

Displays model type, physical parameters, and sampling settings. If verbose is True, lists available ions and technical details.

Parameters:

verbose (bool, optional) – If True, include detailed configuration info.

write_txt(*, params: dict, filename: str | Path | None = None, model: Literal['classic', 'stochastic'] | None = None, max_atomic_number: int)[source]

Export results to a .txt file compatible with external tools.

Required params depend on the selected model:

For model=”classic” (MKM):
Required:

  • “CellType”: str

  • “Alpha_0”: float

Optional:

  • “Beta”: float

For model=”stochastic” (SMK):
Required:

  • “CellType”: str

  • “Alpha_ref”: float

  • “Beta_ref”: float

  • “Alpha0”: float

Optional:

  • “Beta0”: float

  • “scale_factor”: float (defaults to 1.0)

Parameters:

  • params (dict) – Model-dependent metadata to include in the header.

  • filename (str or Path, optional) – Output file path. If None, a default name is generated.

  • model (Literal["classic", "stochastic"], optional) – Force output format. If None, inferred from configuration.

  • max_atomic_number (int) – Maximum Z for ions to include.

Raises:

  • ValueError –

    • If no data has been computed yet.

    • If required parameters are missing.

    • If atomic number exceeds available Z range.

  • KeyError – If unexpected or invalid keys are present in params.

class pymkm.mktable.core.MKTableParameters(domain_radius: float, nucleus_radius: float, z0: float | None = None, beta0: float | None = None, model_name: str = 'Kiefer-Chatterjee', core_radius_type: str = 'energy-dependent', base_points_b: int = 150, base_points_r: int = 150, use_stochastic_model: bool = False, pO2: float | None = None, f_rd_max: float | None = None, f_z0_max: float | None = None, Rmax: float | None = None, K: float = 3.0, apply_oxygen_effect: bool = False)[source]

Bases: object

Configuration container for MKTable model and geometry parameters.

This dataclass defines the physical, numerical, and model-specific parameters needed to generate microdosimetric tables using MKM or SMK.

Variables:

  • domain_radius – Radius of the sensitive domain (μm).

  • nucleus_radius – Radius of the cell nucleus (μm).

  • z0 – Saturation parameter z₀ (Gy). Required for SMK.

  • beta0 – LQ model quadratic coefficient β₀ (Gy⁻²). Required for MKM.

  • model_name – Track structure model: ‘Kiefer-Chatterjee’ or ‘Scholz-Kraft’.

  • core_radius_type – Core radius model: ‘constant’ or ‘energy-dependent’.

  • base_points_b – Number of impact parameter sampling points.

  • base_points_r – Number of radial sampling points.

  • use_stochastic_model – If True, enables SMK computation.

  • pO2 – Oxygen partial pressure (mmHg).

  • f_rd_max – Max scaling factor for domain radius under hypoxia.

  • f_z0_max – Max scaling factor for z₀ under hypoxia.

  • Rmax – Maximum radioresistance ratio at 0 mmHg pO2.

  • K – Half-effect oxygen pressure (mmHg).

  • apply_oxygen_effect – Enable OSMK 2023 correction if True.

K: float = 3.0
Rmax: float | None = None
apply_oxygen_effect: bool = False
base_points_b: int = 150
base_points_r: int = 150
beta0: float | None = None
core_radius_type: str = 'energy-dependent'
domain_radius: float
f_rd_max: float | None = None
f_z0_max: float | None = None
classmethod from_dict(config: dict) → MKTableParameters[source]

Create an MKTableParameters instance from a dictionary.

Parameters:

config (dict) – Dictionary of configuration fields.

Returns:

Populated MKTableParameters instance.

Return type:

MKTableParameters

Raises:

ValueError – If unknown keys are present in the dictionary.

model_name: str = 'Kiefer-Chatterjee'
nucleus_radius: float
pO2: float | None = None
use_stochastic_model: bool = False
z0: float | None = None