dockcert 1.0.0__py3-none-any.whl

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/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/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"
+]

dockcert/core/bias.py

@@ -0,0 +1,85 @@
+"""
+Decoy bias and physicochemical property distribution diagnostics.
+"""
+
+from typing import Dict, Any, Optional
+import numpy as np
+from scipy import stats
+
+
+def evaluate_decoy_bias(
+    active_properties: Dict[str, np.ndarray],
+    decoy_properties: Dict[str, np.ndarray]
+) -> Dict[str, Any]:
+    """
+    Evaluates potential artificial enrichment bias by comparing property distributions
+    (e.g., MW, LogP, HBD, HBA, Rotatable Bonds) between actives and decoys.
+
+    Parameters
+    ----------
+    active_properties : dict
+        Mapping of property name -> 1D array for active molecules.
+    decoy_properties : dict
+        Mapping of property name -> 1D array for decoy molecules.
+
+    Returns
+    -------
+    result : dict
+        Property-by-property Kolmogorov-Smirnov and Wasserstein statistics,
+        bias risk classification (LOW / MODERATE / HIGH), and recommendations.
+    """
+    common_props = set(active_properties.keys()).intersection(set(decoy_properties.keys()))
+    if not common_props:
+        return {
+            "status": "PASS",
+            "risk_level": "LOW",
+            "properties_evaluated": 0,
+            "property_metrics": {},
+            "recommendation": "No property metadata provided for decoy bias auditing. Ensure decoys are property-matched."
+        }
+        
+    property_metrics = {}
+    ks_pvalues = []
+    
+    for prop in common_props:
+        a_vals = np.asarray(active_properties[prop], dtype=float)
+        d_vals = np.asarray(decoy_properties[prop], dtype=float)
+        
+        if len(a_vals) < 2 or len(d_vals) < 2:
+            continue
+            
+        ks_res = stats.ks_2samp(a_vals, d_vals)
+        w_dist = stats.wasserstein_distance(a_vals, d_vals)
+        
+        property_metrics[prop] = {
+            "active_mean": float(np.mean(a_vals)),
+            "decoy_mean": float(np.mean(d_vals)),
+            "ks_statistic": float(ks_res.statistic),
+            "ks_pvalue": float(ks_res.pvalue),
+            "wasserstein_distance": float(w_dist)
+        }
+        ks_pvalues.append(ks_res.pvalue)
+
+    # If KS p-value is extremely low (< 1e-4) across multiple physical properties, decoys are poorly matched
+    significant_biases = sum(1 for p in ks_pvalues if p < 0.001)
+    
+    if significant_biases == 0:
+        risk_level = "LOW"
+        status = "PASS"
+        recommendation = "Decoys and actives are well property-matched. Low risk of artificial enrichment bias."
+    elif significant_biases <= 2:
+        risk_level = "MODERATE"
+        status = "WARNING"
+        recommendation = "Moderate distributional discrepancy observed in physicochemical properties between actives and decoys."
+    else:
+        risk_level = "HIGH"
+        status = "WARNING"
+        recommendation = "High risk of decoy bias: actives and decoys differ significantly in physical properties (e.g. MW, LogP). Enrichment may be artificially inflated."
+
+    return {
+        "status": status,
+        "risk_level": risk_level,
+        "properties_evaluated": len(property_metrics),
+        "property_metrics": property_metrics,
+        "recommendation": recommendation
+    }

dockcert/core/bootstrap.py

@@ -0,0 +1,111 @@
+"""
+Stratified bootstrap confidence interval estimation for virtual screening metrics.
+"""
+
+from typing import Dict, Any, Tuple, Optional
+import numpy as np
+from dockcert.core.enrichment import (
+    calculate_roc_auc,
+    calculate_pr_auc,
+    calculate_bedroc,
+    calculate_enrichment_factor
+)
+
+
+def bootstrap_enrichment_ci(
+    labels: np.ndarray,
+    scores: np.ndarray,
+    n_resamples: int = 1000,
+    confidence_level: float = 0.95,
+    lower_is_better: bool = True,
+    random_state: Optional[int] = 42
+) -> Dict[str, Tuple[float, float, float]]:
+    """
+    Computes stratified non-parametric bootstrap 95% Confidence Intervals for all key metrics.
+
+    Parameters
+    ----------
+    labels : np.ndarray
+        Binary label array (1 = Active, 0 = Decoy).
+    scores : np.ndarray
+        Docking scores.
+    n_resamples : int, default 1000
+        Number of bootstrap iterations.
+    confidence_level : float, default 0.95
+        Confidence level.
+    lower_is_better : bool
+        Sorting direction.
+    random_state : int, optional
+        Seed for reproducibility.
+
+    Returns
+    -------
+    ci_dict : dict
+        Mapping metric_name -> (point_estimate, ci_lower, ci_upper).
+    """
+    y_true = np.asarray(labels, dtype=int)
+    y_scores = np.asarray(scores, dtype=float)
+    
+    active_idx = np.where(y_true == 1)[0]
+    decoy_idx = np.where(y_true == 0)[0]
+    
+    n_act = len(active_idx)
+    n_dec = len(decoy_idx)
+    
+    if n_act == 0 or n_dec == 0:
+        return {}
+        
+    rng = np.random.default_rng(random_state)
+    
+    # Point estimates
+    pe_roc = calculate_roc_auc(y_true, y_scores, lower_is_better)
+    pe_pr = calculate_pr_auc(y_true, y_scores, lower_is_better)
+    pe_bedroc20 = calculate_bedroc(y_true, y_scores, alpha=20.0, lower_is_better=lower_is_better)
+    pe_bedroc80 = calculate_bedroc(y_true, y_scores, alpha=80.5, lower_is_better=lower_is_better)
+    pe_ef1, _ = calculate_enrichment_factor(y_true, y_scores, fraction=0.01, lower_is_better=lower_is_better)
+    pe_ef5, _ = calculate_enrichment_factor(y_true, y_scores, fraction=0.05, lower_is_better=lower_is_better)
+    pe_ef10, _ = calculate_enrichment_factor(y_true, y_scores, fraction=0.10, lower_is_better=lower_is_better)
+    
+    boot_roc = np.empty(n_resamples, dtype=float)
+    boot_pr = np.empty(n_resamples, dtype=float)
+    boot_bedroc20 = np.empty(n_resamples, dtype=float)
+    boot_bedroc80 = np.empty(n_resamples, dtype=float)
+    boot_ef1 = np.empty(n_resamples, dtype=float)
+    boot_ef5 = np.empty(n_resamples, dtype=float)
+    boot_ef10 = np.empty(n_resamples, dtype=float)
+    
+    for b in range(n_resamples):
+        sample_act = rng.choice(active_idx, size=n_act, replace=True)
+        sample_dec = rng.choice(decoy_idx, size=n_dec, replace=True)
+        
+        sample_idx = np.concatenate([sample_act, sample_dec])
+        b_labels = y_true[sample_idx]
+        b_scores = y_scores[sample_idx]
+        
+        boot_roc[b] = calculate_roc_auc(b_labels, b_scores, lower_is_better)
+        boot_pr[b] = calculate_pr_auc(b_labels, b_scores, lower_is_better)
+        boot_bedroc20[b] = calculate_bedroc(b_labels, b_scores, alpha=20.0, lower_is_better=lower_is_better)
+        boot_bedroc80[b] = calculate_bedroc(b_labels, b_scores, alpha=80.5, lower_is_better=lower_is_better)
+        ef1, _ = calculate_enrichment_factor(b_labels, b_scores, fraction=0.01, lower_is_better=lower_is_better)
+        ef5, _ = calculate_enrichment_factor(b_labels, b_scores, fraction=0.05, lower_is_better=lower_is_better)
+        ef10, _ = calculate_enrichment_factor(b_labels, b_scores, fraction=0.10, lower_is_better=lower_is_better)
+        boot_ef1[b] = ef1
+        boot_ef5[b] = ef5
+        boot_ef10[b] = ef10
+        
+    alpha_ci = (1.0 - confidence_level) / 2.0
+    
+    def get_ci(point_est, boot_arr):
+        low = float(np.percentile(boot_arr, 100.0 * alpha_ci))
+        high = float(np.percentile(boot_arr, 100.0 * (1.0 - alpha_ci)))
+        return float(point_est), low, high
+
+    return {
+        "roc_auc": get_ci(pe_roc, boot_roc),
+        "pr_auc": get_ci(pe_pr, boot_pr),
+        "bedroc_20": get_ci(pe_bedroc20, boot_bedroc20),
+        "bedroc_80": get_ci(pe_bedroc80, boot_bedroc80),
+        "ef_1pct": get_ci(pe_ef1, boot_ef1),
+        "ef_5pct": get_ci(pe_ef5, boot_ef5),
+        "ef_10pct": get_ci(pe_ef10, boot_ef10)
+    }