Add per-run provenance manifests and a dataset-level QC/completion report

Both use data that already existed in scattered form (requirements.txt,
environment_lock.txt, per-run output files) -- nothing here is invented.

- New Automation_code/provenance.py: build_manifest()/write_run_manifest()
  record receptor, ligand, seeds, docking parameters, actual runtime tool
  versions (vina --version / obabel -V queried live, not just the static
  lock file), Python version, a UTC timestamp, and SHA-256 hashes of the
  input/output files involved. Hashing a missing file returns None rather
  than raising, so a manifest can still be written for a run that failed
  partway through.

- dataset/code.py's main() now writes run_manifest.json into each
  docking_N/ run directory alongside the existing log.txt/pose_analysis.csv,
  for every run it actually executes (the existing analysis_csv-exists skip
  for already-completed runs is unchanged, so resuming a partial batch does
  not retroactively manifest earlier runs from a prior invocation).

- New collect_qc_data()/write_qc_report() in dataset/code.py aggregate the
  existing per-run completion state (same on-disk layout main() already
  writes) into one checkable statistic, e.g. '480/480 pairs completed
  (1440/1440 individual docking runs)', plus a per-pair list of anything
  incomplete. Written to OUTPUT_ROOT/qc_report.json. This is a pure,
  post-hoc, read-only aggregation over existing output files -- it does not
  change main()'s control flow or its existing resumability behaviour.

- cli.py's 'run' subcommand writes an equivalent run-level manifest
  (receptor/ligands/seeds/params/tool versions) after docking completes;
  'batch' now calls write_qc_report() after master_organizer().

11 new tests (7 for provenance.py, 4 for the QC report, all against
synthetic fixtures/tmp_path layouts -- no network, no Vina, no Open Babel
required). Full suite: 60 passed, 1 skipped (obabel not installed in this
environment, pre-existing/expected skip).

Author: ODOR-SIG

code/Automation_code/provenance.py

@@ -0,0 +1,120 @@
+"""Per-run provenance manifest generation.
+
+Makes "reproducible" a demonstrated, per-run, machine-readable fact rather
+than only an assertion in the manuscript: for a given docking run, this
+records exactly what produced it -- tool versions actually present on the
+machine that ran it (not just the static, project-level requirements.txt /
+environment_lock.txt), the seeds and parameters used, timestamps, and file
+paths/hashes of the inputs and outputs involved.
+
+Every field here is either already known to the caller (receptor/ligand
+names, seeds, docking parameters, file paths) or trivially queryable from the
+running environment (tool --version output, the Python interpreter version,
+a file's own SHA-256) -- nothing here is invented or inferred.
+"""
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+
+def _tool_version(cmd_args, timeout=10):
+    """Run e.g. ['vina', '--version'] and return the first non-empty line of
+    its combined stdout+stderr, or None if the executable isn't found or
+    doesn't respond in time. Never raises."""
+    try:
+        result = subprocess.run(
+            cmd_args, capture_output=True, text=True, timeout=timeout
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    combined = (result.stdout or "") + (result.stderr or "")
+    for line in combined.splitlines():
+        if line.strip():
+            return line.strip()
+    return None
+
+
+def _sha256_of_file(path, chunk_size=1 << 20):
+    """SHA-256 of a file's contents, or None if the file doesn't exist or
+    can't be read (e.g. a run that failed before writing that output)."""
+    if not path or not os.path.isfile(path):
+        return None
+    digest = hashlib.sha256()
+    try:
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(chunk_size), b""):
+                digest.update(chunk)
+    except OSError:
+        return None
+    return digest.hexdigest()
+
+
+def build_manifest(
+    receptor,
+    ligand,
+    seeds,
+    input_files=None,
+    output_files=None,
+    docking_params=None,
+    vina_exe="vina",
+    obabel_exe="obabel",
+    extra=None,
+):
+    """Build a provenance manifest dict for one receptor-ligand docking run.
+
+    Args:
+        receptor: receptor identifier (e.g. "OR7D4").
+        ligand: ligand identifier (e.g. "Androstenone").
+        seeds: the seed(s) actually used for this run (list of ints, or a
+            single int for a one-seed run).
+        input_files: optional {label: path} of input files to hash
+            (e.g. {"receptor_pdbqt": ..., "ligand_pdbqt": ..., "config": ...}).
+        output_files: optional {label: path} of output files to hash
+            (e.g. {"docked_pdbqt": ..., "log": ...}).
+        docking_params: optional dict of docking parameters actually used
+            (exhaustiveness, num_modes, energy_range, etc.) -- recorded
+            verbatim, not recomputed or validated here.
+        vina_exe: the Vina executable/path actually configured for this run
+            (so the manifest reflects what would really execute, matching
+            config.py's ODORSIG_VINA_EXE convention).
+        obabel_exe: same, for Open Babel.
+        extra: optional dict of any additional caller-supplied fields.
+
+    Returns:
+        A JSON-serialisable dict. Does not write anything to disk --
+        see write_run_manifest() for that.
+    """
+    manifest = {
+        "receptor": receptor,
+        "ligand": ligand,
+        "seeds": seeds,
+        "timestamp_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "python_version": sys.version.split()[0],
+        "vina_version": _tool_version([vina_exe, "--version"]),
+        "obabel_version": _tool_version([obabel_exe, "-V"]),
+        "docking_params": docking_params or {},
+        "input_files": {
+            label: {"path": path, "sha256": _sha256_of_file(path)}
+            for label, path in (input_files or {}).items()
+        },
+        "output_files": {
+            label: {"path": path, "sha256": _sha256_of_file(path)}
+            for label, path in (output_files or {}).items()
+        },
+    }
+    if extra:
+        manifest["extra"] = extra
+    return manifest
+
+
+def write_run_manifest(manifest_path, **kwargs):
+    """Build a manifest (see build_manifest() for kwargs) and write it as
+    indented JSON to manifest_path. Returns the manifest dict."""
+    manifest = build_manifest(**kwargs)
+    with open(manifest_path, "w") as f:
+        json.dump(manifest, f, indent=2)
+        f.write("\n")
+    return manifest

code/cli.py

@@ -22,6 +22,7 @@
 This CLI does not introduce a second configuration mechanism.
 """
 import argparse
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -44,6 +45,7 @@ def _cmd_run(args):
     from Automation_code.Step_03_prepare_receptor_ligand import prepare_receptor_and_ligands
     from Automation_code.Step_04_config_file import create_all_configs_for_receptor
     from Automation_code.Step_05_docking import run_all_dockings_for_receptor
+    from Automation_code.provenance import write_run_manifest
 
     ligands = [l.strip() for l in args.ligands.split(",") if l.strip()]
     seed_list = args.seed if args.seed else None  # None -> random-seed mode, matching app.py
@@ -79,6 +81,29 @@ def _cmd_run(args):
         args.receptor, config.PREPARED_MODELS_DIR, seed_list
     )
     print(result)
+
+    # Run-level provenance manifest. run_all_dockings_for_receptor() writes
+    # its own per-seed log/output files directly (not returned as a
+    # structured list), so this records the run as a whole -- receptor,
+    # ligands, seeds/params actually used, and tool versions on this
+    # machine -- rather than per-individual-file hashes as dataset/code.py's
+    # batch path does; see Automation_code/provenance.py.
+    manifest_dir = os.path.join(config.DOCKING_OUTPUT_DIR, f"{args.receptor}_folder")
+    os.makedirs(manifest_dir, exist_ok=True)
+    write_run_manifest(
+        os.path.join(manifest_dir, "run_manifest.json"),
+        receptor=args.receptor,
+        ligand=",".join(ligands),
+        seeds=seed_list if seed_list is not None else "random",
+        docking_params={
+            "exhaustiveness": args.exhaustiveness,
+            "num_modes": args.num_modes,
+            "energy_range": args.energy_range,
+        },
+        vina_exe=os.environ.get("ODORSIG_VINA_EXE", "vina"),
+        obabel_exe=os.environ.get("ODORSIG_OBABEL_PATH", "obabel"),
+        extra={"result_summary": result},
+    )
     return 0
 
 
@@ -108,6 +133,7 @@ def _cmd_batch(args):
 
     dataset_module.main()
     dataset_module.master_organizer()
+    dataset_module.write_qc_report()
     return 0
 
 

dataset/code.py

@@ -1,5 +1,6 @@
 import os
 import time
+import json
 import requests
 import subprocess
 import glob
@@ -15,6 +16,7 @@
 from Automation_code.reproducibility import reproducibility_stats
 from Automation_code.receptor_ligand_prep import extract_chain_a, convert_to_pdbqt
 from Automation_code.Step_04_config_file import generate_blind_config
+from Automation_code.provenance import write_run_manifest
 from Bio import Entrez
 from bs4 import BeautifulSoup
 from selenium import webdriver
@@ -439,6 +441,36 @@ def main():
                             aff = affinities[i] if i < len(affinities) else "N/A"
                             f.write(f"{i+1},{aff},{res['h_bonds']},{res['hydrophobic']}\n")
 
+                # Per-run provenance manifest -- what actually produced this
+                # run's output, machine-readable and checkable, not just
+                # asserted in the manuscript. Written whenever a run
+                # attempted docking (out_pdbqt path is known either way);
+                # file hashes come back None for anything that didn't get
+                # produced, which is itself informative rather than an error.
+                write_run_manifest(
+                    os.path.join(run_dir, "run_manifest.json"),
+                    receptor=rec_name,
+                    ligand=lig_name,
+                    seeds=seed,
+                    docking_params={
+                        "exhaustiveness": EXHAUSTIVENESS,
+                        "num_modes": NUM_POSES,
+                        "energy_range": ENERGY_RANGE,
+                    },
+                    input_files={
+                        "receptor_pdbqt": rec_pdbqt,
+                        "ligand_pdbqt": lig_pdbqt,
+                        "config": config_file,
+                    },
+                    output_files={
+                        "docked_pdbqt": out_pdbqt,
+                        "log": log_file,
+                        "analysis_csv": analysis_csv,
+                    },
+                    vina_exe=VINA_PATH,
+                    obabel_exe=OBABEL_PATH,
+                )
+
             print(f"✅ Row {index+1} Finished.")
         else:
             print(f"🛑 Error preparing inputs for Row {index+1}.")
@@ -585,6 +617,77 @@ def master_organizer():
     print(f"✅ Master Excel created: {os.path.abspath(final_excel_name)}")
 
 
+def collect_qc_data():
+    """Aggregate per-pair, per-run completion status from OUTPUT_ROOT into a
+    single, checkable record -- e.g. "480/480 pairs completed (1440/1440
+    individual docking runs)" -- rather than requiring a reviewer (or the
+    authors) to manually count output folders. Reads the same on-disk layout
+    main() already writes (pair_folder/docking_N/pose_analysis.csv); does not
+    change what main() writes or how it decides to skip already-completed
+    runs.
+
+    Returns a dict; use write_qc_report() to also persist it to disk.
+    """
+    qc = {
+        "requested_pairs": 0,
+        "expected_runs_per_pair": len(DOCKING_SEEDS),
+        "completed_pairs": 0,
+        "completed_runs": 0,
+        "requested_runs": 0,
+        "incomplete_pairs": [],
+    }
+    if not os.path.exists(EXCEL_FILE):
+        qc["completion_summary"] = f"Pair list not found at {EXCEL_FILE}; nothing to report."
+        return qc
+
+    df = pd.read_excel(EXCEL_FILE)
+    qc["requested_pairs"] = len(df)
+
+    for _, row in df.iterrows():
+        rec_name = str(row["Receptor"]).strip()
+        lig_name = str(row["Ligand"]).strip()
+        pair_folder = os.path.join(OUTPUT_ROOT, f"{rec_name}_{lig_name}")
+
+        completed_runs_this_pair = 0
+        for run_num in range(1, len(DOCKING_SEEDS) + 1):
+            qc["requested_runs"] += 1
+            analysis_csv = os.path.join(pair_folder, f"docking_{run_num}", "pose_analysis.csv")
+            if os.path.exists(analysis_csv):
+                completed_runs_this_pair += 1
+                qc["completed_runs"] += 1
+
+        if completed_runs_this_pair == len(DOCKING_SEEDS):
+            qc["completed_pairs"] += 1
+        else:
+            qc["incomplete_pairs"].append({
+                "receptor": rec_name,
+                "ligand": lig_name,
+                "completed_runs": completed_runs_this_pair,
+                "expected_runs": len(DOCKING_SEEDS),
+            })
+
+    qc["completion_summary"] = (
+        f"{qc['completed_pairs']}/{qc['requested_pairs']} pairs completed "
+        f"({qc['completed_runs']}/{qc['requested_runs']} individual docking runs)"
+    )
+    return qc
+
+
+def write_qc_report(path=None):
+    """Write collect_qc_data()'s result to OUTPUT_ROOT/qc_report.json (or a
+    caller-supplied path) as indented JSON, and print the one-line summary."""
+    qc = collect_qc_data()
+    report_path = path or os.path.join(OUTPUT_ROOT, "qc_report.json")
+    os.makedirs(os.path.dirname(report_path) or ".", exist_ok=True)
+    with open(report_path, "w") as f:
+        json.dump(qc, f, indent=2)
+        f.write("\n")
+    print(f"📋 {qc['completion_summary']}")
+    print(f"   QC report saved to: {report_path}")
+    return qc
+
+
 if __name__ == "__main__":
     main()
     master_organizer()
+    write_qc_report()

tests/test_provenance.py

@@ -0,0 +1,92 @@
+"""Unit tests for Automation_code.provenance -- per-run manifest generation.
+
+Pure Python, no network. Tool-version lookups use the real `python`/a
+guaranteed-missing executable rather than mocking subprocess, so the
+"tool not found" path is exercised for real, not just asserted.
+"""
+import hashlib
+import json
+import os
+import sys
+
+from Automation_code.provenance import build_manifest, write_run_manifest, _sha256_of_file, _tool_version
+
+
+def test_tool_version_returns_first_nonempty_line_for_a_real_executable():
+    version = _tool_version([sys.executable, "--version"])
+    assert version is not None
+    assert "Python" in version
+
+
+def test_tool_version_returns_none_for_missing_executable():
+    assert _tool_version(["definitely-not-a-real-executable-xyz"]) is None
+
+
+def test_sha256_of_file_matches_hashlib_reference(tmp_path):
+    f = tmp_path / "sample.txt"
+    f.write_bytes(b"OdorSig provenance test content")
+    expected = hashlib.sha256(b"OdorSig provenance test content").hexdigest()
+    assert _sha256_of_file(str(f)) == expected
+
+
+def test_sha256_of_file_returns_none_for_missing_file():
+    assert _sha256_of_file("/nonexistent/path/does-not-exist.pdbqt") is None
+    assert _sha256_of_file(None) is None
+
+
+def test_build_manifest_records_receptor_ligand_seeds_and_params():
+    manifest = build_manifest(
+        receptor="OR7D4",
+        ligand="Androstenone",
+        seeds=[101, 102, 103],
+        docking_params={"exhaustiveness": 8, "num_modes": 10, "energy_range": 3},
+        vina_exe="definitely-not-installed",
+        obabel_exe="definitely-not-installed",
+    )
+    assert manifest["receptor"] == "OR7D4"
+    assert manifest["ligand"] == "Androstenone"
+    assert manifest["seeds"] == [101, 102, 103]
+    assert manifest["docking_params"] == {"exhaustiveness": 8, "num_modes": 10, "energy_range": 3}
+    assert manifest["vina_version"] is None  # executable genuinely not found
+    assert "timestamp_utc" in manifest
+    assert manifest["python_version"] == sys.version.split()[0]
+
+
+def test_build_manifest_hashes_input_and_output_files(tmp_path):
+    receptor_file = tmp_path / "receptor.pdbqt"
+    receptor_file.write_text("dummy receptor content")
+
+    manifest = build_manifest(
+        receptor="OR7D4", ligand="Androstenone", seeds=[101],
+        input_files={"receptor_pdbqt": str(receptor_file)},
+        output_files={"docked_pdbqt": str(tmp_path / "does_not_exist.pdbqt")},
+    )
+    assert manifest["input_files"]["receptor_pdbqt"]["path"] == str(receptor_file)
+    assert manifest["input_files"]["receptor_pdbqt"]["sha256"] == hashlib.sha256(
+        b"dummy receptor content"
+    ).hexdigest()
+    # Output file doesn't exist yet (e.g. a run that hasn't completed) -- no hash, no crash.
+    assert manifest["output_files"]["docked_pdbqt"]["sha256"] is None
+
+
+def test_write_run_manifest_writes_valid_json(tmp_path):
+    manifest_path = tmp_path / "run_manifest.json"
+    returned = write_run_manifest(
+        str(manifest_path), receptor="OR1A1", ligand="Citral", seeds=[100, 200, 300],
+    )
+    assert manifest_path.is_file()
+    on_disk = json.loads(manifest_path.read_text())
+    assert on_disk == returned
+    assert on_disk["receptor"] == "OR1A1"
+
+
+def test_manifest_is_json_serialisable_end_to_end(tmp_path):
+    """Guards against accidentally putting a non-JSON-serialisable value
+    (e.g. a raw datetime object) into the manifest."""
+    manifest_path = tmp_path / "run_manifest.json"
+    write_run_manifest(
+        str(manifest_path), receptor="OR3A3", ligand="Vanillin", seeds=100,
+        extra={"note": "single random-seed run"},
+    )
+    with open(manifest_path) as f:
+        json.load(f)  # raises if the file isn't valid JSON