fpocket-esm
v0.1.0
Published
fpocket pocket detection compiled to WebAssembly, with a typed ES module API
Readme
fpocket-esm
fpocket 4.2.3 compiled to WebAssembly, with a typed ES module API. Runs in browsers (main thread or workers) and Node ≥ 20.
import { createFpocket } from 'fpocket-esm';
const fpocket = await createFpocket();
const { pockets } = await fpocket.run({ pdb: pdbText });
pockets[0].descriptors.druggabilityScore;
pockets[0].alphaSpheres; // { x, y, z, radius, polarity }[]
pockets[0].residues; // { chain, residueNumber, insertionCode }[]Usage
Loading the wasm
createFpocket() compiles fpocket.wasm once; every run gets a fresh instance, because fpocket keeps global state between runs. By default the wasm is resolved next to the package's JS, which works in Node and in most bundlers.
With Vite, dependency pre-bundling can break that relative URL. Pass the URL explicitly instead:
import { createFpocket } from 'fpocket-esm';
import wasmUrl from 'fpocket-esm/fpocket.wasm?url';
const fpocket = await createFpocket({ wasm: wasmUrl });wasm also accepts bytes or an already compiled WebAssembly.Module. run blocks the thread it runs on (about 100–500 ms for a typical protein), so use a worker in browsers.
Vite logs that node:fs/promises and node:module were externalized for browser compatibility. Both are only used under Node and can be ignored.
Parameters
Every parameter is optional and falls back to fpocket's default. Values are validated before fpocket runs, and invalid ones throw FpocketArgumentError.
| Parameter | fpocket flag | Default |
|---|---|---|
| minAlphaSphereRadius | -m | 3.4 |
| maxAlphaSphereRadius | -M | 6.2 |
| minAlphaSpheresPerPocket | -i | 15 |
| minApolarAlphaSphereProportion | -p | 0 |
| minApolarNeighbours | --number_apol_asph_pocket | 3 |
| clusteringDistance | -D | 2.4 |
| clusteringMethod: single | complete | average | centroid | -C | single |
| clusteringDistanceMeasure: euclidean | manhattan | -e | euclidean |
| volumeMonteCarloIterations | -v | 300 |
| modelNumber | -l | |
| chainFilter: { drop: string[] } | { keep: string[] } | -c / -k | |
| chainsAsLigand | -a | |
| customLigand: { residueNumber, residueName, chain } | -r | |
| explicitPocket: { residues, minContactAtoms? } | -P / -u | minContactAtoms 4 |
Explicit pockets
explicitPocket restricts detection to one binding site lined by the given residues. fpocket runs its usual alpha-sphere detection, then collects the spheres whose contact atoms belong to those residues into a single pocket. minContactAtoms is how many of a sphere's 4 contact atoms must be in the list. Lowering it pulls in spheres from neighbouring pockets.
To merge two detected pockets, pass the union of their residues:
const residues = [...pocketA.residues, ...pocketB.residues]; // deduplicate as needed
const { pockets: [merged] } = await fpocket.run({ pdb, parameters: { explicitPocket: { residues } } });fpocket's parser limits what can be expressed: residue numbers 0–65535, single-character chains and insertion codes, and at most 7999 characters in total.
Results
run resolves to:
pockets: in fpocket's rank order, each withnumber, the 19descriptorsfrominfo.txt,alphaSpheres, contactatomsand their distinctresidues.files: the raw text of<name>_out.pdb,_info.txt,_pockets.pqrand each pocket'satm.pdb/vert.pqr.arguments,stdout,stderr, for logging.
A run that finds nothing resolves with pockets: []. A non-zero fpocket exit throws FpocketError with exitCode, stdout and stderr.
The parsers (parseInfo, parseVerticesPqr, parseAtomsPdb, residuesOf) and buildArguments are exported for use on output produced elsewhere.
Things to know
- Some descriptors are random.
volume,totalSasa,polarSasa,apolarSasa, and thescoreanddruggabilityScorederived from them come from Monte-Carlo sampling, seeded with the current time in seconds. Two runs in the same second give the same values; runs further apart vary by a few percent. Geometry, residues and the other 14 descriptors are deterministic. - Pocket numbers follow the score, so they can change with the random descriptors. Identify pockets by their alpha spheres or residues, not by number, across runs.
- PDB input only. mmCIF input, Amber topologies (
-y), interaction grids (-x),-dand-ware not exposed (see below).
How this build differs from upstream fpocket
| Change | Where | Why |
|---|---|---|
| Flush qhull's output before reading it | patches/0001-flush-qvoronoi-output.patch | Upstream reopens qhull's output file for reading while it is still buffered, so the last vertices are silently lost. How many depends on the C library's buffer size: on HIV protease (1HSG) official macOS binaries lose 202 of 9772 vertices and miss a pocket. With the patch, every platform reads all vertices. Results can differ from official fpocket binaries. |
| system() is a no-op returning 0 | stubs/wasm_stubs.c | fpocket shells out for mkdir and chmod. In browsers that fails and fpocket then writes no output; under Node, Emscripten would run the commands on the host. The wrapper creates the output folders itself. |
| VMD molfile plugins are stubbed | stubs/wasm_stubs.c | Upstream links a prebuilt native libmolfile_plugin.a, only used for mmCIF input and Amber topologies. |
| -Wno-error=incompatible-pointer-types | scripts/build-wasm.sh | fparams.c declares the -P parsing buffer as char *[8000] and uses it as a char buffer; recent clang rejects it. It works because the array is larger than the 8000 characters needed. conda-forge patches the declaration instead. |
Under Node, Emscripten records fpocket's exit status in process.exitCode. The wrapper restores it after each run, so a failed run does not make the host process exit non-zero.
Development
Requires Node ≥ 22.12 and pnpm (corepack enable).
git clone <repo>
pnpm install
pnpm test # compares the committed wasm with test/fixtures
pnpm build # TypeScript → dist/The compiled wasm (wasm/fpocket.{mjs,wasm,d.mts}) is committed, so working on the TypeScript API needs no C toolchain. Rebuilding it requires Docker and the fpocket submodule (git submodule update --init):
pnpm build:wasm # emsdk in Docker → wasm/Rebuild and commit wasm/ whenever the fpocket version, patches/, stubs/, scripts/build-wasm.sh, scripts/prepare-source.sh or the Dockerfile change.
Tests
test/fixtures/ holds results from a native fpocket built from the same patched source (scripts/build-native.sh), for the cases in test/cases.json. The tests require the wasm to produce the same pockets (identical alpha spheres and residues) and the same deterministic descriptors, with tolerances on the Monte-Carlo ones.
Regenerate fixtures after changing cases, patches or the fpocket version (requires a C compiler):
pnpm build:native && pnpm build && pnpm fixturesUpgrading fpocket
git -C fpocket fetch --tags && git -C fpocket checkout <tag>- Check that
patches/*.patchstill apply (pnpm build:wasmfails otherwise). Drop a patch once upstream fixes the bug. - Check
src/arguments.tsandsrc/parse.tsagainst upstream'ssrc/fparams.candsrc/fpout.cfor new or renamed options and descriptors. - Rebuild and commit
wasm/, regenerate fixtures, run the tests, and update the fpocket version at the top of this README. - Release a new minor version (see below): results can change between fpocket versions.
The emsdk version is pinned in the Dockerfile. After bumping it, rebuild, re-run the tests and commit wasm/.
Versioning
The package has its own semver version, independent of fpocket's. The fpocket version it bundles is stated at the top of this README. While the version is 0.x, a minor bump (0.1.0 → 0.2.0) may break the API or change results (including any fpocket upgrade), and a patch bump does neither.
Releasing
From a clean, up-to-date main with the submodule checked out (the package includes its licence files):
git submodule update --init
pnpm version minor # or patch: bumps package.json, commits and tags vX.Y.Z
git push --follow-tags
pnpm publish # runs typecheck, tests and build first (prepublishOnly)Check the contents beforehand with pnpm pack --dry-run.
Licence
This wrapper is MIT-licensed (LICENSE). fpocket is MIT-licensed and bundles Qhull. Both licences ship in the package (fpocket/LICENSE, fpocket/QHULL_COPYING.txt).
