NAPxplorer

NAPxplorer (Nucleic Acid–Protein Explorer) is an open-source, high-performance computational framework and interactive web platform for the comprehensive structural analysis, geometric profiling, quantum chemical energetics, and 3D visualization of protein–nucleic acid complexes (Protein–RNA, Protein–DNA, and Protein–RNA–DNA Hybrids / DRBPs).

Table of Contents

• Key Features
• Scientific Capabilities & Analytical Modules
  • 1. Comprehensive Interface Contact Detection
  • 2. Quantum Chemical Interaction Energetics (g-xTB)
  • 3. Differential Geometry Surface Curvature & Shape Classification
  • 4. Surface Wrapping Index & Nucleic Acid Crowding (OOI Index)
  • 5. Modified Nucleotides & Non-Standard Residues
  • 6. Multi-Model NMR Conformer Ensembles
• Installation
  • Option A: Python Package (PyPI)
  • Option B: Bioconda & Conda-Forge
  • Option C: From Source (Developer Mode)
  • Option D: Docker & Docker Compose
• Quick Start & Usage
  • Python API
  • Command-Line Interface (CLI)
  • Running the Interactive Web Server
• REST API & Programmatic Web Services
• Execution Provenance & Audit Records
• Benchmark & Validation
• Repository Structure
• Citation & References
• License & Contact

Key Features

• Unified Data Representation: Clean, hierarchical, and extensible structural model connecting experimental (X-ray, Cryo-EM, NMR) and predicted (AlphaFold, ESMFold) structures.
• 14 Interaction Subtypes: High-resolution classification of hydrogen bonds, weak C–H…O/N contacts, salt bridges, base stacking (π–π), cation–π, amino–π, sugar–π, 2'-OH contacts, metal coordination, and water-mediated bridges.
• Semi-Empirical Quantum Energetics: Automated g-xTB single-point interaction energies (COSMO implicit water by default, fixed geometry).
• Differential Geometry Morphometry: Solvent-accessible Fibonacci dot clouds, Monge patch quadratic fitting, and Koenderink shape index ($S$) classification (POCKET, GROOVE, RIDGE, SADDLE, PLANAR).
• Nucleic Acid Crowding & OOI Index: A nucleic acid–centered occlusion and crowding index adapting the classical Ooi number (Nishikawa & Ooi, 1986) to quantify local protein residue crowding, paired with directional 36-bin surface wrapping ($W$).
• Dual RNA & DNA Support: Full native support for single-stranded and double-stranded RNA, DNA duplexes, and RNA–DNA heteroduplexes (DRBPs).
• Execution Provenance & Audit Trails: Automated generation of job_manifest.json and README_OUTPUTS.txt for verifiable reproducibility.
• Modern Interactive 3D Webserver & REST API: Seamless integration with PDBe Mol*, 2D contact matrix grids, secondary structure sequence tracks, and full RESTful JSON services.
• Standalone Engine Distribution: Available via PyPI (pip install napxplorer) and Bioconda, cleanly decoupled from the web application.

Scientific Capabilities & Analytical Modules

1. Comprehensive Interface Contact Detection

NAPxplorer evaluates distances, angles, and spatial orientations to classify inter-macromolecular contacts into 14 distinct interaction categories:

• Hydrogen Bonds: Canonical donor-acceptor geometry (D–H…A).
• Weak Hydrogen Bonds: Non-canonical C–H…O/N contacts.
• Salt Bridges & Electrostatics: Oppositely charged ionic networks (e.g., Arg/Lys … Phosphate backbone).
• Base Stacking (π–π): PInteract-style aromatic ring contacts (closest atoms ≤ 5.0 Å, ring-cylinder test) labelled stacked (P, 0–20°), inclined (I, 20–70°) or T-shaped (T, 70–90°) by interplanar tilt (Wilson et al.).
• Cation–π & Amino–π: Positively charged guanidinium/ammonium groups interacting with nucleic acid purine/pyrimidine rings.
• Sugar–π & 2'-OH Mediated Contacts: Ribose C–H and hydroxyl interactions targeting aromatic rings and protein backbones.
• Metal Ion Coordination: Transition and alkali-earth metal coordination spheres (Mg²⁺, Zn²⁺, Ca²⁺, Na⁺, K⁺).
• Water Bridges: Solvent-mediated interaction networks bridging protein and nucleic acid chains.

2. Quantum Chemical Interaction Energetics (g-xTB)

Fixed-geometry g-xTB single-point energies of the contacting fragments (capped, hydrogens added with Reduce, no geometry optimization), in COSMO implicit water by default (-energy-solvent gas for gas phase):

$$ E_{\mathrm{int}} = E_{AB} - E_A - E_B \qquad (\text{water/ion-mediated: } E_{ABM} - E_A - E_B - E_M) $$

• g-xTB is a development method approximating ωB97M-V/def2-TZVPPD properties; the COSMO water model contains only the electrostatic part of solvation.
• No counterpoise, thermal or entropic correction is applied: values are fragment interaction-energy estimates, not binding free energies.
• Positive energies are screened for cross-fragment short contacts (Short_contact_flag: Mild_short_contact / Severe_short_contact).
• Requires reduce and the g-xTB build of xtb 6.7.1 (see Installing g-xTB).

Installing g-xTB

Energy calculations (-energy) need the g-xTB build of xtb 6.7.1, which is not on conda. A Linux x86_64 build is bundled in third_party/g-xtb/ (GPL-3.0, separate from NAPxplorer's MIT license; extract with tar xJf). For other OSes download the archive from the binaries folder of the g-xtb repository. Extract it, and either put the executable on PATH as gxtb or point NAPxplorer to it:

export NAPXPLORER_GXTB_BIN=/path/to/xtb-6.7.1/bin/xtb
napxplorer 3R1L.cif -energy -cpu 8 -outpath results/        # COSMO water (default)
napxplorer 3R1L.cif -energy -cpu 8 -energy-solvent gas -outpath results/

-energy also requires -cpu N. Structures with more than 5,000 interactions skip energies unless -force-energy is given (-max-energy-interactions N changes the limit).

3. Differential Geometry Surface Curvature & Shape Classification

A 5-step differential geometry engine profiles local protein surface curvature at contact interfaces:

1. Fibonacci Dot Cloud: Uniform solvent-accessible dot sampling ($r_{\text{probe}} = 1.4$ Å).
2. Local Patch Selection: 8.0 Å contiguous surface patch around each contacting protein site (Gaussian weighting σ = 4.0 Å).
3. Local PCA Coordinate Frame: Tangent plane ($\hat{u}, \hat{v}$) and surface normal ($\hat{n}$) oriented toward the ligand.
4. Gaussian-Weighted Monge Patch Fitting: Quadratic surface $z = ax^2 + bxy + cy^2 + dx + ey + f$ fitted via weighted least squares ($\sigma = 4.0$ Å).
5. Morphometric Invariants:
   • Mean Curvature ($H$): Average bending direction.
   • Gaussian Curvature ($K = \kappa_1 \kappa_2$): Intrinsic surface topology ($K < 0$ denotes saddle passes).
   • Koenderink Shape Index ($S$): Degree of concavity vs convexity ($S \in [-1, +1]$).
   • Curvedness ($C$): RMS curvature magnitude (Å⁻¹).

4. Surface Wrapping Index & Nucleic Acid Crowding (OOI Index)

• Classical Ooi Number Adaptation: OOI-like measures have traditionally been used to describe radial packing, contact numbers, and solvent exposure around protein residues (Nishikawa and Ooi, 1986). NAPxplorer adapts this formulation to protein–nucleic acid interfaces as a nucleic acid–centered crowding index (OOI index / Ooi number).
• Local Protein Crowding Metric: Quantifies the number of unique protein residues contributing $\mathrm{C}\alpha$ or $\mathrm{C}\beta$ atoms within a 14.0 Å spherical neighborhood of each interacting nucleobase centroid (ooi_rp), discriminating deeply buried cleft nucleotides from loosely exposed interface peripheries.
• Directional Surface Wrapping Index ($W$): 36-bin spherical ray-tracing evaluation capturing steric engulfment and macromolecular shielding around each nucleobase.

5. Modified Nucleotides & Non-Standard Residues

Native parsing and annotation of chemical modifications from the PDB Chemical Component Dictionary (CCD), including pseudouridine (Ψ), 4-thiouridine (FHU), 5-methylcytidine (5MC), and methylated bases.

6. Multi-Model NMR Conformer Ensembles

Full support for multi-conformer NMR ensembles with dynamic model switching, ensemble contact consensus calculation, and per-model geometric tracking.

Installation

Prerequisites

• Python $\ge$ 3.10
• Linux / macOS / WSL2

Option A: Python Package (PyPI)

Install the standalone NAPxplorer computation engine directly via pip:

pip install napxplorer

(All runtime definitions and geometry templates are bundled internally within napxplorer.data—no external git clones required.)

Option B: Bioconda & Conda-Forge

To install with binary scientific dependencies included (reduce and pymol-open-source; g-xTB is installed separately, see Installing g-xTB):

conda install -c bioconda -c conda-forge napxplorer

Option C: From Source (Developer Mode)

# Clone the repository
git clone https://github.com/NAPxplorer/NAPxplorer.git
cd NAPxplorer

# Activate your Conda environment
conda activate NAPxplorer

# Install package and CLI executables in editable mode
pip install -e .

Option D: Docker & Docker Compose Deployment

NAPxplorer includes a fully containerized deployment (Dockerfile & docker-compose.yml) with the bundled g-xTB build (/opt/gxtb/bin/xtb, exposed as NAPXPLORER_GXTB_BIN). reduce and PyMOL are not in the image yet, so energy and PyMOL steps need them added (or Slurm compute nodes that provide them):

# Build and launch web server with Docker Compose
docker-compose up -d --build

Quick Start & Usage

Python API

import napxplorer as nap
from napxplorer import modifications, visualization

# 1. Access modified nucleotide annotations from PDB CCD
mod_info = modifications.get_modification_info("FHU")
print(f"Modified nucleotide details: {mod_info}")

# 2. Inspect visualization utilities
print(f"Visualization module ready: {visualization}")

Command-Line Interface (CLI)

The CLI command is napxplorer (with naxplorer provided as a seamless backward-compatible alias). With internalized assets, specifying -utility-dir is fully optional:

# Basic interface contact analysis with custom distance cutoff (Å)
napxplorer 1URN.cif -cdist 4.5 -outpath results/

# Complete analysis with strict sp2 acceptor angle restraint
napxplorer 1APL.cif -strict_acceptor_angle -cangle 100.0 -outpath results/

# Differential geometry surface curvature & shape classification
napxplorer 1URN.cif -detail -outpath results/

# Compute g-xTB quantum interaction energies with multi-core CPUs (needs gxtb, see Installing g-xTB)
napxplorer 3R1L.cif -energy -cpu 8 -outpath results/

# Multi-model NMR ensemble analysis
napxplorer 1ETG.cif -all -outpath results/

Running the Interactive Web Server

NAPxplorer includes a Flask web server featuring PDBe Mol* 3D visualization, interactive 2D interaction grids, PyMOL .pse session generators, and preloaded benchmark tutorials.

python -m webserver.NAPxplorer.app --port 5000

Open http://localhost:5000 in your web browser.

Interactive 5-Stage Tutorial & Benchmark Suite

The web server features an interactive educational walkthrough centered on PDB 1K8W (TruB/Pus1 + tRNA with modified FHU), demonstrating submission parameters, live asynchronous status monitoring, Mol* 3D translucent molecular surface patch rendering, 5-table breakdown, and data exports. It also includes 9 pre-calculated benchmark test cases:

1. 1URN: Protein–RNA canonical baseline (U1A RRM + U1 hairpin).
2. 1APL: Protein–DNA baseline (MATα2 homeodomain + DNA operator).
3. 3R1L: Protein–RNA with 46 Mg²⁺ ions & 51 ordered water bridges.
4. 1RVB: Protein–DNA with 2 catalytic Mg²⁺ ions & 185 waters (EcoRV).
5. 1K8W: Modified RNA nucleotide (TruB + 4-thiouridine FHU + 39 waters).
6. 1ETG: Multi-model RNA NMR conformer ensemble (HIV-1 Rev + RRE RNA).
7. 2L1G: Multi-model DNA NMR conformer ensemble (THAP1 zinc-finger).
8. 1ZBI: Protein–RNA–DNA hybrid heteroduplex (Bacillus halodurans RNase H catalytic domain).
9. 7K00: High-resolution 1.98 Å cryo-EM E. coli 70S ribosome (49 protein chains, 7 rRNA/tRNA chains, 11 modified rRNA nucleotides).

REST API & Programmatic Web Services

The NAPxplorer webserver exposes a clean RESTful API for integration into bioinformatic pipelines:

cURL Example

# 1. Inspect chains
curl -s "http://localhost:5000/api/parse_chains?pdb_id=1URN"

# 2. Submit job
curl -s -X POST "http://localhost:5000/submit" \
  -F "input_mode=pdb_id" \
  -F "pdb_id=1URN" \
  -F "cdist=4.5" \
  -F "detail=y"

# 3. Poll status
curl -s "http://localhost:5000/status/<session_id>"

# 4. Download execution manifest
curl -O -J "http://localhost:5000/download/<session_id>/<timestamp>/manifest_json"

Python Requests Example

import time
import requests

BASE_URL = "http://localhost:5000"

# 1. Submit job
resp = requests.post(
    f"{BASE_URL}/submit",
    data={"input_mode": "pdb_id", "pdb_id": "1URN", "detail": "y"},
    allow_redirects=False,
)
session_id = resp.headers.get("Location", "").split("/")[-1]

# 2. Poll until complete
while True:
    status_info = requests.get(f"{BASE_URL}/status/{session_id}").json()
    if status_info.get("status") == "Completed":
        timestamp = status_info.get("timestamp")
        break
    time.sleep(2)

# 3. Download results archive
archive = requests.get(f"{BASE_URL}/download/{session_id}/{timestamp}/zip").content
with open(f"results_{session_id}.zip", "wb") as f:
    f.write(archive)

Interactive API documentation and interactive test suites are available on the web server at /api.

Execution Provenance & Audit Records

Every calculation run through the NAPxplorer engine or webserver automatically creates comprehensive audit records:

1. job_manifest.json:
   • Machine-readable provenance detailing package version, execution timestamp, runtime CLI arguments, interface contact metrics, and structured file inventory.
2. README_OUTPUTS.txt:
   • Human-readable summary detailing the calculation environment, geometry parameters, output files, and citations.
3. Complete Result Bundles (.zip):
   • Results packages archive all coordinate files, interaction CSVs, PyMOL visualization scripts, Mol* scenes, and provenance records for direct sharing and publication submission.

Benchmark & Validation

NAPxplorer has been validated across standard structural benchmarks:

• Surface Residues vs NACCESS: High-throughput validation across 262 protein–RNA complexes demonstrates that NAPxplorer surface residue patches ($R_{\text{patch}} = 14.0$ Å) are a 99.43% true subset of NACCESS solvent-accessible surface residues ($R² = 0.9943$).
• Interaction Accuracy: Cross-benchmarked against DSSR, SNAP, and PRDB datasets.

Repository Structure

NAPxplorer/
├── setup.py                   # Setuptools configuration & console entry points
├── pyproject.toml             # PEP 517/518 build metadata & dependencies
├── recipes/                   # Bioconda / Conda-forge distribution recipes
│   └── napxplorer/
│       └── meta.yaml          # Conda package recipe
├── scripts/                   # Analysis executables & CLI wrappers
│   ├── NAPxplorer.py          # Primary computational pipeline & CLI engine
│   ├── NAxplorer.py           # Backward-compatible entrypoint shim
│   └── benchmark_prdbv3_validation.py # Benchmarking pipeline
├── napxplorer/                # Core Python computation package
│   ├── __init__.py            # Package initialization & public API
│   ├── data/                  # Bundled runtime geometry and definition files
│   ├── core/                  # Data models and coordinate representations
│   ├── io/                    # mmCIF, PDB, and CCD readers
│   ├── interactions/          # 14 contact classification engines
│   ├── geometry/              # Surface curvature, PCA, & Monge patch fitting
│   ├── modifications/         # Modified nucleotide mapping & CCD annotations
│   ├── parsers/               # xTB, DSSR, and parser wrappers
│   └── visualization/         # PyMOL scripts & Mol* JSON scene builders
├── utility/                   # Local reference definitions and surface dot cloud
├── webserver/                 # Flask web application & REST API
│   └── NAPxplorer/
│       ├── app.py             # Server routes, REST API endpoints, & orchestrator
│       ├── config.py          # Environment configuration & path resolutions
│       ├── run_job.py         # Standalone calculation worker & manifest generator
│       ├── structure_parser.py# Multi-format structure parser
│       ├── templates/         # UI templates (results, api, tutorial, about)
│       └── static/            # Styling, assets, & PDBe Mol* plugin
├── deploy/                    # Production deployment configurations (Nginx, Apache, Slurm)
├── Dockerfile                 # Container image specification
└── docker-compose.yml         # Containerized production stack

Citation & References

If you use NAPxplorer in your research, please cite:

• NAPxplorer Framework: NAPxplorer: A Unified Computational Platform for Structural Profiling, Differential Geometry Morphometry, and Quantum Energetics of Protein–Nucleic Acid Interfaces. Manuscript in preparation.
• Ooi Number (Residue Crowding / Location Measure): Nishikawa, K., Ooi, T. (1986). Radial locations of amino acid residues in a globular protein: correlation with the sequence. J. Biochem. 100(4): 1043–1047. https://doi.org/10.1093/oxfordjournals.jbchem.a121789
• g-xTB: Froitzheim, T., Müller, M., Hansen, A., Grimme, S. (2025). g-xTB: A General-Purpose Extended Tight-Binding Electronic Structure Method For the Elements H to Lr (Z=1–103). ChemRxiv, not peer-reviewed (development version used; see grimme-lab/g-xtb). https://doi.org/10.26434/chemrxiv-2025-bjxvt
• PLIP: Salentin, S., Schreiber, S., Haupt, V. J., Adasme, M. F., Schroeder, M. (2015). PLIP: collaborating tools for comprehensive analysis of non-covalent interactions. Nucleic Acids Res. 43(W1): W443–W447. https://doi.org/10.1093/nar/gkv315
• 3DNA-DSSR: Lu, X. J., Bussemaker, H. J., Olson, W. K. (2015). DSSR: an integrated software tool for dissecting the spatial structure of RNA. Nucleic Acids Res. 43(21): e142. https://doi.org/10.1093/nar/gkv716
• Leontis-Westhof RNA Base Pairs: Leontis, N. B., Westhof, E. (2001). Geometric nomenclature and classification of RNA base pairs. RNA 7(4): 499–512. https://doi.org/10.1017/s1355838201002515
• Dissecting Recognition Sites: Chakrabarti, P., Janin, J. (2002). Dissecting protein-protein and protein-nucleic acid interfaces. Proteins 47(1): 71–80. https://doi.org/10.1002/prot.10069

Acknowledgements

In the open-science spirit modeled by foundational structural biology projects such as AlphaFold 3, NAPxplorer gratefully acknowledges the open-source software, datasets, and design frameworks that made this platform possible:

• MolNympheas: For the inspiring modern color schema, sleek dark-mode aesthetics, and macromolecular visualization styling ideas adopted across the NAPxplorer webserver.
• xTB (Prof. Stefan Grimme, University of Bonn): For the open-source semi-empirical quantum chemical program (and the g-xTB build of xtb 6.7.1) powering the interface interaction energies.
• PDBe Mol* (PDBe & Mol* Consortium): For the robust WebGL 3D macromolecular rendering engine.
• 3DNA-DSSR (Dr. Xiang-Jun Lu): For foundational secondary structure and base-pair geometry classification algorithms.
• wwPDB & RCSB PDB: For providing the global structural biology community with open macromolecular coordinate archives and APIs.

License & Contact

Distributed under the MIT License. See LICENSE for more information.

• Developer: Shrikant
• GitHub: @shrikantcombio