risk-network 0.0.7b11__py3-none-any.whl → 0.0.8__py3-none-any.whl

risk/__init__.py

@@ -7,4 +7,4 @@ RISK: RISK Infers Spatial Kinships
 
 from risk.risk import RISK
 
-__version__ = "0.0.7-beta.11"
+__version__ = "0.0.8"

risk/annotations/__init__.py

@@ -3,5 +3,5 @@ risk/annotations
 ~~~~~~~~~~~~~~~~
 """
 
-from .annotations import define_top_annotations, get_description
+from .annotations import define_top_annotations, get_weighted_description
 from .io import AnnotationsIO

risk/annotations/annotations.py

@@ -3,8 +3,9 @@ risk/annotations/annotations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
+import re
 from collections import Counter
-from itertools import compress, permutations
+from itertools import compress
 from typing import Any, Dict, List, Set
 
 import networkx as nx
@@ -30,27 +31,30 @@ def _setup_nltk():
 
 # Ensure you have the necessary NLTK data
 _setup_nltk()
+# Initialize English stopwords
+stop_words = set(stopwords.words("english"))
 
 
 def load_annotations(network: nx.Graph, annotations_input: Dict[str, Any]) -> Dict[str, Any]:
     """Convert annotations input to a DataFrame and reindex based on the network's node labels.
 
     Args:
-        annotations_input (dict): A dictionary with annotations.
+        network (nx.Graph): The network graph.
+        annotations_input (Dict[str, Any]): A dictionary with annotations.
 
     Returns:
-        dict: A dictionary containing ordered nodes, ordered annotations, and the binary annotations matrix.
+        Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the binary annotations matrix.
     """
     # Flatten the dictionary to a list of tuples for easier DataFrame creation
     flattened_annotations = [
         (node, annotation) for annotation, nodes in annotations_input.items() for node in nodes
     ]
     # Create a DataFrame from the flattened list
-    annotations = pd.DataFrame(flattened_annotations, columns=["Node", "Annotations"])
-    annotations["Is Member"] = 1
+    annotations = pd.DataFrame(flattened_annotations, columns=["node", "annotations"])
+    annotations["is_member"] = 1
     # Pivot to create a binary matrix with nodes as rows and annotations as columns
     annotations_pivot = annotations.pivot_table(
-        index="Node", columns="Annotations", values="Is Member", fill_value=0, dropna=False
+        index="node", columns="annotations", values="is_member", fill_value=0, dropna=False
     )
     # Reindex the annotations matrix based on the node labels from the network
     node_label_order = list(nx.get_node_attributes(network, "label").values())
@@ -80,7 +84,8 @@ def define_top_annotations(
     network: nx.Graph,
     ordered_annotation_labels: List[str],
     neighborhood_enrichment_sums: List[int],
-    binary_enrichment_matrix: np.ndarray,
+    significant_enrichment_matrix: np.ndarray,
+    significant_binary_enrichment_matrix: np.ndarray,
     min_cluster_size: int = 5,
     max_cluster_size: int = 1000,
 ) -> pd.DataFrame:
@@ -90,42 +95,52 @@ def define_top_annotations(
         network (NetworkX graph): The network graph.
         ordered_annotation_labels (list of str): List of ordered annotation labels.
         neighborhood_enrichment_sums (list of int): List of neighborhood enrichment sums.
-        binary_enrichment_matrix (np.ndarray): Binary enrichment matrix below alpha threshold.
+        significant_enrichment_matrix (np.ndarray): Enrichment matrix below alpha threshold.
+        significant_binary_enrichment_matrix (np.ndarray): Binary enrichment matrix below alpha threshold.
         min_cluster_size (int, optional): Minimum cluster size. Defaults to 5.
         max_cluster_size (int, optional): Maximum cluster size. Defaults to 1000.
 
     Returns:
         pd.DataFrame: DataFrame with top annotations and their properties.
     """
-    # Create DataFrame to store annotations and their neighborhood enrichment sums
+    # Sum the columns of the significant enrichment matrix (positive floating point values)
+    significant_enrichment_scores = significant_enrichment_matrix.sum(axis=0)
+    # Create DataFrame to store annotations, their neighborhood enrichment sums, and enrichment scores
     annotations_enrichment_matrix = pd.DataFrame(
         {
             "id": range(len(ordered_annotation_labels)),
-            "words": ordered_annotation_labels,
-            "neighborhood enrichment sums": neighborhood_enrichment_sums,
+            "full_terms": ordered_annotation_labels,
+            "significant_neighborhood_enrichment_sums": neighborhood_enrichment_sums,
+            "significant_enrichment_score": significant_enrichment_scores,
         }
     )
-    annotations_enrichment_matrix["top attributes"] = False
-    # Apply size constraints to identify potential top attributes
+    annotations_enrichment_matrix["significant_annotations"] = False
+    # Apply size constraints to identify potential significant annotations
     annotations_enrichment_matrix.loc[
-        (annotations_enrichment_matrix["neighborhood enrichment sums"] >= min_cluster_size)
-        & (annotations_enrichment_matrix["neighborhood enrichment sums"] <= max_cluster_size),
-        "top attributes",
+        (
+            annotations_enrichment_matrix["significant_neighborhood_enrichment_sums"]
+            >= min_cluster_size
+        )
+        & (
+            annotations_enrichment_matrix["significant_neighborhood_enrichment_sums"]
+            <= max_cluster_size
+        ),
+        "significant_annotations",
     ] = True
     # Initialize columns for connected components analysis
-    annotations_enrichment_matrix["num connected components"] = 0
-    annotations_enrichment_matrix["size connected components"] = None
-    annotations_enrichment_matrix["size connected components"] = annotations_enrichment_matrix[
-        "size connected components"
+    annotations_enrichment_matrix["num_connected_components"] = 0
+    annotations_enrichment_matrix["size_connected_components"] = None
+    annotations_enrichment_matrix["size_connected_components"] = annotations_enrichment_matrix[
+        "size_connected_components"
     ].astype(object)
-    annotations_enrichment_matrix["num large connected components"] = 0
+    annotations_enrichment_matrix["num_large_connected_components"] = 0
 
     for attribute in annotations_enrichment_matrix.index.values[
-        annotations_enrichment_matrix["top attributes"]
+        annotations_enrichment_matrix["significant_annotations"]
     ]:
         # Identify enriched neighborhoods based on the binary enrichment matrix
         enriched_neighborhoods = list(
-            compress(list(network), binary_enrichment_matrix[:, attribute])
+            compress(list(network), significant_binary_enrichment_matrix[:, attribute])
         )
         enriched_network = nx.subgraph(network, enriched_neighborhoods)
         # Analyze connected components within the enriched subnetwork
@@ -144,57 +159,74 @@ def define_top_annotations(
         num_large_connected_components = len(filtered_size_connected_components)
 
         # Assign the number of connected components
-        annotations_enrichment_matrix.loc[attribute, "num connected components"] = (
+        annotations_enrichment_matrix.loc[attribute, "num_connected_components"] = (
             num_connected_components
         )
         # Filter out attributes with more than one connected component
         annotations_enrichment_matrix.loc[
-            annotations_enrichment_matrix["num connected components"] > 1, "top attributes"
+            annotations_enrichment_matrix["num_connected_components"] > 1, "significant_annotations"
         ] = False
         # Assign the number of large connected components
-        annotations_enrichment_matrix.loc[attribute, "num large connected components"] = (
+        annotations_enrichment_matrix.loc[attribute, "num_large_connected_components"] = (
             num_large_connected_components
         )
         # Assign the size of connected components, ensuring it is always a list
-        annotations_enrichment_matrix.at[attribute, "size connected components"] = (
+        annotations_enrichment_matrix.at[attribute, "size_connected_components"] = (
             filtered_size_connected_components.tolist()
         )
 
     return annotations_enrichment_matrix
 
 
-def get_description(words_column: pd.Series) -> str:
-    """Process input Series to identify and return the top frequent, significant words,
-    filtering based on stopwords and gracefully handling numerical strings.
+def get_weighted_description(words_column: pd.Series, scores_column: pd.Series) -> str:
+    """Generate a weighted description from words and their corresponding scores,
+    with support for stopwords filtering and improved weighting logic.
 
     Args:
         words_column (pd.Series): A pandas Series containing strings to process.
+        scores_column (pd.Series): A pandas Series containing enrichment scores to weigh the terms.
 
     Returns:
-        str: A coherent description formed from the most frequent and significant words.
+        str: A coherent description formed from the most frequent and significant words, weighed by enrichment scores.
     """
-    # Concatenate all rows into a single string and tokenize into words
-    all_words = words_column.str.cat(sep=" ")
-    tokens = word_tokenize(all_words)
-
-    # Separate numeric tokens
-    numeric_tokens = [token for token in tokens if token.replace(".", "", 1).isdigit()]
-    # If there's only one unique numeric value, return it directly as a string
-    unique_numeric_values = set(numeric_tokens)
-    if len(unique_numeric_values) == 1:
-        return f"{list(unique_numeric_values)[0]}"
-
-    # Ensure that all values in 'words' are strings and include both alphabetic and numeric tokens
-    words = [
-        str(
-            word.lower() if word.istitle() else word
-        )  # Convert to string and lowercase all words except proper nouns (e.g., RNA, mRNA)
-        for word in tokens
-        if word.isalpha()
-        or word.replace(".", "", 1).isdigit()  # Keep alphabetic words and numeric strings
-    ]
-    # Generate a coherent description from the processed words
-    description = _generate_coherent_description(words)
+    # Handle case where all scores are the same
+    if scores_column.max() == scores_column.min():
+        normalized_scores = pd.Series([1] * len(scores_column))
+    else:
+        # Normalize the enrichment scores to be between 0 and 1
+        normalized_scores = (scores_column - scores_column.min()) / (
+            scores_column.max() - scores_column.min()
+        )
+
+    # Combine words and normalized scores to create weighted words
+    weighted_words = []
+    for word, score in zip(words_column, normalized_scores):
+        word = str(word)
+        if word not in stop_words:  # Skip stopwords
+            weight = max(1, int((0 if pd.isna(score) else score) * 10))
+            weighted_words.extend([word] * weight)
+
+    # Tokenize the weighted words, but preserve number-word patterns like '4-alpha'
+    tokens = word_tokenize(" ".join(weighted_words))
+    # Ensure we treat "4-alpha" or other "number-word" patterns as single tokens
+    combined_tokens = []
+    for token in tokens:
+        # Match patterns like '4-alpha' or '5-hydroxy' and keep them together
+        if re.match(r"^\d+-\w+", token):
+            combined_tokens.append(token)
+        elif token.replace(".", "", 1).isdigit():  # Handle pure numeric tokens
+            # Ignore pure numbers as descriptions unless necessary
+            continue
+        else:
+            combined_tokens.append(token)
+
+    # Prevent descriptions like just '4' from being selected
+    if len(combined_tokens) == 1 and combined_tokens[0].isdigit():
+        return "N/A"  # Return "N/A" for cases where it's just a number
+
+    # Simplify the word list and generate the description
+    simplified_words = _simplify_word_list(combined_tokens)
+    description = _generate_coherent_description(simplified_words)
 
     return description
 
@@ -257,7 +289,7 @@ def _generate_coherent_description(words: List[str]) -> str:
     If there is only one unique entry, return it directly.
 
     Args:
-        words (list): A list of words or numerical string values.
+        words (List): A list of words or numerical string values.
 
     Returns:
         str: A coherent description formed by arranging the words in a logical sequence.

risk/annotations/io.py

@@ -25,15 +25,15 @@ class AnnotationsIO:
     def __init__(self):
         pass
 
-    def load_json_annotation(self, filepath: str, network: nx.Graph) -> Dict[str, Any]:
+    def load_json_annotation(self, network: nx.Graph, filepath: str) -> Dict[str, Any]:
         """Load annotations from a JSON file and convert them to a DataFrame.
 
         Args:
-            filepath (str): Path to the JSON annotations file.
             network (NetworkX graph): The network to which the annotations are related.
+            filepath (str): Path to the JSON annotations file.
 
         Returns:
-            dict: A dictionary containing ordered nodes, ordered annotations, and the annotations matrix.
+            Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the annotations matrix.
         """
         filetype = "JSON"
         # Log the loading of the JSON file
@@ -49,8 +49,8 @@ class AnnotationsIO:
 
     def load_excel_annotation(
         self,
-        filepath: str,
         network: nx.Graph,
+        filepath: str,
         label_colname: str = "label",
         nodes_colname: str = "nodes",
         sheet_name: str = "Sheet1",
@@ -59,8 +59,8 @@ class AnnotationsIO:
         """Load annotations from an Excel file and associate them with the network.
 
         Args:
-            filepath (str): Path to the Excel annotations file.
             network (nx.Graph): The NetworkX graph to which the annotations are related.
+            filepath (str): Path to the Excel annotations file.
             label_colname (str): Name of the column containing the labels (e.g., GO terms).
             nodes_colname (str): Name of the column containing the nodes associated with each label.
             sheet_name (str, optional): The name of the Excel sheet to load (default is 'Sheet1').
@@ -87,8 +87,8 @@ class AnnotationsIO:
 
     def load_csv_annotation(
         self,
-        filepath: str,
         network: nx.Graph,
+        filepath: str,
         label_colname: str = "label",
         nodes_colname: str = "nodes",
         nodes_delimiter: str = ";",
@@ -96,8 +96,8 @@ class AnnotationsIO:
         """Load annotations from a CSV file and associate them with the network.
 
         Args:
-            filepath (str): Path to the CSV annotations file.
             network (nx.Graph): The NetworkX graph to which the annotations are related.
+            filepath (str): Path to the CSV annotations file.
             label_colname (str): Name of the column containing the labels (e.g., GO terms).
             nodes_colname (str): Name of the column containing the nodes associated with each label.
             nodes_delimiter (str, optional): Delimiter used to separate multiple nodes within the nodes column (default is ';').
@@ -121,8 +121,8 @@ class AnnotationsIO:
 
     def load_tsv_annotation(
         self,
-        filepath: str,
         network: nx.Graph,
+        filepath: str,
         label_colname: str = "label",
         nodes_colname: str = "nodes",
         nodes_delimiter: str = ";",
@@ -130,8 +130,8 @@ class AnnotationsIO:
         """Load annotations from a TSV file and associate them with the network.
 
         Args:
-            filepath (str): Path to the TSV annotations file.
             network (nx.Graph): The NetworkX graph to which the annotations are related.
+            filepath (str): Path to the TSV annotations file.
             label_colname (str): Name of the column containing the labels (e.g., GO terms).
             nodes_colname (str): Name of the column containing the nodes associated with each label.
             nodes_delimiter (str, optional): Delimiter used to separate multiple nodes within the nodes column (default is ';').
@@ -153,15 +153,15 @@ class AnnotationsIO:
         # Load the annotations into the provided network
         return load_annotations(network, annotations_input)
 
-    def load_dict_annotation(self, content: Dict[str, Any], network: nx.Graph) -> Dict[str, Any]:
+    def load_dict_annotation(self, network: nx.Graph, content: Dict[str, Any]) -> Dict[str, Any]:
         """Load annotations from a provided dictionary and convert them to a dictionary annotation.
 
         Args:
-            content (dict): The annotations dictionary to load.
             network (NetworkX graph): The network to which the annotations are related.
+            content (Dict[str, Any]): The annotations dictionary to load.
 
         Returns:
-            dict: A dictionary containing ordered nodes, ordered annotations, and the annotations matrix.
+            Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the annotations matrix.
         """
         # Ensure the input content is a dictionary
         if not isinstance(content, dict):
@@ -219,6 +219,6 @@ def _log_loading(filetype: str, filepath: str = "") -> None:
         filepath (str, optional): The path to the file being loaded.
     """
     log_header("Loading annotations")
-    logger.info(f"Filetype: {filetype}")
+    logger.debug(f"Filetype: {filetype}")
     if filepath:
-        logger.info(f"Filepath: {filepath}")
+        logger.debug(f"Filepath: {filepath}")

risk/log/__init__.py

@@ -3,7 +3,7 @@ risk/log
 ~~~~~~~~
 """
 
-from .config import logger, log_header, set_global_verbosity
+from .console import logger, log_header, set_global_verbosity
 from .params import Params
 
 params = Params()

risk/log/console.py

@@ -0,0 +1,139 @@
+"""
+risk/log/console
+~~~~~~~~~~~~~~~~
+"""
+
+import logging
+
+
+def in_jupyter():
+    """Check if the code is running in a Jupyter notebook environment.
+
+    Returns:
+        bool: True if running in a Jupyter notebook or QtConsole, False otherwise.
+    """
+    try:
+        shell = get_ipython().__class__.__name__
+        if shell == "ZMQInteractiveShell":  # Jupyter Notebook or QtConsole
+            return True
+        elif shell == "TerminalInteractiveShell":  # Terminal running IPython
+            return False
+    except NameError:
+        return False  # Not in Jupyter
+
+
+# Define the MockLogger class to replicate logging behavior with print statements in Jupyter
+class MockLogger:
+    """MockLogger: A lightweight logger replacement using print statements in Jupyter.
+
+    The MockLogger class replicates the behavior of a standard logger using print statements
+    to display messages. This is primarily used in a Jupyter environment to show outputs
+    directly in the notebook. The class supports logging levels such as `info`, `debug`,
+    `warning`, and `error`, while the `verbose` attribute controls whether to display non-error messages.
+    """
+
+    def __init__(self, verbose: bool = True):
+        """Initialize the MockLogger with verbosity settings.
+
+        Args:
+            verbose (bool): If True, display all log messages (info, debug, warning).
+                If False, only display error messages. Defaults to True.
+        """
+        self.verbose = verbose
+
+    def info(self, message: str) -> None:
+        """Display an informational message.
+
+        Args:
+            message (str): The informational message to be printed.
+        """
+        if self.verbose:
+            print(message)
+
+    def debug(self, message: str) -> None:
+        """Display a debug message.
+
+        Args:
+            message (str): The debug message to be printed.
+        """
+        if self.verbose:
+            print(message)
+
+    def warning(self, message: str) -> None:
+        """Display a warning message.
+
+        Args:
+            message (str): The warning message to be printed.
+        """
+        print(message)
+
+    def error(self, message: str) -> None:
+        """Display an error message.
+
+        Args:
+            message (str): The error message to be printed.
+        """
+        print(message)
+
+    def setLevel(self, level: int) -> None:
+        """Adjust verbosity based on the logging level.
+
+        Args:
+            level (int): Logging level to control message display.
+                - logging.DEBUG sets verbose to True (show all messages).
+                - logging.WARNING sets verbose to False (show only warning, error, and critical messages).
+        """
+        if level == logging.DEBUG:
+            self.verbose = True  # Show all messages
+        elif level == logging.WARNING:
+            self.verbose = False  # Suppress all except warning, error, and critical messages
+
+
+# Set up logger based on environment
+if not in_jupyter():
+    # Set up logger normally for .py files or terminal environments
+    logger = logging.getLogger("risk_logger")
+    logger.setLevel(logging.DEBUG)
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.DEBUG)
+    console_handler.setFormatter(logging.Formatter("%(message)s"))
+
+    if not logger.hasHandlers():
+        logger.addHandler(console_handler)
+else:
+    # If in Jupyter, use the MockLogger
+    logger = MockLogger()
+
+
+def set_global_verbosity(verbose):
+    """Set the global verbosity level for the logger.
+
+    Args:
+        verbose (bool): Whether to display all log messages (True) or only error messages (False).
+
+    Returns:
+        None
+    """
+    if not isinstance(logger, MockLogger):
+        # For the regular logger, adjust logging levels
+        if verbose:
+            logger.setLevel(logging.DEBUG)  # Show all messages
+            console_handler.setLevel(logging.DEBUG)
+        else:
+            logger.setLevel(logging.WARNING)  # Show only warning, error, and critical messages
+            console_handler.setLevel(logging.WARNING)
+    else:
+        # For the MockLogger, set verbosity directly
+        logger.setLevel(logging.DEBUG if verbose else logging.WARNING)
+
+
+def log_header(input_string: str) -> None:
+    """Log the input string as a header with a line of dashes above and below it.
+
+    Args:
+        input_string (str): The string to be printed as a header.
+    """
+    border = "-" * len(input_string)
+    logger.info(border)
+    logger.info(input_string)
+    logger.info(border)

risk/log/params.py

@@ -12,7 +12,7 @@ from typing import Any, Dict
 
 import numpy as np
 
-from .config import logger, log_header
+from .console import logger, log_header
 
 # Suppress all warnings - this is to resolve warnings from multiprocessing
 warnings.filterwarnings("ignore")
@@ -159,7 +159,7 @@ class Params:
         """Load and process various parameters, converting any np.ndarray values to lists.
 
         Returns:
-            dict: A dictionary containing the processed parameters.
+            Dict[str, Any]: A dictionary containing the processed parameters.
         """
         log_header("Loading parameters")
         return _convert_ndarray_to_list(
@@ -174,14 +174,14 @@ class Params:
         )
 
 
-def _convert_ndarray_to_list(d: Any) -> Any:
+def _convert_ndarray_to_list(d: Dict[str, Any]) -> Dict[str, Any]:
     """Recursively convert all np.ndarray values in the dictionary to lists.
 
     Args:
-        d (dict): The dictionary to process.
+        d (Dict[str, Any]): The dictionary to process.
 
     Returns:
-        dict: The processed dictionary with np.ndarray values converted to lists.
+        Dict[str, Any]: The processed dictionary with np.ndarray values converted to lists.
     """
     if isinstance(d, dict):
         # Recursively process each value in the dictionary
@@ -193,5 +193,5 @@ def _convert_ndarray_to_list(d: Any) -> Any:
         # Convert numpy arrays to lists
         return d.tolist()
     else:
-        # Return the value unchanged if it's not a dict, list, or ndarray
+        # Return the value unchanged if it's not a dict, List, or ndarray
         return d