mkt.databases.sasa.ResidueSASA

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)

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.

__init__(**data: Any) → None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Methods

_compute_params()	Scalar config forwarded to the (picklable) per-kinase compute worker.
_pymol_available()	Check whether the optional PyMOL backend can be imported.
_resolve_methods()	Resolve the backends to run, dropping PyMOL if it cannot be imported.
_resolve_n_workers()	Resolve n_jobs to a concrete worker count (>=1).
_run_tasks(list_tasks)	Run (kinase, backend) tasks serially or across a process pool.
_validate_config()	Reject incompatible option combinations and warn on inert options.
from_dataclass(config, **kwargs)	Build a ResidueSASA from a vetted config dataclass or standard preset.
run()	Compute per-residue SASA for all kinases and backends.

Attributes

_building_from_dataclass
df	Per-residue SASA results; None until run() is called.
list_methods	Backends to run, selected via bool_biopython / bool_pymol.
dict_kinase	Mapping of HGNC name to KinaseInfo; deserialized on demand if None.
list_ids	HGNC names to deserialize (one at a time) when dict_kinase is None.
bool_biopython	Compute SASA with the Bio.PDB Shrake-Rupley backend.
bool_pymol	Compute SASA with the PyMOL dot_solvent backend.
bool_include_hydrogens	Keep explicit hydrogens; False gives conventional heavy-atom SASA.
bool_relative	Add relative SASA (rSASA); requires heavy-atom SASA (no explicit H).
probe_radius	Solvent/probe radius (Å), shared by both backends.
n_points	Shrake-Rupley sphere points per atom (Bio.PDB only); default 100 is unlikely to be converged for per-residue SASA (use ~960).
dot_density	PyMOL surface point density 1-4 (PyMOL only).
n_jobs	1 serial, >1 pool, -1 all cores.
_df

_compute_params() → dict[str, object]

Scalar config forwarded to the (picklable) per-kinase compute worker.

static _pymol_available() → bool

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]

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

Resolve n_jobs to a concrete worker count (>=1).

_run_tasks(list_tasks: list[tuple]) → list[DataFrame]

Run (kinase, backend) tasks serially or across a process pool.

_validate_config() → ResidueSASA

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

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

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.