core-score 0.4.0__py3-none-any.whl

core_score/__init__.py

@@ -0,0 +1,8 @@
+"""CORE Score: agreement within an ensemble of predicted protein-ligand poses."""
+
+from core_score.pipeline import run
+from core_score.analysis.core import core_score as score
+
+__version__ = "0.4.0"
+
+__all__ = ["run", "score"]

core_score/__main__.py

@@ -0,0 +1,3 @@
+from core_score.cli import main
+
+raise SystemExit(main())

core_score/analysis/__init__.py

@@ -0,0 +1 @@
+"""Check, compare and score the prepared poses."""

core_score/analysis/core.py

@@ -0,0 +1,61 @@
+"""Build each site ensemble's RMSD matrix and calculate CORE at each threshold."""
+
+import itertools
+import numpy as np
+from core_score.outputs.files import diagnostic
+
+NEIGHBOURS = 3  # each pose is scored against its three closest other poses
+
+
+def score_groups(groups, rows, thresholds=(2.0,)):
+    """One score per site ensemble and threshold T. An ensemble with a missing or failed pair is not scored."""
+    scores = []
+    for group in groups:
+        ids = [pose["pose_id"] for pose in group["poses"]]
+        values, error = dict.fromkeys(thresholds), group.get("error")
+        if not error:
+            try:
+                key = (group["ensemble"], group["site"])
+                matrix = build_matrix(ids, [r for r in rows if (r["ensemble"], r["site"]) == key])
+                values = {threshold: core_score(matrix, threshold) for threshold in thresholds}
+            except ValueError as exc:
+                error = diagnostic("scoring", exc)
+        scores += [
+            dict(ensemble=group["ensemble"], site=group["site"], name=group["name"], pose_count=len(ids), threshold_angstrom=threshold,
+                 core_score=value, error=error["error"] if error else None)
+            for threshold, value in values.items()
+        ]
+    return scores
+
+
+def build_matrix(pose_ids, rows):
+    """Pairwise ligand-RMSD matrix. Raises unless every pair has exactly one usable RMSD;
+    a missing or failed comparison is never filled in."""
+    index = {pose_id: i for i, pose_id in enumerate(pose_ids)}
+    matrix = np.full((len(pose_ids), len(pose_ids)), np.nan)
+    np.fill_diagonal(matrix, 0.0)
+    for row in rows:
+        if row["n_assigned"] == 1 and not row["error"]:
+            i, j = index[row["pose_i"]], index[row["pose_j"]]
+            matrix[i, j] = matrix[j, i] = row["rmsd"]
+    missing = [(a, b) for (i, a), (j, b) in itertools.combinations(enumerate(pose_ids), 2)
+               if not np.isfinite(matrix[i, j])]
+    if missing:
+        raise ValueError(f"No usable ligand RMSD for pairs {missing}; CORE needs every pair")
+    return matrix
+
+
+def core_score(matrix, threshold=2.0, neighbours=NEIGHBOURS):
+    """CORE Score of an ensemble from its complete pairwise ligand-RMSD matrix.
+
+    Each pose's RMSDs to its `neighbours` closest other poses are capped at `threshold`
+    and divided by it, and their mean is that pose's penalty: zero when those poses
+    reproduce it exactly, one when none of them lies within the threshold. CORE is one
+    minus the mean penalty over all poses, so it needs at least `neighbours` + 1 poses.
+    """
+    distances = np.array(matrix, dtype=float)
+    if len(distances) <= neighbours:
+        raise ValueError(f"CORE needs at least {neighbours + 1} poses; this ensemble has {len(distances)}")
+    np.fill_diagonal(distances, np.inf)
+    closest = np.sort(distances, axis=1)[:, :neighbours]
+    return float(1.0 - np.mean(np.minimum(closest, threshold) / threshold))

core_score/analysis/ost.py

@@ -0,0 +1,79 @@
+"""Run OpenStructure's command-line actions. `ost` is found on PATH, and its chemical
+library through OST's own discovery or OST_COMPOUNDS_CHEMLIB."""
+
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+import numpy as np
+
+
+class OSTError(RuntimeError):
+    def __init__(self, message, evidence):
+        super().__init__(message)
+        self.evidence = evidence
+
+
+def execute(arguments, timeout=None):
+    """Run `ost <arguments> -o <file>` and return its JSON output with the execution record."""
+    # One numerical-library thread per process, so --workers alone sets the parallelism.
+    env = dict(os.environ, OMP_NUM_THREADS="1", OPENBLAS_NUM_THREADS="1", MKL_NUM_THREADS="1")
+    with tempfile.TemporaryDirectory() as directory:
+        output = Path(directory) / "ost.json"
+        command = ["ost", *map(str, arguments), "-o", str(output)]
+        process = subprocess.run(command, env=env, capture_output=True, text=True, timeout=timeout)
+        execution = dict(command=command, returncode=process.returncode,
+                         stdout=process.stdout, stderr=process.stderr)
+        if not output.exists():
+            raise OSTError(process.stderr.strip() or f"OST exited with code {process.returncode}", execution)
+        return json.loads(output.read_text()), execution
+
+
+def compare_ligands(model, reference, timeout=None, radius=4.0, lddt_pli=False):
+    """`ost compare-ligand-structures` result for one model/reference pair of prepared structures.
+    lDDT-PLI is only computed when asked for, since CORE uses RMSD alone."""
+    arguments = ["compare-ligand-structures", "-m", model["path"]]
+    if model["ligand_sdfs"]:
+        arguments += ["-ml", *model["ligand_sdfs"]]
+    arguments += ["-r", reference["path"]]
+    if reference["ligand_sdfs"]:
+        arguments += ["-rl", *reference["ligand_sdfs"]]
+    arguments += ["--fault-tolerant", "--rmsd", "--full-bs-search", "--full-results"]
+    if lddt_pli:
+        arguments += ["--lddt-pli", "--lddt-pli-add-mdl-contacts"]
+    if radius != 4.0:
+        arguments += ["--radius", radius]
+    result, execution = execute(arguments, timeout)
+    if execution["returncode"] or result.get("status") != "SUCCESS":
+        result["status"] = "FAILURE"
+        result.setdefault("exception", execution["stderr"][-2000:] or "OST did not report success")
+    result["_execution"] = execution
+    return result
+
+
+def reads_ligand(prepared, timeout=None):
+    """Whether OST reads each ligand copy from the structure itself, connected the same way
+    as in the package's own SDFs (bonds from the coordinates). A ligand OST cannot find,
+    cannot read, or connects differently returns False."""
+    sdfs = [copy["ost_sdf"] for copy in prepared["copy_records"]]
+    try:
+        result = compare_ligands(prepared, dict(prepared, ligand_sdfs=sdfs), timeout)
+    except OSTError:
+        return False
+    assigned = [] if result["status"] == "FAILURE" else result.get("rmsd", {}).get("assigned_scores", [])
+    return len(assigned) == len(sdfs)
+
+
+def superpose(model_path, reference_path, timeout=None):
+    """OST rigid superposition of matched protein C-alpha atoms, model onto reference."""
+    result, execution = execute(
+        ["compare-structures", "-m", model_path, "-r", reference_path, "--rigid-scores"], timeout
+    )
+    if execution["returncode"] or result.get("status") != "SUCCESS" or result.get("transform") is None:
+        raise OSTError(
+            f"OST rigid superposition failed (status {result.get('status')}); chains may not map",
+            dict(execution, ost_results=result),
+        )
+    return dict(transform=np.asarray(result["transform"], dtype=float),
+                rmsd=result.get("rmsd"), chain_mapping=result.get("chain_mapping") or {})

core_score/analysis/pairs.py

@@ -0,0 +1,119 @@
+"""Compare every pair of poses within each site ensemble with OST and save the measurements."""
+
+import itertools
+import math
+from concurrent.futures import ProcessPoolExecutor
+from functools import partial
+from core_score.analysis import ost
+from core_score.outputs.files import diagnostic, write_csv, write_jsonl
+
+
+def compare_groups(groups, output, *, workers=1, timeout=None, radius_fallback=True):
+    results = run_pair_tasks(pair_tasks(groups), workers, timeout=timeout, radius_fallback=radius_fallback)
+    results.sort(key=lambda result: tuple(result[0][k] for k in ("ensemble", "site", "pose_i", "pose_j")))
+    rows = [row for row, _ in results]
+    write_csv(output / "pairs.csv", rows)
+    write_jsonl(output / "ligand_details.jsonl", [detail for _, detail in results])
+    return rows
+
+
+def pair_tasks(groups):
+    """Every pair of poses within each site ensemble; earlier poses are the OST model."""
+    return [
+        (group, pose_i, pose_j)
+        for group in groups
+        if not group.get("error")
+        for pose_i, pose_j in itertools.combinations(group["poses"], 2)
+    ]
+
+
+def run_pair_tasks(tasks, workers=1, **options):
+    """(row, detail) for each task, in task order, using up to `workers` processes."""
+    job = partial(pair_job, **options)
+    if workers == 1:
+        return [job(task) for task in tasks]
+    with ProcessPoolExecutor(max_workers=workers) as pool:
+        return list(pool.map(job, tasks))
+
+
+def pair_job(task, *, timeout=None, radius_fallback=True, lddt_pli=False):
+    group, pose_i, pose_j = task
+    ids = dict(ensemble=group["ensemble"], site=group["site"],
+               pose_i=pose_i["pose_id"], pose_j=pose_j["pose_id"])
+    try:
+        row, detail = compare_pair(pose_i, pose_j, timeout=timeout, radius_fallback=radius_fallback, lddt_pli=lddt_pli)
+    except Exception as exc:
+        detail = diagnostic("comparison", exc, inputs=[pose_i["path"], pose_j["path"]])
+        row = dict(n_assigned=0, error=detail["error"])
+    return dict(ids, **row), dict(ids, **detail)
+
+
+def compare_pair(pose_i, pose_j, *, timeout=None, radius_fallback=True, lddt_pli=False):
+    """OST scores for one pair, retried at 6 and then 8 A after a binding-site failure at 4 A.
+
+    The RMSD metrics come from the radius that scored. lDDT-PLI always stays from 4 A.
+    """
+    model, reference = pose_i["prepared"], pose_j["prepared"]
+    # Recovery needs one ligand copy per side. Ensembles are split by site before comparison.
+    retry = radius_fallback and model["copies"] == reference["copies"] == 1
+    results, attempts = [], []
+    for radius in (4.0, 6.0, 8.0) if retry else (4.0,):
+        result = ost.compare_ligands(model, reference, timeout, radius, lddt_pli)
+        failed = result["status"] == "FAILURE"
+        assigned = [] if failed else result.get("rmsd", {}).get("assigned_scores", [])
+        score = assigned[0].get("score") if len(assigned) == 1 else None
+        reason = result["exception"] if failed else result.get("rmsd", {})
+        results.append(result)
+        attempts.append(dict(radius=radius, score=score, reason=reason))
+        if usable(score) or not binding_site_failure(reason):
+            break
+    recovered = len(attempts) > 1 and usable(attempts[-1]["score"])
+    result = dict(results[0])
+    if recovered:
+        result["rmsd"] = results[-1]["rmsd"]
+    row = summarize(result)
+    if row["n_assigned"] == 0 and not row["error"]:
+        row["error"] = "OST assigned no ligand pair; see the saved OST results"
+    scored = attempts[-1] if recovered else attempts[0]
+    row.update(
+        standard_rmsd=attempts[0]["score"] if usable(attempts[0]["score"]) else None,
+        binding_site_radius_angstrom=scored["radius"] if usable(scored["score"]) else None,
+        radius_fallback_used=recovered,
+    )
+    detail = dict(error=row["error"], source_pose_i=pose_i["path"], source_pose_j=pose_j["path"],
+                  radius_attempts=attempts, ost_results=results)
+    return row, detail
+
+
+def summarize(result):
+    """OST's scores for the pair, blank unless exactly one ligand pair was assigned."""
+    failed = result["status"] == "FAILURE"
+    assigned = [] if failed else [
+        s for s in result.get("rmsd", {}).get("assigned_scores", []) if s.get("score") is not None
+    ]
+    contacts = [] if failed else [
+        s["score"] for s in result.get("lddt_pli", {}).get("assigned_scores", []) if s.get("score") is not None
+    ]
+    single = assigned[0] if len(assigned) == 1 else {}
+    return dict(
+        n_assigned=len(assigned),
+        rmsd=single.get("score"),
+        bb_rmsd=single.get("bb_rmsd"),
+        lddt_lp=single.get("lddt_lp"),
+        lddt_pli=contacts[0] if len(contacts) == 1 else None,
+        error=str(result.get("exception") or result.get("traceback") or "OST failed") if failed else "",
+    )
+
+
+def usable(score):
+    """A finite, non-negative RMSD."""
+    return score is not None and math.isfinite(float(score)) and float(score) >= 0
+
+
+def binding_site_failure(result):
+    """Whether OST's reasons name a binding-site failure (not a graph or general failure)."""
+    if isinstance(result, dict):
+        return any(binding_site_failure(v) for v in result.values())
+    if isinstance(result, (list, tuple)):
+        return any(binding_site_failure(v) for v in result)
+    return result in ("target_binding_site", "model_binding_site", "binding_site")

core_score/analysis/posebusters.py

@@ -0,0 +1,65 @@
+"""PoseBusters dock checks for every pose. The results are saved for use downstream, such as
+choosing the top-ranked valid pose. CORE uses every pose whatever its result. Unknown never
+counts as a pass."""
+
+from core_score.outputs.files import clean, diagnostic, write_json
+
+
+def run_posebusters(groups, output):
+    from posebusters import PoseBusters
+
+    buster = PoseBusters(config="dock", max_workers=0)
+    checks = dock_checks(buster)
+    records = [check_pose(buster, checks, pose) for group in groups for pose in group["poses"]]
+    write_json(output / "posebusters.json", records)
+    return records
+
+
+def dock_checks(buster):
+    """Names of the binary checks in PoseBusters' dock configuration."""
+    return [
+        normalized(module.get("rename_outputs", {}).get(name, name))
+        for module in buster.config["modules"]
+        for name in module.get("chosen_binary_test_output", [])
+    ]
+
+
+def normalized(name):
+    return name.lower().replace(" ", "_")
+
+
+def aggregate(values):
+    """False if any check failed, None if any is unknown (or there are none), otherwise True."""
+    values = list(values)
+    if any(v is False for v in values):
+        return False
+    if not values or any(v is None for v in values):
+        return None
+    return True
+
+
+def check_pose(buster, checks, pose):
+    """A pose is valid only if every ligand copy passes every dock check. Each check's result
+    for the pose combines its copies the same way."""
+    record = dict(ensemble=pose["ensemble"], pose_id=pose["pose_id"], pb_valid=None,
+                  checks=dict.fromkeys(checks))
+    if pose.get("error"):
+        return dict(record, error="Pose was not prepared; see details/prepared_manifest.json")
+    prepared = pose["prepared"]
+    copies = [check_copy(buster, checks, copy, prepared["receptor"]) for copy in prepared["copy_records"]]
+    combined = {name: aggregate(copy.get("checks", {}).get(name) for copy in copies) for name in checks}
+    return dict(record, pb_valid=aggregate(copy["pb_valid"] for copy in copies), checks=combined, copies=copies)
+
+
+def check_copy(buster, checks, copy, receptor):
+    record = dict(copy_id=copy["copy_id"], preparation=copy["provenance"], pb_valid=None)
+    if copy["pb_error"]:
+        return dict(record, error=copy["pb_error"])
+    try:
+        report = buster.bust(copy["pb_sdf"], mol_cond=receptor, full_report=True)
+    except Exception as exc:
+        return dict(record, **diagnostic("posebusters", exc))
+    tests = {normalized(k): clean(v) for k, v in report.iloc[0].items()}
+    results = {name: tests.get(name) if isinstance(tests.get(name), bool) else None for name in checks}
+    return dict(record, pb_valid=aggregate(results.values()), checks=results, tests=tests)
+

core_score/analysis/reference.py

@@ -0,0 +1,59 @@
+"""Optional comparison of every prediction against its ensemble's ground-truth structure.
+
+A pose is correct at threshold T when its ligand RMSD to the reference is below T and its
+lDDT-PLI is above 0.8, the definition used in the paper."""
+
+import math
+from core_score.outputs.files import fingerprint, write_json
+from core_score.analysis.pairs import run_pair_tasks
+from core_score.inputs.prepare import prepare
+
+LDDT_PLI_CUTOFF = 0.8
+
+
+def evaluate_groups(groups, output, thresholds=(2.0,), *, workers=1, timeout=None, radius_fallback=True):
+    """Ligand RMSD and lDDT-PLI of each prepared prediction to its reference, labelled correct
+    or not at each threshold. Ensembles without a reference are skipped. Reference results
+    never enter CORE."""
+    groups = [group for group in groups if "reference" in group]
+    tasks, records = [], []
+    for group in groups:
+        destination = output / "references" / fingerprint(group["ensemble"])[:20] / "reference.cif"
+        reference = prepare(group["reference"], destination, timeout=timeout)
+        for pose in group["poses"]:
+            error = reference.get("error") or pose.get("error")
+            if error:
+                records.append(dict(ensemble=group["ensemble"], pose_id=pose["pose_id"], rmsd=None, error=error))
+            else:
+                tasks.append((dict(group, site="reference"), pose, reference))
+    for row, detail in run_pair_tasks(tasks, workers, timeout=timeout, radius_fallback=radius_fallback, lddt_pli=True):
+        records.append(dict(row, pose_id=row["pose_i"], detail=detail))
+    write_json(output / "reference_details.json", records)
+    keys = ((group["ensemble"], pose["pose_id"]) for group in groups for pose in group["poses"])
+    order = {key: i for i, key in enumerate(keys)}
+    labels = label_reference_results(records, thresholds)
+    return sorted(labels, key=lambda label: order[label["ensemble"], label["pose_id"]])
+
+
+def correct_column(threshold):
+    """The column saying whether a pose is correct at `threshold`."""
+    return f"correct_{threshold:g}A"
+
+
+def label_reference_results(records, thresholds):
+    """One row per pose. A pose is correct at T when RMSD < T and lDDT-PLI > 0.8. A failed or
+    ambiguous comparison, or one missing either score, is unknown (blank scores and labels),
+    not incorrect."""
+    labels = []
+    for record in records:
+        rmsd, lddt_pli = record.get("rmsd"), record.get("lddt_pli")
+        known = not record.get("error") and all(v is not None and math.isfinite(v) for v in (rmsd, lddt_pli))
+        label = dict(ensemble=record["ensemble"], pose_id=record["pose_id"],
+                     rmsd=rmsd if known else None, lddt_pli=lddt_pli if known else None)
+        for threshold in thresholds:
+            label[correct_column(threshold)] = bool(rmsd < threshold and lddt_pli > LDDT_PLI_CUTOFF) if known else None
+        label["radius_fallback_used"] = record.get("radius_fallback_used", False)
+        error = record.get("error")
+        label["error"] = (error["error"] if isinstance(error, dict) else error) or None  # message only; details in JSON
+        labels.append(label)
+    return labels

core_score/cli.py

@@ -0,0 +1,90 @@
+"""One command: load inputs and run the analysis."""
+
+import argparse
+import math
+import sys
+from pathlib import Path
+from core_score.pipeline import run
+
+
+def positive(value):
+    number = float(value)
+    if not math.isfinite(number) or number <= 0:
+        raise argparse.ArgumentTypeError("must be finite and positive")
+    return number
+
+
+def fraction(value):
+    number = float(value)
+    if not 0 <= number <= 1:
+        raise argparse.ArgumentTypeError("must be between 0 and 1")
+    return number
+
+
+def worker_count(value):
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return number
+
+
+def parser():
+    p = argparse.ArgumentParser(
+        prog="core-score",
+        description="Prepare structures, run PoseBusters, compare poses and calculate CORE.",
+        epilog="Example: core-score inputs.csv --out results/ --workers 4. Make inputs.csv with core-score-csv.",
+    )
+    p.add_argument("inputs", metavar="INPUT", nargs="+", type=Path,
+                   help="CSV of ensembles, or structure files forming one ensemble")
+    p.add_argument("--out", type=Path, required=True, help="Results directory")
+    p.add_argument("--smiles", help="Ligand SMILES for structure files; a CSV sets its own")
+    p.add_argument("--ligand-chain", dest="ligand_chains", action="append",
+                   help="Ligand chain for structure files; repeat for identical copies")
+    p.add_argument("--workers", type=worker_count, default=1,
+                   help="Simultaneous OST comparisons (default: 1)")
+    p.add_argument("--timeout", type=positive, default=None,
+                   help="Seconds per OST call (default: no timeout)")
+    p.add_argument("--no-radius-fallback", action="store_true",
+                   help="Disable eligible binding-site retries at 6 and 8 angstroms")
+    p.add_argument("--skip-posebusters", action="store_true", help="Do not run PoseBusters checks")
+    p.add_argument("--reference", type=Path,
+                   help="Ground-truth structure for structure files; a CSV sets its own")
+    p.add_argument("--rmsd-thresholds", type=positive, nargs="+", default=[2.0],
+                   help="Thresholds T in angstroms: CORE is calculated at each, and a pose is "
+                        "correct when its RMSD to the reference is below T and its lDDT-PLI is "
+                        "above 0.8 (default: 2)")
+    p.add_argument("--plot", action="store_true",
+                   help="Also save core_scores.png: a dot per complex (needs matplotlib)")
+    p.add_argument("--core-cutoffs", type=fraction, nargs="+", default=[0.5, 0.6, 0.7, 0.8, 0.9],
+                   help="CORE cutoffs: each complex is reported as above (CORE >= cutoff) or below "
+                        "each one (default: 0.5 to 0.9)")
+    return p
+
+
+def main(argv=None):
+    words = sys.argv[1:] if argv is None else argv
+    args = parser().parse_args(words or ["--help"])
+    try:
+        summary = run(
+            args.inputs,
+            args.out,
+            smiles=args.smiles,
+            ligand_chains=args.ligand_chains,
+            reference=args.reference,
+            workers=args.workers,
+            timeout=args.timeout,
+            radius_fallback=not args.no_radius_fallback,
+            skip_posebusters=args.skip_posebusters,
+            thresholds=args.rmsd_thresholds,
+            cutoffs=args.core_cutoffs,
+            plot=args.plot,
+        )
+    except (ValueError, OSError, RuntimeError) as exc:
+        print(f"core-score: {exc}", file=sys.stderr)
+        return 2
+    print(
+        f"Completed {summary['completed_comparisons']}/{summary['comparison_count']} "
+        f"pair comparisons; calculated {summary['score_count']} CORE scores."
+    )
+    print(f"Results saved to {args.out}")
+    return int(any(summary["status"].values()))

core_score/inputs/__init__.py

@@ -0,0 +1 @@
+"""Read the inputs and prepare every pose."""

core_score/inputs/inputs.py

@@ -0,0 +1,113 @@
+"""Load prediction ensembles from a CSV file, or from structure files given directly.
+
+The CSV needs three columns. `poses` is one structure file, or a wildcard matching many:
+
+    ensemble,smiles,poses
+    7ly6,CC(=O)Nc1ccc(O)cc1,predictions/7ly6/*.cif
+
+Optional columns are confidence (one pose per row), ligand_chain (space separated when the
+ligand has several copies), reference (the ground-truth structure) and ligand_sdf (the
+ligand in the structure's frame, for docking outputs). Paths are relative to the CSV.
+"""
+
+import csv
+import glob
+import os
+from collections import defaultdict
+from pathlib import Path
+from core_score.analysis.core import NEIGHBOURS
+from core_score.inputs.structures import template_mol
+
+REQUIRED = ("ensemble", "smiles", "poses")
+OPTIONAL = ("confidence", "ligand_chain", "reference", "ligand_sdf")
+MIN_POSES = NEIGHBOURS + 1
+
+
+def load_inputs(inputs, *, smiles=None, ligand_chains=None, reference=None):
+    """Ensemble records from one CSV, or from structure files forming one ensemble.
+
+    Poses are sorted by path, never kept in listing order. That order fixes the
+    site-assignment anchor and which pose of each pair OST treats as the model, so
+    reordering the input never changes a score. Pose IDs are paths relative to the CSV.
+    """
+    inputs = [Path(path) for path in inputs]
+    if len(inputs) == 1 and inputs[0].suffix.lower() == ".csv":
+        base, rows = inputs[0].resolve().parent, read_csv(inputs[0])
+    else:
+        base = Path.cwd()
+        rows = [dict(ensemble="ensemble", smiles=smiles or "", poses=str(path),
+                     ligand_chain=" ".join(ligand_chains or []), reference=str(reference or ""))
+                for path in inputs]
+    ensembles = defaultdict(list)
+    for row in rows:
+        ensembles[row["ensemble"]].append({k: v.strip() for k, v in row.items() if v and v.strip()})
+    groups = [make_group(name, members, base) for name, members in ensembles.items()]
+    small = [f"{group['ensemble']} ({len(group['poses'])})" for group in groups if len(group["poses"]) < MIN_POSES]
+    if small:
+        raise ValueError(f"CORE needs at least {MIN_POSES} poses per ensemble, since each pose is scored "
+                         f"against its {NEIGHBOURS} closest others. Too few: {', '.join(small)}")
+    return groups
+
+
+def read_csv(path):
+    with Path(path).open(newline="") as handle:
+        reader = csv.DictReader(handle)
+        columns = reader.fieldnames or []
+        missing = [c for c in REQUIRED if c not in columns]
+        unknown = [c for c in columns if c not in REQUIRED + OPTIONAL]
+        if missing or unknown:
+            raise ValueError(f"{path}: missing columns {missing}, unknown columns {unknown}. "
+                             f"The CSV needs {', '.join(REQUIRED)} and may add {', '.join(OPTIONAL)}.")
+        rows = list(reader)
+    blank = [i + 2 for i, row in enumerate(rows) if not all((row[c] or "").strip() for c in REQUIRED)]
+    if blank:
+        raise ValueError(f"{path}: lines {blank} leave ensemble, smiles or poses empty")
+    return rows
+
+
+def make_group(name, rows, base):
+    """One ensemble from its CSV rows. Every row must give the same SMILES and reference."""
+    for column in ("smiles", "reference"):
+        if len({row.get(column) for row in rows}) > 1:
+            raise ValueError(f"{name}: every row of an ensemble needs the same {column}")
+    try:
+        template_mol(rows[0].get("smiles", ""))
+    except ValueError as exc:
+        raise ValueError(f"{name}: {exc}. Give the ligand SMILES in the CSV, or --smiles with structure files.") from exc
+    poses = [pose for row in rows for pose in make_poses(name, row, base)]
+    paths = [pose["path"] for pose in poses]
+    if len(set(paths)) != len(paths):
+        raise ValueError(f"{name}: a structure is listed more than once")
+    if len({"confidence" in pose for pose in poses}) != 1:
+        raise ValueError(f"{name}: give a confidence for every pose or for none")
+    group = dict(ensemble=name, poses=sorted(poses, key=lambda pose: pose["path"]))
+    if rows[0].get("reference"):
+        path = resolve(base, rows[0]["reference"])
+        group["reference"] = dict(ensemble=name, pose_id="reference", path=path, smiles=rows[0]["smiles"])
+    return group
+
+
+def make_poses(name, row, base):
+    """The poses one CSV row names: one file, or every file its wildcard matches."""
+    paths = sorted(glob.glob(str(base / row["poses"]), recursive=True))
+    if not paths:
+        raise FileNotFoundError(f"{name}: no structure file matches {row['poses']}")
+    single = {k: row[k] for k in ("confidence", "ligand_sdf") if k in row}
+    if single and len(paths) > 1:
+        raise ValueError(f"{name}: {row['poses']} matches {len(paths)} files, so give "
+                         f"{' and '.join(single)} on a row of its own for each pose")
+    poses = []
+    for path in paths:
+        path = str(Path(path).resolve())
+        pose = dict(ensemble=name, pose_id=Path(os.path.relpath(path, base)).as_posix(), path=path,
+                    smiles=row["smiles"], ligand_chains=row.get("ligand_chain", "").split())
+        if "confidence" in row:
+            pose["confidence"] = float(row["confidence"])
+        if "ligand_sdf" in row:
+            pose["ligand_sdfs"] = [resolve(base, row["ligand_sdf"])]
+        poses.append(pose)
+    return poses
+
+
+def resolve(base, path):
+    return str((base / path).resolve(strict=True))