risk-network 0.0.12b1__py3-none-any.whl → 0.0.12b3__py3-none-any.whl

risk/__init__.py

@@ -7,4 +7,4 @@ RISK: Regional Inference of Significant Kinships
 
 from risk.risk import RISK
 
-__version__ = "0.0.12-beta.1"
+__version__ = "0.0.12-beta.3"

risk/annotation/__init__.py

@@ -0,0 +1,10 @@
+"""
+risk/annotation
+~~~~~~~~~~~~~~~
+"""
+
+from risk.annotation.annotation import (
+    define_top_annotation,
+    get_weighted_description,
+)
+from risk.annotation.io import AnnotationIO

risk/{annotations/annotations.py → annotation/annotation.py}

@@ -1,6 +1,6 @@
 """
-risk/annotations/annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/annotation/annotation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import re
@@ -14,7 +14,7 @@ import pandas as pd
 from nltk.tokenize import word_tokenize
 from scipy.sparse import coo_matrix
 
-from risk.annotations.nltk_setup import setup_nltk_resources
+from risk.annotation.nltk_setup import setup_nltk_resources
 from risk.log import logger
 
 
@@ -35,14 +35,14 @@ def initialize_nltk():
 initialize_nltk()
 
 
-def load_annotations(
-    network: nx.Graph, annotations_input: Dict[str, Any], min_nodes_per_term: int = 2
+def load_annotation(
+    network: nx.Graph, annotation_input: Dict[str, Any], min_nodes_per_term: int = 2
 ) -> Dict[str, Any]:
-    """Convert annotations input to a sparse matrix and reindex based on the network's node labels.
+    """Convert annotation input to a sparse matrix and reindex based on the network's node labels.
 
     Args:
         network (nx.Graph): The network graph.
-        annotations_input (Dict[str, Any]): A dictionary with annotations.
+        annotation_input (Dict[str, Any]): An annotation dictionary.
         min_nodes_per_term (int, optional): The minimum number of network nodes required for each annotation
             term to be included. Defaults to 2.
 
@@ -51,18 +51,18 @@ def load_annotations(
             matrix.
 
     Raises:
-        ValueError: If no annotations are found for the nodes in the network.
-        ValueError: If no annotations have at least min_nodes_per_term nodes in the network.
+        ValueError: If no annotation is found for the nodes in the network.
+        ValueError: If no annotation has at least min_nodes_per_term nodes in the network.
     """
     # Step 1: Map nodes and annotations to indices
     node_label_order = [attr["label"] for _, attr in network.nodes(data=True) if "label" in attr]
     node_to_idx = {node: i for i, node in enumerate(node_label_order)}
-    annotation_to_idx = {annotation: i for i, annotation in enumerate(annotations_input)}
+    annotation_to_idx = {annotation: i for i, annotation in enumerate(annotation_input)}
     # Step 2: Construct a sparse binary matrix directly
     row = []
     col = []
     data = []
-    for annotation, nodes in annotations_input.items():
+    for annotation, nodes in annotation_input.items():
         for node in nodes:
             if node in node_to_idx and annotation in annotation_to_idx:
                 row.append(node_to_idx[node])
@@ -71,40 +71,40 @@ def load_annotations(
 
     # Create a sparse binary matrix
     num_nodes = len(node_to_idx)
-    num_annotations = len(annotation_to_idx)
-    annotations_pivot = coo_matrix((data, (row, col)), shape=(num_nodes, num_annotations)).tocsr()
+    num_annotation = len(annotation_to_idx)
+    annotation_pivot = coo_matrix((data, (row, col)), shape=(num_nodes, num_annotation)).tocsr()
     # Step 3: Filter out annotations with fewer than min_nodes_per_term occurrences
-    valid_annotations = annotations_pivot.sum(axis=0).A1 >= min_nodes_per_term
-    annotations_pivot = annotations_pivot[:, valid_annotations]
+    valid_annotation = annotation_pivot.sum(axis=0).A1 >= min_nodes_per_term
+    annotation_pivot = annotation_pivot[:, valid_annotation]
     # Step 4: Raise errors for empty matrices
-    if annotations_pivot.nnz == 0:
+    if annotation_pivot.nnz == 0:
         raise ValueError("No terms found in the annotation file for the nodes in the network.")
 
-    num_remaining_annotations = annotations_pivot.shape[1]
-    if num_remaining_annotations == 0:
+    num_remaining_annotation = annotation_pivot.shape[1]
+    if num_remaining_annotation == 0:
         raise ValueError(
             f"No annotation terms found with at least {min_nodes_per_term} nodes in the network."
         )
 
     # Step 5: Extract ordered nodes and annotations
     ordered_nodes = tuple(node_label_order)
-    ordered_annotations = tuple(
-        annotation for annotation, is_valid in zip(annotation_to_idx, valid_annotations) if is_valid
+    ordered_annotation = tuple(
+        annotation for annotation, is_valid in zip(annotation_to_idx, valid_annotation) if is_valid
     )
 
     # Log the filtering details
     logger.info(f"Minimum number of nodes per annotation term: {min_nodes_per_term}")
-    logger.info(f"Number of input annotation terms: {num_annotations}")
-    logger.info(f"Number of remaining annotation terms: {num_remaining_annotations}")
+    logger.info(f"Number of input annotation terms: {num_annotation}")
+    logger.info(f"Number of remaining annotation terms: {num_remaining_annotation}")
 
     return {
         "ordered_nodes": ordered_nodes,
-        "ordered_annotations": ordered_annotations,
-        "matrix": annotations_pivot,
+        "ordered_annotation": ordered_annotation,
+        "matrix": annotation_pivot,
     }
 
 
-def define_top_annotations(
+def define_top_annotation(
     network: nx.Graph,
     ordered_annotation_labels: List[str],
     neighborhood_significance_sums: List[int],
@@ -130,7 +130,7 @@ def define_top_annotations(
     # Sum the columns of the significant significance matrix (positive floating point values)
     significant_significance_scores = significant_significance_matrix.sum(axis=0)
     # Create DataFrame to store annotations, their neighborhood significance sums, and significance scores
-    annotations_significance_matrix = pd.DataFrame(
+    annotation_significance_matrix = pd.DataFrame(
         {
             "id": range(len(ordered_annotation_labels)),
             "full_terms": ordered_annotation_labels,
@@ -138,29 +138,29 @@ def define_top_annotations(
             "significant_significance_score": significant_significance_scores,
         }
     )
-    annotations_significance_matrix["significant_annotations"] = False
+    annotation_significance_matrix["significant_annotation"] = False
     # Apply size constraints to identify potential significant annotations
-    annotations_significance_matrix.loc[
+    annotation_significance_matrix.loc[
         (
-            annotations_significance_matrix["significant_neighborhood_significance_sums"]
+            annotation_significance_matrix["significant_neighborhood_significance_sums"]
             >= min_cluster_size
         )
         & (
-            annotations_significance_matrix["significant_neighborhood_significance_sums"]
+            annotation_significance_matrix["significant_neighborhood_significance_sums"]
             <= max_cluster_size
         ),
-        "significant_annotations",
+        "significant_annotation",
     ] = True
     # Initialize columns for connected components analysis
-    annotations_significance_matrix["num_connected_components"] = 0
-    annotations_significance_matrix["size_connected_components"] = None
-    annotations_significance_matrix["size_connected_components"] = annotations_significance_matrix[
+    annotation_significance_matrix["num_connected_components"] = 0
+    annotation_significance_matrix["size_connected_components"] = None
+    annotation_significance_matrix["size_connected_components"] = annotation_significance_matrix[
         "size_connected_components"
     ].astype(object)
-    annotations_significance_matrix["num_large_connected_components"] = 0
+    annotation_significance_matrix["num_large_connected_components"] = 0
 
-    for attribute in annotations_significance_matrix.index.values[
-        annotations_significance_matrix["significant_annotations"]
+    for attribute in annotation_significance_matrix.index.values[
+        annotation_significance_matrix["significant_annotation"]
     ]:
         # Identify significant neighborhoods based on the binary significance matrix
         significant_neighborhoods = list(
@@ -183,24 +183,24 @@ def define_top_annotations(
         num_large_connected_components = len(filtered_size_connected_components)
 
         # Assign the number of connected components
-        annotations_significance_matrix.loc[attribute, "num_connected_components"] = (
+        annotation_significance_matrix.loc[attribute, "num_connected_components"] = (
             num_connected_components
         )
         # Filter out attributes with more than one connected component
-        annotations_significance_matrix.loc[
-            annotations_significance_matrix["num_connected_components"] > 1,
-            "significant_annotations",
+        annotation_significance_matrix.loc[
+            annotation_significance_matrix["num_connected_components"] > 1,
+            "significant_annotation",
         ] = False
         # Assign the number of large connected components
-        annotations_significance_matrix.loc[attribute, "num_large_connected_components"] = (
+        annotation_significance_matrix.loc[attribute, "num_large_connected_components"] = (
             num_large_connected_components
         )
         # Assign the size of connected components, ensuring it is always a list
-        annotations_significance_matrix.at[attribute, "size_connected_components"] = (
+        annotation_significance_matrix.at[attribute, "size_connected_components"] = (
             filtered_size_connected_components.tolist()
         )
 
-    return annotations_significance_matrix
+    return annotation_significance_matrix
 
 
 def get_weighted_description(words_column: pd.Series, scores_column: pd.Series) -> str:

risk/{annotations → annotation}/io.py

@@ -1,6 +1,6 @@
 """
-risk/annotations/io
-~~~~~~~~~~~~~~~~~~~
+risk/annotation/io
+~~~~~~~~~~~~~~~~~~
 """
 
 import json
@@ -9,45 +9,45 @@ from typing import Any, Dict
 import networkx as nx
 import pandas as pd
 
-from risk.annotations.annotations import load_annotations
+from risk.annotation.annotation import load_annotation
 from risk.log import log_header, logger, params
 
 
-class AnnotationsIO:
-    """Handles the loading and exporting of annotations in various file formats.
+class AnnotationIO:
+    """Handles the loading and exporting of annotation in various file formats.
 
-    The AnnotationsIO class provides methods to load annotations from different file types (JSON, CSV, Excel, etc.)
+    The AnnotationIO class provides methods to load annotation from different file types (JSON, CSV, Excel, etc.)
     and to export parameter data to various formats like JSON, CSV, and text files.
     """
 
-    def load_json_annotation(
+    def load_annotation_json(
         self, network: nx.Graph, filepath: str, min_nodes_per_term: int = 2
     ) -> Dict[str, Any]:
-        """Load annotations from a JSON file and convert them to a DataFrame.
+        """Load annotation from a JSON file and convert them to a DataFrame.
 
         Args:
-            network (NetworkX graph): The network to which the annotations are related.
-            filepath (str): Path to the JSON annotations file.
+            network (NetworkX graph): The network to which the annotation is related.
+            filepath (str): Path to the JSON annotation file.
             min_nodes_per_term (int, optional): The minimum number of network nodes required for each annotation
                 term to be included. Defaults to 2.
 
         Returns:
-            Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the annotations matrix.
+            Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the annotation matrix.
         """
         filetype = "JSON"
         # Log the loading of the JSON file
-        params.log_annotations(
+        params.log_annotation(
             filetype=filetype, filepath=filepath, min_nodes_per_term=min_nodes_per_term
         )
         self._log_loading(filetype, filepath=filepath)
 
         # Load the JSON file into a dictionary
         with open(filepath, "r", encoding="utf-8") as file:
-            annotations_input = json.load(file)
+            annotation_input = json.load(file)
 
-        return load_annotations(network, annotations_input, min_nodes_per_term)
+        return load_annotation(network, annotation_input, min_nodes_per_term)
 
-    def load_excel_annotation(
+    def load_annotation_excel(
         self,
         network: nx.Graph,
         filepath: str,
@@ -57,11 +57,11 @@ class AnnotationsIO:
         nodes_delimiter: str = ";",
         min_nodes_per_term: int = 2,
     ) -> Dict[str, Any]:
-        """Load annotations from an Excel file and associate them with the network.
+        """Load annotation from an Excel file and associate them with the network.
 
         Args:
-            network (nx.Graph): The NetworkX graph to which the annotations are related.
-            filepath (str): Path to the Excel annotations file.
+            network (nx.Graph): The NetworkX graph to which the annotation is related.
+            filepath (str): Path to the Excel annotation 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').
@@ -75,7 +75,7 @@ class AnnotationsIO:
         """
         filetype = "Excel"
         # Log the loading of the Excel file
-        params.log_annotations(
+        params.log_annotation(
             filetype=filetype, filepath=filepath, min_nodes_per_term=min_nodes_per_term
         )
         self._log_loading(filetype, filepath=filepath)
@@ -87,11 +87,11 @@ class AnnotationsIO:
             lambda x: x.split(nodes_delimiter)
         )
         # Convert the DataFrame to a dictionary pairing labels with their corresponding nodes
-        annotations_input = annotation.set_index(label_colname)[nodes_colname].to_dict()
+        annotation_input = annotation.set_index(label_colname)[nodes_colname].to_dict()
 
-        return load_annotations(network, annotations_input, min_nodes_per_term)
+        return load_annotation(network, annotation_input, min_nodes_per_term)
 
-    def load_csv_annotation(
+    def load_annotation_csv(
         self,
         network: nx.Graph,
         filepath: str,
@@ -100,11 +100,11 @@ class AnnotationsIO:
         nodes_delimiter: str = ";",
         min_nodes_per_term: int = 2,
     ) -> Dict[str, Any]:
-        """Load annotations from a CSV file and associate them with the network.
+        """Load annotation from a CSV file and associate them with the network.
 
         Args:
-            network (nx.Graph): The NetworkX graph to which the annotations are related.
-            filepath (str): Path to the CSV annotations file.
+            network (nx.Graph): The NetworkX graph to which the annotation is related.
+            filepath (str): Path to the CSV annotation 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 ';').
@@ -117,19 +117,19 @@ class AnnotationsIO:
         """
         filetype = "CSV"
         # Log the loading of the CSV file
-        params.log_annotations(
+        params.log_annotation(
             filetype=filetype, filepath=filepath, min_nodes_per_term=min_nodes_per_term
         )
         self._log_loading(filetype, filepath=filepath)
 
         # Load the CSV file into a dictionary
-        annotations_input = self._load_matrix_file(
+        annotation_input = self._load_matrix_file(
             filepath, label_colname, nodes_colname, delimiter=",", nodes_delimiter=nodes_delimiter
         )
 
-        return load_annotations(network, annotations_input, min_nodes_per_term)
+        return load_annotation(network, annotation_input, min_nodes_per_term)
 
-    def load_tsv_annotation(
+    def load_annotation_tsv(
         self,
         network: nx.Graph,
         filepath: str,
@@ -138,11 +138,11 @@ class AnnotationsIO:
         nodes_delimiter: str = ";",
         min_nodes_per_term: int = 2,
     ) -> Dict[str, Any]:
-        """Load annotations from a TSV file and associate them with the network.
+        """Load annotation from a TSV file and associate them with the network.
 
         Args:
-            network (nx.Graph): The NetworkX graph to which the annotations are related.
-            filepath (str): Path to the TSV annotations file.
+            network (nx.Graph): The NetworkX graph to which the annotation is related.
+            filepath (str): Path to the TSV annotation 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 ';').
@@ -155,31 +155,31 @@ class AnnotationsIO:
         """
         filetype = "TSV"
         # Log the loading of the TSV file
-        params.log_annotations(
+        params.log_annotation(
             filetype=filetype, filepath=filepath, min_nodes_per_term=min_nodes_per_term
         )
         self._log_loading(filetype, filepath=filepath)
 
         # Load the TSV file into a dictionary
-        annotations_input = self._load_matrix_file(
+        annotation_input = self._load_matrix_file(
             filepath, label_colname, nodes_colname, delimiter="\t", nodes_delimiter=nodes_delimiter
         )
 
-        return load_annotations(network, annotations_input, min_nodes_per_term)
+        return load_annotation(network, annotation_input, min_nodes_per_term)
 
-    def load_dict_annotation(
+    def load_annotation_dict(
         self, network: nx.Graph, content: Dict[str, Any], min_nodes_per_term: int = 2
     ) -> Dict[str, Any]:
-        """Load annotations from a provided dictionary and convert them to a dictionary annotation.
+        """Load annotation from a provided dictionary and convert them to a dictionary annotation.
 
         Args:
-            network (NetworkX graph): The network to which the annotations are related.
-            content (Dict[str, Any]): The annotations dictionary to load.
+            network (NetworkX graph): The network to which the annotation is related.
+            content (Dict[str, Any]): The annotation dictionary to load.
             min_nodes_per_term (int, optional): The minimum number of network nodes required for each annotation
                 term to be included. Defaults to 2.
 
         Returns:
-            Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the annotations matrix.
+            Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the annotation matrix.
 
         Raises:
             TypeError: If the content is not a dictionary.
@@ -191,12 +191,12 @@ class AnnotationsIO:
             )
 
         filetype = "Dictionary"
-        # Log the loading of the annotations from the dictionary
-        params.log_annotations(filepath="In-memory dictionary", filetype=filetype)
+        # Log the loading of the annotation from the dictionary
+        params.log_annotation(filepath="In-memory dictionary", filetype=filetype)
         self._log_loading(filetype, "In-memory dictionary")
 
-        # Load the annotations as a dictionary from the provided dictionary
-        return load_annotations(network, content, min_nodes_per_term)
+        # Load the annotation as a dictionary from the provided dictionary
+        return load_annotation(network, content, min_nodes_per_term)
 
     def _load_matrix_file(
         self,
@@ -206,7 +206,7 @@ class AnnotationsIO:
         delimiter: str = ",",
         nodes_delimiter: str = ";",
     ) -> Dict[str, Any]:
-        """Load annotations from a CSV or TSV file and convert them to a dictionary.
+        """Load annotation from a CSV or TSV file and convert them to a dictionary.
 
         Args:
             filepath (str): Path to the annotation file.
@@ -235,7 +235,7 @@ class AnnotationsIO:
             filetype (str): The type of the file being loaded (e.g., 'Cytoscape').
             filepath (str, optional): The path to the file being loaded.
         """
-        log_header("Loading annotations")
+        log_header("Loading annotation")
         logger.debug(f"Filetype: {filetype}")
         if filepath:
             logger.debug(f"Filepath: {filepath}")

risk/{annotations → annotation}/nltk_setup.py

@@ -1,11 +1,11 @@
 """
-risk/annotations/nltk_setup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/annotation/nltk_setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import os
 import zipfile
-from typing import List, Tuple
+from typing import List, Optional, Tuple
 
 import nltk
 from nltk.data import find
@@ -14,7 +14,7 @@ from nltk.data import path as nltk_data_path
 from risk.log import logger
 
 
-def setup_nltk_resources(required_resources: List[Tuple[str, str]] = None) -> None:
+def setup_nltk_resources(required_resources: Optional[List[Tuple[str, str]]] = None) -> None:
     """Ensures all required NLTK resources are available and properly extracted.
     Uses NLTK's default paths and mechanisms.
 

risk/log/parameters.py

@@ -21,7 +21,7 @@ class Params:
     """Handles the storage and logging of various parameters for network analysis.
 
     The Params class provides methods to log parameters related to different components of the analysis,
-    such as the network, annotations, neighborhoods, graph, and plotter settings. It also stores
+    such as the network, annotation, neighborhoods, graph, and plotter settings. It also stores
     the current datetime when the parameters were initialized.
     """
 
@@ -33,7 +33,7 @@ class Params:
     def initialize(self) -> None:
         """Initialize the parameter dictionaries for different components."""
         self.network = {}
-        self.annotations = {}
+        self.annotation = {}
         self.neighborhoods = {}
         self.graph = {}
         self.plotter = {}
@@ -46,13 +46,13 @@ class Params:
         """
         self.network = {**self.network, **kwargs}
 
-    def log_annotations(self, **kwargs) -> None:
+    def log_annotation(self, **kwargs) -> None:
         """Log annotation-related parameters.
 
         Args:
             **kwargs: Annotation parameters to log.
         """
-        self.annotations = {**self.annotations, **kwargs}
+        self.annotation = {**self.annotation, **kwargs}
 
     def log_neighborhoods(self, **kwargs) -> None:
         """Log neighborhood-related parameters.
@@ -139,7 +139,7 @@ class Params:
         log_header("Loading parameters")
         return self._convert_ndarray_to_list(
             {
-                "annotations": self.annotations,
+                "annotation": self.annotation,
                 "datetime": self.datetime,
                 "graph": self.graph,
                 "neighborhoods": self.neighborhoods,