pymkm.mktable

Tools for generating microdosimetric model tables (MKTable).

This subpackage provides all components to compute, analyze, and export dose-averaged specific energy quantities used in the Microdosimetric Kinetic Model (MKM), its stochastic extension (SMK), and the oxygen-enhanced variant as described by Inaniwa & Kanematsu, (JRR, 2023).

The typical workflow includes: - configuration of model and geometry parameters - per-ion table computation from LET data - saturation correction and optional hypoxia adjustment - interactive visualization and export to clinical-compatible formats

Each computed result is stored in the self.table dictionary with the structure:

MKTable.table = {
    "C": {
        "params": {...},                   # Input model parameters
        "stopping_power_info": {...},     # Metadata (LET, Z, A, source...)
        "data": pd.DataFrame([            # Main output table
            {
                "energy": ...,            # [MeV/u]
                "let": ...,               # [MeV/cm]
                "z_bar_star_domain": ..., # [Gy]
                "z_bar_domain": ...,      # [Gy] (SMK only)
                "z_bar_nucleus": ...      # [Gy] (SMK only)
            },
            ...
        ])
    },
    ...
}

Modules

• core: Defines MKTableParameters and MKTable, which manage configuration, geometry, stopping power sets, and result storage.

• compute: Implements compute(), the numerical engine that builds microdosimetric tables from energy–LET inputs.

• plot: Adds plot(), enabling multi-ion plots of dose-averaged specific energy quantities vs. energy or LET.

Usage

This subpackage is the main high-level interface to pyMKM.

from pymkm.mktable import MKTable, MKTableParameters

params = MKTableParameters(domain_radius=0.5, nucleus_radius=3.0, beta0=0.05)
mktable = MKTable(params)
mktable.compute()
mktable.plot()
mktable.save()
mktable.write_txt(...)

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

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)

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

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)

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)

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)

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)

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

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

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

Submodules

• pymkm.mktable.compute
  • compute()
• pymkm.mktable.core
• pymkm.mktable.plot
  • plot()