Metadata-Version: 2.4
Name: alphacert
Version: 1.1.0
Summary: Automated Quality-Control, pLDDT/PAE Assessment, and Stereochemical Certification for Predicted Protein Structures (AlphaFold2/3, ColabFold, ESMFold)
Author-email: Andrés Monreal-Hernández <andres.monreal@ues.mx>
License: MIT
Project-URL: Homepage, https://github.com/sircalch/alphacert
Project-URL: Documentation, https://github.com/sircalch/alphacert#readme
Project-URL: Repository, https://github.com/sircalch/alphacert.git
Project-URL: Bug Tracker, https://github.com/sircalch/alphacert/issues
Project-URL: Changelog, https://github.com/sircalch/alphacert/blob/main/CHANGELOG.md
Keywords: alphafold,alphafold2,alphafold3,colabfold,esmfold,plddt,predicted-aligned-error,pae,protein-structure,structural-biology,ramachandran,docking-validation,reproducibility
Classifier: Development Status :: 5 - Production/Stable
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: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: networkx>=2.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

﻿# AlphaCert

[![CI](https://github.com/sircalch/alphacert/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/alphacert/actions)
[![PyPI version](https://img.shields.io/pypi/v/alphacert.svg?color=blue)](https://pypi.org/project/alphacert/)
[![Python versions](https://img.shields.io/pypi/pyversions/alphacert.svg)](https://pypi.org/project/alphacert/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22217576.svg)](https://doi.org/10.5281/zenodo.22217576)

> **Automated Quality-Control, pLDDT/PAE Assessment, and Stereochemical Certification for Predicted Protein Structures (AlphaFold2/3, ColabFold, ESMFold).**

---

## Overview

**AlphaCert** is an open-source scientific toolkit designed to systematically audit, validate, and certify the reliability of 3D protein structures predicted by **AlphaFold2**, **AlphaFold-Multimer**, **AlphaFold3**, **ColabFold**, and **ESMFold**.

Rather than blindly relying on predicted models for molecular docking, molecular dynamics, or drug discovery campaigns, `alphacert` performs an automated multi-criteria structural audit in a single command:

- 📊 **Residue pLDDT Confidence Profile & Classification**:
  - Categorizes residues into the 4 canonical AlphaFold bands:
    - 🔵 **Very High Confidence ($> 90$)**: Suitable for atomic side-chain modeling and docking.
    - 🔷 **Confident ($70 - 90$)**: Reliable backbone topology.
    - 🟡 **Low Confidence ($50 - 70$)**: Loop regions or flexible segments.
    - 🟠 **Very Low Confidence ($< 50$)**: Intrinsically Disordered Regions (IDRs).
- 🧩 **2D Predicted Aligned Error (PAE) Matrix Audit**:
  - Identifies rigid domains by clustering the PAE matrix with Croll's greedy-modularity method (the method used by ChimeraX and AlphaFold DB; cutoff 5 Å). Disordered clusters with mean pLDDT < 70 are excluded.
  - Evaluates multimer interfaces with ipTM as the primary criterion (> 0.8 confident, 0.6–0.8 grey zone, < 0.6 likely failed). The symmetrised inter-chain PAE is used when no ipTM is available.
- 📐 **Stereochemical & Geometry Quality**:
  - Heavy-atom clash score: non-bonded pairs (more than 3 covalent bonds apart) with $d_{ij} < r_{\text{vdw}, i} + r_{\text{vdw}, j} - 0.40$ Å, per 1000 heavy atoms. This is a proxy without hydrogens, not the MolProbity clashscore.
  - Ramachandran dihedral distribution ($\phi, \psi$ Favored $\ge 88\%$, Outliers $< 3\%$) using approximate rectangular regions, not the MolProbity Top8000 contours. For publication-grade figures, use MolProbity or PHENIX.
  - Non-proline *cis*-peptide bond identification.
- 🎯 **Target Application Readiness Certification**:
  - 💊 **`DOCKING_READY`**: Verifies that active/binding site residues have $\text{pLDDT} \ge 80$.
  - 🌊 **`MD_READY`**: Verifies that disordered terminal loops do not compromise solvated simulation stability.
  - 🤝 **`INTERFACE_VALID`**: Distinguishes authentic protein-protein interfaces from non-binding artifacts.
- 📑 **Publication Deliverables**:
  - Interactive self-contained `report.html` dashboard.
  - Publication vector plots (pLDDT sequence profile, 2D PAE error heatmap, Ramachandran scatter plot) in SVG, PDF, PNG (300 DPI).
  - Ready-to-compile LaTeX summary tables (`.tex`).
  - Draft **Methods** text snippet and BibTeX citation (`citation.bib`).

```
   AlphaFold PDB / mmCIF + PAE JSON
                  │
                  ▼
  ┌───────────────────────────────────────────────────────────┐
  │                         AlphaCert                         │
  │  ├── Residue-level pLDDT Band Categorization & IDR Audit  │
  │  ├── 2D Predicted Aligned Error (PAE) Domain Decomposition│
  │  ├── Steric Clashscore & Ramachandran Geometry Check      │
  │  └── Downstream Certification (Docking-Ready / MD-Ready)  │
  └───────────────────────────────────────────────────────────┘
                  │
                  ▼
  ┌───────────────────────────────────────────────────────────┐
  │                   Publication Deliverables                │
  │  ├── report.html (Interactive Dashboard & Badges)         │
  │  ├── alphacert_plddt_profile.pdf/svg/png                  │
  │  ├── alphacert_pae_matrix.pdf/svg/png                     │
  │  ├── alphacert_ramachandran_plot.pdf/svg/png              │
  │  ├── alphacert_summary_table.tex / .csv                   │
  │  ├── methods_snippet.txt (Ready for Manuscript)           │
  │  └── citation.bib (BibTeX Reference)                      │
  └───────────────────────────────────────────────────────────┘
```

---

## Installation

### From PyPI
> **Note:** PyPI release pending. Until then, install from the tagged GitHub release:

```bash
pip install "git+https://github.com/sircalch/alphacert@v1.0.0"
```

### From Source
```bash
git clone https://github.com/sircalch/alphacert.git
cd alphacert
pip install -e .[dev]
```

---

## Quickstart (CLI)

### 1. Run Benchmark Demo (Instant AlphaFold Kinase Model Audit)
```bash
alphacert demo -o my_protein_audit/
```
Open `my_protein_audit/report.html` in any browser to inspect the interactive report!

### 2. Assess Predicted PDB Structure
```bash
alphacert assess -i predicted_structure.pdb --pae predicted_pae.json -o struct_report/
```

### 3. Certify Binding Pocket for Molecular Docking
```bash
alphacert assess -i model.pdb --pocket "45,46,47,78,120,121" -o docking_check/
```

---

## Python API Usage

```python
from alphacert import assess_alphafold_quality
from alphacert.parsers import parse_protein_structure, parse_pae_matrix
from alphacert.reporters import generate_alphacert_figures, generate_alphacert_manuscript_assets, generate_alphacert_html_report

# 1. Parse structure and PAE matrix
struct = parse_protein_structure("alphafold_model.pdb")
pae = parse_pae_matrix("alphafold_pae.json")

# 2. Assess structure quality
report = assess_alphafold_quality(
    metadata={"name": "Target Kinase", "engine": "AlphaFold2"},
    plddt_values=struct["per_residue_plddt"],
    pae_matrix=pae["pae_matrix"],
    coordinates=struct["coordinates"],
    atom_elements=struct["atom_elements"],
    backbone_atoms=struct["backbone_atoms"],
    binding_site_indices=[45, 46, 47, 78, 120]
)

print(f"Overall Certification: {report.overall_status}")
print(f"Mean pLDDT: {report.plddt_result.mean_plddt:.1f}")
print(f"Docking Readiness: {report.docking_readiness['status']}")

# 3. Export publication deliverables
generate_alphacert_figures(report, "output_dir/")
generate_alphacert_manuscript_assets(report, "output_dir/")
generate_alphacert_html_report(report, "output_dir/report.html")
```

---

## Citation

If you use AlphaCert in your research, please cite:

```bibtex
@software{monreal2026alphacert,
  author = {Monreal-Hern{\'a}ndez, Andre},
  title = {{AlphaCert: An Open-Source Toolkit for Quality-Control, pLDDT/PAE Assessment, and Stereochemical Certification of Predicted Protein Structures}},
  year = {2026},
  version = {1.0.0},
  publisher = {Zenodo},
  url = {https://github.com/sircalch/alphacert}
}
```

---

## License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

