graphpop-cli 0.1.0__py3-none-any.whl

graphpop_cli/__init__.py

@@ -0,0 +1,2 @@
+"""GraphPop CLI — command-line interface for graph-native population genomics."""
+__version__ = "0.1.0"

graphpop_cli/cli.py

@@ -0,0 +1,161 @@
+"""GraphPop CLI — command-line interface for graph-native population genomics.
+
+Usage:
+    graphpop diversity chr22 1 50000000 EUR -o diversity.tsv
+    graphpop ihs chr22 EUR --min-af 0.05 --persist -o ihs.tsv
+    graphpop genome-scan chr22 EUR 100000 50000 --persist -o scan.tsv
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .connection import load_config, get_driver
+
+
+class GraphPopContext:
+    """Shared context passed to all commands."""
+    def __init__(self, uri=None, user=None, password=None, database=None,
+                 config_path=None):
+        cfg = load_config(Path(config_path) if config_path else None)
+        if uri:
+            cfg["uri"] = uri
+        if user:
+            cfg["user"] = user
+        if password:
+            cfg["password"] = password
+        if database:
+            cfg["database"] = database
+        self.cfg = cfg
+        self._driver = None
+
+    @property
+    def driver(self):
+        if self._driver is None:
+            self._driver = get_driver(self.cfg)
+        return self._driver
+
+    @property
+    def database(self):
+        return self.cfg["database"]
+
+    def run(self, cypher: str, parameters: dict | None = None) -> list[dict]:
+        """Run Cypher and return records as list of dicts."""
+        try:
+            with self.driver.session(database=self.database) as session:
+                return [rec.data() for rec in session.run(cypher, parameters)]
+        except Exception as e:
+            err_msg = str(e)
+            if "Connection refused" in err_msg or "Failed to establish" in err_msg:
+                click.echo(
+                    "Error: Cannot connect to Neo4j at "
+                    f"{self.cfg['uri']}.\n"
+                    "Is Neo4j running? Check connection with:\n"
+                    f"  export GRAPHPOP_URI={self.cfg['uri']}\n"
+                    "  or create ~/.graphpop/config.yaml",
+                    err=True,
+                )
+            else:
+                click.echo(f"Error: {e}", err=True)
+            raise SystemExit(1)
+
+    def close(self):
+        if self._driver:
+            self._driver.close()
+
+
+pass_ctx = click.make_pass_decorator(GraphPopContext, ensure=True)
+
+
+@click.group()
+@click.option("--uri", envvar="GRAPHPOP_URI", help="Neo4j bolt URI")
+@click.option("--user", envvar="GRAPHPOP_USER", help="Neo4j username")
+@click.option("--password", envvar="GRAPHPOP_PASSWORD", help="Neo4j password")
+@click.option("--database", envvar="GRAPHPOP_DATABASE", help="Neo4j database name")
+@click.option("--config", "config_path", type=click.Path(),
+              help="Config file path (default: ~/.graphpop/config.yaml)")
+@click.version_option(package_name="graphpop-cli")
+@click.pass_context
+def main(ctx, uri, user, password, database, config_path):
+    """GraphPop — graph-native population genomics from the command line.
+
+    Compute population genetics statistics via Neo4j stored procedures with
+    default TSV output. Use --persist to write results to graph nodes.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj = GraphPopContext(uri=uri, user=user, password=password,
+                              database=database, config_path=config_path)
+
+
+# Import all command modules
+from .commands import (  # noqa: E402
+    diversity, divergence, sfs, joint_sfs,
+    genome_scan, pop_summary,
+    ld, ihs, xpehh, nsl, roh, garud_h,
+    query, run_all, aggregate, export_windows,
+    setup, server, db, import_data, dump,
+    config_cmd, validate, filter_results, plot,
+    lookup, converge, inventory, rank_genes,
+    extract, export_bed, batch, compare,
+    report, neighbors,
+)
+
+# Individual procedures (12)
+main.add_command(diversity.diversity)
+main.add_command(divergence.divergence)
+main.add_command(sfs.sfs)
+main.add_command(joint_sfs.joint_sfs)
+main.add_command(genome_scan.genome_scan)
+main.add_command(pop_summary.pop_summary)
+main.add_command(ld.ld)
+main.add_command(ihs.ihs)
+main.add_command(xpehh.xpehh)
+main.add_command(nsl.nsl)
+main.add_command(roh.roh)
+main.add_command(garud_h.garud_h)
+
+# Orchestration and export
+main.add_command(run_all.run_all)
+main.add_command(aggregate.aggregate)
+main.add_command(export_windows.export_windows)
+main.add_command(query.query)
+main.add_command(filter_results.filter_results)
+
+# Setup and server management
+main.add_command(setup.setup)
+main.add_command(server.start)
+main.add_command(server.stop)
+main.add_command(server.status)
+
+# Database management
+main.add_command(db.db)
+main.add_command(import_data.import_data)
+main.add_command(dump.dump)
+main.add_command(dump.load)
+
+# Configuration and validation
+main.add_command(config_cmd.config)
+main.add_command(validate.validate)
+main.add_command(plot.plot)
+
+# Phase 1 high-priority commands
+main.add_command(lookup.lookup)
+main.add_command(converge.converge)
+main.add_command(inventory.inventory)
+main.add_command(rank_genes.rank_genes)
+
+# Phase 2 commands
+main.add_command(extract.extract)
+main.add_command(export_bed.export_bed)
+main.add_command(batch.batch)
+main.add_command(compare.compare)
+
+# Phase 3 commands
+main.add_command(report.report)
+main.add_command(neighbors.neighbors)
+
+
+if __name__ == "__main__":
+    main()

graphpop_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""GraphPop CLI command modules."""

graphpop_cli/commands/aggregate.py

@@ -0,0 +1,206 @@
+"""graphpop aggregate — aggregate results and generate summary tables."""
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+import click
+
+from ..cli import pass_ctx
+
+
+@click.command()
+@click.option("--results-dir", "-d", type=click.Path(exists=True), required=True,
+              help="Directory with per-procedure TSV results (from run-all)")
+@click.option("--json-results", "-j", type=click.Path(exists=True),
+              help="JSON results file (from run-all)")
+@click.option("--output-dir", "-o", type=click.Path(), default="graphpop_tables",
+              help="Output directory for summary tables")
+@pass_ctx
+def aggregate(ctx, results_dir, json_results, output_dir):
+    """Aggregate per-population results into summary tables.
+
+    Reads TSV results from a run-all output directory and produces
+    publication-ready summary tables:
+
+    \b
+      population_summary.tsv   — per-pop diversity, theta, Tajima's D, Fis
+      fst_matrix.tsv           — pairwise Fst matrix
+      pinpis.tsv               — piN/piS ratios (if conditioned results exist)
+      selection_peaks.tsv      — top iHS/XP-EHH/nSL peaks per population
+      roh_summary.tsv          — per-pop FROH statistics
+    """
+    results_path = Path(results_dir)
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Load JSON results if provided
+    all_results = {}
+    if json_results:
+        with open(json_results) as f:
+            all_results = json.load(f)
+        click.echo(f"Loaded {len(all_results)} results from JSON")
+
+    # --- Table 1: Population Summary ---
+    diversity_dir = results_path / "diversity"
+    if diversity_dir.exists():
+        click.echo("Generating population_summary.tsv...")
+        pop_stats = _aggregate_single_row_tsv(diversity_dir)
+        _write_summary(out_dir / "population_summary.tsv", pop_stats,
+                       ["population", "chr", "pi", "theta_w", "tajima_d",
+                        "het_exp", "het_obs", "fis", "n_variants", "n_segregating"])
+
+    # --- Table 2: Fst Matrix ---
+    divergence_dir = results_path / "divergence"
+    if divergence_dir.exists():
+        click.echo("Generating fst_matrix.tsv...")
+        div_stats = _aggregate_single_row_tsv(divergence_dir)
+        _write_summary(out_dir / "fst_matrix.tsv", div_stats,
+                       ["pop1", "pop2", "chr", "fst_hudson", "fst_wc", "dxy", "da"])
+
+    # --- Table 3: ROH Summary ---
+    roh_dir = results_path / "roh"
+    if roh_dir.exists():
+        click.echo("Generating roh_summary.tsv...")
+        roh_data = _aggregate_multi_row_tsv(roh_dir)
+        # Compute per-population means
+        pop_roh = {}
+        for rec in roh_data:
+            pop = rec.get("population", rec.get("file_pop", "unknown"))
+            if pop not in pop_roh:
+                pop_roh[pop] = {"n_samples": 0, "total_froh": 0.0,
+                                "total_n_roh": 0, "max_froh": 0.0}
+            pop_roh[pop]["n_samples"] += 1
+            froh = float(rec.get("froh", 0))
+            pop_roh[pop]["total_froh"] += froh
+            pop_roh[pop]["total_n_roh"] += int(rec.get("n_roh", 0))
+            pop_roh[pop]["max_froh"] = max(pop_roh[pop]["max_froh"], froh)
+
+        rows = []
+        for pop, s in sorted(pop_roh.items()):
+            rows.append({
+                "population": pop,
+                "n_samples": s["n_samples"],
+                "mean_froh": f"{s['total_froh'] / s['n_samples']:.6f}",
+                "mean_n_roh": f"{s['total_n_roh'] / s['n_samples']:.1f}",
+                "max_froh": f"{s['max_froh']:.6f}",
+            })
+        _write_dict_tsv(out_dir / "roh_summary.tsv", rows)
+
+    # --- Table 4: Selection Peaks ---
+    for proc in ("ihs", "nsl", "xpehh"):
+        proc_dir = results_path / proc
+        if proc_dir.exists():
+            click.echo(f"Generating {proc}_peaks.tsv...")
+            peaks = _extract_peaks(proc_dir, proc, top_n=100)
+            _write_dict_tsv(out_dir / f"{proc}_peaks.tsv", peaks)
+
+    # --- Table 5: Garud's H Sweep Windows ---
+    garud_dir = results_path / "garud_h"
+    if garud_dir.exists():
+        click.echo("Generating sweep_windows.tsv...")
+        sweeps = _extract_sweep_windows(garud_dir, h12_threshold=0.1)
+        _write_dict_tsv(out_dir / "sweep_windows.tsv", sweeps)
+
+    click.echo(f"\nSummary tables written to {out_dir}/")
+    for f in sorted(out_dir.glob("*.tsv")):
+        n_lines = sum(1 for _ in open(f)) - 1
+        click.echo(f"  {f.name}: {n_lines} rows")
+
+
+def _aggregate_single_row_tsv(directory: Path) -> list[dict]:
+    """Read TSV files with single data row, extract pop/chr from filename."""
+    rows = []
+    for tsv in sorted(directory.glob("*.tsv")):
+        parts = tsv.stem.split("_")
+        with open(tsv) as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            for rec in reader:
+                # Infer pop and chr from filename: POP_CHR.tsv
+                if len(parts) >= 2:
+                    rec["population"] = "_".join(parts[:-1])
+                    rec["chr"] = parts[-1]
+                elif "vs" in tsv.stem:
+                    # Pairwise: POP1_vs_POP2_CHR.tsv
+                    vs_idx = parts.index("vs")
+                    rec["pop1"] = "_".join(parts[:vs_idx])
+                    rec["pop2"] = "_".join(parts[vs_idx + 1:-1])
+                    rec["chr"] = parts[-1]
+                rows.append(rec)
+    return rows
+
+
+def _aggregate_multi_row_tsv(directory: Path) -> list[dict]:
+    """Read TSV files with multiple data rows."""
+    rows = []
+    for tsv in sorted(directory.glob("*.tsv")):
+        parts = tsv.stem.split("_")
+        pop = "_".join(parts[:-1]) if len(parts) >= 2 else parts[0]
+        with open(tsv) as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            for rec in reader:
+                rec["file_pop"] = pop
+                rows.append(rec)
+    return rows
+
+
+def _extract_peaks(directory: Path, stat_name: str,
+                   top_n: int = 100) -> list[dict]:
+    """Extract top peaks from per-variant result files."""
+    all_variants = []
+    for tsv in sorted(directory.glob("*.tsv")):
+        parts = tsv.stem.split("_")
+        with open(tsv) as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            for rec in reader:
+                score = rec.get(stat_name, rec.get(f"{stat_name}_unstd", "0"))
+                try:
+                    rec["abs_score"] = abs(float(score))
+                except (ValueError, TypeError):
+                    rec["abs_score"] = 0
+                rec["source_file"] = tsv.stem
+                all_variants.append(rec)
+
+    all_variants.sort(key=lambda r: r["abs_score"], reverse=True)
+    return all_variants[:top_n]
+
+
+def _extract_sweep_windows(directory: Path,
+                           h12_threshold: float = 0.1) -> list[dict]:
+    """Extract windows exceeding H12 threshold."""
+    sweeps = []
+    for tsv in sorted(directory.glob("*.tsv")):
+        with open(tsv) as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            for rec in reader:
+                try:
+                    if float(rec.get("h12", 0)) >= h12_threshold:
+                        sweeps.append(rec)
+                except (ValueError, TypeError):
+                    pass
+    sweeps.sort(key=lambda r: float(r.get("h12", 0)), reverse=True)
+    return sweeps
+
+
+def _write_summary(path: Path, rows: list[dict], columns: list[str]):
+    """Write summary table with specified columns."""
+    with open(path, "w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=columns, delimiter="\t",
+                                extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(rows)
+
+
+def _write_dict_tsv(path: Path, rows: list[dict]):
+    """Write list of dicts as TSV."""
+    if not rows:
+        with open(path, "w") as f:
+            f.write("# No results\n")
+        return
+    keys = list(rows[0].keys())
+    with open(path, "w", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=keys, delimiter="\t",
+                                extrasaction="ignore")
+        writer.writeheader()
+        writer.writerows(rows)

graphpop_cli/commands/batch.py

@@ -0,0 +1,155 @@
+"""graphpop batch — run any procedure across multiple populations and chromosomes."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ..cli import pass_ctx
+from ..config import build_options_map, build_cypher
+from ..formatters import format_output
+
+
+# Map command names to their procedure and yield columns
+COMMAND_REGISTRY = {
+    "diversity": {
+        "procedure": "graphpop.diversity",
+        "args": lambda chr, pop, **kw: [f"'{chr}'", "1", "999999999", f"'{pop}'"],
+        "yield": ["pi", "theta_w", "tajima_d", "fay_wu_h", "fay_wu_h_norm",
+                   "het_exp", "het_obs", "fis", "n_variants", "n_segregating",
+                   "n_polarized"],
+    },
+    "divergence": {
+        "procedure": "graphpop.divergence",
+        "args": lambda chr, pop, pop2=None, **kw: [
+            f"'{chr}'", "1", "999999999", f"'{pop}'", f"'{pop2}'"
+        ] if pop2 else None,
+        "yield": ["fst_hudson", "fst_wc", "dxy", "da", "n_variants"],
+    },
+    "ihs": {
+        "procedure": "graphpop.ihs",
+        "args": lambda chr, pop, **kw: [f"'{chr}'", f"'{pop}'"],
+        "yield": ["n_variants", "n_computed", "n_significant"],
+    },
+    "xpehh": {
+        "procedure": "graphpop.xpehh",
+        "args": lambda chr, pop, pop2=None, **kw: [
+            f"'{chr}'", f"'{pop}'", f"'{pop2}'"
+        ] if pop2 else None,
+        "yield": ["n_variants", "n_computed", "n_significant"],
+    },
+    "nsl": {
+        "procedure": "graphpop.nsl",
+        "args": lambda chr, pop, **kw: [f"'{chr}'", f"'{pop}'"],
+        "yield": ["n_variants", "n_computed", "n_significant"],
+    },
+    "sfs": {
+        "procedure": "graphpop.sfs",
+        "args": lambda chr, pop, **kw: [f"'{chr}'", "1", "999999999", f"'{pop}'"],
+        "yield": ["sfs", "n_variants", "n_segregating"],
+    },
+    "roh": {
+        "procedure": "graphpop.roh",
+        "args": lambda chr, pop, **kw: [f"'{chr}'", f"'{pop}'"],
+        "yield": ["n_samples", "mean_froh", "median_froh", "n_roh_segments"],
+    },
+    "garud-h": {
+        "procedure": "graphpop.garud_h",
+        "args": lambda chr, pop, **kw: [f"'{chr}'", f"'{pop}'"],
+        "yield": ["n_windows", "mean_h12", "max_h12"],
+    },
+}
+
+
+@click.command("batch")
+@click.argument("command")
+@click.option("--pops", required=True, help="Comma-separated population list")
+@click.option("--chrs", required=True, help="Comma-separated chromosome list")
+@click.option("--pop2", help="Second population (for divergence/xpehh, applied to all)")
+@click.option("--workers", type=int, default=1,
+              help="Parallel workers (default: 1, currently sequential)")
+@click.option("-d", "--output-dir", required=True,
+              type=click.Path(), help="Output directory (one TSV per pop-chr combo)")
+@click.option("--persist", is_flag=True, help="Pass --persist to underlying command")
+@click.option("--consequence", help="Filter by VEP consequence type")
+@click.option("--pathway", help="Filter by pathway name")
+@click.option("--format", "fmt", default="tsv", type=click.Choice(["tsv", "csv", "json"]))
+@pass_ctx
+def batch(ctx, command, pops, chrs, pop2, workers, output_dir, persist,
+          consequence, pathway, fmt):
+    """Run a GraphPop procedure across multiple populations and/or chromosomes.
+
+    COMMAND is the procedure name: diversity, divergence, ihs, xpehh, nsl,
+    sfs, roh, garud-h.
+
+    Creates one output file per (population, chromosome) combination in
+    the output directory, named {command}_{pop}_{chr}.{ext}.
+
+    \b
+    Examples:
+      graphpop batch diversity --pops EUR,AFR,EAS --chrs chr1,chr2,chr22 -d output/
+      graphpop batch ihs --pops EUR,AFR --chrs chr22 --persist -d output/
+      graphpop batch divergence --pops EUR --pop2 AFR --chrs chr22 -d output/
+    """
+    if command not in COMMAND_REGISTRY:
+        available = ", ".join(sorted(COMMAND_REGISTRY.keys()))
+        click.echo(f"Error: unknown command '{command}'. Available: {available}", err=True)
+        raise SystemExit(1)
+
+    spec = COMMAND_REGISTRY[command]
+    pop_list = [p.strip() for p in pops.split(",")]
+    chr_list = [c.strip() for c in chrs.split(",")]
+
+    # Create output directory
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    ext = fmt
+    opts = build_options_map(consequence=consequence, pathway=pathway)
+    if persist:
+        opts["persist"] = True
+
+    total = len(pop_list) * len(chr_list)
+    completed = 0
+    failed = 0
+
+    for pop in pop_list:
+        for chr_name in chr_list:
+            completed += 1
+            label = f"[{completed}/{total}] {command} {pop} {chr_name}"
+            click.echo(f"{label} ...", err=True)
+
+            try:
+                args = spec["args"](chr=chr_name, pop=pop, pop2=pop2)
+                if args is None:
+                    click.echo(f"  Skipping: missing required argument (e.g., --pop2).", err=True)
+                    failed += 1
+                    continue
+
+                cypher = build_cypher(
+                    spec["procedure"],
+                    args,
+                    options=opts if opts else None,
+                    yield_cols=spec["yield"],
+                )
+                records = ctx.run(cypher)
+
+                if not records:
+                    click.echo(f"  No results.", err=True)
+                    failed += 1
+                    continue
+
+                out_file = out_dir / f"{command}_{pop}_{chr_name}.{ext}"
+                format_output(records, str(out_file), fmt, f"batch {command}",
+                              {"population": pop, "chr": chr_name})
+                click.echo(f"  -> {out_file} ({len(records)} rows)", err=True)
+
+            except SystemExit:
+                click.echo(f"  FAILED (query error).", err=True)
+                failed += 1
+            except Exception as e:
+                click.echo(f"  FAILED: {e}", err=True)
+                failed += 1
+
+    click.echo(f"\nBatch complete: {completed - failed}/{total} succeeded, "
+               f"{failed} failed.", err=True)

graphpop_cli/commands/compare.py

@@ -0,0 +1,118 @@
+"""graphpop compare — compare statistics between two populations."""
+from __future__ import annotations
+
+import re
+
+import click
+
+from ..cli import pass_ctx
+from ..formatters import format_output
+
+# Allowed stat names — used to whitelist dynamic property access
+_VALID_STATS = {"pi", "theta_w", "tajima_d", "fst", "ihs"}
+_IDENT_RE = re.compile(r'^[A-Za-z0-9_-]+$')
+
+
+def _validate_identifier(value: str, label: str) -> str:
+    """Validate that a value is safe for use as a Cypher property name."""
+    if not _IDENT_RE.match(value):
+        raise click.BadParameter(
+            f"Invalid {label}: {value!r}. Only alphanumeric, hyphen, "
+            "and underscore characters are allowed."
+        )
+    return value
+
+
+@click.command("compare")
+@click.argument("pop1")
+@click.argument("pop2")
+@click.argument("chr", metavar="CHR")
+@click.option("--stat", required=True,
+              type=click.Choice(["pi", "theta_w", "tajima_d", "fst", "ihs"]),
+              help="Statistic to compare")
+@click.option("--window-size", type=int, default=100000,
+              help="Sliding window size for comparison (default: 100000)")
+@click.option("-o", "--output", "output_path", help="Output file (default: stdout)")
+@click.option("--format", "fmt", default="tsv", type=click.Choice(["tsv", "csv", "json"]))
+@click.option("--limit", type=int, default=10000, help="Maximum rows (default: 10000)")
+@pass_ctx
+def compare(ctx, pop1, pop2, chr, stat, window_size, output_path, fmt, limit):
+    """Compare statistics between two populations across a chromosome.
+
+    For window-based stats (pi, theta_w, tajima_d, fst), queries GenomicWindow
+    nodes for both populations and joins by window position to compute delta.
+
+    For ihs, queries Variant nodes with ihs_{POP1} and ihs_{POP2} properties
+    and computes the per-variant difference.
+
+    Output columns: window_start, window_end, stat_pop1, stat_pop2, delta, abs_delta.
+
+    \b
+    Examples:
+      graphpop compare EUR AFR chr22 --stat pi -o delta_pi.tsv
+      graphpop compare GJ-tmp GJ-trp Chr1 --stat fst -o delta.tsv
+      graphpop compare EUR EAS chr22 --stat ihs -o ihs_diff.tsv
+    """
+    # Validate identifiers used in dynamic property names
+    pop1 = _validate_identifier(pop1, "population")
+    pop2 = _validate_identifier(pop2, "population")
+
+    if stat == "ihs":
+        records = _compare_variant_stat(ctx, pop1, pop2, chr, stat, limit)
+    else:
+        records = _compare_window_stat(ctx, pop1, pop2, chr, stat, window_size, limit)
+
+    if not records:
+        click.echo(f"No comparison data found for {stat} on {chr} "
+                    f"({pop1} vs {pop2}).", err=True)
+        return
+
+    click.echo(f"Found {len(records)} comparison rows.", err=True)
+    format_output(records, output_path, fmt, "compare",
+                  {"pop1": pop1, "pop2": pop2, "chr": chr, "stat": stat})
+
+
+def _compare_window_stat(ctx, pop1, pop2, chr, stat, window_size, limit):
+    """Compare window-based statistics between two populations."""
+    prop = stat
+    params = {"chr": chr, "pop1": pop1, "pop2": pop2, "limit": limit}
+
+    cypher = (
+        f"MATCH (w1:GenomicWindow) "
+        f"WHERE w1.chr = $chr AND w1.population = $pop1 "
+        f"AND w1.{prop} IS NOT NULL "
+        f"WITH w1 "
+        f"MATCH (w2:GenomicWindow) "
+        f"WHERE w2.chr = $chr AND w2.population = $pop2 "
+        f"AND w2.start = w1.start AND w2.end = w1.end "
+        f"AND w2.{prop} IS NOT NULL "
+        f"RETURN w1.start AS window_start, "
+        f"w1.end AS window_end, "
+        f"w1.{prop} AS {stat}_{pop1}, "
+        f"w2.{prop} AS {stat}_{pop2}, "
+        f"(w1.{prop} - w2.{prop}) AS delta, "
+        f"abs(w1.{prop} - w2.{prop}) AS abs_delta "
+        f"ORDER BY w1.start LIMIT $limit"
+    )
+    return ctx.run(cypher, params)
+
+
+def _compare_variant_stat(ctx, pop1, pop2, chr, stat, limit):
+    """Compare variant-based statistics (ihs) between two populations."""
+    prop1 = f"{stat}_{pop1}"
+    prop2 = f"{stat}_{pop2}"
+    params = {"chr": chr, "limit": limit}
+
+    cypher = (
+        f"MATCH (v:Variant) "
+        f"WHERE v.chr = $chr "
+        f"AND v.{prop1} IS NOT NULL AND v.{prop2} IS NOT NULL "
+        f"RETURN v.pos AS pos, "
+        f"v.variantId AS variantId, "
+        f"v.{prop1} AS {stat}_{pop1}, "
+        f"v.{prop2} AS {stat}_{pop2}, "
+        f"(v.{prop1} - v.{prop2}) AS delta, "
+        f"abs(v.{prop1} - v.{prop2}) AS abs_delta "
+        f"ORDER BY v.pos LIMIT $limit"
+    )
+    return ctx.run(cypher, params)