TSUMUGI 1.0.1__py3-none-any.whl

TSUMUGI/subcommands/count_filterer.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+from tqdm import tqdm
+
+from TSUMUGI import io_handler
+
+
+def filter_by_number_of_phenotypes_per_gene(
+    path_pairwise_similarity_annotations: str | Path | None,
+    path_genewise_phenotype_annotations: str | Path,
+    min_phenotypes: int | None = None,
+    max_phenotypes: int | None = None,
+) -> None:
+    genewise_phenotype_annotations = io_handler.read_jsonl(path_genewise_phenotype_annotations)
+
+    cnt = Counter(rec["marker_symbol"] for rec in genewise_phenotype_annotations if rec["significant"])
+    matched_genes = {
+        marker
+        for marker, c in cnt.items()
+        if (min_phenotypes is None or c >= min_phenotypes) and (max_phenotypes is None or c <= max_phenotypes)
+    }
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in tqdm(pairwise_similarity_annotations, desc="Filtering gene pairs"):
+        # check both genes in the pair match the criteria
+        if record["gene1_symbol"] in matched_genes and record["gene2_symbol"] in matched_genes:
+            # output to stdout as JSON
+            io_handler.write_jsonl_to_stdout(record)
+
+
+def filter_by_number_of_phenotypes_per_pair(
+    path_pairwise_similarity_annotations: str | Path | None,
+    min_phenotypes: int | None = None,
+    max_phenotypes: int | None = None,
+) -> None:
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in pairwise_similarity_annotations:
+        num_shared_phenotypes = len(record["phenotype_shared_annotations"])
+        if min_phenotypes is not None and num_shared_phenotypes < min_phenotypes:
+            continue
+        if max_phenotypes is not None and num_shared_phenotypes > max_phenotypes:
+            continue
+
+        # output to stdout as JSON
+        io_handler.write_jsonl_to_stdout(record)

TSUMUGI/subcommands/genes_filterer.py

@@ -0,0 +1,89 @@
+from collections.abc import Iterator
+from pathlib import Path
+
+from TSUMUGI import io_handler
+
+###############################################################################
+# filter_annotations_by_genes
+###############################################################################
+
+
+def _filter_annotations_by_genes(
+    pairwise_similarity_annotations: Iterator[dict[str, str | dict[str, dict] | dict[str | int]]],
+    gene_list: set[str],
+    keep: bool = False,
+    drop: bool = False,
+) -> Iterator[dict[str, str | dict[str, dict] | dict[str | int]]]:
+    for pairwise_similarity_annotation in pairwise_similarity_annotations:
+        gene1 = pairwise_similarity_annotation["gene1_symbol"]
+        gene2 = pairwise_similarity_annotation["gene2_symbol"]
+
+        # Keep if either gene is in the list
+        # - gene1: A, gene2: B, gene_list: {A, C} -> Keep
+        # - gene1: D, gene2: E, gene_list: {A, C} -> Drop
+        if (gene1 in gene_list or gene2 in gene_list) and keep:
+            yield pairwise_similarity_annotation
+
+        # Drop only when both genes are not in the list
+        # - gene1: A, gene2: B, gene_list: {A, C} -> Drop
+        # - gene1: D, gene2: E, gene_list: {A, C} -> Keep
+        if (gene1 not in gene_list and gene2 not in gene_list) and drop:
+            yield pairwise_similarity_annotation
+
+
+def filter_annotations_by_genes(
+    path_pairwise_similarity_annotations: str | Path,
+    gene_list: set[str],
+    keep: bool = False,
+    drop: bool = False,
+) -> None:
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in _filter_annotations_by_genes(
+        pairwise_similarity_annotations=pairwise_similarity_annotations,
+        gene_list=gene_list,
+        keep=keep,
+        drop=drop,
+    ):
+        # output to stdout as JSONL
+        io_handler.write_jsonl_to_stdout(record)
+
+
+###############################################################################
+# filter_annotations_by_gene_pairs
+###############################################################################
+
+
+def _filter_annotations_by_gene_pairs(
+    pairwise_similarity_annotations: Iterator[dict[str, str | dict[str, dict] | dict[str | int]]],
+    gene_pairs: set[frozenset[str]],
+    keep: bool = False,
+    drop: bool = False,
+) -> Iterator[dict[str, str | dict[str, dict] | dict[str | int]]]:
+    for pairwise_similarity_annotation in pairwise_similarity_annotations:
+        gene1 = pairwise_similarity_annotation["gene1_symbol"]
+        gene2 = pairwise_similarity_annotation["gene2_symbol"]
+        gene_pair = frozenset({gene1, gene2})
+
+        # Keep if either gene is in the list
+        if gene_pair in gene_pairs and keep:
+            yield pairwise_similarity_annotation
+        # Drop only when both genes are not in the list
+        if gene_pair not in gene_pairs and drop:
+            yield pairwise_similarity_annotation
+
+
+def filter_annotations_by_gene_pairs(
+    path_pairwise_similarity_annotations: str | Path,
+    gene_pairs: set[frozenset[str]],
+    keep: bool = False,
+    drop: bool = False,
+):
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in _filter_annotations_by_gene_pairs(
+        pairwise_similarity_annotations=pairwise_similarity_annotations,
+        gene_pairs=gene_pairs,
+        keep=keep,
+        drop=drop,
+    ):
+        # output to stdout as JSONL
+        io_handler.write_jsonl_to_stdout(record)

TSUMUGI/subcommands/graphml_builder.py

@@ -0,0 +1,158 @@
+import io
+import sys
+from collections import defaultdict
+
+import networkx as nx
+
+from TSUMUGI import io_handler
+
+
+def format_suffix(zygosity: str, life_stage: str, sexual_dimorphism: str) -> str:
+    """Produce strings like (Homo, Early, Male); omit sexual_dimorphism when it equals 'None'."""
+    parts = [zygosity, life_stage]
+    if sexual_dimorphism and sexual_dimorphism != "None":
+        parts.append(sexual_dimorphism)
+    return f"({', '.join(parts)})"
+
+
+def build_nodes(genewise_phenotype_annotations: list[dict]) -> dict:
+    """
+    Read genewise_phenotype_annotations.jsonl.gz and aggregate node attributes per marker_symbol.
+    - node_id: marker_symbol
+    - label: marker_symbol
+    - effect_size: always 1
+    - node_annotations:
+        Phenotypes of GeneA KO mice
+        - vertebral transformation (Homo, Early, Male)
+        ...
+        Associated Human Diseases
+        - Male infertility (Homo, Early)
+        ...
+    """
+    phenotypes_per_gene = defaultdict(list)
+    diseases_per_gene = defaultdict(list)
+
+    for record in genewise_phenotype_annotations:
+        marker_symbol = record["marker_symbol"]
+        mp_term_name = record["mp_term_name"]
+        zygosity = record["zygosity"]
+        life_stage = record["life_stage"]
+        sexual_dimorphism = record.get("sexual_dimorphism", "None")
+        disease_annotation = record.get("disease_annotation", [])
+
+        suffix = format_suffix(zygosity, life_stage, sexual_dimorphism)
+
+        # KO mouse phenotypes
+        pheno_text = f"{mp_term_name} {suffix}"
+        phenotypes_per_gene[marker_symbol].append(pheno_text)
+
+        # Human diseases
+        for d in disease_annotation:
+            disease_text = f"{d} {suffix}"
+            diseases_per_gene[marker_symbol].append(disease_text)
+
+    nodes = {}
+    for marker_symbol in phenotypes_per_gene.keys() | diseases_per_gene.keys():
+        lines = []
+
+        # Phenotypes section
+        lines.append(f"Phenotypes of {marker_symbol} KO mice")
+        for pheno in phenotypes_per_gene.get(marker_symbol, []):
+            lines.append(f"- {pheno}")
+
+        # Diseases section (if available)
+        diseases = diseases_per_gene.get(marker_symbol, [])
+        if diseases:
+            lines.append("Associated Human Diseases")
+            for dis in diseases:
+                lines.append(f"- {dis}")
+
+        node_annotations = "\n".join(lines)
+
+        nodes[marker_symbol] = {
+            "label": marker_symbol,
+            "effect_size": 1.0,
+            "node_annotations": node_annotations,
+        }
+
+    return nodes
+
+
+def build_graph(pairwise_similarity_annotations: list[dict], nodes: dict) -> nx.Graph:
+    """
+    Build a Graph using pairwise_similarity_annotations and the supplied nodes.
+    - Nodes: add the contents from nodes (and create empty nodes for unseen genes)
+    - Edges: gene1_symbol, gene2_symbol
+        - weight: phenotype_similarity_score
+        - edge_annotations:
+          Shared phenotypes of GeneA and GeneB KOs (Similarity: 59)
+          - vertebral transformation (Homo, Early, Male)
+          ...
+    """
+    G = nx.Graph()
+
+    edge_id = 0  # Place outside the loop so multiple edges get sequential IDs
+    geneset = set()
+    # Add edges
+    for record in pairwise_similarity_annotations:
+        g1 = record["gene1_symbol"]
+        g2 = record["gene2_symbol"]
+        score = record["phenotype_similarity_score"]
+        shared = record.get("phenotype_shared_annotations", {})
+
+        # Add missing nodes (genes absent from the genewise data)
+        if g1 not in G:
+            G.add_node(g1, label=g1, effect_size=1.0, node_annotations="")
+        if g2 not in G:
+            G.add_node(g2, label=g2, effect_size=1.0, node_annotations="")
+
+        # Format phenotype_shared_annotations
+        edge_texts = []
+        for mp_term_name, meta in shared.items():
+            zygosity = meta.get("zygosity", "")
+            life_stage = meta.get("life_stage", "")
+            sexual_dimorphism = meta.get("sexual_dimorphism", "None")
+            suffix = format_suffix(zygosity, life_stage, sexual_dimorphism)
+            edge_texts.append(f"{mp_term_name} {suffix}")
+
+        lines = []
+        lines.append(f"Shared phenotypes of {g1} and {g2} KOs (Similarity: {score})")
+        for txt in edge_texts:
+            lines.append(f"- {txt}")
+
+        edge_annotations = "\n".join(lines)
+
+        G.add_edge(
+            g1,
+            g2,
+            id=f"e{edge_id}",
+            weight=score,
+            edge_annotations=edge_annotations,
+        )
+        edge_id += 1
+        geneset.add(g1)
+        geneset.add(g2)
+
+    # Add nodes
+    for node_id, attrs in nodes.items():
+        if node_id in geneset:
+            G.add_node(node_id, **attrs)
+
+    return G
+
+
+def write_graphml_to_stdout(pairwise_path: str, genewise_path: str) -> None:
+    """
+    Write GraphML to stdout using pairwise_similarity_annotations.jsonl.gz
+    and genewise_phenotype_annotations.jsonl.gz.
+    """
+    pairwise_similarity_annotations = io_handler.read_jsonl(pairwise_path)
+    genewise_phenotype_annotations = io_handler.read_jsonl(genewise_path)
+
+    nodes = build_nodes(genewise_phenotype_annotations)
+    G = build_graph(pairwise_similarity_annotations, nodes)
+
+    text_buffer = io.StringIO()
+    nx.write_graphml(G, text_buffer, encoding="unicode")
+
+    sys.stdout.write(text_buffer.getvalue())

TSUMUGI/subcommands/life_stage_filterer.py

@@ -0,0 +1,48 @@
+from collections.abc import Generator
+from pathlib import Path
+
+from TSUMUGI import io_handler
+
+
+def _filter_annotations_by_life_stage(
+    pairwise_similarity_annotations: list[dict[str, str | dict[str, dict] | dict[str | int]]],
+    life_stage: str = "",
+    keep: bool = False,
+    drop: bool = False,
+) -> Generator[frozenset[str], dict[str, dict, int]]:
+    for pairwise_similarity_annotation in pairwise_similarity_annotations:
+        phenotype_shared_annotations = pairwise_similarity_annotation["phenotype_shared_annotations"]
+
+        if len(phenotype_shared_annotations) == 0:
+            continue
+
+        phenotype_shared_annotations_filtered = {}
+        for term_name, annotation in phenotype_shared_annotations.items():
+            if annotation["life_stage"] == life_stage and keep:
+                phenotype_shared_annotations_filtered[term_name] = annotation
+            if annotation["life_stage"] != life_stage and drop:
+                phenotype_shared_annotations_filtered[term_name] = annotation
+
+        if len(phenotype_shared_annotations_filtered) == 0:
+            continue
+
+        pairwise_similarity_annotation["phenotype_shared_annotations"] = phenotype_shared_annotations_filtered
+
+        yield pairwise_similarity_annotation
+
+
+def filter_annotations_by_life_stage(
+    path_pairwise_similarity_annotations: str | Path,
+    life_stage: str,
+    keep: bool = False,
+    drop: bool = False,
+) -> None:
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in _filter_annotations_by_life_stage(
+        pairwise_similarity_annotations=pairwise_similarity_annotations,
+        life_stage=life_stage,
+        keep=keep,
+        drop=drop,
+    ):
+        # output to stdout as JSONL
+        io_handler.write_jsonl_to_stdout(record)

TSUMUGI/subcommands/mp_filterer.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from TSUMUGI import io_handler, ontology_handler
+
+###########################################################
+# Include gene pairs with target_mp_term_id and its descendants
+###########################################################
+
+
+def include_specific_phenotype(
+    path_pairwise_similarity_annotations: str | Path | None,
+    path_genewise_phenotype_annotations: str | Path | None,
+    path_obo: str | Path,
+    mp_term_id: str,
+    life_stage: str | None = None,
+    sex: str | None = None,
+    zygosity: str | None = None,
+    is_pairwise: bool = True,
+) -> None:
+    ontology_terms = io_handler.parse_obo_file(path_obo)
+    _, child_term_map = ontology_handler.build_term_hierarchy(ontology_terms)
+    descendants_of_term_ids = ontology_handler.find_all_descendant_terms(mp_term_id, child_term_map)
+    descendants_of_term_ids.add(mp_term_id)
+    descendants_of_term_name = {
+        data["name"] for term_id, data in ontology_terms.items() if term_id in descendants_of_term_ids
+    }
+
+    if is_pairwise:
+        pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+        for record in pairwise_similarity_annotations:
+            target_term_names = set(record["phenotype_shared_annotations"].keys()).intersection(
+                descendants_of_term_name
+            )
+
+            # If none of the target terms are present, skip
+            if not target_term_names:
+                continue
+
+            # Check if any of the target terms have the specified phenotype
+            has_phenotype = False
+            for term_name in target_term_names:
+                annotation = record["phenotype_shared_annotations"][term_name]
+                if life_stage is not None and annotation["life_stage"] != life_stage:
+                    continue
+                if sex is not None and annotation["sexual_dimorphism"] != sex:
+                    continue
+                if zygosity is not None and annotation["zygosity"] != zygosity:
+                    continue
+                has_phenotype = True
+
+            if has_phenotype:
+                # output to stdout as JSONL
+                io_handler.write_jsonl_to_stdout(record)
+    else:
+        genewise_phenotype_annotations = io_handler.read_jsonl(path_genewise_phenotype_annotations)
+        for record in genewise_phenotype_annotations:
+            if record["mp_term_id"] not in descendants_of_term_ids:
+                continue
+            if record.get("significant") is False:
+                continue
+            if life_stage is not None and record["life_stage"] != life_stage:
+                continue
+            if sex is not None and record["sexual_dimorphism"] != sex:
+                continue
+            if zygosity is not None and record["zygosity"] != zygosity:
+                continue
+            # output to stdout as JSONL
+            io_handler.write_jsonl_to_stdout(record)
+
+
+###########################################################
+# Exclude gene pairs with target_mp_term_id and its descendants
+###########################################################
+
+
+def exclude_specific_phenotype(
+    path_pairwise_similarity_annotations: str | Path | None,
+    path_genewise_phenotype_annotations: str | Path,
+    path_obo: str | Path,
+    mp_term_id: str,
+    life_stage: str | None = None,
+    sex: str | None = None,
+    zygosity: str | None = None,
+    is_pairwise: bool = True,
+) -> None:
+    ontology_terms = io_handler.parse_obo_file(path_obo)
+    parent_term_map, child_term_map = ontology_handler.build_term_hierarchy(ontology_terms)
+    descendants_of_term_id = ontology_handler.find_all_descendant_terms(mp_term_id, child_term_map)
+    ancesters_of_term_id = ontology_handler.find_all_ancestor_terms(mp_term_id, parent_term_map)
+
+    # If a gene exhibits a significant abnormal phenotype annotated to
+    # the target mp_term_id or any of its ancestor/descendant terms,
+    # the gene is classified as “having a phenotype.”
+    genewise_phenotype_annotations = list(io_handler.read_jsonl(Path(path_genewise_phenotype_annotations)))
+    genes_with_phenotype = set()
+    for record in genewise_phenotype_annotations:
+        condition1 = record["mp_term_id"] == mp_term_id
+        condition2 = record["mp_term_id"] in ancesters_of_term_id
+        condition3 = record["mp_term_id"] in descendants_of_term_id
+        if (condition1 or condition2 or condition3) and record["significant"] is True:
+            if life_stage is not None and record["life_stage"] != life_stage:
+                continue
+            if sex is not None and record["sexual_dimorphism"] != sex:
+                continue
+            if zygosity is not None and record["zygosity"] != zygosity:
+                continue
+            genes_with_phenotype.add(record["marker_symbol"])
+
+    # For genes whose phenotype status remains undetermined in (1),
+    # if a non-significant phenotype annotation exists for the target mp_term_id or any of
+    # its ancestor/descendant terms, the gene is classified as “confirmed as having no phenotype.”
+    genes_without_phenotype = set()
+    for record in genewise_phenotype_annotations:
+        if record["marker_symbol"] in genes_with_phenotype:
+            continue
+
+        condition1 = record["mp_term_id"] == mp_term_id
+        condition2 = record["mp_term_id"] in ancesters_of_term_id
+        condition3 = record["mp_term_id"] in descendants_of_term_id
+        if (condition1 or condition2 or condition3) and record["significant"] is False:
+            if life_stage is not None and record["life_stage"] != life_stage:
+                continue
+            if sex is not None and record["sexual_dimorphism"] != sex:
+                continue
+            if zygosity is not None and record["zygosity"] != zygosity:
+                continue
+            genes_without_phenotype.add(record["marker_symbol"])
+
+    # Now filter gene pairs based on genes_without_phenotype
+    if is_pairwise:
+        pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+        for record in pairwise_similarity_annotations:
+            if record["gene1_symbol"] in genes_without_phenotype and record["gene2_symbol"] in genes_without_phenotype:
+                # output to stdout as JSONL
+                io_handler.write_jsonl_to_stdout(record)
+    else:
+        for record in genewise_phenotype_annotations:
+            if record["marker_symbol"] in genes_without_phenotype:
+                # output to stdout as JSONL
+                io_handler.write_jsonl_to_stdout(record)

TSUMUGI/subcommands/score_filterer.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from TSUMUGI import io_handler
+
+
+def filter_by_score_of_phenotypes_per_pair(
+    path_pairwise_similarity_annotations: str | Path | None,
+    min_phenotypes: int | None = None,
+    max_phenotypes: int | None = None,
+) -> None:
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in pairwise_similarity_annotations:
+        phenotype_similarity_score = record["phenotype_similarity_score"]
+        if min_phenotypes is not None and phenotype_similarity_score < min_phenotypes:
+            continue
+        if max_phenotypes is not None and phenotype_similarity_score > max_phenotypes:
+            continue
+
+        # output to stdout as JSON
+        io_handler.write_jsonl_to_stdout(record)

TSUMUGI/subcommands/sex_filterer.py

@@ -0,0 +1,48 @@
+from collections.abc import Generator
+from pathlib import Path
+
+from TSUMUGI import io_handler
+
+
+def _filter_annotations_by_sex(
+    pairwise_similarity_annotations: list[dict[str, str | dict[str, dict] | dict[str | int]]],
+    sex: str = "None",
+    keep: bool = False,
+    drop: bool = False,
+) -> Generator[frozenset[str], dict[str, dict, int]]:
+    for pairwise_similarity_annotation in pairwise_similarity_annotations:
+        phenotype_shared_annotations = pairwise_similarity_annotation["phenotype_shared_annotations"]
+
+        if len(phenotype_shared_annotations) == 0:
+            continue
+
+        phenotype_shared_annotations_filtered = {}
+        for term_name, annotation in phenotype_shared_annotations.items():
+            if annotation["sexual_dimorphism"] == sex and keep:
+                phenotype_shared_annotations_filtered[term_name] = annotation
+            if annotation["sexual_dimorphism"] != sex and drop:
+                phenotype_shared_annotations_filtered[term_name] = annotation
+
+        if len(phenotype_shared_annotations_filtered) == 0:
+            continue
+
+        pairwise_similarity_annotation["phenotype_shared_annotations"] = phenotype_shared_annotations_filtered
+
+        yield pairwise_similarity_annotation
+
+
+def filter_annotations_by_sex(
+    path_pairwise_similarity_annotations: str | Path,
+    sex: str,
+    keep: bool = False,
+    drop: bool = False,
+) -> None:
+    pairwise_similarity_annotations = io_handler.read_jsonl(path_pairwise_similarity_annotations)
+    for record in _filter_annotations_by_sex(
+        pairwise_similarity_annotations=pairwise_similarity_annotations,
+        sex=sex,
+        keep=keep,
+        drop=drop,
+    ):
+        # output to stdout as JSONL
+        io_handler.write_jsonl_to_stdout(record)