mkt.databases.sasa

Solvent-accessible surface area (SASA) computation configs and residue-level calculation.

Defines SASA configuration dataclasses (Biopython and PyMOL backends, with and without hydrogens), the StandardSASAConfigs presets, and the ResidueSASA model produced by residue-level SASA computation.

Module Attributes

`MAX_ASA_TIEN_2013`	Theoretical maximum accessible surface area (Å^2) per residue.
`DEFAULT_PROBE_RADIUS`	Default solvent/probe radius (Å), shared by both SASA backends.
`DEFAULT_N_POINTS`	Default Shrake-Rupley sphere points per atom (Bio.PDB); presets raise this to ~960 for converged per-residue SASA.
`DEFAULT_DOT_DENSITY`	Default PyMOL surface point density (1-4).

Functions

`_assemble_sasa_df`(list_rows, *, bool_relative)	Build the per-residue DataFrame and optional relative-SASA column.
`_compute_kinase_sasa`(obj_kinase, str_method, ...)	Compute per-residue SASA for one kinase with one backend.
`_residue_sasa_biopython`(structure, *, ...)	Per-residue SASA rows via Bio.PDB Shrake-Rupley.
`_residue_sasa_pymol`(structure, *, ...)	Per-residue SASA rows via PyMOL `dot_solvent` (lazy `pymol2` import).
`_sasa_task`(task)	Worker entry point: compute one (kinase, backend) task and tag the rows.
`_strip_hydrogens`(structure)	Remove all hydrogen atoms from a Bio.PDB Structure in place.

Classes

`BaseSASAConfig`(*[, bool_biopython, ...])	Backend-compatible options for `ResidueSASA`.
`BioPythonHeavyConfig`(*[, bool_biopython, ...])	Heavy-atom Bio.PDB Shrake-Rupley with converged sampling (recommended).
`BioPythonHydrogenConfig`(*[, bool_biopython, ...])	All-atom (explicit-H) Bio.PDB Shrake-Rupley; rSASA disabled.
`CrossValidationConfig`(*[, bool_biopython, ...])	Heavy-atom SASA from both backends with matched probe/sampling.
`CrossValidationHydrogenConfig`(*[, ...])	All-atom (explicit-H) SASA from both backends; rSASA disabled.
`PyMOLHeavyConfig`(*[, bool_biopython, ...])	Heavy-atom PyMOL `dot_solvent` with high dot density.
`PyMOLHydrogenConfig`(*[, bool_biopython, ...])	All-atom (explicit-H) PyMOL `dot_solvent`; rSASA disabled.
`ResidueSASA`(*[, dict_kinase, list_ids, ...])	Calculate per-residue solvent accessible surface area from KinCore CIFs.
`StandardSASAConfigChoice`(value)	String aliases for `StandardSASAConfigs` (e.g. for CLI choices).
`StandardSASAConfigs`(value)	Named, internally consistent SASA configurations.

class mkt.databases.sasa.BaseSASAConfig(*, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 100, dot_density: int = 3)[source]

Bases: object

Backend-compatible options for ResidueSASA.

Field names mirror the ResidueSASA constructor so a config can be expanded via ResidueSASA.from_dataclass(). Presets (subclasses) override these defaults into vetted, internally consistent recipes; see StandardSASAConfigs.

__init__(*, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 100, dot_density: int = 3) → None

bool_biopython: bool = True: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_include_hydrogens: bool = False: Keep explicit hydrogens; False gives conventional heavy-atom SASA.

bool_pymol: bool = False: Compute SASA with the PyMOL dot_solvent backend.

bool_relative: bool = True: Add relative SASA (rSASA); requires heavy-atom SASA (no explicit H).

dot_density: int = 3: PyMOL surface point density 1-4 (PyMOL only).

n_points: int = 100: Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (presets use ~960).

probe_radius: float = 1.4: Solvent/probe radius (Å), shared by both backends.

class mkt.databases.sasa.BioPythonHeavyConfig(*, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 3)[source]

Bases: BaseSASAConfig

Heavy-atom Bio.PDB Shrake-Rupley with converged sampling (recommended).

__init__(*, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 3) → None

bool_biopython: bool = True: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_pymol: bool = False: Compute SASA with the PyMOL dot_solvent backend.

n_points: int = 960: Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (presets use ~960).

class mkt.databases.sasa.BioPythonHydrogenConfig(*, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = True, bool_relative: bool = False, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 3)[source]

Bases: BaseSASAConfig

All-atom (explicit-H) Bio.PDB Shrake-Rupley; rSASA disabled.

Bondi radii + explicit hydrogens is a standard, self-consistent all-atom surface (not a double count). rSASA is disabled because the Tien et al. (2013) maxima are a heavy-atom reference; the structures must actually carry hydrogens (the run warns per structure if they do not).

__init__(*, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = True, bool_relative: bool = False, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 3) → None

bool_biopython: bool = True: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_include_hydrogens: bool = True: Keep explicit hydrogens; False gives conventional heavy-atom SASA.

bool_pymol: bool = False: Compute SASA with the PyMOL dot_solvent backend.

bool_relative: bool = False: Add relative SASA (rSASA); requires heavy-atom SASA (no explicit H).

n_points: int = 960: Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (presets use ~960).

class mkt.databases.sasa.CrossValidationConfig(*, bool_biopython: bool = True, bool_pymol: bool = True, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 4)[source]

Bases: BaseSASAConfig

Heavy-atom SASA from both backends with matched probe/sampling.

__init__(*, bool_biopython: bool = True, bool_pymol: bool = True, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 4) → None

bool_biopython: bool = True: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_pymol: bool = True: Compute SASA with the PyMOL dot_solvent backend.

dot_density: int = 4: PyMOL surface point density 1-4 (PyMOL only).

n_points: int = 960: Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (presets use ~960).

class mkt.databases.sasa.CrossValidationHydrogenConfig(*, bool_biopython: bool = True, bool_pymol: bool = True, bool_include_hydrogens: bool = True, bool_relative: bool = False, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 4)[source]

Bases: BaseSASAConfig

All-atom (explicit-H) SASA from both backends; rSASA disabled.

__init__(*, bool_biopython: bool = True, bool_pymol: bool = True, bool_include_hydrogens: bool = True, bool_relative: bool = False, probe_radius: float = 1.4, n_points: int = 960, dot_density: int = 4) → None

bool_biopython: bool = True: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_include_hydrogens: bool = True: Keep explicit hydrogens; False gives conventional heavy-atom SASA.

bool_pymol: bool = True: Compute SASA with the PyMOL dot_solvent backend.

bool_relative: bool = False: Add relative SASA (rSASA); requires heavy-atom SASA (no explicit H).

dot_density: int = 4: PyMOL surface point density 1-4 (PyMOL only).

n_points: int = 960: Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (presets use ~960).

mkt.databases.sasa.DEFAULT_DOT_DENSITY = 3: Default PyMOL surface point density (1-4).

mkt.databases.sasa.DEFAULT_N_POINTS = 100: Default Shrake-Rupley sphere points per atom (Bio.PDB); presets raise this to ~960 for converged per-residue SASA.

mkt.databases.sasa.DEFAULT_PROBE_RADIUS = 1.4: Default solvent/probe radius (Å), shared by both SASA backends.

mkt.databases.sasa.MAX_ASA_TIEN_2013 = {'ALA': 129.0, 'ARG': 274.0, 'ASN': 195.0, 'ASP': 193.0, 'CYS': 167.0, 'GLN': 225.0, 'GLU': 223.0, 'GLY': 104.0, 'HIS': 224.0, 'ILE': 197.0, 'LEU': 201.0, 'LYS': 236.0, 'MET': 224.0, 'PHE': 240.0, 'PRO': 159.0, 'SER': 155.0, 'THR': 172.0, 'TRP': 285.0, 'TYR': 263.0, 'VAL': 174.0}

Theoretical maximum accessible surface area (Å^2) per residue.

From Tien et al. (2013), PLoS ONE 8(11): e80635; used to normalize SASA to relative solvent accessibility (rSASA), keyed by 3-letter residue name.

class mkt.databases.sasa.PyMOLHeavyConfig(*, bool_biopython: bool = False, bool_pymol: bool = True, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 100, dot_density: int = 4)[source]

Bases: BaseSASAConfig

Heavy-atom PyMOL dot_solvent with high dot density.

__init__(*, bool_biopython: bool = False, bool_pymol: bool = True, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: float = 1.4, n_points: int = 100, dot_density: int = 4) → None

bool_biopython: bool = False: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_pymol: bool = True: Compute SASA with the PyMOL dot_solvent backend.

dot_density: int = 4: PyMOL surface point density 1-4 (PyMOL only).

class mkt.databases.sasa.PyMOLHydrogenConfig(*, bool_biopython: bool = False, bool_pymol: bool = True, bool_include_hydrogens: bool = True, bool_relative: bool = False, probe_radius: float = 1.4, n_points: int = 100, dot_density: int = 4)[source]

Bases: BaseSASAConfig

All-atom (explicit-H) PyMOL dot_solvent; rSASA disabled.

__init__(*, bool_biopython: bool = False, bool_pymol: bool = True, bool_include_hydrogens: bool = True, bool_relative: bool = False, probe_radius: float = 1.4, n_points: int = 100, dot_density: int = 4) → None

bool_biopython: bool = False: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_include_hydrogens: bool = True: Keep explicit hydrogens; False gives conventional heavy-atom SASA.

bool_pymol: bool = True: Compute SASA with the PyMOL dot_solvent backend.

bool_relative: bool = False: Add relative SASA (rSASA); requires heavy-atom SASA (no explicit H).

dot_density: int = 4: PyMOL surface point density 1-4 (PyMOL only).

class mkt.databases.sasa.ResidueSASA(*, dict_kinase: dict[str, KinaseInfo] | None = None, list_ids: list[str] | None = None, bool_biopython: bool = True, bool_pymol: bool = False, bool_include_hydrogens: bool = False, bool_relative: bool = True, probe_radius: Annotated[float, Gt(gt=0)] = 1.4, n_points: Annotated[int, Ge(ge=1)] = 100, dot_density: Annotated[int, Ge(ge=1), Le(le=4)] = 3, n_jobs: int = 1)[source]

Bases: BaseModel

Calculate per-residue solvent accessible surface area from KinCore CIFs.

Configure the run via the fields below, then call run() to compute per-residue SASA for each kinase with each selected backend; results are cached on and accessed via the df property. Residues are numbered by UniProt sequence position (the CIF auth_seq_id), and hydrogens are removed by default so SASA reflects conventional heavy atoms.

Prefer from_dataclass() with a StandardSASAConfigs preset for vetted, backend-compatible options; direct construction is allowed but warns that option compatibility is the caller’s responsibility.

Parameters:

dict_kinasedict[str, KinaseInfo] | None: Mapping of HGNC name to KinaseInfo object. If None, kinases are deserialized on demand: one at a time via load_kinase_object when list_ids is given, else the whole proteome via return_kinase_dict.
list_idslist[str] | None: HGNC names to deserialize (one at a time) when dict_kinase is None; None loads all kinases.
bool_biopythonbool: If True (default), compute SASA with Bio.PDB Shrake-Rupley.
bool_pymolbool: If True, also compute SASA with PyMOL dot_solvent (requires pymol-open-source, installed via conda); False by default. If PyMOL cannot be imported it is skipped with a warning, unless it is the only selected backend, in which case an ImportError is raised.
bool_include_hydrogensbool: If False (default), strip hydrogens for heavy-atom SASA; AlphaFold2 CIFs include explicit hydrogens.
bool_relativebool: If True (default), add an rsa column normalizing SASA by the Tien et al. (2013) theoretical maximum ASA for each residue type.
probe_radiusfloat: Solvent/probe radius in Å, shared by both backends, by default 1.40.
n_pointsint: Shrake-Rupley sphere points per atom (Bio.PDB), by default 100. The default is fast but unlikely to be converged for per-residue SASA; use ~960 (e.g. StandardSASAConfigs.BIOPYTHON_HEAVY) for analysis.
dot_densityint: PyMOL surface point density (1-4), by default 3.
n_jobsint: Worker processes for run(). 1 (default) runs serially; >1 uses a process pool; -1 uses all CPU cores. Parallelism is process-based (Shrake-Rupley is CPU-bound); each task carries its KinaseInfo, so workers do no deserialization. Worthwhile for many kinases or high n_points.

_compute_params() → dict[str, object][source]: Scalar config forwarded to the (picklable) per-kinase compute worker.

static _pymol_available() → bool[source]

Check whether the optional PyMOL backend can be imported.

The PyMOL PyPI wheel is unreliable, so any import failure (not just ModuleNotFoundError) is treated as unavailable.

Returns:

bool: True if pymol2 imports successfully, otherwise False.

_resolve_methods() → list[str][source]

Resolve the backends to run, dropping PyMOL if it cannot be imported.

Returns:

list[str]: Selected backends with “pymol” removed (with a warning) when pymol2 is unavailable but the Bio.PDB backend can stand in.

Raises:

ImportError: If PyMOL is the only requested backend but is unavailable.

_resolve_n_workers() → int[source]: Resolve n_jobs to a concrete worker count (>=1).

_run_tasks(list_tasks: list[tuple]) → list[DataFrame][source]: Run (kinase, backend) tasks serially or across a process pool.

_validate_config() → ResidueSASA[source]

Reject incompatible option combinations and warn on inert options.

Numeric ranges are enforced by Field constraints; this covers the cross-field rules that Field cannot express.

Raises:

ValueError: If no backend is selected, or if relative SASA is requested together with explicit hydrogens.

bool_biopython: bool: Compute SASA with the Bio.PDB Shrake-Rupley backend.

bool_include_hydrogens: bool: Keep explicit hydrogens; False gives conventional heavy-atom SASA.

bool_pymol: bool: Compute SASA with the PyMOL dot_solvent backend.

bool_relative: bool: Add relative SASA (rSASA); requires heavy-atom SASA (no explicit H).

property df: DataFrame | None

Per-residue SASA results; None until run() is called.

Long-format DataFrame with columns hgnc_name, method, uniprot_idx (UniProt position), residue (single-letter code), resname (3-letter code), sasa (Å^2), and, if bool_relative, rsa. Empty if no kinase had a CIF structure.

dict_kinase: dict[str, KinaseInfo] | None: Mapping of HGNC name to KinaseInfo; deserialized on demand if None.

dot_density: int: PyMOL surface point density 1-4 (PyMOL only).

classmethod from_dataclass(config: BaseSASAConfig | StandardSASAConfigs, **kwargs) → ResidueSASA[source]

Build a ResidueSASA from a vetted config dataclass or standard preset.

This is the recommended constructor: presets in StandardSASAConfigs carry backend-compatible options, so the direct-construction compatibility warning is suppressed.

Parameters:

configBaseSASAConfig | StandardSASAConfigs: A SASA config dataclass (e.g. BioPythonHeavyConfig) or a StandardSASAConfigs enum member.
**kwargs: Extra constructor arguments, e.g. dict_kinase or list_ids.

Returns:

ResidueSASA: Configured (but not yet run) instance.

list_ids: list[str] | None: HGNC names to deserialize (one at a time) when dict_kinase is None.

property list_methods: list[str]: Backends to run, selected via bool_biopython / bool_pymol.

n_jobs: int

1 serial, >1 pool, -1 all cores.

Type:: Worker processes for run()

n_points: int: Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (use ~960).

probe_radius: float: Solvent/probe radius (Å), shared by both backends.

run() → None[source]

Compute per-residue SASA for all kinases and backends.

Loops over each selected backend and kinase, tagging rows with method and hgnc_name; kinases without a KinCore CIF are skipped. The long-format result is stored on df (not returned).

Returns:

None: Results are cached on df; see that property for the columns.

class mkt.databases.sasa.StandardSASAConfigChoice(value)[source]

Bases: str, Enum

String aliases for StandardSASAConfigs (e.g. for CLI choices).

BIOPYTHON_HEAVY = 'BIOPYTHON_HEAVY'

BIOPYTHON_HYDROGEN = 'BIOPYTHON_HYDROGEN'

CROSS_VALIDATION = 'CROSS_VALIDATION'

CROSS_VALIDATION_HYDROGEN = 'CROSS_VALIDATION_HYDROGEN'

PYMOL_HEAVY = 'PYMOL_HEAVY'

PYMOL_HYDROGEN = 'PYMOL_HYDROGEN'

class mkt.databases.sasa.StandardSASAConfigs(value)[source]

Bases: Enum

Named, internally consistent SASA configurations.

Use via ResidueSASA.from_dataclass(StandardSASAConfigs.BIOPYTHON_HEAVY). Each value omits any backend-inert field, so nothing silently no-ops. *_HEAVY give heavy-atom SASA with rSASA; *_HYDROGEN give all-atom (explicit-H) absolute SASA with rSASA disabled.

BIOPYTHON_HEAVY = BioPythonHeavyConfig(bool_biopython=True, bool_pymol=False, bool_include_hydrogens=False, bool_relative=True, probe_radius=1.4, n_points=960, dot_density=3)

BIOPYTHON_HYDROGEN = BioPythonHydrogenConfig(bool_biopython=True, bool_pymol=False, bool_include_hydrogens=True, bool_relative=False, probe_radius=1.4, n_points=960, dot_density=3)

CROSS_VALIDATION = CrossValidationConfig(bool_biopython=True, bool_pymol=True, bool_include_hydrogens=False, bool_relative=True, probe_radius=1.4, n_points=960, dot_density=4)

CROSS_VALIDATION_HYDROGEN = CrossValidationHydrogenConfig(bool_biopython=True, bool_pymol=True, bool_include_hydrogens=True, bool_relative=False, probe_radius=1.4, n_points=960, dot_density=4)

PYMOL_HEAVY = PyMOLHeavyConfig(bool_biopython=False, bool_pymol=True, bool_include_hydrogens=False, bool_relative=True, probe_radius=1.4, n_points=100, dot_density=4)

PYMOL_HYDROGEN = PyMOLHydrogenConfig(bool_biopython=False, bool_pymol=True, bool_include_hydrogens=True, bool_relative=False, probe_radius=1.4, n_points=100, dot_density=4)

mkt.databases.sasa._assemble_sasa_df(list_rows: list[dict[str, object]], *, bool_relative: bool) → DataFrame[source]: Build the per-residue DataFrame and optional relative-SASA column.

mkt.databases.sasa._compute_kinase_sasa(obj_kinase: KinaseInfo, str_method: str, *, bool_include_hydrogens: bool, bool_relative: bool, probe_radius: float, n_points: int, dot_density: int) → DataFrame | None[source]

Compute per-residue SASA for one kinase with one backend.

Returns the per-residue DataFrame (without hgnc_name/method tags), or None if the kinase has no KinCore CIF structure.

mkt.databases.sasa._residue_sasa_biopython(structure: Structure, *, bool_include_hydrogens: bool, probe_radius: float, n_points: int) → list[dict[str, object]][source]: Per-residue SASA rows via Bio.PDB Shrake-Rupley.

mkt.databases.sasa._residue_sasa_pymol(structure: Structure, *, bool_include_hydrogens: bool, probe_radius: float, dot_density: int) → list[dict[str, object]][source]: Per-residue SASA rows via PyMOL dot_solvent (lazy pymol2 import).

mkt.databases.sasa._sasa_task(task: tuple) → DataFrame | None[source]

Worker entry point: compute one (kinase, backend) task and tag the rows.

task is (hgnc_name, obj_kinase, str_method, params) where params is the scalar config dict from ResidueSASA._compute_params().

mkt.databases.sasa._strip_hydrogens(structure: Structure) → None[source]: Remove all hydrogen atoms from a Bio.PDB Structure in place.