> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# NA-MPNN
> [NA-MPNN](https://github.com/baker-laboratory/NA-MPNN) is a message-passing neural network for nucleic-acid sequence design and protein–DNA specificity prediction. Given a protein–DNA complex structure, it predicts, for each DNA position, the base preference of the bound protein. This toolkit exposes that specificity prediction as a single tool that returns a canonical DNA-only position probability matrix (PPM) in `A,C,G,T` order.
**License:** NA-MPNN uses MIT for code and BSD-3-Clause for model weights and may require explicit attribution when utilized. Please refer to the [code license](https://github.com/baker-laboratory/NA-MPNN/blob/main/LICENSE) and [model weights license](https://github.com/baker-laboratory/NA-MPNN/blob/main/LICENSE) for full terms.
Proto is not affiliated with University of Washington. 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.
| Function | Description | |
| --------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_na_mpnn_specificity()` | Predict protein-DNA specificity (DNA-only A,C,G,T PPM) using NA-MPNN (GPU) | Docs Source |
## Background
Sequence-specific DNA-binding proteins recognize their target sites through a combination of direct base contacts and indirect shape readout. Predicting the base preference a protein imposes at each position of a bound DNA site is central to engineering transcription factors, characterizing binding specificity, and designing synthetic regulatory elements such as repressors and promoters.
NA-MPNN ([Kubaney et al., 2025](https://www.biorxiv.org/content/10.1101/2025.10.03.679414v2)) is a message-passing neural network that represents proteins, DNA, and RNA within a single unified biopolymer graph, framing both RNA sequence design and protein–DNA binding specificity as nucleic-acid inverse-folding problems (recovering likely sequences for a fixed three-dimensional structure). For specificity prediction, the model conditions on a fixed-docked protein–DNA complex and emits per-position nucleotide probabilities over the DNA chains, which this toolkit canonicalizes into a DNA-only `L x 4` PPM together with the recovered true sequence and chain labels.
### Learning Resources
* [baker-laboratory/NA-MPNN](https://github.com/baker-laboratory/NA-MPNN). Official repository with the training and inference code, installation instructions, and usage examples.
## Tools
### NA-MPNN Specificity (`na-mpnn-specificity`)
Predicts the DNA base preference of a bound protein from one or more protein–DNA complex structures. For each input PDB, the tool runs NA-MPNN specificity inference, restricts the output to valid DNA positions, and returns a canonical PPM (`L x 4`, `A,C,G,T` order), the recovered true DNA sequence (indices `0..3`), per-row masks, and chain labels. Each result is also written to a canonical `.npz` file whose path is returned in `output_npz_path`.
#### API Reference
Source
PDB file paths for protein-DNA complexes to score. A bare string is normalized into a single-element list.
Source
Batch size per inference call.
Number of prediction batches to run.
Sampling temperature for NA-MPNN.
Residues to omit during NA-MPNN sampling.
Restrict design tokens to nucleic acid positions.
Optional directory for canonical NPZ artifacts.
Keep intermediate raw NA-MPNN output directories.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run inference on (inherited).
Maximum execution time in seconds. `None` waits indefinitely.
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
Canonicalized result per input structure, index-aligned with `pdb_paths`.
Basename (stem) of the scored input structure.
Source method tag, always `"na_mpnn"`.
Path to the canonical `.npz` output file.
Canonical DNA PPM (`L x 4`) in A,C,G,T order.
Canonical DNA truth indices in `0..3` per row.
Valid-residue mask for canonical rows.
DNA-residue mask for canonical rows.
Canonical chain IDs per canonical row.
#### Applications
This tool is appropriate for scoring and ranking candidate protein–DNA binder designs by their predicted specificity, for comparing the base preference of a designed binder against a target motif inside an optimization loop, and for characterizing the specificity landscape of natural or engineered DNA-binding proteins. The per-position PPM can be compared to a desired motif to drive specificity-based selection.
#### Usage Tips
* **The NA-MPNN checkout and checkpoint are provisioned for you.** The standalone setup clones a pinned revision of the repository (which ships the specificity checkpoint in-tree) into the managed weights cache, so no repository or checkpoint path is configured. Point `PROTO_NA_MPNN_SPECIFICITY_WEIGHTS_DIR` at an existing checkout to reuse it. A run that uses `device='proto'` fails fast because these local resources cannot be staged.
* **`predicted_ppm` rows are DNA-only and renormalized.** Only positions that are both valid and DNA are kept, and each row is renormalized over `A,C,G,T`, so the returned matrix already excludes protein and masked positions.
* **`temperature` controls sampling sharpness.** Lower values (default `0.1`) concentrate probability on the most-preferred base; raise it to soften the distribution.
* **`output_directory` and `keep_intermediate` control artifacts.** Leave `output_directory` unset to write canonical `.npz` files to a temporary directory, or set it to persist them. Set `keep_intermediate=True` to retain the raw NA-MPNN output for debugging.
## Toolkit Notes
* NA-MPNN runs as an isolated standalone environment that shells out to the upstream NA-MPNN inference CLI; the heavy model dependencies stay out of the main environment.
* The standalone setup clones a pinned NA-MPNN revision (with its in-tree specificity checkpoint) into the managed weights cache. If the clone cannot reach GitHub, the environment setup signals a clean test skip rather than a hard failure.
**Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/47e34afa5ea240a3b406e323dc38aa5dc85f223e/proto_tools/tools/sequence_scoring/na_mpnn_specificity/examples/example.ipynb) for a copy-paste-ready walkthrough.
## Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.
Keep a tool's model warm across calls instead of reloading it every invocation.How GPUs are allocated to tools and how to target specific devices.Fan a batch of inputs out across multiple GPUs.
evo-design/proto-tools/proto\_tools/tools/sequence\_scoring/na\_mpnn\_specificity
