napistu 0.4.2__tar.gz → 0.4.4__tar.gz

{napistu-0.4.2/src/napistu.egg-info → napistu-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napistu
-Version: 0.4.2
+Version: 0.4.4
 Summary: Connecting high-dimensional data to curated pathways
 Home-page: https://github.com/napistu/napistu-py
 Author: Sean Hackett

{napistu-0.4.2 → napistu-0.4.4}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = napistu
-version = 0.4.2
+version = 0.4.4
 description = Connecting high-dimensional data to curated pathways
 long_description = file: README.md
 long_description_content_type = text/markdown

{napistu-0.4.2 → napistu-0.4.4}/src/napistu/consensus.py

@@ -426,7 +426,7 @@ def post_consensus_species_ontology_check(sbml_dfs: sbml_dfs_core.SBML_dfs) -> s
 
     # get the sources of species in the consensus model
     consensus_sbmldf_tbl_var_sc = (
-        source.unnest_sources(sbml_dfs.species, SBML_DFS.S_SOURCE, verbose=False)
+        source.unnest_sources(sbml_dfs.species, verbose=False)
         .reset_index()
         .sort_values([SOURCE_SPEC.NAME])
     )
@@ -504,12 +504,11 @@ def post_consensus_source_check(
 ) -> pd.DataFrame:
     """Provide sources of tables in a consensus model; the output df will be used to determine whether models are merged."""
 
-    table_source = sbml_dfs.schema[table_name][SOURCE_SPEC.SOURCE]
-    table_pk = sbml_dfs.schema[table_name]["pk"]
+    table_pk = sbml_dfs.schema[table_name][SCHEMA_DEFS.PK]
 
     sbml_dfs_tbl = getattr(sbml_dfs, table_name)
     sbml_dfs_tbl_pathway_source = (
-        source.unnest_sources(sbml_dfs_tbl, table_source, verbose=False)
+        source.unnest_sources(sbml_dfs_tbl, verbose=False)
         .reset_index()
         .sort_values(["name"])
     )

{napistu-0.4.2 → napistu-0.4.4}/src/napistu/ingestion/constants.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 from types import SimpleNamespace
 
+from napistu.constants import SBOTERM_NAMES
 
 SPECIES_FULL_NAME_HUMAN = "Homo sapiens"
 SPECIES_FULL_NAME_MOUSE = "Mus musculus"
@@ -90,6 +91,56 @@ REACTOME_PATHWAYS_URL = "https://reactome.org/download/current/ReactomePathways.
 REACTOME_PATHWAY_INDEX_COLUMNS = ["file", "source", "species", "pathway_id", "name"]
 REACTOME_PATHWAY_LIST_COLUMNS = ["pathway_id", "name", "species"]
 
+# REACTOME FI
+REACTOME_FI_URL = "http://cpws.reactome.org/caBigR3WebApp2025/FIsInGene_04142025_with_annotations.txt.zip"
+
+REACTOME_FI = SimpleNamespace(
+    GENE1="Gene1",
+    GENE2="Gene2",
+    ANNOTATION="Annotation",
+    DIRECTION="Direction",
+    SCORE="Score",
+)
+
+REACTOME_FI_DIRECTIONS = SimpleNamespace(
+    UNDIRECTED="-",
+    STIMULATED_BY="<-",
+    STIMULATES="->",
+    STIMULATES_AND_STIMULATED_BY="<->",
+    INHIBITED_BY="|-",
+    INHIBITS="-|",
+    INHIBITS_AND_INHIBITED_BY="|-|",
+    STIMULATES_AND_INHIBITED_BY="|->",
+    INHIBITS_AND_STIMULATED_BY="<-|",
+)
+
+VALID_REACTOME_FI_DIRECTIONS = REACTOME_FI_DIRECTIONS.__dict__.values()
+
+REACTOME_FI_RULES_REVERSE = SimpleNamespace(
+    NAME_RULES={"catalyzed by": SBOTERM_NAMES.CATALYST},
+    DIRECTION_RULES={
+        REACTOME_FI_DIRECTIONS.STIMULATED_BY: SBOTERM_NAMES.STIMULATOR,
+        REACTOME_FI_DIRECTIONS.STIMULATES_AND_STIMULATED_BY: SBOTERM_NAMES.STIMULATOR,
+        REACTOME_FI_DIRECTIONS.INHIBITED_BY: SBOTERM_NAMES.INHIBITOR,
+        REACTOME_FI_DIRECTIONS.INHIBITS_AND_INHIBITED_BY: SBOTERM_NAMES.INHIBITOR,
+        REACTOME_FI_DIRECTIONS.STIMULATES_AND_INHIBITED_BY: SBOTERM_NAMES.INHIBITOR,
+        REACTOME_FI_DIRECTIONS.UNDIRECTED: SBOTERM_NAMES.INTERACTOR,
+    },
+)
+
+REACTOME_FI_RULES_FORWARD = SimpleNamespace(
+    NAME_RULES={"catalyze(;$)": SBOTERM_NAMES.CATALYST},
+    DIRECTION_RULES={
+        REACTOME_FI_DIRECTIONS.STIMULATES: SBOTERM_NAMES.STIMULATOR,
+        REACTOME_FI_DIRECTIONS.STIMULATES_AND_STIMULATED_BY: SBOTERM_NAMES.STIMULATOR,
+        REACTOME_FI_DIRECTIONS.STIMULATES_AND_INHIBITED_BY: SBOTERM_NAMES.STIMULATOR,
+        REACTOME_FI_DIRECTIONS.INHIBITS: SBOTERM_NAMES.INHIBITOR,
+        REACTOME_FI_DIRECTIONS.INHIBITS_AND_INHIBITED_BY: SBOTERM_NAMES.INHIBITOR,
+        REACTOME_FI_DIRECTIONS.INHIBITS_AND_STIMULATED_BY: SBOTERM_NAMES.INHIBITOR,
+        REACTOME_FI_DIRECTIONS.UNDIRECTED: SBOTERM_NAMES.INTERACTOR,
+    },
+)
+
 # SBML
 SBML_DEFS = SimpleNamespace(
     ERROR_NUMBER="error_number",

napistu-0.4.4/src/napistu/ingestion/reactom_fi.py

@@ -0,0 +1,208 @@
+import logging
+import pandas as pd
+
+from napistu.identifiers import Identifiers
+from napistu import utils
+from napistu.ingestion.constants import (
+    REACTOME_FI,
+    REACTOME_FI_RULES_FORWARD,
+    REACTOME_FI_RULES_REVERSE,
+    REACTOME_FI_URL,
+    VALID_REACTOME_FI_DIRECTIONS,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+def download_reactome_fi(target_uri: str, url: str = REACTOME_FI_URL) -> None:
+    """
+    Download the Reactome Functional Interactions (FI) dataset as a TSV file.
+
+    Parameters
+    ----------
+    target_uri : str
+        The URI where the Reactome FI data should be saved. Should end with .tsv
+    url : str, optional
+        URL to download the zipped Reactome functional interactions TSV from.
+        Defaults to REACTOME_FI_URL.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If target_uri does not end with .tsv
+    """
+
+    if not target_uri.endswith(".tsv"):
+        raise ValueError(f"Target URI must end with .tsv, got {target_uri}")
+
+    file_ext = url.split(".")[-1]
+    target_filename = url.split("/")[-1].split(f".{file_ext}")[0]
+    logger.info("Start downloading proteinatlas %s to %s", url, target_uri)
+    # target_filename is the name of the file in the zip file which will be renamed to target_uri
+    utils.download_wget(url, target_uri, target_filename=target_filename)
+
+    return None
+
+
+def format_reactome_fi_edgelist(interactions: pd.DataFrame):
+    """
+    Format the Reactome FI interactions DataFrame as an edgelist for network analysis.
+
+    Parameters
+    ----------
+    interactions : pd.DataFrame
+        DataFrame containing Reactome FI interactions.
+
+    Returns
+    -------
+    Dictonary of:
+
+    interaction_edgelist : pd.DataFrame
+        Table containing molecular interactions with columns:
+        - upstream_name : str, matches "s_name" from species_df
+        - downstream_name : str, matches "s_name" from species_df
+        - upstream_compartment : str, matches "c_name" from compartments_df
+        - downstream_compartment : str, matches "c_name" from compartments_df
+        - r_name : str, name for the interaction
+        - sbo_term : str, SBO term defining interaction type
+        - r_Identifiers : identifiers.Identifiers, supporting identifiers
+        - r_isreversible : bool, whether reaction is reversible
+    species_df : pd.DataFrame
+        Table defining molecular species with columns:
+        - s_name : str, name of molecular species
+        - s_Identifiers : identifiers.Identifiers, species identifiers
+    compartments_df : pd.DataFrame
+        Table defining compartments with columns:
+        - c_name : str, name of compartment
+        - c_Identifiers : identifiers.Identifiers, compartment identifiers
+
+    Notes
+    -----
+    This function is not yet implemented and will raise NotImplementedError.
+    """
+
+    raise NotImplementedError("TO DO - This function is incomplete")
+
+    formatted_annotations = _parse_reactome_fi_annotations(interactions)
+
+    # this join will expand some rows to 2 since the bidirectional relationships are captured as separate edges in Napistu
+    annotated_interactions = interactions.merge(
+        formatted_annotations,
+        on=[REACTOME_FI.ANNOTATION, REACTOME_FI.DIRECTION],
+        how="left",
+    )
+
+    # flip reverse entries so all relationships are forward or undirected
+    formatted_interactions = (
+        pd.concat(
+            [
+                annotated_interactions.query("polarity == 'forward'"),
+                (
+                    annotated_interactions.query("polarity == 'reverse'").rename(
+                        columns={
+                            REACTOME_FI.GENE1: REACTOME_FI.GENE2,
+                            REACTOME_FI.GENE2: REACTOME_FI.GENE1,
+                        }
+                    )
+                ),
+            ]
+        )[[REACTOME_FI.GENE1, REACTOME_FI.GENE2, "sbo_term_name", "Score"]]
+        # looks like they were already unique edges
+        .sort_values("Score", ascending=False)
+        .groupby([REACTOME_FI.GENE1, REACTOME_FI.GENE2])
+        .first()
+    )
+
+    fi_edgelist = (
+        formatted_interactions.reset_index()
+        .rename(
+            columns={
+                REACTOME_FI.GENE1: "upstream_name",
+                REACTOME_FI.GENE2: "downstream_name",
+            }
+        )
+        .assign(r_Identifiers=Identifiers([]))
+    )
+
+    return fi_edgelist
+
+
+def _parse_reactome_fi_annotations(interactions: pd.DataFrame) -> pd.DataFrame:
+    """
+    Parse and annotate Reactome FI interaction types and directions using regex-based rules.
+
+    Parameters
+    ----------
+    interactions : pd.DataFrame
+        DataFrame containing Reactome FI interactions, with annotation and direction columns.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with annotation, direction, SBO term name, and polarity for each unique annotation/direction pair.
+
+    Raises
+    ------
+    ValueError
+        If an annotation/direction pair cannot be matched to a rule or if invalid directions are found.
+    """
+
+    distinct_annotations = (
+        interactions[[REACTOME_FI.ANNOTATION, REACTOME_FI.DIRECTION]]
+        .drop_duplicates()
+        .reset_index(drop=True)
+    )
+    invalid_directions = distinct_annotations.loc[
+        ~distinct_annotations[REACTOME_FI.DIRECTION].isin(VALID_REACTOME_FI_DIRECTIONS),
+        "Direction",
+    ]
+    if len(invalid_directions) > 0:
+        raise ValueError(f"Invalid directions: {invalid_directions}")
+
+    annotations = list()
+    for _, vals in distinct_annotations.iterrows():
+        annot, direction = vals
+
+        forward_match = utils.match_regex_dict(
+            annot, REACTOME_FI_RULES_FORWARD.NAME_RULES
+        )
+        if not forward_match:
+            if direction in REACTOME_FI_RULES_FORWARD.DIRECTION_RULES:
+                forward_match = REACTOME_FI_RULES_FORWARD.DIRECTION_RULES[direction]
+
+        reverse_match = utils.match_regex_dict(
+            annot, REACTOME_FI_RULES_REVERSE.NAME_RULES
+        )
+        if not reverse_match:
+            if direction in REACTOME_FI_RULES_REVERSE.DIRECTION_RULES:
+                reverse_match = REACTOME_FI_RULES_REVERSE.DIRECTION_RULES[direction]
+
+        if not (forward_match or reverse_match):
+            raise ValueError(f"No match found for {annot} with direction {direction}")
+
+        if forward_match:
+            annotations.append(
+                {
+                    REACTOME_FI.ANNOTATION: annot,
+                    REACTOME_FI.DIRECTION: direction,
+                    "sbo_term_name": forward_match,
+                    "polarity": "forward",
+                }
+            )
+
+        if reverse_match:
+            annotations.append(
+                {
+                    REACTOME_FI.ANNOTATION: annot,
+                    REACTOME_FI.DIRECTION: direction,
+                    "sbo_term_name": reverse_match,
+                    "polarity": "reverse",
+                }
+            )
+
+    return pd.DataFrame(annotations)

{napistu-0.4.2 → napistu-0.4.4}/src/napistu/network/neighborhoods.py

@@ -34,6 +34,7 @@ def find_and_prune_neighborhoods(
     napistu_graph: ig.Graph,
     compartmentalized_species: str | list[str],
     precomputed_distances: pd.DataFrame | None = None,
+    source_total_counts: pd.Series | None = None,
     network_type: str = NEIGHBORHOOD_NETWORK_TYPES.DOWNSTREAM,
     order: int = 3,
     verbose: bool = True,
@@ -44,7 +45,7 @@ def find_and_prune_neighborhoods(
 
     Wrapper which combines find_neighborhoods() and prune_neighborhoods()
 
-     Parameters
+    Parameters
     ----------
     sbml_dfs: sbml_dfs_core.SBML_dfs
         A mechanistic molecular model
@@ -54,6 +55,9 @@ def find_and_prune_neighborhoods(
         Compartmentalized species IDs for neighborhood centers
     precomputed_distances : pd.DataFrame or None
         If provided, an edgelist of origin->destination path weights and lengths
+    source_total_counts: pd.Series | None
+        Optional, A series of the total counts of each source. As produced by
+        source.get_source_total_counts()
     network_type: str
         If the network is directed should neighbors be located "downstream",
         or "upstream" of each compartmentalized species. The "hourglass" option
@@ -109,6 +113,7 @@ def find_and_prune_neighborhoods(
         order=order,
         verbose=verbose,
         precomputed_neighbors=precomputed_neighbors,
+        source_total_counts=source_total_counts,
     )
 
     pruned_neighborhoods = prune_neighborhoods(neighborhoods, top_n=top_n)
@@ -132,7 +137,7 @@ def load_neighborhoods(
 
     Load existing neighborhoods if they exist
     (and overwrite = False) and otherwise construct
-     neighborhoods using the provided settings
+    neighborhoods using the provided settings
 
     Parameters
     ----------
@@ -509,12 +514,13 @@ def find_neighborhoods(
     order: int = 3,
     verbose: bool = True,
     precomputed_neighbors: pd.DataFrame | None = None,
+    source_total_counts: pd.Series | None = None,
 ) -> dict:
     """
     Find Neighborhood
 
     Create a network composed of all species and reactions within N steps of
-      each of a set of compartmentalized species.
+    each of a set of compartmentalized species.
 
     Parameters
     ----------
@@ -535,11 +541,14 @@ def find_neighborhoods(
     precomputed_neighbors: pd.DataFrame or None
         If provided, a pre-filtered table of nodes nearby the compartmentalized species
         which will be used to skip on-the-fly neighborhood generation.
+    source_total_counts: pd.Series | None
+        Optional, A series of the total counts of each source. As produced by
+        source.get_source_total_counts()
 
     Returns:
     ----------
     A dict containing the neighborhood of each compartmentalized species.
-      Each entry in the dict is a dict of the subgraph, vertices, and edges.
+    Each entry in the dict is a dict of the subgraph, vertices, and edges.
     """
 
     if not isinstance(network_type, str):
@@ -567,7 +576,12 @@ def find_neighborhoods(
     # format the vertices and edges in each compartmentalized species' network
     neighborhood_dict = {
         sc_id: create_neighborhood_dict_entry(
-            sc_id, neighborhood_df, sbml_dfs, napistu_graph, verbose=verbose
+            sc_id,
+            neighborhood_df=neighborhood_df,
+            sbml_dfs=sbml_dfs,
+            napistu_graph=napistu_graph,
+            source_total_counts=source_total_counts,
+            verbose=verbose,
         )
         for sc_id in compartmentalized_species
     }
@@ -580,6 +594,7 @@ def create_neighborhood_dict_entry(
     neighborhood_df: pd.DataFrame,
     sbml_dfs: sbml_dfs_core.SBML_dfs,
     napistu_graph: ig.Graph,
+    source_total_counts: pd.Series | None = None,
     verbose: bool = False,
 ) -> dict[str, Any]:
     """
@@ -597,6 +612,9 @@ def create_neighborhood_dict_entry(
         A mechanistic molecular model
     napistu_graph: igraph.Graph
         A network connecting molecular species and reactions
+    source_total_counts: pd.Series
+        Optional, A series of the total counts of each source. As produced by
+        source.get_source_total_counts()
     verbose: bool
         Extra reporting?
 
@@ -645,7 +663,10 @@ def create_neighborhood_dict_entry(
 
     try:
         edge_sources = ng_utils.get_minimal_sources_edges(
-            vertices.rename(columns={"name": "node"}), sbml_dfs
+            vertices.rename(columns={"name": "node"}),
+            sbml_dfs,
+            # optional, counts of sources across the whole model
+            source_total_counts,
         )
     except Exception:
         edge_sources = None
@@ -1441,7 +1462,7 @@ def _prune_vertex_set(one_neighborhood: dict, top_n: int) -> pd.DataFrame:
     ----------
     one_neighborhood: dict
         The neighborhood around a single compartmentalized species - one of the values
-         in dict created by find_neighborhoods().
+        in dict created by find_neighborhoods().
     top_n: int
         How many neighboring molecular species should be retained?
         If the neighborhood includes both upstream and downstream connections

{napistu-0.4.2 → napistu-0.4.4}/src/napistu/network/ng_utils.py

@@ -66,7 +66,7 @@ def compartmentalize_species_pairs(
     Compartmentalize Shortest Paths
 
     For a set of origin and destination species pairs, consider each species in every
-      compartment it operates in, seperately.
+    compartment it operates in, seperately.
 
     Parameters
     ----------
@@ -112,22 +112,42 @@ def compartmentalize_species_pairs(
 
 
 def get_minimal_sources_edges(
-    vertices: pd.DataFrame, sbml_dfs: sbml_dfs_core.SBML_dfs
+    vertices: pd.DataFrame,
+    sbml_dfs: sbml_dfs_core.SBML_dfs,
+    source_total_counts: Optional[pd.Series] = None,
 ) -> pd.DataFrame | None:
-    """Assign edges to a set of sources."""
+    """
+    Assign edges to a set of sources.
+
+    Parameters
+    ----------
+    vertices: pd.DataFrame
+        A table of vertices.
+    sbml_dfs: sbml_dfs_core.SBML_dfs
+        A pathway model
+    source_total_counts: pd.Series
+        A series of the total counts of each source.
+
+    Returns
+    -------
+    edge_sources: pd.DataFrame
+        A table of edges and the sources they are assigned to.
+    """
+
     nodes = vertices["node"].tolist()
     present_reactions = sbml_dfs.reactions[sbml_dfs.reactions.index.isin(nodes)]
 
     if len(present_reactions) == 0:
         return None
 
-    table_schema = sbml_dfs.schema[SBML_DFS.REACTIONS]
-    source_df = source.unnest_sources(present_reactions, table_schema["source"])
+    source_df = source.unnest_sources(present_reactions)
 
     if source_df is None:
         return None
     else:
-        edge_sources = source.greedy_set_coverge_of_sources(source_df, table_schema)
+        edge_sources = source.source_set_coverage(
+            source_df, source_total_counts, sbml_dfs
+        )
         return edge_sources.reset_index()[
             [SBML_DFS.R_ID, SOURCE_SPEC.PATHWAY_ID, SOURCE_SPEC.NAME]
         ]

{napistu-0.4.2 → napistu-0.4.4}/src/napistu/network/precompute.py

@@ -110,6 +110,62 @@ def precompute_distances(
     return filtered_precomputed_distances
 
 
+def filter_precomputed_distances_top_n(precomputed_distances, top_n=50):
+    """
+    Filter precomputed distances to only include the top-n pairs for each distance measure.
+
+    Parameters
+    ----------
+    precomputed_distances : pd.DataFrame
+        Precomputed distances.
+    top_n : int, optional
+        Top-n pairs to include for each distance measure.
+
+    Returns
+    -------
+    pd.DataFrame
+        Filtered precomputed distances.
+    """
+
+    # take the union of top-n for each distance measure; and from origin -> dest and dest -> origin
+    distance_vars = set(precomputed_distances.columns) - {
+        NAPISTU_EDGELIST.SC_ID_ORIGIN,
+        NAPISTU_EDGELIST.SC_ID_DEST,
+    }
+
+    valid_pairs = list()
+    for distance_var in distance_vars:
+        top_n_pairs_by_origin = (
+            precomputed_distances.sort_values(by=distance_var, ascending=False)
+            .groupby(NAPISTU_EDGELIST.SC_ID_ORIGIN)
+            .head(top_n)
+        )
+        top_n_pairs_by_dest = (
+            precomputed_distances.sort_values(by=distance_var, ascending=False)
+            .groupby(NAPISTU_EDGELIST.SC_ID_DEST)
+            .head(top_n)
+        )
+
+        valid_pairs.append(
+            top_n_pairs_by_origin[
+                [NAPISTU_EDGELIST.SC_ID_ORIGIN, NAPISTU_EDGELIST.SC_ID_DEST]
+            ]
+        )
+        valid_pairs.append(
+            top_n_pairs_by_dest[
+                [NAPISTU_EDGELIST.SC_ID_ORIGIN, NAPISTU_EDGELIST.SC_ID_DEST]
+            ]
+        )
+
+    all_valid_pairs = pd.concat(valid_pairs).drop_duplicates()
+
+    return precomputed_distances.merge(
+        all_valid_pairs,
+        on=[NAPISTU_EDGELIST.SC_ID_ORIGIN, NAPISTU_EDGELIST.SC_ID_DEST],
+        how="inner",
+    )
+
+
 def _calculate_distances_subset(
     napistu_graph: NapistuGraph,
     vs_to_partition: pd.DataFrame,

{napistu-0.4.2 → napistu-0.4.4}/src/napistu/sbml_dfs_utils.py

@@ -456,8 +456,14 @@ def infer_entity_type(df: pd.DataFrame) -> str:
             if entity_schema.get(SCHEMA_DEFS.PK) == df.index.name:
                 return entity_type
 
-    # Get DataFrame columns that are also primary keys
-    df_columns = set(df.columns).intersection(primary_keys)
+    # Get DataFrame columns that are also primary keys, including index or MultiIndex names
+    index_names = []
+    if isinstance(df.index, pd.MultiIndex):
+        index_names = [name for name in df.index.names if name is not None]
+    elif df.index.name is not None:
+        index_names = [df.index.name]
+
+    df_columns = set(df.columns).union(index_names).intersection(primary_keys)
 
     # Check for exact match with primary key + foreign keys
     for entity_type, entity_schema in schema.items():