graphpop-cli 0.1.0__tar.gz

graphpop_cli-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: graphpop-cli
+Version: 0.1.0
+Summary: Graph database-native population genomics CLI with O(V*K) complexity
+Author: Jianfeng Mao
+License: MIT
+Project-URL: Homepage, https://github.com/jfmao/GraphPop
+Project-URL: Repository, https://github.com/jfmao/GraphPop
+Project-URL: Issues, https://github.com/jfmao/GraphPop/issues
+Keywords: population-genomics,graph-database,neo4j,bioinformatics,genetics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: neo4j>=5.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == "plot"
+Requires-Dist: numpy>=1.22; extra == "plot"
+
+# GraphPop CLI
+
+Command-line interface for **GraphPop** — a graph database-native population genomics engine that reduces summary statistic complexity from O(V×N) to O(V×K), independent of sample count.
+
+## Quick Start
+
+```bash
+pip install graphpop-cli
+graphpop setup --password mypass    # Downloads Neo4j + procedures plugin
+graphpop start                      # Start the database
+```
+
+**Prerequisites:** Python 3.10+, Java 21+ (for Neo4j runtime).
+
+## Features
+
+- **60 commands** across 11 functional domains
+- **12 population genetics procedures**: diversity, Fst, SFS, iHS, XP-EHH, nSL, ROH, Garud's H, LD, genome scan, pop summary, joint SFS
+- **Annotation conditioning**: `--consequence`, `--pathway`, `--gene` flags on any procedure
+- **Persistent analytical records**: `--persist` writes results to graph nodes
+- **Publication-ready plots**: 11 visualization types following Nature Methods guidelines
+
+## Usage
+
+```bash
+# Population diversity
+graphpop diversity chr1 1 50000000 EUR -o diversity.tsv
+
+# Annotation-conditioned analysis
+graphpop diversity chr1 1 43270923 GJ-tmp --consequence missense_variant
+
+# Selection scan
+graphpop ihs chr22 EUR --persist -o ihs.tsv
+
+# Multi-statistic convergence
+graphpop converge --stats ihs,xpehh,h12 --thresholds 2,2,0.3 --pop EUR
+```
+
+## Documentation
+
+- [Full documentation](https://github.com/jfmao/GraphPop)
+- [Rice 3K vignette](https://github.com/jfmao/GraphPop/blob/main/graphpop-cli/vignettes/rice-3k-analysis.md)
+- [Human 1000G vignette](https://github.com/jfmao/GraphPop/blob/main/graphpop-cli/vignettes/human-1000g-analysis.md)
+
+## License
+
+MIT

graphpop_cli-0.1.0/README.md

@@ -0,0 +1,47 @@
+# GraphPop CLI
+
+Command-line interface for **GraphPop** — a graph database-native population genomics engine that reduces summary statistic complexity from O(V×N) to O(V×K), independent of sample count.
+
+## Quick Start
+
+```bash
+pip install graphpop-cli
+graphpop setup --password mypass    # Downloads Neo4j + procedures plugin
+graphpop start                      # Start the database
+```
+
+**Prerequisites:** Python 3.10+, Java 21+ (for Neo4j runtime).
+
+## Features
+
+- **60 commands** across 11 functional domains
+- **12 population genetics procedures**: diversity, Fst, SFS, iHS, XP-EHH, nSL, ROH, Garud's H, LD, genome scan, pop summary, joint SFS
+- **Annotation conditioning**: `--consequence`, `--pathway`, `--gene` flags on any procedure
+- **Persistent analytical records**: `--persist` writes results to graph nodes
+- **Publication-ready plots**: 11 visualization types following Nature Methods guidelines
+
+## Usage
+
+```bash
+# Population diversity
+graphpop diversity chr1 1 50000000 EUR -o diversity.tsv
+
+# Annotation-conditioned analysis
+graphpop diversity chr1 1 43270923 GJ-tmp --consequence missense_variant
+
+# Selection scan
+graphpop ihs chr22 EUR --persist -o ihs.tsv
+
+# Multi-statistic convergence
+graphpop converge --stats ihs,xpehh,h12 --thresholds 2,2,0.3 --pop EUR
+```
+
+## Documentation
+
+- [Full documentation](https://github.com/jfmao/GraphPop)
+- [Rice 3K vignette](https://github.com/jfmao/GraphPop/blob/main/graphpop-cli/vignettes/rice-3k-analysis.md)
+- [Human 1000G vignette](https://github.com/jfmao/GraphPop/blob/main/graphpop-cli/vignettes/human-1000g-analysis.md)
+
+## License
+
+MIT

graphpop_cli-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "graphpop-cli"
+version = "0.1.0"
+description = "Graph database-native population genomics CLI with O(V*K) complexity"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Jianfeng Mao"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+keywords = ["population-genomics", "graph-database", "neo4j", "bioinformatics", "genetics"]
+dependencies = [
+    "click>=8.0",
+    "neo4j>=5.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+plot = [
+    "matplotlib>=3.5",
+    "numpy>=1.22",
+]
+
+[project.urls]
+Homepage = "https://github.com/jfmao/GraphPop"
+Repository = "https://github.com/jfmao/GraphPop"
+Issues = "https://github.com/jfmao/GraphPop/issues"
+
+[project.scripts]
+graphpop = "graphpop_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

graphpop_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

graphpop_cli-0.1.0/src/graphpop_cli/__init__.py

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

graphpop_cli-0.1.0/src/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-0.1.0/src/graphpop_cli/commands/__init__.py

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

graphpop_cli-0.1.0/src/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)