molforge.wrappers.pockets¶

pockets ¶

Pocket detection engine wrappers.

A pocket detector takes a :class:molforge.core.Protein and returns a list of :class:molforge.docking.Pocket — the candidate ligand-binding pockets on its surface, ranked by the detector's own scoring.

Concrete detectors:

:func:molforge.wrappers.pockets.fpocket.detect_pockets — fpocket, the Voronoi-based (geometric) algorithm from the Discngine/fpocket project.
:func:molforge.wrappers.pockets.p2rank.detect_pockets_p2rank — P2Rank, the machine-learning (random-forest) detector, which returns the same :class:Pocket shape and is a drop-in alternative.

Detectors are free functions rather than classes because they're stateless: there's no in-process model to load, no per-call reuse benefit. They shell out to an external binary and parse its output — P2Rank's ML model is loaded by its own Java process. A Python-native ML detector (PUResNet, ScanNet) that warm-loads weights in-process may adopt a class-based pattern; that's a per-detector decision when each lands.

Pocket detection sits next to docking in the workflow taxonomy: a typical use is detection -> pick a pocket -> dock against it, which is also why :class:molforge.docking.Pocket lives alongside :class:Pose and :class:DockingResult in the docking module.

FpocketNotInstalledError ¶

Bases: RuntimeError

Raised when the fpocket binary isn't on PATH (or wherever fpocket_executable points to).

fpocket isn't pip-installable — users install it through their system package manager or build from source. The error message points at the install path so users don't have to grep for it.

P2RankNotInstalledError ¶

Bases: RuntimeError

Raised when the P2Rank prank launcher isn't on PATH (or wherever prank_executable points).

P2Rank isn't pip-installable — it's a Java application users download from the project releases (or install via conda). The error message points at the install path so users don't have to grep for it.

detect_pockets ¶

detect_pockets(
    protein: Protein,
    *,
    fpocket_executable: str = "fpocket",
    min_alpha_spheres: int | None = None,
    min_volume: float | None = None,
    timeout: float = 60.0,
) -> list[Pocket]

Detect candidate ligand-binding pockets with fpocket.

Runs the fpocket binary against the protein, parses the output, and returns a list of :class:Pocket ranked by fpocket's own scoring (best first).

Parameters:

Name	Type	Description	Default
`protein`	`Protein`	The :class:`molforge.core.Protein` to analyse. Written to a temporary PDB and passed via `-f`.	required
`fpocket_executable`	`str`	Name or full path of the fpocket binary. Defaults to `"fpocket"` (expected on `$PATH`).	`'fpocket'`
`min_alpha_spheres`	`int \| None`	If set, passed as `-i N` to fpocket — minimum number of alpha spheres a pocket must contain to appear in the results. fpocket's own default is 15; this argument lets callers tighten or relax that.	`None`
`min_volume`	`float \| None`	If set, post-filter: drop pockets whose volume is below this threshold (Å³). fpocket itself doesn't have a clean volume filter; we apply it after parsing.	`None`
`timeout`	`float`	Subprocess timeout in seconds. Real proteins complete in well under a minute; the default 60s is comfortable for normal-sized inputs and forces a hard failure rather than indefinite hang for pathological cases.	`60.0`

Returns:

Type	Description
`list[Pocket]`	A list of :class:`Pocket` ranked by fpocket's score
`list[Pocket]`	(descending; pocket 0 is the best by fpocket). Empty list
`list[Pocket]`	when fpocket finds no pockets meeting its criteria.

Raises:

Type	Description
`FpocketNotInstalledError`	If `fpocket_executable` isn't on `$PATH` (or wherever it points).
`RuntimeError`	If fpocket exits non-zero, times out, or produces no parseable output. The error message echoes fpocket's stderr where available.

detect_pockets_p2rank ¶

detect_pockets_p2rank(
    protein: Protein,
    *,
    prank_executable: str = "prank",
    timeout: float = 300.0,
) -> list[Pocket]

Detect candidate ligand-binding pockets with P2Rank.

Runs prank predict against the protein, parses the prediction CSV, and returns a list of :class:Pocket ranked by P2Rank's score (best first).

Parameters:

Name	Type	Description	Default
`protein`	`Protein`	The :class:`molforge.core.Protein` to analyse. Written to a temporary PDB and passed via `-f`.	required
`prank_executable`	`str`	Name or full path of the P2Rank launcher. Defaults to `"prank"` (expected on `$PATH`).	`'prank'`
`timeout`	`float`	Subprocess timeout in seconds. P2Rank's ML scoring is slower than a geometric detector — the default 300s is comfortable for normal-sized inputs while still forcing a hard failure rather than an indefinite hang.	`300.0`

Returns:

Type	Description
`list[Pocket]`	A list of :class:`Pocket` ranked by P2Rank's score (descending;
`list[Pocket]`	pocket 0 is the best). Empty list when P2Rank finds no pockets.

Raises:

Type	Description
`P2RankNotInstalledError`	If `prank_executable` isn't on `$PATH` (or wherever it points).
`RuntimeError`	If P2Rank exits non-zero, times out, or produces no parseable output. The error echoes P2Rank's stderr where available.