Metadata-Version: 2.4
Name: protkit-md
Version: 0.1.5
Summary: Protein Dynamics Analysis Suite — conformational clustering, residue networks, mutant scanning, and MD QC in one pip-installable toolkit.
Author: protkit contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/protkit
Project-URL: Documentation, https://github.com/yourusername/protkit#readme
Project-URL: Repository, https://github.com/yourusername/protkit
Project-URL: Bug Tracker, https://github.com/yourusername/protkit/issues
Keywords: bioinformatics,structural biology,molecular dynamics,protein structure,conformational clustering,residue network,mutant stability,HDBSCAN,MDTraj,proteomics
Classifier: Development Status :: 3 - Alpha
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mdtraj>=1.9.9
Requires-Dist: numpy>=1.24
Requires-Dist: networkx>=3.1
Requires-Dist: scikit-learn>=1.3
Requires-Dist: hdbscan>=0.8.33
Requires-Dist: matplotlib>=3.7
Provides-Extra: ml
Requires-Dist: torch>=2.0; extra == "ml"
Requires-Dist: fair-esm>=2.0.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: protkit[ml]; extra == "all"
Requires-Dist: protkit[dev]; extra == "all"
Dynamic: license-file

# 🧬 protkit

**Protein Dynamics Analysis Suite** — a unified, pip-installable toolkit for structural bioinformatics.

[![PyPI version](https://badge.fury.io/py/protkit-md.svg)](https://badge.fury.io/py/protkit-md)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey)]()

---

## What is protkit?

Most structural bioinformatics workflows require stitching together 4–5 separate scripts, tools, and environments. **protkit** unifies them into one clean CLI + Python library:

| Module | What it does |
|---|---|
| `qc` | MD simulation quality control (RMSD, RMSF, Rg, H-bonds, convergence) |
| `cluster` | Conformational state clustering with HDBSCAN (no k required) |
| `mutant` | Point mutation ΔΔG prediction via physics scoring or ESM-2 ML |
| `network` | Protein Residue Network — hub residues, allosteric pathways |
| `run-all` | Full pipeline in one command |

Every command produces a **CLI summary**, a **text report**, an **interactive HTML report**, and a **raw JSON data file**.

---

## Installation

```bash
pip install protkit-md
```

With ML-based mutation scoring (ESM-2):
```bash
pip install protkit-md[ml]
```

---

## Quick Start

```bash
# Quality control
protkit qc --traj md.xtc --top protein.pdb

# Conformational clustering
protkit cluster --traj md.xtc --top protein.pdb --method hdbscan

# Mutant stability scan
protkit mutant --pdb protein.pdb --mutations A100G,V200I,R300K --method both

# Residue network analysis
protkit network --traj md.xtc --top protein.pdb --source 50 --target 200

# Full pipeline
protkit run-all --traj md.xtc --top protein.pdb --mutations A100G
```

---

## The `--learn` Flag

Every command supports `--learn` for full theory + analogy before the run:

```bash
protkit cluster --traj md.xtc --top protein.pdb --learn
```

Output:
```
╔══════════════════════════════════════════════════════════════════════╗
║  📚  Conformational Clustering — Theory & Intuition                  ║
╚══════════════════════════════════════════════════════════════════════╝

WHAT IS CONFORMATIONAL CLUSTERING?
...

THE ANALOGY 🗺️
Think of your protein's conformational journey like GPS tracking
a person walking around a city all day...
```

Without `--learn`, every run still prints a clean one-liner explaining what's happening.

---

## Supported Trajectory Formats

| Software | Formats |
|---|---|
| GROMACS | `.xtc`, `.trr`, `.gro` |
| AMBER | `.nc`, `.ncdf`, `.crd` |
| NAMD / CHARMM | `.dcd` |
| Generic | `.pdb` (multi-model) |

---

## Command Reference

### `protkit qc`

```
--traj FILE          Trajectory file
--top  FILE          Topology/reference PDB
--ref  FILE          Reference PDB for alignment (optional; uses frame 0)
--energy FILE        GROMACS .log or two-column energy file (optional)
--stride N           Load every Nth frame (default: 1)
--no-align           Skip alignment
--learn              Show theory + analogy
--output DIR         Output directory
```

### `protkit cluster`

```
--traj FILE          Trajectory file
--top  FILE          Topology PDB
--method             hdbscan (default) | gromos | agglomerative
--min-cluster-size N HDBSCAN min_cluster_size (auto if omitted)
--n-clusters K       For agglomerative clustering
--cutoff Å           GROMOS RMSD cutoff (default: 2.0 Å)
--learn
```

### `protkit mutant`

```
--pdb FILE           Input PDB
--mutations STR      e.g. A100G,V200I or A:R50K (chain:mutation)
--method             physics (default) | ml | both
--centroids-json     JSON file: {cluster_id: pdb_path} for multi-state scan
--learn
```

### `protkit network`

```
--traj FILE          Trajectory file
--top  FILE          Topology PDB
--edge-mode          ca_cutoff (default) | heavy_atom
--cutoff-ca Å        Cα cutoff (default: 8.0 Å)
--cutoff-heavy Å     Heavy atom cutoff (default: 4.5 Å)
--source RESID       Source residue for pathway calculation
--target RESID       Target residue for pathway calculation
--learn
```

### `protkit run-all`

Runs QC → Clustering → Network → Mutant Scan in sequence.
Cluster centroids from step 2 are automatically piped into the mutant scan.

```
--traj FILE
--top  FILE
--mutations STR      (optional)
--mutant-method      physics | ml | both
--cluster-method     hdbscan | gromos | agglomerative
--edge-mode          ca_cutoff | heavy_atom
--source / --target  for pathway
--learn
```

---

## Output Files

Every run creates a timestamped directory:

```
protkit_results_20250101_143022/
├── protkit_report.html     ← Interactive HTML dashboard
├── protkit_report.txt      ← Plain text report
├── protkit_data.json       ← Raw data (all computed arrays)
├── cluster_0_centroid.pdb  ← Centroid structure per cluster
├── cluster_1_centroid.pdb
└── ...
```

---

## Using as a Python Library

```python
import mdtraj as md
from protkit.modules.qc import run_qc
from protkit.modules.cluster import run_cluster
from protkit.modules.network import run_network
from pathlib import Path

# Load trajectory
traj = md.load("md.xtc", top="protein.pdb")

# QC
qc_results = run_qc(traj, output_dir=Path("./output"))

# Clustering
cluster_results = run_cluster(traj, output_dir=Path("./output"), method="hdbscan")

# Residue network
network_results = run_network(traj, output_dir=Path("./output"), edge_mode="ca_cutoff")
```

---

## Dependencies

**Core (auto-installed):**
- [MDTraj](https://mdtraj.org) — trajectory loading and analysis
- [NumPy](https://numpy.org) — numerical operations
- [NetworkX](https://networkx.org) — graph analysis
- [scikit-learn](https://scikit-learn.org) — machine learning utilities
- [HDBSCAN](https://hdbscan.readthedocs.io) — clustering

**Optional (`pip install protkit-md[ml]`):**
- [PyTorch](https://pytorch.org) + [fair-esm](https://github.com/facebookresearch/esm) — ESM-2 ML scoring

---

## Theory

protkit is built on peer-validated methods:

- **HDBSCAN clustering** on RMSD matrices ([Bioinformatics, Oxford, 2022](https://academic.oup.com/bioinformatics))
- **Residue network centrality** for allosteric hub detection ([Bhattacharyya et al., 2016](https://www.nature.com/articles/srep35191))
- **ESM-2** protein language model for mutation scoring ([Lin et al., Science, 2023](https://www.science.org/doi/10.1126/science.ade2574))
- **Physics-based ΔΔG** using hydrophobicity, volume, and charge empirical terms

---

## License

MIT — free for academic and commercial use.

---

## Citation

If you use protkit in your research, please cite:

```
protkit: Protein Dynamics Analysis Suite (2025)
https://github.com/Eswar-mse/protkit
```
