napxplorer 1.0.0__tar.gz

napxplorer-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shrikant (<shrikant92pharmacy@gmail.com>)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

napxplorer-1.0.0/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: napxplorer
+Version: 1.0.0
+Summary: NAPxplorer: Structural Analysis, Quantum Energetics & 3D Visualization of Nucleic Acid–Protein Complexes
+Author: Shrikant
+Author-email: Satyabrata Maiti <napxplorer@gmail.com>, Shri Kant <napxplorer@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/NAPxplorer/NAPxplorer
+Project-URL: Documentation, https://github.com/NAPxplorer/NAPxplorer#readme
+Project-URL: Repository, https://github.com/NAPxplorer/NAPxplorer.git
+Project-URL: Issues, https://github.com/NAPxplorer/NAPxplorer/issues
+Keywords: structural-biology,rna-protein-interactions,dna-protein-interactions,nucleic-acids,bioinformatics,xtb,quantum-chemistry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: biopython>=1.80
+Requires-Dist: gemmi>=0.6.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: networkx>=2.8
+Requires-Dist: scikit-learn>=1.1.0
+Requires-Dist: matplotlib>=3.6.0
+Requires-Dist: seaborn>=0.12.0
+Provides-Extra: webserver
+Requires-Dist: Flask>=2.0; extra == "webserver"
+Requires-Dist: Flask-WTF>=1.0; extra == "webserver"
+Requires-Dist: Flask-Limiter>=3.0; extra == "webserver"
+Requires-Dist: wtforms>=3.0; extra == "webserver"
+Provides-Extra: e2e
+Requires-Dist: playwright>=1.40; extra == "e2e"
+Requires-Dist: pytest>=7.0; extra == "e2e"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# NAPxplorer
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="webserver/NAPxplorer/static/images/NAPxplorer_logo_kit_final/svg/NAPxplorer_wordmark_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="webserver/NAPxplorer/static/images/NAPxplorer_logo_kit_final/svg/NAPxplorer_wordmark.svg">
+    <img src="webserver/NAPxplorer/static/images/NAPxplorer_logo_kit_final/svg/NAPxplorer_wordmark.svg" alt="NAPxplorer Logo" width="460">
+  </picture>
+</p>
+
+[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![PyPI Version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/napxplorer/)
+[![Bioconda](https://img.shields.io/badge/bioconda-napxplorer-green.svg)](https://bioconda.github.io/)
+[![Interface Analysis](https://img.shields.io/badge/Analysis-Protein--Nucleic%20Acid%20Interfaces-purple.svg)](#scientific-capabilities--analytical-modules)
+[![Quantum Chemistry](https://img.shields.io/badge/Quantum%20QC-g--xTB%20COSMO-orange.svg)](#quantum-chemical-interaction-energetics)
+[![3D Viewer](https://img.shields.io/badge/Visualization-PDBe%20Mol*-cyan.svg)](#running-the-interactive-web-server)
+
+**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](#key-features)
+- [Scientific Capabilities & Analytical Modules](#scientific-capabilities--analytical-modules)
+  - [1. Comprehensive Interface Contact Detection](#1-comprehensive-interface-contact-detection)
+  - [2. Quantum Chemical Interaction Energetics (g-xTB)](#2-quantum-chemical-interaction-energetics-g-xtb)
+  - [3. Differential Geometry Surface Curvature & Shape Classification](#3-differential-geometry-surface-curvature--shape-classification)
+  - [4. Surface Wrapping Index & Nucleic Acid Crowding (OOI Index)](#4-surface-wrapping-index--nucleic-acid-crowding-ooi-index)
+  - [5. Modified Nucleotides & Non-Standard Residues](#5-modified-nucleotides--non-standard-residues)
+  - [6. Multi-Model NMR Conformer Ensembles](#6-multi-model-nmr-conformer-ensembles)
+- [Installation](#installation)
+  - [Option A: Python Package (PyPI)](#option-a-python-package-pypi)
+  - [Option B: Bioconda & Conda-Forge](#option-b-bioconda--conda-forge)
+  - [Option C: From Source (Developer Mode)](#option-c-from-source-developer-mode)
+  - [Option D: Docker & Docker Compose](#option-d-docker--docker-compose-deployment)
+- [Quick Start & Usage](#quick-start--usage)
+  - [Python API](#python-api)
+  - [Command-Line Interface (CLI)](#command-line-interface-cli)
+  - [Running the Interactive Web Server](#running-the-interactive-web-server)
+- [REST API & Programmatic Web Services](#rest-api--programmatic-web-services)
+- [Execution Provenance & Audit Records](#execution-provenance--audit-records)
+- [Benchmark & Validation](#benchmark--validation)
+- [Repository Structure](#repository-structure)
+- [Citation & References](#citation--references)
+- [License & Contact](#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](https://github.com/grimme-lab/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)).
+
+#### 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/`](third_party/g-xtb/NOTICE.md) (GPL-3.0, separate from NAPxplorer's MIT license; extract with `tar xJf`). For other OSes download the archive from the [`binaries`](https://github.com/grimme-lab/g-xtb/tree/main/binaries) folder of the g-xtb repository. Extract it, and either put the executable on `PATH` as `gxtb` or point NAPxplorer to it:
+```bash
+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 (Å⁻¹).
+
+| Shape Class | Shape Index ($S$) Criteria | Biological Interpretation |
+|---|---|---|
+| **POCKET** | $S \ge 0.625$ | Strongly concave cup / enclosed binding pocket |
+| **GROOVE** | $0.125 \le S < 0.625$ | Concave protein channel / cleft enclosing nucleic acid |
+| **SADDLE** | $|S| < 0.125$ | Hyperbolic pass between opposing surface curvatures |
+| **RIDGE** | $-0.625 < S \le -0.125$ | Convex protein protrusion / spine inserting into groove |
+| **CAP** | $S \le -0.625$ | Strongly convex dome / localized bump |
+| **PLANAR** | $C < 0.02$ Å⁻¹ | Flat protein platform |
+
+### 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`:
+```bash
+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](#installing-g-xtb)):
+```bash
+conda install -c bioconda -c conda-forge napxplorer
+```
+
+### Option C: From Source (Developer Mode)
+```bash
+# 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):
+```bash
+# Build and launch web server with Docker Compose
+docker-compose up -d --build
+```
+
+---
+
+## Quick Start & Usage
+
+### Python API
+
+```python
+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:
+
+```bash
+# 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.
+
+```bash
+python -m webserver.NAPxplorer.app --port 5000
+```
+Open **[http://localhost:5000](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:
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/api/parse_chains?pdb_id=<ID>` | Inspect protein and nucleic acid chains for a PDB code |
+| `POST` | `/api/parse_upload_chains` | Parse chain IDs from an uploaded `.cif` or `.pdb` file |
+| `POST` | `/submit` | Dispatch single structure or batch calculation jobs |
+| `GET` | `/status/<session_id>` | Poll live calculation progress, counts, and status |
+| `GET` | `/api/interactions/<session_id>/<timestamp>` | Retrieve Mol* 3D visualization JSON and interaction records |
+| `GET` | `/download/<session_id>/<timestamp>/<file_type>` | Download outputs (`manifest_json`, `readme_txt`, `zip`, `csv`, `pse`, `curvature_csv`, `wrapping_csv`) |
+
+### cURL Example
+
+```bash
+# 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
+
+```python
+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`](http://localhost:5000/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
+
+```text
+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](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://github.com/grimme-lab/g-xtb)). [https://doi.org/10.26434/chemrxiv-2025-bjxvt](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](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](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](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](https://doi.org/10.1002/prot.10069)
+
+---
+
+## Acknowledgements
+
+In the open-science spirit modeled by foundational structural biology projects such as [AlphaFold 3](https://github.com/google-deepmind/alphafold3), NAPxplorer gratefully acknowledges the open-source software, datasets, and design frameworks that made this platform possible:
+
+- **[MolNympheas](https://github.com/JMB-Scripts/MolNympheas.git)**: For the inspiring modern color schema, sleek dark-mode aesthetics, and macromolecular visualization styling ideas adopted across the NAPxplorer webserver.
+- **[xTB](https://github.com/grimme-lab/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*](https://github.com/PDBe-KB/pdbe-molstar)** (PDBe & Mol* Consortium): For the robust WebGL 3D macromolecular rendering engine.
+- **[3DNA-DSSR](https://x3dna.org/)** (Dr. Xiang-Jun Lu): For foundational secondary structure and base-pair geometry classification algorithms.
+- **[wwPDB](https://www.wwpdb.org/) & [RCSB PDB](https://www.rcsb.org/)**: 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](https://github.com/shrikantcombio)