risk-network 0.0.11__py3-none-any.whl → 0.0.12__py3-none-any.whl

risk/{stats → neighborhoods/stats}/permutation/permutation.py

@@ -1,9 +1,9 @@
 """
-risk/stats/permutation/permutation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/neighborhoods/stats/permutation/permutation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
-from multiprocessing import get_context, Manager
+from multiprocessing import Manager, get_context
 from multiprocessing.managers import ValueProxy
 from typing import Any, Callable, Dict, List, Tuple, Union
 
@@ -12,12 +12,12 @@ from scipy.sparse import csr_matrix
 from threadpoolctl import threadpool_limits
 from tqdm import tqdm
 
-from risk.stats.permutation.test_functions import DISPATCH_TEST_FUNCTIONS
+from risk.neighborhoods.stats.permutation.test_functions import DISPATCH_TEST_FUNCTIONS
 
 
 def compute_permutation_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     score_metric: str = "sum",
     null_distribution: str = "network",
     num_permutations: int = 1000,
@@ -28,9 +28,9 @@ def compute_permutation_test(
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
         score_metric (str, optional): Metric to use for scoring ('sum' or 'stdev'). Defaults to "sum".
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
         num_permutations (int, optional): Number of permutations to run. Defaults to 1000.
         random_seed (int, optional): Seed for random number generation. Defaults to 888.
         max_workers (int, optional): Number of workers for multiprocessing. Defaults to 1.
@@ -41,14 +41,14 @@ def compute_permutation_test(
     # Ensure that the matrices are in the correct format and free of NaN values
     # NOTE: Keep the data type as float32 to avoid locking issues with dot product operations
     neighborhoods = neighborhoods.astype(np.float32)
-    annotations = annotations.astype(np.float32)
+    annotation = annotation.astype(np.float32)
     # Retrieve the appropriate neighborhood score function based on the metric
     neighborhood_score_func = DISPATCH_TEST_FUNCTIONS[score_metric]
 
     # Run the permutation test to calculate depletion and enrichment counts
     counts_depletion, counts_enrichment = _run_permutation_test(
         neighborhoods=neighborhoods,
-        annotations=annotations,
+        annotation=annotation,
         neighborhood_score_func=neighborhood_score_func,
         null_distribution=null_distribution,
         num_permutations=num_permutations,
@@ -68,7 +68,7 @@ def compute_permutation_test(
 
 def _run_permutation_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     neighborhood_score_func: Callable,
     null_distribution: str = "network",
     num_permutations: int = 1000,
@@ -79,31 +79,34 @@ def _run_permutation_test(
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
         neighborhood_score_func (Callable): Function to calculate neighborhood scores.
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
         num_permutations (int, optional): Number of permutations. Defaults to 1000.
         random_seed (int, optional): Seed for random number generation. Defaults to 888.
         max_workers (int, optional): Number of workers for multiprocessing. Defaults to 4.
 
     Returns:
         tuple: Depletion and enrichment counts.
+
+    Raises:
+        ValueError: If an invalid null_distribution value is provided.
     """
     # Initialize the RNG for reproducibility
     rng = np.random.default_rng(seed=random_seed)
     # Determine the indices to use based on the null distribution type
     if null_distribution == "network":
-        idxs = range(annotations.shape[0])
-    elif null_distribution == "annotations":
-        idxs = np.nonzero(annotations.getnnz(axis=1) > 0)[0]
+        idxs = range(annotation.shape[0])
+    elif null_distribution == "annotation":
+        idxs = np.nonzero(annotation.getnnz(axis=1) > 0)[0]
     else:
         raise ValueError(
-            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+            "Invalid null_distribution value. Choose either 'network' or 'annotation'."
         )
 
-    # Replace NaNs with zeros in the sparse annotations matrix
-    annotations.data[np.isnan(annotations.data)] = 0
-    annotation_matrix_obsv = annotations[idxs]
+    # Replace NaNs with zeros in the sparse annotation matrix
+    annotation.data[np.isnan(annotation.data)] = 0
+    annotation_matrix_obsv = annotation[idxs]
     neighborhoods_matrix_obsv = neighborhoods.T[idxs].T
     # Calculate observed neighborhood scores
     with np.errstate(invalid="ignore", divide="ignore"):
@@ -139,7 +142,7 @@ def _run_permutation_test(
             params_list = [
                 (
                     permutation_batches[i],  # Pass the batch of precomputed permutations
-                    annotations,
+                    annotation,
                     neighborhoods_matrix_obsv,
                     observed_neighborhood_scores,
                     neighborhood_score_func,
@@ -182,7 +185,7 @@ def _permutation_process_batch(
 
     Args:
         permutations (Union[List, Tuple, np.ndarray]): Permutation batch to process.
-        annotation_matrix (csr_matrix): Sparse binary matrix representing annotations.
+        annotation_matrix (csr_matrix): Sparse binary matrix representing annotation.
         neighborhoods_matrix_obsv (csr_matrix): Sparse binary matrix representing observed neighborhoods.
         observed_neighborhood_scores (np.ndarray): Observed neighborhood scores.
         neighborhood_score_func (Callable): Function to calculate neighborhood scores.

risk/{stats → neighborhoods/stats}/permutation/test_functions.py

@@ -1,6 +1,6 @@
 """
-risk/stats/permutation/test_functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/neighborhoods/stats/permutation/test_functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import numpy as np
@@ -24,7 +24,7 @@ def compute_neighborhood_score_by_sum(
     Returns:
         np.ndarray: Dense array of summed attribute values for each neighborhood.
     """
-    # Calculate the neighborhood score as the dot product of neighborhoods and annotations
+    # Calculate the neighborhood score as the dot product of neighborhoods and annotation
     neighborhood_score = neighborhoods_matrix @ annotation_matrix  # Sparse matrix multiplication
     # Convert the result to a dense array for downstream calculations
     neighborhood_score_dense = neighborhood_score.toarray()
@@ -43,7 +43,7 @@ def compute_neighborhood_score_by_stdev(
     Returns:
         np.ndarray: Standard deviation of the neighborhood scores.
     """
-    # Calculate the neighborhood score as the dot product of neighborhoods and annotations
+    # Calculate the neighborhood score as the dot product of neighborhoods and annotation
     neighborhood_score = neighborhoods_matrix @ annotation_matrix  # Sparse matrix multiplication
     # Calculate the number of elements in each neighborhood (sum of rows)
     N = neighborhoods_matrix.sum(axis=1).A.flatten()  # Convert to 1D array

risk/{stats/stat_tests.py → neighborhoods/stats/tests.py}

@@ -1,52 +1,51 @@
 """
-risk/stats/stat_tests
-~~~~~~~~~~~~~~~~~~~~~
+risk/neighborhoods/stats/tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict
 
 import numpy as np
 from scipy.sparse import csr_matrix
-from scipy.stats import binom
-from scipy.stats import chi2
-from scipy.stats import hypergeom
-from scipy.stats import norm
-from scipy.stats import poisson
+from scipy.stats import binom, chi2, hypergeom, norm, poisson
 
 
 def compute_binom_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
     """Compute Binomial test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
 
     Returns:
         Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+
+    Raises:
+        ValueError: If an invalid null_distribution value is provided.
     """
     # Get the total number of nodes in the network
     total_nodes = neighborhoods.shape[1]
 
     # Compute sums (remain sparse here)
     neighborhood_sizes = neighborhoods.sum(axis=1)  # Row sums
-    annotation_totals = annotations.sum(axis=0)  # Column sums
+    annotation_totals = annotation.sum(axis=0)  # Column sums
     # Compute probabilities (convert to dense)
     if null_distribution == "network":
         p_values = (annotation_totals / total_nodes).A.flatten()  # Dense 1D array
-    elif null_distribution == "annotations":
-        p_values = (annotation_totals / annotations.sum()).A.flatten()  # Dense 1D array
+    elif null_distribution == "annotation":
+        p_values = (annotation_totals / annotation.sum()).A.flatten()  # Dense 1D array
     else:
         raise ValueError(
-            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+            "Invalid null_distribution value. Choose either 'network' or 'annotation'."
         )
 
     # Observed counts (sparse matrix multiplication)
-    annotated_counts = neighborhoods @ annotations  # Sparse result
+    annotated_counts = neighborhoods @ annotation  # Sparse result
     annotated_counts_dense = annotated_counts.toarray()  # Convert for dense operations
 
     # Compute enrichment and depletion p-values
@@ -58,18 +57,21 @@ def compute_binom_test(
 
 def compute_chi2_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
     """Compute chi-squared test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
 
     Returns:
         Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+
+    Raises:
+        ValueError: If an invalid null_distribution value is provided.
     """
     # Total number of nodes in the network
     total_node_count = neighborhoods.shape[0]
@@ -78,22 +80,22 @@ def compute_chi2_test(
         # Case 1: Use all nodes as the background
         background_population = total_node_count
         neighborhood_sums = neighborhoods.sum(axis=0)  # Column sums of neighborhoods
-        annotation_sums = annotations.sum(axis=0)  # Column sums of annotations
-    elif null_distribution == "annotations":
+        annotation_sums = annotation.sum(axis=0)  # Column sums of annotations
+    elif null_distribution == "annotation":
         # Case 2: Only consider nodes with at least one annotation
         annotated_nodes = (
-            np.ravel(annotations.sum(axis=1)) > 0
+            np.ravel(annotation.sum(axis=1)) > 0
         )  # Row-wise sum to filter nodes with annotations
         background_population = annotated_nodes.sum()  # Total number of annotated nodes
         neighborhood_sums = neighborhoods[annotated_nodes].sum(
             axis=0
         )  # Neighborhood sums for annotated nodes
-        annotation_sums = annotations[annotated_nodes].sum(
+        annotation_sums = annotation[annotated_nodes].sum(
             axis=0
         )  # Annotation sums for annotated nodes
     else:
         raise ValueError(
-            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+            "Invalid null_distribution value. Choose either 'network' or 'annotation'."
         )
 
     # Convert to dense arrays for downstream computations
@@ -101,7 +103,7 @@ def compute_chi2_test(
     annotation_sums = np.asarray(annotation_sums).reshape(1, -1)  # Ensure row vector shape
 
     # Observed values: number of annotated nodes in each neighborhood
-    observed = neighborhoods.T @ annotations  # Shape: (neighborhoods, annotations)
+    observed = neighborhoods.T @ annotation  # Shape: (neighborhoods, annotation)
     # Expected values under the null
     expected = (neighborhood_sums @ annotation_sums) / background_population
     # Chi-squared statistic: sum((observed - expected)^2 / expected)
@@ -117,41 +119,43 @@ def compute_chi2_test(
 
 def compute_hypergeom_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """
-    Compute hypergeometric test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """Compute hypergeometric test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
 
     Returns:
         Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+
+    Raises:
+        ValueError: If an invalid null_distribution value is provided.
     """
     # Get the total number of nodes in the network
     total_nodes = neighborhoods.shape[1]
 
     # Compute sums
     neighborhood_sums = neighborhoods.sum(axis=0).A.flatten()  # Convert to dense array
-    annotation_sums = annotations.sum(axis=0).A.flatten()  # Convert to dense array
+    annotation_sums = annotation.sum(axis=0).A.flatten()  # Convert to dense array
 
     if null_distribution == "network":
         background_population = total_nodes
-    elif null_distribution == "annotations":
-        annotated_nodes = annotations.sum(axis=1).A.flatten() > 0  # Boolean mask
+    elif null_distribution == "annotation":
+        annotated_nodes = annotation.sum(axis=1).A.flatten() > 0  # Boolean mask
         background_population = annotated_nodes.sum()
         neighborhood_sums = neighborhoods[annotated_nodes].sum(axis=0).A.flatten()
-        annotation_sums = annotations[annotated_nodes].sum(axis=0).A.flatten()
+        annotation_sums = annotation[annotated_nodes].sum(axis=0).A.flatten()
     else:
         raise ValueError(
-            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+            "Invalid null_distribution value. Choose either 'network' or 'annotation'."
         )
 
     # Observed counts
-    annotated_in_neighborhood = neighborhoods.T @ annotations  # Sparse result
+    annotated_in_neighborhood = neighborhoods.T @ annotation  # Sparse result
     annotated_in_neighborhood = annotated_in_neighborhood.toarray()  # Convert to dense
     # Align shapes for broadcasting
     neighborhood_sums = neighborhood_sums.reshape(-1, 1)
@@ -171,22 +175,24 @@ def compute_hypergeom_test(
 
 def compute_poisson_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """
-    Compute Poisson test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """Compute Poisson test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
 
     Returns:
         Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+
+    Raises:
+        ValueError: If an invalid null_distribution value is provided.
     """
     # Matrix multiplication to get the number of annotated nodes in each neighborhood
-    annotated_in_neighborhood = neighborhoods @ annotations  # Sparse result
+    annotated_in_neighborhood = neighborhoods @ annotation  # Sparse result
     # Convert annotated counts to dense for downstream calculations
     annotated_in_neighborhood_dense = annotated_in_neighborhood.toarray()
 
@@ -194,12 +200,12 @@ def compute_poisson_test(
     if null_distribution == "network":
         # Use the mean across neighborhoods (axis=1)
         lambda_expected = np.mean(annotated_in_neighborhood_dense, axis=1, keepdims=True)
-    elif null_distribution == "annotations":
+    elif null_distribution == "annotation":
         # Use the mean across annotations (axis=0)
         lambda_expected = np.mean(annotated_in_neighborhood_dense, axis=0, keepdims=True)
     else:
         raise ValueError(
-            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+            "Invalid null_distribution value. Choose either 'network' or 'annotation'."
         )
 
     # Compute p-values for enrichment and depletion using Poisson distribution
@@ -211,19 +217,21 @@ def compute_poisson_test(
 
 def compute_zscore_test(
     neighborhoods: csr_matrix,
-    annotations: csr_matrix,
+    annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """
-    Compute z-score test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """Compute z-score test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
-        annotations (csr_matrix): Sparse binary matrix representing annotations.
-        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+        annotation (csr_matrix): Sparse binary matrix representing annotation.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotation'). Defaults to "network".
 
     Returns:
         Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+
+    Raises:
+        ValueError: If an invalid null_distribution value is provided.
     """
     # Total number of nodes in the network
     total_node_count = neighborhoods.shape[1]
@@ -232,19 +240,19 @@ def compute_zscore_test(
     if null_distribution == "network":
         background_population = total_node_count
         neighborhood_sums = neighborhoods.sum(axis=0).A.flatten()  # Dense column sums
-        annotation_sums = annotations.sum(axis=0).A.flatten()  # Dense row sums
-    elif null_distribution == "annotations":
-        annotated_nodes = annotations.sum(axis=1).A.flatten() > 0  # Dense boolean mask
+        annotation_sums = annotation.sum(axis=0).A.flatten()  # Dense row sums
+    elif null_distribution == "annotation":
+        annotated_nodes = annotation.sum(axis=1).A.flatten() > 0  # Dense boolean mask
         background_population = annotated_nodes.sum()
         neighborhood_sums = neighborhoods[annotated_nodes].sum(axis=0).A.flatten()
-        annotation_sums = annotations[annotated_nodes].sum(axis=0).A.flatten()
+        annotation_sums = annotation[annotated_nodes].sum(axis=0).A.flatten()
     else:
         raise ValueError(
-            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+            "Invalid null_distribution value. Choose either 'network' or 'annotation'."
         )
 
     # Observed values
-    observed = (neighborhoods.T @ annotations).toarray()  # Convert sparse result to dense
+    observed = (neighborhoods.T @ annotation).toarray()  # Convert sparse result to dense
     # Expected values under the null
     neighborhood_sums = neighborhood_sums.reshape(-1, 1)  # Ensure correct shape
     annotation_sums = annotation_sums.reshape(1, -1)  # Ensure correct shape

risk/network/__init__.py

@@ -2,5 +2,3 @@
 risk/network
 ~~~~~~~~~~~~
 """
-
-from risk.network.io import NetworkIO

risk/network/graph/__init__.py

@@ -2,5 +2,3 @@
 risk/network/graph
 ~~~~~~~~~~~~~~~~~~
 """
-
-from risk.network.graph.api import GraphAPI

risk/network/graph/api.py

@@ -9,15 +9,15 @@ from typing import Any, Dict, Union
 import networkx as nx
 import pandas as pd
 
-from risk.annotations import define_top_annotations
-from risk.log import logger, log_header, params
+from risk.annotation import define_top_annotation
+from risk.log import log_header, logger, params
 from risk.neighborhoods import (
     define_domains,
     process_neighborhoods,
     trim_domains,
 )
 from risk.network.graph.graph import Graph
-from risk.stats import calculate_significance_matrices
+from risk.network.graph.stats import calculate_significance_matrices
 
 
 class GraphAPI:
@@ -26,13 +26,13 @@ class GraphAPI:
     The GraphAPI class provides methods to load and process network graphs, annotations, and neighborhoods.
     """
 
-    def __init__() -> None:
+    def __init__(self) -> None:
         pass
 
     def load_graph(
         self,
         network: nx.Graph,
-        annotations: Dict[str, Any],
+        annotation: Dict[str, Any],
         neighborhoods: Dict[str, Any],
         tail: str = "right",
         pval_cutoff: float = 0.01,
@@ -50,7 +50,7 @@ class GraphAPI:
 
         Args:
             network (nx.Graph): The network graph.
-            annotations (Dict[str, Any]): The annotations associated with the network.
+            annotation (Dict[str, Any]): The annotation associated with the network.
             neighborhoods (Dict[str, Any]): Neighborhood significance data.
             tail (str, optional): Type of significance tail ("right", "left", "both"). Defaults to "right".
             pval_cutoff (float, optional): p-value cutoff for significance. Defaults to 0.01.
@@ -115,9 +115,9 @@ class GraphAPI:
         logger.debug(f"Min cluster size: {min_cluster_size}")
         logger.debug(f"Max cluster size: {max_cluster_size}")
         # Define top annotations based on processed neighborhoods
-        top_annotations = self._define_top_annotations(
+        top_annotation = self._define_top_annotation(
             network=network,
-            annotations=annotations,
+            annotation=annotation,
             neighborhoods=processed_neighborhoods,
             min_cluster_size=min_cluster_size,
             max_cluster_size=max_cluster_size,
@@ -130,7 +130,7 @@ class GraphAPI:
         ]
         # Define domains in the network using the specified clustering settings
         domains = define_domains(
-            top_annotations=top_annotations,
+            top_annotation=top_annotation,
             significant_neighborhoods_significance=significant_neighborhoods_significance,
             linkage_criterion=linkage_criterion,
             linkage_method=linkage_method,
@@ -140,20 +140,20 @@ class GraphAPI:
         # Trim domains and top annotations based on cluster size constraints
         domains, trimmed_domains = trim_domains(
             domains=domains,
-            top_annotations=top_annotations,
+            top_annotation=top_annotation,
             min_cluster_size=min_cluster_size,
             max_cluster_size=max_cluster_size,
         )
 
         # Prepare node mapping and significance sums for the final Graph object
-        ordered_nodes = annotations["ordered_nodes"]
+        ordered_nodes = annotation["ordered_nodes"]
         node_label_to_id = dict(zip(ordered_nodes, range(len(ordered_nodes))))
         node_significance_sums = processed_neighborhoods["node_significance_sums"]
 
         # Return the fully initialized Graph object
         return Graph(
             network=network,
-            annotations=annotations,
+            annotation=annotation,
             neighborhoods=neighborhoods,
             domains=domains,
             trimmed_domains=trimmed_domains,
@@ -161,10 +161,10 @@ class GraphAPI:
             node_significance_sums=node_significance_sums,
         )
 
-    def _define_top_annotations(
+    def _define_top_annotation(
         self,
         network: nx.Graph,
-        annotations: Dict[str, Any],
+        annotation: Dict[str, Any],
         neighborhoods: Dict[str, Any],
         min_cluster_size: int = 5,
         max_cluster_size: int = 1000,
@@ -173,7 +173,7 @@ class GraphAPI:
 
         Args:
             network (nx.Graph): The network graph.
-            annotations (Dict[str, Any]): Annotations data for the network.
+            annotation (Dict[str, Any]): Annotation data for the network.
             neighborhoods (Dict[str, Any]): Neighborhood significance data.
             min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
             max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
@@ -181,17 +181,17 @@ class GraphAPI:
         Returns:
             Dict[str, Any]: Top annotations identified within the network.
         """
-        # Extract necessary data from annotations and neighborhoods
-        ordered_annotations = annotations["ordered_annotations"]
+        # Extract necessary data from annotation and neighborhoods
+        ordered_annotation = annotation["ordered_annotation"]
         neighborhood_significance_sums = neighborhoods["neighborhood_significance_counts"]
         significant_significance_matrix = neighborhoods["significant_significance_matrix"]
         significant_binary_significance_matrix = neighborhoods[
             "significant_binary_significance_matrix"
         ]
         # Call external function to define top annotations
-        return define_top_annotations(
+        return define_top_annotation(
             network=network,
-            ordered_annotation_labels=ordered_annotations,
+            ordered_annotation_labels=ordered_annotation,
             neighborhood_significance_sums=neighborhood_significance_sums,
             significant_significance_matrix=significant_significance_matrix,
             significant_binary_significance_matrix=significant_binary_significance_matrix,