graphpop-cli 0.1.0__py3-none-any.whl

graphpop_cli/commands/lookup.py

@@ -0,0 +1,207 @@
+"""graphpop lookup — query genes, pathways, variants, and regions in the graph."""
+from __future__ import annotations
+
+import click
+
+from ..cli import pass_ctx
+from ..formatters import format_output
+
+
+@click.group()
+def lookup():
+    """Look up genes, pathways, variants, or genomic regions.
+
+    \b
+    Subcommands:
+      gene      Look up a gene by symbol or ID
+      pathway   Look up a pathway by name
+      variant   Look up a variant by ID
+      region    Look up genes and stats in a genomic region
+
+    \b
+    Examples:
+      graphpop lookup gene KCNE1
+      graphpop lookup pathway "Cardiac repolarization"
+      graphpop lookup variant chr22:16050075:A:G
+      graphpop lookup region chr6 9000000 9600000
+    """
+    pass
+
+
+@lookup.command("gene")
+@click.argument("gene_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 lookup_gene(ctx, gene_name, output_path, fmt):
+    """Look up a gene: variant count, consequences, pathways, and selection stats.
+
+    GENE_NAME can be a gene symbol (e.g., KCNE1) or gene ID (e.g., ENSG00000180509).
+
+    \b
+    Examples:
+      graphpop lookup gene KCNE1
+      graphpop lookup gene GW5 -o gw5_info.tsv
+      graphpop lookup gene ENSG00000180509 --format json
+    """
+    cypher = """
+    MATCH (g:Gene)
+    WHERE g.symbol = $gene_name OR g.geneId = $gene_name
+    OPTIONAL MATCH (v:Variant)-[:HAS_CONSEQUENCE]->(g)
+    OPTIONAL MATCH (g)-[:IN_PATHWAY]->(pw:Pathway)
+    WITH g, v, COLLECT(DISTINCT pw.name) AS pathways
+    RETURN g.symbol AS gene,
+           g.geneId AS gene_id,
+           g.chr AS chr,
+           g.start AS start,
+           g.end AS end,
+           v.variantId AS variant_id,
+           v.pos AS pos,
+           v.ref AS ref,
+           v.alt AS alt,
+           pathways,
+           CASE WHEN v IS NOT NULL THEN [k IN keys(v) WHERE k STARTS WITH 'ihs_' | k + '=' + toString(v[k])] ELSE [] END AS ihs_scores,
+           CASE WHEN v IS NOT NULL THEN [k IN keys(v) WHERE k STARTS WITH 'xpehh_' | k + '=' + toString(v[k])] ELSE [] END AS xpehh_scores
+    ORDER BY v.pos
+    """
+    records = ctx.run(cypher, {"gene_name": gene_name})
+
+    if not records:
+        click.echo(f"Gene '{gene_name}' not found in the graph.", err=True)
+        return
+
+    click.echo(f"Found {len(records)} variants for gene {gene_name}.", err=True)
+    format_output(records, output_path, fmt, "lookup gene",
+                  {"gene": gene_name})
+
+
+@lookup.command("pathway")
+@click.argument("pw_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 lookup_pathway(ctx, pw_name, output_path, fmt):
+    """Look up a pathway: member genes and variant counts.
+
+    PW_NAME is matched as a substring (CONTAINS) against pathway names.
+
+    \b
+    Examples:
+      graphpop lookup pathway "Cardiac repolarization"
+      graphpop lookup pathway "starch" -o starch_pathway.tsv
+    """
+    cypher = """
+    MATCH (pw:Pathway)
+    WHERE pw.name CONTAINS $pw_name
+    OPTIONAL MATCH (g:Gene)-[:IN_PATHWAY]->(pw)
+    OPTIONAL MATCH (v:Variant)-[:HAS_CONSEQUENCE]->(g)
+    WITH pw, g, COUNT(DISTINCT v) AS variant_count
+    RETURN pw.name AS pathway,
+           pw.pathwayId AS pathway_id,
+           g.symbol AS gene,
+           g.geneId AS gene_id,
+           g.chr AS chr,
+           g.start AS gene_start,
+           g.end AS gene_end,
+           variant_count
+    ORDER BY pw.name, g.symbol
+    """
+    records = ctx.run(cypher, {"pw_name": pw_name})
+
+    if not records:
+        click.echo(f"No pathways matching '{pw_name}' found.", err=True)
+        return
+
+    click.echo(f"Found {len(records)} gene entries across matching pathways.", err=True)
+    format_output(records, output_path, fmt, "lookup pathway",
+                  {"pathway": pw_name})
+
+
+@lookup.command("variant")
+@click.argument("var_id")
+@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 lookup_variant(ctx, var_id, output_path, fmt):
+    """Full annotation for a single variant.
+
+    VAR_ID format: chr:pos:ref:alt (e.g., chr22:16050075:A:G).
+
+    \b
+    Examples:
+      graphpop lookup variant chr22:16050075:A:G
+      graphpop lookup variant Chr01:12345:A:T --format json
+    """
+    cypher = """
+    MATCH (v:Variant {variantId: $var_id})
+    OPTIONAL MATCH (v)-[:HAS_CONSEQUENCE]->(g:Gene)
+    OPTIONAL MATCH (g)-[:IN_PATHWAY]->(pw:Pathway)
+    RETURN v AS variant_props,
+           g.symbol AS gene,
+           g.geneId AS gene_id,
+           COLLECT(DISTINCT pw.name) AS pathways
+    """
+    records = ctx.run(cypher, {"var_id": var_id})
+
+    if not records:
+        click.echo(f"Variant '{var_id}' not found.", err=True)
+        return
+
+    # Flatten variant properties into columns
+    flat_records = []
+    for rec in records:
+        row = {}
+        vprops = rec.get("variant_props", {})
+        if vprops:
+            for k, v in vprops.items():
+                row[k] = v
+        row["gene"] = rec.get("gene")
+        row["gene_id"] = rec.get("gene_id")
+        row["pathways"] = rec.get("pathways", [])
+        flat_records.append(row)
+
+    format_output(flat_records, output_path, fmt, "lookup variant",
+                  {"variant_id": var_id})
+
+
+@lookup.command("region")
+@click.argument("chr")
+@click.argument("start", type=int)
+@click.argument("end", 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"]))
+@pass_ctx
+def lookup_region(ctx, chr, start, end, output_path, fmt):
+    """Genes and summary stats in a genomic region.
+
+    Returns per-gene variant counts and mean allele frequencies in the region.
+
+    \b
+    Examples:
+      graphpop lookup region chr6 9000000 9600000
+      graphpop lookup region chr22 16000000 17000000 -o region.tsv
+    """
+    cypher = """
+    MATCH (v:Variant)
+    WHERE v.chr = $chr AND v.pos >= $start AND v.pos <= $end
+    OPTIONAL MATCH (v)-[:HAS_CONSEQUENCE]->(g:Gene)
+    WITH g, COUNT(DISTINCT v) AS variant_count,
+         MIN(v.pos) AS min_pos, MAX(v.pos) AS max_pos
+    RETURN COALESCE(g.symbol, 'intergenic') AS gene,
+           g.geneId AS gene_id,
+           g.start AS gene_start,
+           g.end AS gene_end,
+           variant_count,
+           min_pos,
+           max_pos
+    ORDER BY min_pos
+    """
+    records = ctx.run(cypher, {"chr": chr, "start": start, "end": end})
+
+    if not records:
+        click.echo(f"No variants found in {chr}:{start}-{end}.", err=True)
+        return
+
+    click.echo(f"Found {len(records)} genes/regions in {chr}:{start}-{end}.", err=True)
+    format_output(records, output_path, fmt, "lookup region",
+                  {"chr": chr, "start": start, "end": end})

graphpop_cli/commands/neighbors.py

@@ -0,0 +1,175 @@
+"""graphpop neighbors -- explore the graph neighborhood around a gene."""
+from __future__ import annotations
+
+import click
+
+from ..cli import pass_ctx
+from ..formatters import format_output
+
+
+@click.command()
+@click.argument("gene")
+@click.option("--hops", default=1, type=click.IntRange(1, 3),
+              help="Number of hops to traverse (default: 1, max: 3)")
+@click.option("--via", default="IN_PATHWAY",
+              type=click.Choice(["IN_PATHWAY", "LD", "HAS_GO_TERM"],
+                                case_sensitive=False),
+              help="Relationship type to traverse (default: IN_PATHWAY)")
+@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 neighbors(ctx, gene, hops, via, output_path, fmt):
+    """Explore the graph neighborhood around a gene.
+
+    Traverses shared pathways, LD edges, or GO terms to find related genes.
+
+    \b
+    Examples:
+      graphpop neighbors KCNE1 -o neighbors.tsv
+      graphpop neighbors KCNE1 --hops 2 -o neighbors_2hop.tsv
+      graphpop neighbors GW5 --via HAS_GO_TERM --format json
+    """
+    via = via.upper()
+
+    if via == "IN_PATHWAY":
+        cypher, params = _pathway_query(hops)
+    elif via == "LD":
+        cypher, params = _ld_query(hops)
+    elif via == "HAS_GO_TERM":
+        cypher, params = _go_query(hops)
+    else:
+        click.echo(f"Unsupported --via type: {via}", err=True)
+        raise SystemExit(1)
+
+    params["gene"] = gene
+    records = ctx.run(cypher, params)
+
+    if not records:
+        click.echo(f"No neighbors found for gene '{gene}' via {via} "
+                    f"({hops} hop(s)).", err=True)
+        return
+
+    click.echo(f"Found {len(records)} neighbor(s) for {gene} via {via} "
+                f"({hops} hop(s)).", err=True)
+    format_output(records, output_path, fmt, "neighbors",
+                  {"gene": gene, "hops": hops, "via": via})
+
+
+def _pathway_query(hops: int) -> tuple[str, dict]:
+    """Build pathway-based neighbor query."""
+    if hops == 1:
+        return (
+            "MATCH (g1:Gene)-[:IN_PATHWAY]->(p:Pathway)<-[:IN_PATHWAY]-(g2:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) AND g1 <> g2 "
+            "RETURN DISTINCT g2.symbol AS gene, p.name AS shared_pathway, "
+            "g2.chr AS chr, g2.start AS start, g2.end AS end "
+            "ORDER BY gene",
+            {},
+        )
+    elif hops == 2:
+        return (
+            "MATCH (g1:Gene)-[:IN_PATHWAY]->(p1:Pathway)<-[:IN_PATHWAY]-(g2:Gene)"
+            "-[:IN_PATHWAY]->(p2:Pathway)<-[:IN_PATHWAY]-(g3:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) "
+            "AND g1 <> g2 AND g1 <> g3 AND g2 <> g3 "
+            "RETURN DISTINCT g3.symbol AS gene, "
+            "g2.symbol AS via_gene, p1.name AS pathway_1, p2.name AS pathway_2, "
+            "g3.chr AS chr, g3.start AS start, g3.end AS end "
+            "ORDER BY gene",
+            {},
+        )
+    else:  # hops == 3
+        return (
+            "MATCH path = (g1:Gene)"
+            "(-[:IN_PATHWAY]->(:Pathway)<-[:IN_PATHWAY]-(:Gene)){3} "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) "
+            "WITH g1, last(nodes(path)) AS g_end, "
+            "[n IN nodes(path) WHERE 'Pathway' IN labels(n) | n.name] AS pws, "
+            "[n IN nodes(path) WHERE 'Gene' IN labels(n) | n.symbol] AS genes "
+            "WHERE g1 <> g_end "
+            "RETURN DISTINCT g_end.symbol AS gene, "
+            "g_end.chr AS chr, g_end.start AS start, g_end.end AS end, "
+            "pws AS pathways, genes AS via_genes "
+            "ORDER BY gene "
+            "LIMIT 500",
+            {},
+        )
+
+
+def _ld_query(hops: int) -> tuple[str, dict]:
+    """Build LD-based neighbor query."""
+    if hops == 1:
+        return (
+            "MATCH (g1:Gene)<-[:HAS_CONSEQUENCE]-(v1:Variant)"
+            "-[ld:LD]-(v2:Variant)-[:HAS_CONSEQUENCE]->(g2:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) AND g1 <> g2 "
+            "RETURN DISTINCT g2.symbol AS gene, "
+            "max(ld.r2) AS max_r2, g2.chr AS chr "
+            "ORDER BY max_r2 DESC",
+            {},
+        )
+    elif hops == 2:
+        return (
+            "MATCH (g1:Gene)<-[:HAS_CONSEQUENCE]-(v1:Variant)"
+            "-[:LD]-(v2:Variant)-[:LD]-(v3:Variant)"
+            "-[:HAS_CONSEQUENCE]->(g2:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) AND g1 <> g2 "
+            "RETURN DISTINCT g2.symbol AS gene, g2.chr AS chr "
+            "ORDER BY gene "
+            "LIMIT 500",
+            {},
+        )
+    else:  # hops == 3
+        return (
+            "MATCH (g1:Gene)<-[:HAS_CONSEQUENCE]-(v1:Variant)"
+            "-[:LD]-(v2:Variant)-[:LD]-(v3:Variant)-[:LD]-(v4:Variant)"
+            "-[:HAS_CONSEQUENCE]->(g2:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) AND g1 <> g2 "
+            "RETURN DISTINCT g2.symbol AS gene, g2.chr AS chr "
+            "ORDER BY gene "
+            "LIMIT 500",
+            {},
+        )
+
+
+def _go_query(hops: int) -> tuple[str, dict]:
+    """Build GO term-based neighbor query."""
+    if hops == 1:
+        return (
+            "MATCH (g1:Gene)-[:HAS_GO_TERM]->(go:GOTerm)<-[:HAS_GO_TERM]-(g2:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) AND g1 <> g2 "
+            "RETURN DISTINCT g2.symbol AS gene, go.name AS shared_go_term, "
+            "go.goId AS go_id, g2.chr AS chr "
+            "ORDER BY gene",
+            {},
+        )
+    elif hops == 2:
+        return (
+            "MATCH (g1:Gene)-[:HAS_GO_TERM]->(:GOTerm)<-[:HAS_GO_TERM]-(g2:Gene)"
+            "-[:HAS_GO_TERM]->(go2:GOTerm)<-[:HAS_GO_TERM]-(g3:Gene) "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) "
+            "AND g1 <> g2 AND g1 <> g3 AND g2 <> g3 "
+            "RETURN DISTINCT g3.symbol AS gene, "
+            "g2.symbol AS via_gene, go2.name AS go_term, "
+            "g3.chr AS chr "
+            "ORDER BY gene "
+            "LIMIT 500",
+            {},
+        )
+    else:  # hops == 3
+        return (
+            "MATCH path = (g1:Gene)"
+            "(-[:HAS_GO_TERM]->(:GOTerm)<-[:HAS_GO_TERM]-(:Gene)){3} "
+            "WHERE (g1.symbol = $gene OR g1.geneId = $gene) "
+            "WITH g1, last(nodes(path)) AS g_end, "
+            "[n IN nodes(path) WHERE 'GOTerm' IN labels(n) | n.name] AS terms, "
+            "[n IN nodes(path) WHERE 'Gene' IN labels(n) | n.symbol] AS genes "
+            "WHERE g1 <> g_end "
+            "RETURN DISTINCT g_end.symbol AS gene, "
+            "g_end.chr AS chr, "
+            "terms AS go_terms, genes AS via_genes "
+            "ORDER BY gene "
+            "LIMIT 500",
+            {},
+        )

graphpop_cli/commands/nsl.py

@@ -0,0 +1,29 @@
+"""graphpop nsl — number of segregating sites by length."""
+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 nSL 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 nsl(ctx, chr, population, min_af, persist, output_path, fmt):
+    """Compute number of segregating sites by length (nSL)."""
+    opts = build_options_map(min_af=min_af, persist=persist)
+    cypher = build_cypher(
+        "graphpop.nsl",
+        [f"'{chr}'", f"'{population}'"],
+        options=opts if opts else None,
+        yield_cols=["variantId", "pos", "af", "nsl_unstd", "nsl"],
+    )
+    records = ctx.run(cypher)
+    format_output(records, output_path, fmt, "nsl",
+                  {"chr": chr, "pop": population, "min_af": min_af,
+                   "persist": persist})