graphpop-cli 0.1.0__py3-none-any.whl

graphpop_cli/commands/extract.py

@@ -0,0 +1,271 @@
+"""graphpop extract — extract variants, samples, and genotypes from the graph."""
+from __future__ import annotations
+
+import click
+
+from ..cli import pass_ctx
+from ..formatters import format_output
+
+
+@click.group()
+def extract():
+    """Extract data from the graph: variants, samples, or genotypes.
+
+    \b
+    Subcommands:
+      variants   Query Variant nodes with flexible filters
+      samples    Query Sample nodes for a population
+      genotypes  Extract sample x variant dosage matrix for a region
+
+    \b
+    Examples:
+      graphpop extract variants --chr chr22 --pop EUR --consequence missense_variant -o variants.tsv
+      graphpop extract samples --pop EUR -o samples.tsv
+      graphpop extract genotypes --chr chr22 --start 16000000 --end 17000000 --pop EUR -o geno.tsv
+    """
+    pass
+
+
+@extract.command("variants")
+@click.option("--chr", "chromosome", help="Chromosome filter")
+@click.option("--start", type=int, help="Region start position")
+@click.option("--end", type=int, help="Region end position")
+@click.option("--pop", "population", help="Population name (for AF lookup)")
+@click.option("--min-af", type=float, help="Minimum allele frequency")
+@click.option("--max-af", type=float, help="Maximum allele frequency")
+@click.option("--consequence", help="VEP consequence type (e.g., missense_variant)")
+@click.option("--pathway", help="Pathway name (substring match)")
+@click.option("--gene", help="Gene symbol or ID")
+@click.option("--fields", default="variantId,pos,ref,alt,af",
+              help="Comma-separated fields to return (default: variantId,pos,ref,alt,af)")
+@click.option("--limit", type=int, default=10000, help="Maximum rows (default: 10000)")
+@click.option("-o", "--output", "output_path", help="Output file (default: stdout)")
+@click.option("--format", "fmt", default="tsv", type=click.Choice(["tsv", "csv", "json"]))
+@pass_ctx
+def extract_variants(ctx, chromosome, start, end, population, min_af, max_af,
+                     consequence, pathway, gene, fields, limit, output_path, fmt):
+    """Query Variant nodes with optional filters.
+
+    Builds Cypher dynamically based on provided filters. Use --fields to
+    select which variant properties to return.
+
+    \b
+    Examples:
+      graphpop extract variants --chr chr22 --pop EUR --consequence missense_variant -o variants.tsv
+      graphpop extract variants --chr chr22 --start 16000000 --end 17000000 --fields pos,ref,alt,af,fst,ihs -o region.tsv
+      graphpop extract variants --gene KCNE1 --pop EUR -o kcne1_variants.tsv
+    """
+    field_list = [f.strip() for f in fields.split(",")]
+    params = {}
+
+    # Build MATCH clause with optional annotation joins
+    match_clause = "MATCH (v:Variant)"
+    where_parts = []
+
+    if consequence:
+        match_clause += "-[:HAS_CONSEQUENCE]->(hc)"
+        where_parts.append("hc.consequence = $consequence")
+        params["consequence"] = consequence
+    if gene:
+        if "-[:HAS_CONSEQUENCE]->" not in match_clause:
+            match_clause += "-[:HAS_CONSEQUENCE]->(g:Gene)"
+        else:
+            match_clause = "MATCH (v:Variant)-[:HAS_CONSEQUENCE]->(g:Gene)"
+            if consequence:
+                match_clause = "MATCH (v:Variant)-[hc_rel:HAS_CONSEQUENCE]->(g:Gene)"
+                where_parts = [p for p in where_parts if "hc.consequence" not in p]
+                where_parts.append("hc_rel.consequence = $consequence")
+        where_parts.append("(g.symbol = $gene OR g.geneId = $gene)")
+        params["gene"] = gene
+    if pathway:
+        if "Gene" not in match_clause:
+            match_clause += "-[:HAS_CONSEQUENCE]->(g:Gene)-[:IN_PATHWAY]->(pw:Pathway)"
+        else:
+            match_clause += "-[:IN_PATHWAY]->(pw:Pathway)"
+        where_parts.append("pw.name CONTAINS $pathway")
+        params["pathway"] = pathway
+
+    if chromosome:
+        where_parts.append("v.chr = $chromosome")
+        params["chromosome"] = chromosome
+    if start is not None:
+        where_parts.append("v.pos >= $start")
+        params["start"] = start
+    if end is not None:
+        where_parts.append("v.pos <= $end")
+        params["end"] = end
+
+    # AF filtering: if population is given, look up index in pop_ids array
+    if population and (min_af is not None or max_af is not None):
+        params["population"] = population
+        if min_af is not None:
+            where_parts.append(
+                "ANY(i IN range(0, size(v.pop_ids)-1) "
+                "WHERE v.pop_ids[i] = $population AND v.af[i] >= $min_af)"
+            )
+            params["min_af"] = min_af
+        if max_af is not None:
+            where_parts.append(
+                "ANY(i IN range(0, size(v.pop_ids)-1) "
+                "WHERE v.pop_ids[i] = $population AND v.af[i] <= $max_af)"
+            )
+            params["max_af"] = max_af
+
+    # Build RETURN clause from requested fields
+    return_cols = []
+    for f in field_list:
+        if f == "af" and population:
+            if "population" not in params:
+                params["population"] = population
+            return_cols.append(
+                "[i IN range(0, size(v.pop_ids)-1) "
+                "WHERE v.pop_ids[i] = $population | v.af[i]][0] AS af_" + population
+            )
+        elif f in ("gene", "gene_symbol") and "Gene" in match_clause:
+            return_cols.append("g.symbol AS gene")
+        elif f == "consequence" and consequence:
+            col = "hc.consequence" if "hc)" in match_clause else "hc_rel.consequence"
+            return_cols.append(f"{col} AS consequence")
+        else:
+            return_cols.append(f"v.{f} AS {f}")
+
+    params["limit"] = limit
+    where_str = " AND ".join(where_parts) if where_parts else "true"
+    cypher = (
+        f"{match_clause} "
+        f"WHERE {where_str} "
+        f"RETURN DISTINCT {', '.join(return_cols)} "
+        f"ORDER BY v.pos LIMIT $limit"
+    )
+
+    records = ctx.run(cypher, params)
+    if not records:
+        click.echo("No variants found with given filters.", err=True)
+        return
+
+    click.echo(f"Found {len(records)} variants.", err=True)
+    format_output(records, output_path, fmt, "extract variants",
+                  {"chr": chromosome, "start": start, "end": end,
+                   "pop": population, "consequence": consequence,
+                   "pathway": pathway, "gene": gene})
+
+
+@extract.command("samples")
+@click.option("--pop", "population", required=True, help="Population name")
+@click.option("-o", "--output", "output_path", help="Output file (default: stdout)")
+@click.option("--format", "fmt", default="tsv", type=click.Choice(["tsv", "csv", "json"]))
+@pass_ctx
+def extract_samples(ctx, population, output_path, fmt):
+    """Query Sample nodes for a population.
+
+    Returns sampleId, population, and packed_index for each sample. If
+    population-level summary stats (e.g., FROH) are available, they are
+    included.
+
+    \b
+    Examples:
+      graphpop extract samples --pop EUR -o samples.tsv
+      graphpop extract samples --pop GJ-tmp --format json
+    """
+    cypher = """
+    MATCH (s:Sample)
+    WHERE s.population = $population
+    OPTIONAL MATCH (p:Population {name: $population})
+    RETURN s.sampleId AS sampleId,
+           s.population AS population,
+           s.packed_index AS packed_index,
+           s.froh AS froh,
+           p.n_samples AS pop_n_samples,
+           p.mean_froh AS pop_mean_froh
+    ORDER BY s.packed_index
+    """
+    records = ctx.run(cypher, {"population": population})
+    if not records:
+        click.echo(f"No samples found for population '{population}'.", err=True)
+        return
+
+    click.echo(f"Found {len(records)} samples for {population}.", err=True)
+    format_output(records, output_path, fmt, "extract samples",
+                  {"population": population})
+
+
+@extract.command("genotypes")
+@click.option("--chr", "chromosome", required=True, help="Chromosome")
+@click.option("--start", type=int, required=True, help="Region start position")
+@click.option("--end", type=int, required=True, help="Region end position")
+@click.option("--pop", "population", required=True, help="Population name")
+@click.option("--format-gt", "gt_format", default="dosage",
+              type=click.Choice(["dosage", "gt", "raw"]),
+              help="Output format: dosage (0/1/2), gt (0/0, 0/1, 1/1), or raw (hex gt_packed)")
+@click.option("--limit", type=int, default=1000, help="Maximum variants (default: 1000)")
+@click.option("-o", "--output", "output_path", help="Output file (default: stdout)")
+@click.option("--format", "fmt", default="tsv", type=click.Choice(["tsv", "csv", "json"]))
+@pass_ctx
+def extract_genotypes(ctx, chromosome, start, end, population, gt_format,
+                      limit, output_path, fmt):
+    """Extract genotype data for a region and population.
+
+    Queries CARRIES edges between Sample and Variant nodes to build a
+    sample x variant matrix. For large regions, consider using --limit
+    to cap the number of variants.
+
+    Note: gt_packed decoding requires bit operations. With --format-gt raw,
+    the raw gt_packed byte array is returned as a hex string per variant.
+    With dosage or gt mode, individual CARRIES edges are queried instead.
+
+    \b
+    Examples:
+      graphpop extract genotypes --chr chr22 --start 16000000 --end 17000000 --pop EUR -o geno.tsv
+      graphpop extract genotypes --chr chr22 --start 16000000 --end 17000000 --pop EUR --format-gt raw -o geno_raw.tsv
+    """
+    params = {
+        "chromosome": chromosome,
+        "start": start,
+        "end": end,
+        "population": population,
+        "limit": limit,
+    }
+
+    if gt_format == "raw":
+        # Return per-variant summary with raw gt_packed as hex
+        cypher = (
+            "MATCH (v:Variant) "
+            "WHERE v.chr = $chromosome AND v.pos >= $start AND v.pos <= $end "
+            "RETURN v.variantId AS variantId, v.pos AS pos, v.ref AS ref, v.alt AS alt, "
+            "v.gt_packed AS gt_packed_hex, "
+            "[i IN range(0, size(v.pop_ids)-1) "
+            "WHERE v.pop_ids[i] = $population | v.af[i]][0] AS af "
+            "ORDER BY v.pos LIMIT $limit"
+        )
+        records = ctx.run(cypher, params)
+        if not records:
+            click.echo("No variants found in region.", err=True)
+            return
+        click.echo(f"Found {len(records)} variants (raw gt_packed mode).", err=True)
+        format_output(records, output_path, fmt, "extract genotypes",
+                      {"chr": chromosome, "start": start, "end": end,
+                       "pop": population, "format": gt_format})
+    else:
+        # Query CARRIES edges for individual genotypes
+        gt_label = "c.gt" if gt_format == "dosage" else (
+            "CASE c.gt WHEN 1 THEN '0/1' WHEN 2 THEN '1/1' ELSE '0/0' END"
+        )
+        params["carries_limit"] = limit * 100
+        cypher = (
+            "MATCH (s:Sample)-[c:CARRIES]->(v:Variant) "
+            "WHERE s.population = $population "
+            "AND v.chr = $chromosome AND v.pos >= $start AND v.pos <= $end "
+            "RETURN s.sampleId AS sampleId, v.variantId AS variantId, "
+            f"v.pos AS pos, {gt_label} AS genotype "
+            "ORDER BY v.pos, s.sampleId "
+            "LIMIT $carries_limit"
+        )
+        records = ctx.run(cypher, params)
+        if not records:
+            click.echo("No genotype data found. CARRIES edges may not exist "
+                       "for this region/population.", err=True)
+            return
+        click.echo(f"Found {len(records)} genotype entries.", err=True)
+        format_output(records, output_path, fmt, "extract genotypes",
+                      {"chr": chromosome, "start": start, "end": end,
+                       "pop": population, "format": gt_format})

graphpop_cli/commands/filter_results.py

@@ -0,0 +1,165 @@
+"""graphpop filter — query persisted results with annotation filters."""
+from __future__ import annotations
+
+import click
+
+from ..cli import pass_ctx
+from ..formatters import format_output
+
+
+@click.command("filter")
+@click.argument("statistic", type=click.Choice([
+    "ihs", "xpehh", "nsl", "fst", "pi", "tajima_d", "h12",
+]))
+@click.argument("chr")
+@click.argument("population")
+@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("--consequence", help="Filter by VEP consequence type (e.g., missense_variant)")
+@click.option("--pathway", help="Filter by pathway name")
+@click.option("--gene", help="Filter by gene name or ID")
+@click.option("--min-score", type=float, help="Minimum absolute score")
+@click.option("--max-score", type=float, help="Maximum absolute score")
+@click.option("--pop2", help="Second population (for xpehh)")
+@click.option("--limit", type=int, default=10000, help="Maximum rows (default: 10000)")
+@pass_ctx
+def filter_results(ctx, statistic, chr, population, output_path, fmt,
+                   consequence, pathway, gene, min_score, max_score, pop2, limit):
+    """Query persisted statistics with annotation-based filters.
+
+    This command retrieves already-computed statistics (iHS, XP-EHH, nSL, etc.)
+    from graph nodes and filters them by functional annotation. It is the
+    recommended way to perform conditioned analysis for haplotype-based
+    statistics, which must be computed genome-wide first and then filtered.
+
+    \b
+    Workflow:
+      1. Compute statistics:  graphpop ihs chr1 EUR --persist
+      2. Filter by annotation: graphpop filter ihs chr1 EUR --consequence missense_variant
+
+    \b
+    Examples:
+      graphpop filter ihs chr1 EUR --consequence missense_variant -o ihs_missense.tsv
+      graphpop filter xpehh chr1 EUR --pop2 AFR --pathway "Cardiac repolarization"
+      graphpop filter nsl chr1 GJ-tmp --gene GW5 --min-score 2.0
+      graphpop filter h12 chr1 GJ-tmp --consequence missense_variant
+    """
+    # Build the property name for this statistic
+    if statistic == "xpehh" and pop2:
+        prop = f"xpehh_{population}_{pop2}"
+        prop_unstd = f"xpehh_unstd_{population}_{pop2}"
+    elif statistic == "xpehh":
+        # Try to find any xpehh property
+        prop = f"xpehh_{population}_*"
+        click.echo("Warning: --pop2 not specified; will search for any XP-EHH involving this population.", err=True)
+        prop = None
+    elif statistic in ("ihs", "nsl"):
+        prop = f"{statistic}_{population}"
+        prop_unstd = f"{statistic}_unstd_{population}"
+    elif statistic in ("fst", "pi", "tajima_d", "h12"):
+        prop = statistic
+        prop_unstd = None
+    else:
+        prop = statistic
+        prop_unstd = None
+
+    # Build Cypher query
+    params: dict = {"chr": chr, "population": population, "limit": limit}
+
+    if statistic in ("ihs", "xpehh", "nsl"):
+        # Per-variant statistics stored on Variant nodes
+        match_clause = "MATCH (v:Variant)"
+        where_parts = ["v.chr = $chr"]
+        if prop:
+            where_parts.append(f"v.{prop} IS NOT NULL")
+
+        # Annotation join
+        if consequence:
+            match_clause += "-[:HAS_CONSEQUENCE]->(hc)"
+            where_parts.append("hc.consequence = $consequence")
+            params["consequence"] = consequence
+        if pathway:
+            match_clause += "-[:HAS_CONSEQUENCE]->(:Gene)-[:IN_PATHWAY]->(pw:Pathway)"
+            where_parts.append("pw.name CONTAINS $pathway")
+            params["pathway"] = pathway
+        if gene:
+            match_clause += "-[:HAS_CONSEQUENCE]->(g:Gene)"
+            where_parts.append("(g.geneId = $gene OR g.symbol = $gene)")
+            params["gene"] = gene
+
+        if min_score is not None and prop:
+            where_parts.append(f"abs(v.{prop}) >= {min_score}")
+        if max_score is not None and prop:
+            where_parts.append(f"abs(v.{prop}) <= {max_score}")
+
+        return_cols = [
+            "v.variantId AS variant_id",
+            "v.pos AS pos",
+        ]
+        if prop:
+            return_cols.append(f"v.{prop} AS {statistic}")
+        if prop_unstd:
+            return_cols.append(f"v.{prop_unstd} AS {statistic}_unstd")
+        if consequence:
+            return_cols.append("hc.consequence AS consequence")
+            return_cols.append("hc.impact AS impact")
+        if gene:
+            return_cols.append("g.symbol AS gene")
+
+        cypher = (
+            f"{match_clause} "
+            f"WHERE {' AND '.join(where_parts)} "
+            f"RETURN DISTINCT {', '.join(return_cols)} "
+            "ORDER BY v.pos LIMIT $limit"
+        )
+
+    elif statistic == "h12":
+        # Garud's H stored on GenomicWindow nodes
+        match_clause = "MATCH (w:GenomicWindow)"
+        where_parts = [
+            "w.chr = $chr",
+            "w.population = $population",
+        ]
+        if min_score is not None:
+            where_parts.append(f"w.h12 >= {min_score}")
+
+        cypher = (
+            f"{match_clause} "
+            f"WHERE {' AND '.join(where_parts)} "
+            "RETURN w.windowId AS window_id, w.chr AS chr, "
+            "w.start AS start, w.end AS end, "
+            "w.h12 AS h12, w.h2_h1 AS h2_h1, w.hap_diversity AS hap_div "
+            "ORDER BY w.h12 DESC LIMIT $limit"
+        )
+
+    else:
+        # Window-level statistics (fst, pi, tajima_d)
+        match_clause = "MATCH (w:GenomicWindow)"
+        where_parts = [
+            "w.chr = $chr",
+            "w.population = $population",
+        ]
+        if min_score is not None:
+            where_parts.append(f"w.{prop} >= {min_score}")
+        if max_score is not None:
+            where_parts.append(f"w.{prop} <= {max_score}")
+
+        cypher = (
+            f"{match_clause} "
+            f"WHERE {' AND '.join(where_parts)} "
+            f"RETURN w.windowId AS window_id, w.start AS start, w.end AS end, "
+            f"w.{prop} AS {statistic}, w.n_variants AS n_variants "
+            "ORDER BY w.start LIMIT $limit"
+        )
+
+    records = ctx.run(cypher, params)
+
+    if not records:
+        click.echo(f"No results found for {statistic} on {chr}/{population} "
+                    f"with given filters.", err=True)
+        return
+
+    click.echo(f"Found {len(records)} records.", err=True)
+    format_output(records, output_path, fmt, "filter",
+                  {"statistic": statistic, "chr": chr, "population": population,
+                   "consequence": consequence, "pathway": pathway, "gene": gene})

graphpop_cli/commands/garud_h.py

@@ -0,0 +1,30 @@
+"""graphpop garud-h — Garud's H statistics for haplotype homozygosity."""
+import click
+from ..cli import pass_ctx
+from ..config import build_options_map, build_cypher
+from ..formatters import format_output
+
+
+@click.command("garud-h")
+@click.argument("chr")
+@click.argument("population")
+@click.argument("window_size", type=int)
+@click.argument("step_size", type=int)
+@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("--min-af", type=float, help="Minimum allele frequency")
+@pass_ctx
+def garud_h(ctx, chr, population, window_size, step_size, output_path, fmt, min_af):
+    """Compute Garud's H1, H12, H2/H1 in sliding windows."""
+    opts = build_options_map(min_af=min_af)
+    cypher = build_cypher(
+        "graphpop.garud_h",
+        [f"'{chr}'", f"'{population}'", str(window_size), str(step_size)],
+        options=opts if opts else None,
+        yield_cols=["chr", "start", "end", "population", "h1", "h12", "h2_h1",
+                     "hap_diversity", "n_haplotypes", "n_variants"],
+    )
+    records = ctx.run(cypher)
+    format_output(records, output_path, fmt, "garud-h",
+                  {"chr": chr, "pop": population, "window": window_size,
+                   "step": step_size})

graphpop_cli/commands/genome_scan.py

@@ -0,0 +1,41 @@
+"""graphpop genome-scan — sliding-window genome scan."""
+import click
+from ..cli import pass_ctx
+from ..config import build_options_map, build_cypher
+from ..formatters import format_output
+
+
+@click.command("genome-scan")
+@click.argument("chr")
+@click.argument("population")
+@click.argument("window_size", type=int)
+@click.argument("step_size", type=int)
+@click.option("--pop2", help="Second population for Fst/Dxy/PBS")
+@click.option("--persist", is_flag=True, default=False,
+              help="Persist window results to graph (default behavior)")
+@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("--consequence", help="Filter by VEP consequence type")
+@click.option("--pathway", help="Filter by pathway name")
+@click.option("--gene", help="Filter by gene name")
+@click.option("--min-af", type=float, help="Minimum allele frequency")
+@pass_ctx
+def genome_scan(ctx, chr, population, window_size, step_size, pop2, persist,
+                output_path, fmt, consequence, pathway, gene, min_af):
+    """Run a sliding-window genome scan (pi, theta, Tajima's D, Fst, etc.)."""
+    opts = build_options_map(consequence=consequence, pathway=pathway, gene=gene,
+                             min_af=min_af)
+    positional = [f"'{chr}'", f"'{population}'", str(window_size), str(step_size)]
+    if pop2:
+        positional.append(f"'{pop2}'")
+    cypher = build_cypher(
+        "graphpop.genome_scan", positional,
+        options=opts if opts else None,
+        yield_cols=["window_id", "chr", "start", "end", "population",
+                     "n_variants", "n_segregating", "pi", "theta_w", "tajima_d",
+                     "fst", "fst_wc", "dxy", "pbs", "fay_wu_h"],
+    )
+    records = ctx.run(cypher)
+    format_output(records, output_path, fmt, "genome-scan",
+                  {"chr": chr, "pop": population, "window": window_size,
+                   "step": step_size, "pop2": pop2})

graphpop_cli/commands/ihs.py

@@ -0,0 +1,29 @@
+"""graphpop ihs — integrated haplotype score."""
+import click
+from ..cli import pass_ctx
+from ..config import build_options_map, build_cypher
+from ..formatters import format_output
+
+
+@click.command()
+@click.argument("chr")
+@click.argument("population")
+@click.option("--min-af", type=float, help="Minimum allele frequency filter")
+@click.option("--persist", is_flag=True, default=False,
+              help="Write iHS scores to Variant nodes")
+@click.option("-o", "--output", "output_path", help="Output file (default: stdout)")
+@click.option("--format", "fmt", default="tsv", type=click.Choice(["tsv", "csv", "json"]))
+@pass_ctx
+def ihs(ctx, chr, population, min_af, persist, output_path, fmt):
+    """Compute integrated haplotype score (iHS) across a chromosome."""
+    opts = build_options_map(min_af=min_af, persist=persist)
+    cypher = build_cypher(
+        "graphpop.ihs",
+        [f"'{chr}'", f"'{population}'"],
+        options=opts if opts else None,
+        yield_cols=["variantId", "pos", "af", "ihs_unstd", "ihs"],
+    )
+    records = ctx.run(cypher)
+    format_output(records, output_path, fmt, "ihs",
+                  {"chr": chr, "pop": population, "min_af": min_af,
+                   "persist": persist})