Metadata-Version: 2.4
Name: chiralfold
Version: 3.5.1
Summary: Chirality-correct protein stereochemistry toolkit: PDB auditing, D-peptide construction, AF3 correction, and mirror-image design
Author-email: "Tommaso R. Marena" <marena@cua.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Tommaso-R-Marena/ChiralFold
Project-URL: Repository, https://github.com/Tommaso-R-Marena/ChiralFold
Project-URL: Issues, https://github.com/Tommaso-R-Marena/ChiralFold/issues
Project-URL: Documentation, https://github.com/Tommaso-R-Marena/ChiralFold/blob/master/README.md
Keywords: chirality,peptide,D-amino-acid,diastereomer,structure-prediction,alphafold,PDB,stereochemistry,MolProbity
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
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: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.21
Requires-Dist: rdkit<2027,>=2023.3
Requires-Dist: scipy<2.0,>=1.9
Requires-Dist: pandas<3.0,>=1.3
Provides-Extra: web
Requires-Dist: gradio<6,>=4.44; extra == "web"
Requires-Dist: huggingface_hub<1.0,>=0.23; extra == "web"
Provides-Extra: viz
Requires-Dist: matplotlib<4.0,>=3.5; extra == "viz"
Requires-Dist: seaborn<1.0,>=0.11; extra == "viz"
Requires-Dist: scikit-learn<2.0,>=1.0; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: matplotlib<4.0,>=3.5; extra == "dev"
Requires-Dist: seaborn<1.0,>=0.11; extra == "dev"
Requires-Dist: scikit-learn<2.0,>=1.0; extra == "dev"
Dynamic: license-file

# ChiralFold

**Chirality-correct protein stereochemistry toolkit** — audit any PDB, fix AF3 chirality errors, build D-peptides by construction, and generate exact L↔D mirrors.

![Tests](https://github.com/Tommaso-R-Marena/ChiralFold/actions/workflows/ci.yml/badge.svg?branch=master)
[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-Launch%20Web%20UI-0D9488?style=for-the-badge)](https://huggingface.co/spaces/The-Philosopher/ChiralFold-App)
[![Reproduce D-residue errors (5 min)](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Tommaso-R-Marena/ChiralFold/blob/master/demos/Reproduce_PDB_D_Residue_Errors_5min.ipynb)
[![Quick Demo](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Tommaso-R-Marena/ChiralFold/blob/master/demos/ChiralFold_Quick_Demo.ipynb)

---

## Start here

| Goal | Link |
|------|------|
| **Use in a browser** (upload PDB → correct / mirror → download) | [Hugging Face Space](https://huggingface.co/spaces/The-Philosopher/ChiralFold-App) |
| **Reproduce D-residue survey errors (&lt;5 min)** | [Colab notebook](https://colab.research.google.com/github/Tommaso-R-Marena/ChiralFold/blob/master/demos/Reproduce_PDB_D_Residue_Errors_5min.ipynb) · or `python benchmarks/reproduce_d_residue_errors.py` |
| **Interactive results dashboard** | [Colab dashboard](https://colab.research.google.com/github/Tommaso-R-Marena/ChiralFold/blob/master/demos/ChiralFold_Results_Dashboard.ipynb) ⚠️ auto-installs (~1–2 min) |
| **Demo: unusual cases + clash-safety** | [Colab notebook](https://colab.research.google.com/github/Tommaso-R-Marena/ChiralFold/blob/master/demos/Demo_Unusual_Cases_Clash_Safety.ipynb) |

---

## Install

Works on **Linux, macOS, and Windows** (Python 3.9–3.12).

```bash
# Recommended — always current (PyPI package pending Trusted Publisher setup)
pip install -U pip
pip install "chiralfold @ git+https://github.com/Tommaso-R-Marena/ChiralFold.git@v3.5.1"

# Or clone + editable
git clone https://github.com/Tommaso-R-Marena/ChiralFold.git
cd ChiralFold
pip install -e .
```

> **Note:** Bare `pip install chiralfold` requires PyPI publishing to succeed.
> See [`docs/PYPI_PUBLISHING.md`](docs/PYPI_PUBLISHING.md) for Trusted Publisher setup
> (or set secret `PYPI_API_TOKEN`). Until then, use the Git install above — same package.

Core dependencies: `numpy`, `scipy`, `pandas`, `rdkit`.  
Optional: `pip install "chiralfold[web]"` (Gradio UI) · `pip install "chiralfold[viz]"` (matplotlib/seaborn for benchmarks).

**If `rdkit` fails on your platform:**

```bash
conda install -c conda-forge rdkit
pip install "chiralfold @ git+https://github.com/Tommaso-R-Marena/ChiralFold.git"
```

Full platform notes: [`docs/INSTALL.md`](docs/INSTALL.md).

```bash
# Verify
python -c "import chiralfold; print(chiralfold.__version__)"
chiralfold --help
```

---

## Reviewer path (&lt;5 minutes, offline)

Reproduce the **29 D-label / L-coordinate mismatches** from the frozen survey CSV — no network, no ChiralFold install required beyond numpy:

```bash
git clone --depth 1 https://github.com/Tommaso-R-Marena/ChiralFold.git
cd ChiralFold
pip install numpy   # only dependency for this script
python benchmarks/reproduce_d_residue_errors.py
```

Expected output: `12,573` checkable residues · `29` errors · `16` structures · rate `0.23%`.

Or open the [Reproduce D-residue errors Colab](https://colab.research.google.com/github/Tommaso-R-Marena/ChiralFold/blob/master/demos/Reproduce_PDB_D_Residue_Errors_5min.ipynb).

---

## What ChiralFold does

```python
from chiralfold import audit_pdb, correct_af3_output, mirror_pdb, ChiralFold

report = audit_pdb("protein.pdb")          # chirality, Rama, clashes, score
correct_af3_output("af3.pdb", "fixed.pdb") # fix inverted stereocenters
mirror_pdb("1YCR.pdb", "1YCR_D.pdb")       # exact L↔D (RMSD 0.0 Å)
pred = ChiralFold().predict("AFWKELDR")     # D-peptide, 0% violations by construction
```

Web UI (local):

```bash
pip install "chiralfold[web]"
chiralfold-web   # http://localhost:7860
```

---

## Key results (at a glance)

| Result | Number | Where |
|--------|--------|-------|
| PDB-wide D-residue survey | **12,573** residues · **29** errors in **16** structures (0.23%) | `results/d_residue_verification_summary.json` |
| Experimental validation | **14/14** non-borderline pass (2 borderline) | `results/experimental_validation_report.json` |
| Ramachandran vs wwPDB (paper) | **n=362** · Spearman **ρ=0.52** · Pearson **r=0.853** | `results/ramachandran_279struct_chainfix_summary.json` |
| AF3 synthetic correction | **100%** detection · **0%** residual · ~37 ms | `results/af3_resource_benchmark.json` |
| Mirror clashscore | **Unchanged** (isometry — distances preserved) | `tests/test_clash_preservation.py` |
| Lean 4 chirality no-go | Distance-only reps cannot recover signed orientation | [`formal/chirality_nogo/`](formal/chirality_nogo/) |

MolProbity does **not** flag the D-residue annotation errors (L-only Cα check).

---

## Unusual cases

ChiralFold is tested on structures that break naive assumptions:

| Case | Example | What happens |
|------|---------|--------------|
| **Strained / cyclic macrocycle** | **1XT7** daptomycin · **2RMI** astressin | Signed volume still classifies Cα; Stereochem errors detected |
| **Non-standard ligands (CCD)** | **1OF6** (8× DTY←L-Tyr) · **1BG0** DAR←L-Arg | Coordinates match L; CCD InChI confirms mislabel |
| **Ultra-high resolution** | **1HHZ** (0.99 Å) DAL error | Not a density/resolution artifact |
| **Low-res / non-protein Rama** | **5M2K** vancomycin glycopeptide | Excluded from protein Rama benchmark by pre-specified rule |

See [`demos/Demo_Unusual_Cases_Clash_Safety.ipynb`](demos/Demo_Unusual_Cases_Clash_Safety.ipynb) and `results/5m2k_benchmark_exclusion.json`.

### “By construction” does not invent clashes

- **Mirror L↔D** is a global isometry: all pairwise distances are preserved → **clashscore is identical** before and after (`tests/test_clash_preservation.py`).
- **AF3 chirality correction** reflects only the violating Cα across the N–C–Cβ plane, preserving CA–N / CA–C / CA–Cβ bond lengths. Clashscore may change slightly when a bad stereocenter is fixed; residual chirality violations go to **0%**.

---

## Repository map

```
chiralfold/          # Installable Python package
web/                 # Gradio UI (chiralfold-web)
hf_space/            # Hugging Face Space source
demos/               # Colab notebooks (start with Reproduce_PDB_D_Residue_Errors_5min)
benchmarks/          # Reproducible survey / validation / Rama scripts
results/             # Frozen CSV/JSON artefacts (do not hand-edit)
tests/               # pytest suite
paper/submission/    # Bioinformatics Overleaf package
docs/                # Install notes, navigation
```

---

## Citation

```bibtex
@software{chiralfold2026,
  author = {Marena, Tommaso R.},
  title  = {ChiralFold: Chirality-correct protein stereochemistry toolkit},
  year   = {2026},
  url    = {https://github.com/Tommaso-R-Marena/ChiralFold}
}
```

AF3 D-peptide context: Childs, Zhou & Donald (2025) bioRxiv [10.1101/2025.03.14.643307](https://doi.org/10.1101/2025.03.14.643307).

---

## License

MIT — see [`LICENSE`](LICENSE).
