dockcert 1.0.0__tar.gz

dockcert-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Monreal-Hernández
+
+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.

dockcert-1.0.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: dockcert
+Version: 1.0.0
+Summary: Automated Statistical Validation, Enrichment Metrics, and Reproducibility Toolkit for Molecular Docking and Virtual Screening
+Author-email: Andre Monreal-Hernández <amonreal@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sircalch/dockcert
+Project-URL: Documentation, https://github.com/sircalch/dockcert#readme
+Project-URL: Repository, https://github.com/sircalch/dockcert.git
+Project-URL: Bug Tracker, https://github.com/sircalch/dockcert/issues
+Project-URL: Changelog, https://github.com/sircalch/dockcert/blob/main/CHANGELOG.md
+Keywords: molecular-docking,virtual-screening,autodock-vina,smina,gnina,glide,gold,roc-auc,bedroc,enrichment-factor,rmsd,reproducibility,chemoinformatics,drug-discovery
+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: scikit-learn>=1.0.0
+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
+
+# DockCert
+
+[![CI](https://github.com/sircalch/dockcert/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/dockcert/actions)
+[![PyPI version](https://img.shields.io/pypi/v/dockcert.svg?color=blue)](https://pypi.org/project/dockcert/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dockcert.svg)](https://pypi.org/project/dockcert/)
+[![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.1234568.svg)](https://doi.org/10.5281/zenodo.1234568)
+
+> **Automated Statistical Validation, Early Enrichment Metrics, and Reproducibility Assessment for Molecular Docking and Virtual Screening Studies.**
+
+---
+
+## Overview
+
+**DockCert** is an open-source scientific toolkit engineered to evaluate whether a molecular docking or virtual screening protocol is rigorously validated before publication.
+
+Instead of computing enrichment factors or pose RMSD across fragmented scripts, `dockcert` analyzes your screening results and docked structures in a single run:
+
+- 🎯 **Redocking & Cross-Docking Pose Accuracy**: Heavy-atom & symmetry-corrected RMSD (Hungarian algorithm).
+- 📈 **Early Enrichment Quantification**:
+  - **BEDROC** ($\alpha=20.0, 80.5, 160.9$)
+  - **RIE** (Robust Initial Enhancement)
+  - **EF1%**, **EF5%**, **EF10%** (Enrichment Factors)
+  - **ROC-AUC** & **PR-AUC** (Precision-Recall AUC)
+  - **logAUC** & **Optimal MCC** (Matthews Correlation Coefficient)
+- 🎲 **95% Stratified Bootstrap Confidence Intervals** for every metric.
+- 🔬 **Decoy Bias & Artificial Enrichment Audit**: Kolmogorov-Smirnov & Wasserstein property tests (MW, LogP, HBD, HBA).
+- 🚦 **Quality Certification Badges (`PASS` / `WARNING` / `FAIL`)**.
+- 📑 **Publication Deliverables**: Interactive self-contained `report.html`, vector plots (SVG/PDF/PNG 300 DPI), LaTeX summary tables (`.tex`), and a draft **Methods & Supporting Information** paragraph with automated **BibTeX citations**.
+- 🔌 **Engine Agnostic**: Works seamlessly with AutoDock Vina, Smina, GNINA, Schrödinger Glide, CCDC GOLD, DOCK, rDock, and generic CSV tables.
+
+```
+  Docking Results (.csv, .sdf, .pdbqt, logs)
+                     │
+                     ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                         DockCert                          │
+  │  ├── Redocking RMSD (Symmetry corrected)                  │
+  │  ├── Early Enrichment (BEDROC, RIE, EF1%, ROC-AUC)        │
+  │  ├── Stratified 95% Bootstrap Confidence Intervals        │
+  │  └── Decoy Bias Audit (MW, LogP KS-tests)                 │
+  └───────────────────────────────────────────────────────────┘
+                     │
+                     ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                   Publication Deliverables                │
+  │  ├── report.html (Interactive Dashboard & Badges)         │
+  │  ├── dockcert_validation_overview.pdf/svg/png             │
+  │  ├── dockcert_summary_table.tex / .csv                    │
+  │  ├── methods_snippet.txt (Ready for Manuscript)           │
+  │  └── citation.bib (BibTeX Reference)                      │
+  └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### From PyPI
+```bash
+pip install dockcert
+```
+
+### From Source
+```bash
+git clone https://github.com/sircalch/dockcert.git
+cd dockcert
+pip install -e .[dev]
+```
+
+---
+
+## Quickstart (CLI)
+
+### 1. Run Demonstration Mode (Instant Benchmark Dataset)
+```bash
+dockcert demo -o my_docking_validation/
+```
+Open `my_docking_validation/report.html` in your browser!
+
+### 2. Assess Virtual Screening CSV
+```bash
+dockcert assess -i screening_results.csv --score-col docking_score --label-col is_active -o validation_report/
+```
+
+### 3. Assess with Reference Ligand Pose RMSD
+```bash
+dockcert assess -i screening_results.csv --ref-ligand crystal_ligand.sdf --docked-pose docked_pose.sdf -o full_report/
+```
+
+---
+
+## Python API Usage
+
+```python
+import numpy as np
+from dockcert import assess_docking_quality
+from dockcert.reporters import generate_docking_figures, generate_docking_manuscript_assets, generate_docking_html_report
+
+# Screening scores (e.g. 50 actives, 1000 decoys)
+labels = np.array([1]*50 + [0]*1000)
+scores = np.concatenate([np.random.normal(-9.2, 0.8, 50), np.random.normal(-6.5, 1.1, 1000)])
+
+# Assess quality
+report = assess_docking_quality(
+    labels=labels,
+    scores=scores,
+    rmsd_values=[1.42, 1.85, 2.30],
+    lower_is_better=True
+)
+
+print(f"Overall Validation Status: {report.overall_status}")
+print(f"ROC-AUC: {report.enrichment_metrics['roc_auc'].value:.3f}")
+print(f"BEDROC (alpha=20.0): {report.enrichment_metrics['bedroc_20'].value:.3f}")
+print(f"EF 1%: {report.enrichment_metrics['ef_1pct'].value:.1f}x")
+
+# Export publication deliverables
+generate_docking_figures(labels, scores, report, "output_dir/")
+generate_docking_manuscript_assets(report, "output_dir/")
+generate_docking_html_report(report, "output_dir/report.html")
+```
+
+---
+
+## Citation
+
+If you use DockCert to evaluate molecular docking validation or virtual screening enrichment, please cite:
+
+```bibtex
+@software{monreal2026dockcert,
+  author = {Monreal-Hern{\'a}ndez, Andre},
+  title = {{DockCert: An Open-Source Toolkit for Statistical Validation, Enrichment Metrics, and Reproducibility Assessment of Molecular Docking Studies}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/dockcert}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+

dockcert-1.0.0/README.md

@@ -0,0 +1,145 @@
+# DockCert
+
+[![CI](https://github.com/sircalch/dockcert/actions/workflows/test.yml/badge.svg)](https://github.com/sircalch/dockcert/actions)
+[![PyPI version](https://img.shields.io/pypi/v/dockcert.svg?color=blue)](https://pypi.org/project/dockcert/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dockcert.svg)](https://pypi.org/project/dockcert/)
+[![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.1234568.svg)](https://doi.org/10.5281/zenodo.1234568)
+
+> **Automated Statistical Validation, Early Enrichment Metrics, and Reproducibility Assessment for Molecular Docking and Virtual Screening Studies.**
+
+---
+
+## Overview
+
+**DockCert** is an open-source scientific toolkit engineered to evaluate whether a molecular docking or virtual screening protocol is rigorously validated before publication.
+
+Instead of computing enrichment factors or pose RMSD across fragmented scripts, `dockcert` analyzes your screening results and docked structures in a single run:
+
+- 🎯 **Redocking & Cross-Docking Pose Accuracy**: Heavy-atom & symmetry-corrected RMSD (Hungarian algorithm).
+- 📈 **Early Enrichment Quantification**:
+  - **BEDROC** ($\alpha=20.0, 80.5, 160.9$)
+  - **RIE** (Robust Initial Enhancement)
+  - **EF1%**, **EF5%**, **EF10%** (Enrichment Factors)
+  - **ROC-AUC** & **PR-AUC** (Precision-Recall AUC)
+  - **logAUC** & **Optimal MCC** (Matthews Correlation Coefficient)
+- 🎲 **95% Stratified Bootstrap Confidence Intervals** for every metric.
+- 🔬 **Decoy Bias & Artificial Enrichment Audit**: Kolmogorov-Smirnov & Wasserstein property tests (MW, LogP, HBD, HBA).
+- 🚦 **Quality Certification Badges (`PASS` / `WARNING` / `FAIL`)**.
+- 📑 **Publication Deliverables**: Interactive self-contained `report.html`, vector plots (SVG/PDF/PNG 300 DPI), LaTeX summary tables (`.tex`), and a draft **Methods & Supporting Information** paragraph with automated **BibTeX citations**.
+- 🔌 **Engine Agnostic**: Works seamlessly with AutoDock Vina, Smina, GNINA, Schrödinger Glide, CCDC GOLD, DOCK, rDock, and generic CSV tables.
+
+```
+  Docking Results (.csv, .sdf, .pdbqt, logs)
+                     │
+                     ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                         DockCert                          │
+  │  ├── Redocking RMSD (Symmetry corrected)                  │
+  │  ├── Early Enrichment (BEDROC, RIE, EF1%, ROC-AUC)        │
+  │  ├── Stratified 95% Bootstrap Confidence Intervals        │
+  │  └── Decoy Bias Audit (MW, LogP KS-tests)                 │
+  └───────────────────────────────────────────────────────────┘
+                     │
+                     ▼
+  ┌───────────────────────────────────────────────────────────┐
+  │                   Publication Deliverables                │
+  │  ├── report.html (Interactive Dashboard & Badges)         │
+  │  ├── dockcert_validation_overview.pdf/svg/png             │
+  │  ├── dockcert_summary_table.tex / .csv                    │
+  │  ├── methods_snippet.txt (Ready for Manuscript)           │
+  │  └── citation.bib (BibTeX Reference)                      │
+  └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+### From PyPI
+```bash
+pip install dockcert
+```
+
+### From Source
+```bash
+git clone https://github.com/sircalch/dockcert.git
+cd dockcert
+pip install -e .[dev]
+```
+
+---
+
+## Quickstart (CLI)
+
+### 1. Run Demonstration Mode (Instant Benchmark Dataset)
+```bash
+dockcert demo -o my_docking_validation/
+```
+Open `my_docking_validation/report.html` in your browser!
+
+### 2. Assess Virtual Screening CSV
+```bash
+dockcert assess -i screening_results.csv --score-col docking_score --label-col is_active -o validation_report/
+```
+
+### 3. Assess with Reference Ligand Pose RMSD
+```bash
+dockcert assess -i screening_results.csv --ref-ligand crystal_ligand.sdf --docked-pose docked_pose.sdf -o full_report/
+```
+
+---
+
+## Python API Usage
+
+```python
+import numpy as np
+from dockcert import assess_docking_quality
+from dockcert.reporters import generate_docking_figures, generate_docking_manuscript_assets, generate_docking_html_report
+
+# Screening scores (e.g. 50 actives, 1000 decoys)
+labels = np.array([1]*50 + [0]*1000)
+scores = np.concatenate([np.random.normal(-9.2, 0.8, 50), np.random.normal(-6.5, 1.1, 1000)])
+
+# Assess quality
+report = assess_docking_quality(
+    labels=labels,
+    scores=scores,
+    rmsd_values=[1.42, 1.85, 2.30],
+    lower_is_better=True
+)
+
+print(f"Overall Validation Status: {report.overall_status}")
+print(f"ROC-AUC: {report.enrichment_metrics['roc_auc'].value:.3f}")
+print(f"BEDROC (alpha=20.0): {report.enrichment_metrics['bedroc_20'].value:.3f}")
+print(f"EF 1%: {report.enrichment_metrics['ef_1pct'].value:.1f}x")
+
+# Export publication deliverables
+generate_docking_figures(labels, scores, report, "output_dir/")
+generate_docking_manuscript_assets(report, "output_dir/")
+generate_docking_html_report(report, "output_dir/report.html")
+```
+
+---
+
+## Citation
+
+If you use DockCert to evaluate molecular docking validation or virtual screening enrichment, please cite:
+
+```bibtex
+@software{monreal2026dockcert,
+  author = {Monreal-Hern{\'a}ndez, Andre},
+  title = {{DockCert: An Open-Source Toolkit for Statistical Validation, Enrichment Metrics, and Reproducibility Assessment of Molecular Docking Studies}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/dockcert}
+}
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+

dockcert-1.0.0/dockcert/__init__.py

@@ -0,0 +1,46 @@
+"""
+DockCert: Automated Statistical Validation, Enrichment Metrics, and Reproducibility
+Assessment for Molecular Docking and Virtual Screening Studies.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Andre Monreal-Hernández"
+__license__ = "MIT"
+
+from dockcert.core.enrichment import (
+    calculate_roc_auc,
+    calculate_pr_auc,
+    calculate_bedroc,
+    calculate_rie,
+    calculate_enrichment_factor,
+    calculate_log_auc,
+    calculate_optimal_mcc,
+    evaluate_all_enrichment_metrics
+)
+from dockcert.core.rmsd import (
+    calculate_heavy_atom_rmsd,
+    calculate_symmetry_corrected_rmsd,
+    evaluate_redocking_success
+)
+from dockcert.core.bias import evaluate_decoy_bias
+from dockcert.core.bootstrap import bootstrap_enrichment_ci
+from dockcert.core.scoring import assess_docking_quality, DockingValidationReport
+
+__all__ = [
+    "__version__",
+    "calculate_roc_auc",
+    "calculate_pr_auc",
+    "calculate_bedroc",
+    "calculate_rie",
+    "calculate_enrichment_factor",
+    "calculate_log_auc",
+    "calculate_optimal_mcc",
+    "evaluate_all_enrichment_metrics",
+    "calculate_heavy_atom_rmsd",
+    "calculate_symmetry_corrected_rmsd",
+    "evaluate_redocking_success",
+    "evaluate_decoy_bias",
+    "bootstrap_enrichment_ci",
+    "assess_docking_quality",
+    "DockingValidationReport"
+]

dockcert-1.0.0/dockcert/cli.py

@@ -0,0 +1,241 @@
+"""
+Command Line Interface (CLI) for DockCert.
+"""
+
+import sys
+import os
+import argparse
+import numpy as np
+
+from dockcert import __version__
+from dockcert.parsers.generic_csv import load_docking_csv
+from dockcert.parsers.structure_io import load_molecule_coordinates
+from dockcert.core.rmsd import calculate_heavy_atom_rmsd, calculate_symmetry_corrected_rmsd
+from dockcert.core.scoring import assess_docking_quality
+from dockcert.reporters.plot_generator import generate_docking_figures
+from dockcert.reporters.manuscript_prep import generate_docking_manuscript_assets
+from dockcert.reporters.html_report import generate_docking_html_report
+
+
+def print_banner():
+    banner = rf"""
+  _____             _    _____          _   
+ |  __ \           | |  / ____|        | |  
+ | |  | | ___   ___| | _| |     ___ _ __| |_ 
+ | |  | |/ _ \ / __| |/ / |    / _ \ '__| __|
+ | |__| | (_) | (__|   <| |___|  __/ |  | |_ 
+ |_____/ \___/ \___|_|\_\\_____\___|_|   \__| v{__version__}
+
+ Molecular Docking Validation & Statistical Quality Toolkit
+ Monreal-Hernández et al., 2026
+"""
+    print(banner)
+
+
+def run_demo(output_dir: str = "dockcert_demo_output"):
+    """
+    Generates a realistic DUD-E-like benchmark dataset (100 actives, 2000 property-matched decoys,
+    redocking RMSD = 1.43 A) and executes the full validation pipeline.
+    """
+    print(f"\n[DockCert] Running demonstration mode...")
+    os.makedirs(output_dir, exist_ok=True)
+    
+    n_actives = 100
+    n_decoys = 2000
+    
+    rng = np.random.default_rng(42)
+    
+    # Active scores: N(-9.4 kcal/mol, 1.1)
+    active_scores = rng.normal(-9.4, 1.1, size=n_actives)
+    # Decoy scores: N(-6.8 kcal/mol, 1.2)
+    decoy_scores = rng.normal(-6.8, 1.2, size=n_decoys)
+    
+    labels = np.concatenate([np.ones(n_actives, dtype=int), np.zeros(n_decoys, dtype=int)])
+    scores = np.concatenate([active_scores, decoy_scores])
+    
+    # Redocking poses: Best RMSD = 1.43 A, ensemble of 9 poses
+    redocking_rmsds = [1.43, 1.78, 2.15, 2.40, 2.89, 3.10, 3.45, 4.12, 4.55]
+    
+    # Physicochemical properties for bias audit (MW & LogP)
+    active_mw = rng.normal(380.0, 45.0, size=n_actives)
+    decoy_mw = rng.normal(375.0, 50.0, size=n_decoys)
+    
+    active_logp = rng.normal(2.8, 0.7, size=n_actives)
+    decoy_logp = rng.normal(2.7, 0.8, size=n_decoys)
+    
+    active_props = {"MolecularWeight": active_mw, "LogP": active_logp}
+    decoy_props = {"MolecularWeight": decoy_mw, "LogP": decoy_logp}
+    
+    print("  -> Calculating ROC-AUC, PR-AUC, BEDROC (alpha=20.0), EF1%, EF5%, logAUC, and Bootstrap 95% CIs...")
+    report = assess_docking_quality(
+        labels=labels,
+        scores=scores,
+        rmsd_values=redocking_rmsds,
+        active_properties=active_props,
+        decoy_properties=decoy_props,
+        lower_is_better=True
+    )
+    
+    print("  -> Generating publication-quality vector charts (ROC, PR, Score distributions, RMSD)...")
+    generate_docking_figures(labels, scores, report, output_dir, lower_is_better=True, rmsd_values=redocking_rmsds)
+    
+    print("  -> Drafting manuscript Methods text snippet, summary LaTeX tables, and BibTeX citations...")
+    assets = generate_docking_manuscript_assets(report, output_dir)
+    
+    with open(assets["methods_text"], "r", encoding="utf-8") as f:
+        methods_txt = f.read()
+    with open(assets["citation_bib"], "r", encoding="utf-8") as f:
+        bib_txt = f.read()
+        
+    html_p = os.path.join(output_dir, "report.html")
+    print(f"  -> Writing interactive dashboard to {html_p}...")
+    generate_docking_html_report(report, html_p, methods_text=methods_txt, citation_bib=bib_txt)
+    
+    print("\n" + "="*70)
+    print(f" [RESULT] Overall Docking Certification: {report.overall_status}")
+    print(f" [SCORE]  {report.validation_score}")
+    print("="*70)
+    if report.redocking_result:
+        rr = report.redocking_result
+        print(f" * Redocking RMSD     : Best = {rr['min_rmsd']:.2f} A | Success Rate (<=2A) = {rr['success_rate_2a']:.1f}% | Status: {rr['status']}")
+    for k, item in report.enrichment_metrics.items():
+        ci_s = f"[{item.ci_lower_95:.2f}, {item.ci_upper_95:.2f}]" if item.ci_lower_95 is not None else ""
+        print(f" * {item.name:18s}: Value = {item.value:6.3f} {ci_s:14s} | Threshold = {item.threshold_pass:4.2f} | Status: {item.status}")
+    if report.decoy_bias_result:
+        print(f" * Decoy Bias Risk    : Level = {report.decoy_bias_result['risk_level']} | Status: {report.decoy_bias_result['status']}")
+    print("="*70)
+    print(f"\nAll outputs successfully saved to: {os.path.abspath(output_dir)}/")
+    print(f"Open {os.path.abspath(html_p)} in your browser to inspect the full report.\n")
+
+
+def run_assess(args):
+    """
+    Evaluates user-provided CSV and optional structure files.
+    """
+    output_dir = args.output
+    os.makedirs(output_dir, exist_ok=True)
+    
+    csv_file = args.input
+    if not csv_file:
+        print("[Error] Please specify a results CSV file with --input.", file=sys.stderr)
+        sys.exit(1)
+        
+    print(f"\n[DockCert] Loading docking screening dataset from {csv_file}...")
+    labels, scores, props_dict, meta = load_docking_csv(
+        csv_file,
+        score_column=args.score_col,
+        label_column=args.label_col
+    )
+    print(f"  -> Identified {meta['n_total']} entries: {meta['n_actives']} actives, {meta['n_decoys']} decoys.")
+    
+    # RMSD from structures if provided
+    rmsd_values = None
+    if args.ref_ligand and args.docked_pose:
+        print("  -> Calculating heavy-atom RMSD between reference and docked pose...")
+        c_ref, el_ref = load_molecule_coordinates(args.ref_ligand)
+        c_dock, el_dock = load_molecule_coordinates(args.docked_pose)
+        rmsd_val = calculate_symmetry_corrected_rmsd(c_ref, c_dock, elements=el_ref)
+        rmsd_values = [rmsd_val]
+        print(f"  -> Calculated Redocking RMSD: {rmsd_val:.2f} A")
+        
+    print("  -> Performing statistical validation and enrichment analysis...")
+    report = assess_docking_quality(
+        labels=labels,
+        scores=scores,
+        rmsd_values=rmsd_values,
+        lower_is_better=not args.higher_is_better
+    )
+    
+    print("  -> Generating publication charts...")
+    generate_docking_figures(labels, scores, report, output_dir, lower_is_better=not args.higher_is_better, rmsd_values=rmsd_values)
+    
+    print("  -> Generating manuscript text, LaTeX summary table, and BibTeX citations...")
+    assets = generate_docking_manuscript_assets(report, output_dir)
+    
+    with open(assets["methods_text"], "r", encoding="utf-8") as f:
+        methods_txt = f.read()
+    with open(assets["citation_bib"], "r", encoding="utf-8") as f:
+        bib_txt = f.read()
+        
+    html_p = os.path.join(output_dir, "report.html")
+    print(f"  -> Writing HTML quality report to {html_p}...")
+    generate_docking_html_report(report, html_p, methods_text=methods_txt, citation_bib=bib_txt)
+    
+    print("\n" + "="*70)
+    print(f" [RESULT] Overall Docking Certification: {report.overall_status}")
+    print(f" [SCORE]  {report.validation_score}")
+    print("="*70)
+    for k, item in report.enrichment_metrics.items():
+        print(f" * {item.name:18s}: {item.value:6.3f} | Status: {item.status}")
+    if report.redocking_result:
+        print(f" * Redocking RMSD     : {report.redocking_result['min_rmsd']:.2f} A | Status: {report.redocking_result['status']}")
+    print("="*70)
+    print(f"\nReport ready at: {os.path.abspath(html_p)}\n")
+
+
+def print_citation():
+    bib = """@software{monreal2026dockcert,
+  author = {Monreal-Hern\\'andez, Andre},
+  title = {{DockCert: An Open-Source Toolkit for Statistical Validation, Enrichment Metrics, and Reproducibility Assessment of Molecular Docking Studies}},
+  year = {2026},
+  version = {1.0.0},
+  publisher = {Zenodo},
+  url = {https://github.com/sircalch/dockcert}
+}"""
+    print("\nIf you use DockCert in your publications, please cite:\n")
+    print("APA Style:")
+    print("Monreal-Hernández, A. (2026). DockCert: An Open-Source Toolkit for Statistical Validation, Enrichment Metrics, and Reproducibility Assessment of Molecular Docking Studies (v1.0.0). Zenodo. https://github.com/sircalch/dockcert\n")
+    print("BibTeX:")
+    print(bib)
+    print()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="dockcert",
+        description="DockCert: Automated Statistical Validation, Enrichment Metrics, and Reproducibility Toolkit for Molecular Docking."
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"dockcert {__version__}")
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+    
+    # Assess command
+    assess_parser = subparsers.add_parser("assess", help="Assess virtual screening enrichment and docking accuracy")
+    assess_parser.add_argument("-i", "--input", required=True, help="Virtual screening results file (.csv, .tsv, .txt)")
+    assess_parser.add_argument("--score-col", help="Column name containing docking scores/affinities")
+    assess_parser.add_argument("--label-col", help="Column name containing active/decoy labels")
+    assess_parser.add_argument("--ref-ligand", help="Reference crystallographic ligand structure (.sdf, .pdb, .pdbqt)")
+    assess_parser.add_argument("--docked-pose", help="Docked pose structure (.sdf, .pdb, .pdbqt)")
+    assess_parser.add_argument("--higher-is-better", action="store_true", help="Set if higher score values indicate better affinity")
+    assess_parser.add_argument("-o", "--output", default="dockcert_output", help="Directory for output report and assets (default: dockcert_output)")
+    
+    # Demo command
+    demo_parser = subparsers.add_parser("demo", help="Run DockCert on a benchmark DUD-E-like simulation dataset")
+    demo_parser.add_argument("-o", "--output", default="dockcert_demo_output", help="Output directory (default: dockcert_demo_output)")
+    
+    # Cite command
+    subparsers.add_parser("cite", help="Display BibTeX and APA citation details")
+    
+    if len(sys.argv) == 1:
+        print_banner()
+        parser.print_help()
+        sys.exit(0)
+        
+    args = parser.parse_args()
+    
+    if args.command == "assess":
+        print_banner()
+        run_assess(args)
+    elif args.command == "demo":
+        print_banner()
+        run_demo(args.output)
+    elif args.command == "cite":
+        print_banner()
+        print_citation()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()
+

dockcert-1.0.0/dockcert/core/__init__.py

@@ -0,0 +1,40 @@
+"""
+Core mathematical and validation algorithms for DockCert.
+"""
+
+from dockcert.core.enrichment import (
+    calculate_roc_auc,
+    calculate_pr_auc,
+    calculate_bedroc,
+    calculate_rie,
+    calculate_enrichment_factor,
+    calculate_log_auc,
+    calculate_optimal_mcc,
+    evaluate_all_enrichment_metrics
+)
+from dockcert.core.rmsd import (
+    calculate_heavy_atom_rmsd,
+    calculate_symmetry_corrected_rmsd,
+    evaluate_redocking_success
+)
+from dockcert.core.bias import evaluate_decoy_bias
+from dockcert.core.bootstrap import bootstrap_enrichment_ci
+from dockcert.core.scoring import assess_docking_quality, DockingValidationReport
+
+__all__ = [
+    "calculate_roc_auc",
+    "calculate_pr_auc",
+    "calculate_bedroc",
+    "calculate_rie",
+    "calculate_enrichment_factor",
+    "calculate_log_auc",
+    "calculate_optimal_mcc",
+    "evaluate_all_enrichment_metrics",
+    "calculate_heavy_atom_rmsd",
+    "calculate_symmetry_corrected_rmsd",
+    "evaluate_redocking_success",
+    "evaluate_decoy_bias",
+    "bootstrap_enrichment_ci",
+    "assess_docking_quality",
+    "DockingValidationReport"
+]