USCLicense: DeepPBS Specificity is open source and free for academic and commercial use under a BSD-3-Clause license and may require explicit attribution when utilized. Please refer to the license for full terms.
Proto is not affiliated with University of Southern California. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.
timkartar/DeepPBS
Geometric deep learning of protein—DNA binding specificity
evo-design/proto-tools/proto_tools/tools/sequence_scoring/deeppbs_specificityOpen Notebook
Open notebook
Run locally with proto-tools
Background
Sequence-specific recognition of DNA by proteins underlies transcriptional regulation, and predicting a protein’s binding preference directly from a co-crystal structure is a long-standing goal. DeepPBS (Mitra et al., 2024) applies geometric deep learning over a graph representation of the protein-DNA interface to predict per-position base preferences that generalize across protein families, on experimental or predicted complex structures. The model consumes a processed representation of the complex built from DSSR/X3DNA geometry, so the wrapper depends on a local DeepPBS repository and a local X3DNA install.Learning Resources
- DeepPBS GitHub repository - source code, processing scripts, and pretrained weights.
- DeepPBS paper (Nature Methods, 2024) - the method, benchmarks, and applications.
Tools
DeepPBS Specificity (deeppbs-specificity)
Runs DeepPBS preprocessing and prediction on each input protein-DNA structure and returns, per structure, a canonical DNA PPM (L x 4, A,C,G,T order), the true DNA sequence indices, residue and DNA masks, per-base chain labels, and the path to a canonical .npz artifact. When a required DeepPBS dependency (the X3DNA x3dna-dssr/analyze binaries) is missing, or preprocessing or prediction fails to produce output, the tool raises by default. Set allow_fallback=True to instead emit a conservative fallback result: a uniform PPM (0.25 per base) derived from the DNA residues in the input PDB, flagged with used_fallback=True and a human-readable fallback_reason.API Reference
Source
Input: DeepPBSSpecificityInput
Input: DeepPBSSpecificityInput
List[string]
required
PDB paths for protein-DNA structures to score. A single path string is normalized to a one-element list. At least one path is required.
Source
Config: DeepPBSSpecificityConfig
Config: DeepPBSSpecificityConfig
string
Optional directory for canonical NPZ artifacts. A temporary directory is used when unset.
boolean
default:"False"
Keep intermediate process and predict files.
boolean
default:"False"
Pass —no_cleanp to DeepPBS preprocessing to skip pdb2pqr-dependent protein cleaning.
boolean
default:"False"
On missing DeepPBS deps/outputs, return a uniform fallback PPM instead of raising.
integer
default:"0"
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr).
True is coerced to 1 and False to 0.string
default:"cuda"
Device to run DeepPBS inference on (inherited).
integer
default:"3600"
Maximum execution time in seconds.
None waits indefinitely.integer
Random seed. When set, tools run reproducibly up to small GPU float noise (see
BaseToolOutput.approx_equal), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded. Source
Output: DeepPBSSpecificityOutput
Output: DeepPBSSpecificityOutput
List[DeepPBSSpecificityResult]
Canonicalized results per input, index-aligned with
inputs.pdb_paths.Applications
- Estimating the DNA base preference of a designed or natural protein-DNA complex.
- Scoring protein-DNA designs for specificity against a target motif.
- Generating canonical PPMs for downstream motif comparison.
Usage Tips
- Inputs are full protein-DNA PDB structures. Provide a clean co-crystal containing both DNA strands; missing strands or non-standard residues can trigger the fallback path.
- DeepPBS, X3DNA, and the weights are provisioned for you. The standalone setup clones a pinned revision of the DeepPBS repository (which bundles the X3DNA/DSSR binaries, the process/predict configs, and the trained inference weights) into the managed weights cache and installs it, so no repository or X3DNA path is configured. Point
PROTO_DEEPPBS_SPECIFICITY_WEIGHTS_DIRat an existing checkout to reuse it. - Fallback is opt-in. By default a missing dependency or failed run raises; pass
allow_fallback=Trueto get a uniform fallback PPM instead. Aused_fallback=Trueresult carries a uniform PPM, not a real prediction.
Toolkit Notes
- The DeepPBS checkout is self-contained and auto-provisioned. The standalone setup clones a pinned DeepPBS revision (bundling the X3DNA/DSSR binaries, configs, and inference weights) into the managed weights cache and installs it editable. The tool shells out to those local scripts and binaries, so it cannot run on
device='proto'. If the clone cannot reach GitHub, the environment setup signals a clean test skip rather than a hard failure. - Failures raise by default. When a dependency is missing or processing fails, the tool raises; set
allow_fallback=Trueto instead return a uniform fallback PPM flagged withused_fallbackso downstream code can filter or re-run. - Results are index-aligned with the input. Each result corresponds to the input structure at the same position.
Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.Tool Persistence
Keep a tool’s model warm across calls instead of reloading it every invocation.
Device Management
How GPUs are allocated to tools and how to target specific devices.
Parallel Execution
Fan a batch of inputs out across multiple GPUs.