risk-network 0.0.14b1__tar.gz → 0.0.14b3__tar.gz

{risk_network-0.0.14b1/src/risk_network.egg-info → risk_network-0.0.14b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: risk-network
-Version: 0.0.14b1
+Version: 0.0.14b3
 Summary: A Python package for scalable network analysis and high-quality visualization.
 Author-email: Ira Horecka <ira89@icloud.com>
 License: GPL-3.0-or-later

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/src/risk/__init__.py

@@ -8,4 +8,4 @@ RISK: Regional Inference of Significant Kinships
 from ._risk import RISK
 
 __all__ = ["RISK"]
-__version__ = "0.0.14-beta.1"
+__version__ = "0.0.14-beta.3"

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/src/risk/_neighborhoods/_domains.py

@@ -54,37 +54,48 @@ def define_domains(
     Raises:
         ValueError: If the clustering criterion is set to "off" or if an error occurs during clustering.
     """
-    try:
-        if linkage_criterion == "off":
-            raise ValueError("Clustering is turned off.")
+    # Validate args first; let user mistakes raise immediately
+    clustering_off = _validate_clustering_args(
+        linkage_criterion, linkage_method, linkage_metric, linkage_threshold
+    )
 
+    # If clustering is turned off, assign unique domains and skip
+    if clustering_off:
+        n_rows = len(top_annotation)
+        logger.warning("Clustering is turned off. Skipping clustering.")
+        top_annotation["domain"] = range(1, n_rows + 1)
+    else:
         # Transpose the matrix to cluster annotations
         m = significant_neighborhoods_significance[:, top_annotation["significant_annotation"]].T
         # Safeguard the matrix by replacing NaN, Inf, and -Inf values
         m = _safeguard_matrix(m)
-        # Optimize silhouette score across different linkage methods and distance metrics
-        best_linkage, best_metric, best_threshold = _optimize_silhouette_across_linkage_and_metrics(
-            m, linkage_criterion, linkage_method, linkage_metric, linkage_threshold
-        )
-        # Perform hierarchical clustering
-        Z = linkage(m, method=best_linkage, metric=best_metric)
-        logger.warning(
-            f"Linkage criterion: '{linkage_criterion}'\nLinkage method: '{best_linkage}'\nLinkage metric: '{best_metric}'\nLinkage threshold: {round(best_threshold, 3)}"
-        )
-        # Calculate the optimal threshold for clustering
-        max_d_optimal = np.max(Z[:, 2]) * best_threshold
-        # Assign domains to the annotation matrix
-        domains = fcluster(Z, max_d_optimal, criterion=linkage_criterion)
-        top_annotation["domain"] = 0
-        top_annotation.loc[top_annotation["significant_annotation"], "domain"] = domains
-    except (ValueError, LinAlgError):
-        # If a ValueError is encountered, handle it by assigning unique domains
-        n_rows = len(top_annotation)
-        if linkage_criterion == "off":
-            logger.warning("Clustering is turned off. Skipping clustering.")
-        else:
-            logger.error("Error encountered. Skipping clustering.")
-        top_annotation["domain"] = range(1, n_rows + 1)  # Assign unique domains
+        try:
+            # Optimize silhouette score across different linkage methods and distance metrics
+            (
+                best_linkage,
+                best_metric,
+                best_threshold,
+            ) = _optimize_silhouette_across_linkage_and_metrics(
+                m, linkage_criterion, linkage_method, linkage_metric, linkage_threshold
+            )
+            # Perform hierarchical clustering
+            Z = linkage(m, method=best_linkage, metric=best_metric)
+            logger.warning(
+                f"Linkage criterion: '{linkage_criterion}'\nLinkage method: '{best_linkage}'\nLinkage metric: '{best_metric}'\nLinkage threshold: {round(best_threshold, 3)}"
+            )
+            # Calculate the optimal threshold for clustering
+            max_d_optimal = np.max(Z[:, 2]) * best_threshold
+            # Assign domains to the annotation matrix
+            domains = fcluster(Z, max_d_optimal, criterion=linkage_criterion)
+            top_annotation["domain"] = 0
+            top_annotation.loc[top_annotation["significant_annotation"], "domain"] = domains
+        except (LinAlgError, ValueError):
+            # Numerical errors or degenerate input are handled gracefully (not user error)
+            n_rows = len(top_annotation)
+            logger.error(
+                "Clustering failed due to numerical or data degeneracy. Assigning unique domains."
+            )
+            top_annotation["domain"] = range(1, n_rows + 1)
 
     # Create DataFrames to store domain information
     node_to_significance = pd.DataFrame(
@@ -184,6 +195,46 @@ def trim_domains(
     return valid_domains, valid_trimmed_domains_matrix
 
 
+def _validate_clustering_args(
+    linkage_criterion: str,
+    linkage_method: str,
+    linkage_metric: str,
+    linkage_threshold: Union[float, str],
+) -> bool:
+    """
+    Validate user-provided clustering arguments.
+
+    Returns:
+        bool: True if clustering is turned off (criterion == 'off'); False otherwise.
+
+    Raises:
+        ValueError: If any argument is invalid (user error).
+    """
+    # Allow opting out of clustering without raising
+    if linkage_criterion == "off":
+        return True
+    # Validate linkage method (allow "auto")
+    if linkage_method != "auto" and linkage_method not in LINKAGE_METHODS:
+        raise ValueError(
+            f"Invalid linkage_method '{linkage_method}'. Allowed values are 'auto' or one of: {sorted(LINKAGE_METHODS)}"
+        )
+    # Validate linkage metric (allow "auto")
+    if linkage_metric != "auto" and linkage_metric not in LINKAGE_METRICS:
+        raise ValueError(
+            f"Invalid linkage_metric '{linkage_metric}'. Allowed values are 'auto' or one of: {sorted(LINKAGE_METRICS)}"
+        )
+    # Validate linkage threshold (allow "auto"; otherwise must be float in (0, 1])
+    if linkage_threshold != "auto":
+        try:
+            lt = float(linkage_threshold)
+        except (TypeError, ValueError):
+            raise ValueError("linkage_threshold must be 'auto' or a float in the interval (0, 1].")
+        if not (0.0 < lt <= 1.0):
+            raise ValueError(f"linkage_threshold must be within (0, 1]. Received: {lt}")
+
+    return False
+
+
 def _safeguard_matrix(matrix: np.ndarray) -> np.ndarray:
     """
     Safeguard the matrix by replacing NaN, Inf, and -Inf values.

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/src/risk/_neighborhoods/_neighborhoods.py

@@ -394,34 +394,33 @@ def _prune_neighbors(
     # Identify indices with non-zero rows in the binary significance matrix
     non_zero_indices = np.where(significant_binary_significance_matrix.sum(axis=1) != 0)[0]
     median_distances = []
+    distance_lookup = {}
     for node in non_zero_indices:
-        neighbors = [
-            n
-            for n in network.neighbors(node)
-            if significant_binary_significance_matrix[n].sum() != 0
-        ]
-        if neighbors:
-            median_distance = np.median(
-                [_get_euclidean_distance(node, n, network) for n in neighbors]
-            )
-            median_distances.append(median_distance)
+        dist = _median_distance_to_significant_neighbors(
+            node, network, significant_binary_significance_matrix
+        )
+        if dist is not None:
+            median_distances.append(dist)
+            distance_lookup[node] = dist
+
+    if not median_distances:
+        logger.warning("No significant neighbors found for pruning.")
+        significant_significance_matrix = np.where(
+            significant_binary_significance_matrix == 1, significance_matrix, 0
+        )
+        return (
+            significance_matrix,
+            significant_binary_significance_matrix,
+            significant_significance_matrix,
+        )
 
     # Calculate the distance threshold value based on rank
     distance_threshold_value = _calculate_threshold(median_distances, 1 - distance_threshold)
     # Prune nodes that are outliers based on the distance threshold
-    for row_index in non_zero_indices:
-        neighbors = [
-            n
-            for n in network.neighbors(row_index)
-            if significant_binary_significance_matrix[n].sum() != 0
-        ]
-        if neighbors:
-            median_distance = np.median(
-                [_get_euclidean_distance(row_index, n, network) for n in neighbors]
-            )
-            if median_distance >= distance_threshold_value:
-                significance_matrix[row_index] = 0
-                significant_binary_significance_matrix[row_index] = 0
+    for node, dist in distance_lookup.items():
+        if dist >= distance_threshold_value:
+            significance_matrix[node] = 0
+            significant_binary_significance_matrix[node] = 0
 
     # Create a matrix where non-significant entries are set to zero
     significant_significance_matrix = np.where(
@@ -435,6 +434,29 @@ def _prune_neighbors(
     )
 
 
+def _median_distance_to_significant_neighbors(
+    node, network, significance_mask
+) -> Union[float, None]:
+    """
+    Calculate the median distance from a node to its significant neighbors.
+
+    Args:
+        node (Any): The node for which the median distance is being calculated.
+        network (nx.Graph): The network graph containing the nodes.
+        significance_mask (np.ndarray): Binary matrix indicating significant nodes.
+
+    Returns:
+        Union[float, None]: The median distance to significant neighbors, or None if no significant neighbors exist.
+    """
+    neighbors = [n for n in network.neighbors(node) if significance_mask[n].sum() != 0]
+    if not neighbors:
+        return None
+    # Calculate distances to significant neighbors
+    distances = [_get_euclidean_distance(node, n, network) for n in neighbors]
+
+    return np.median(distances)
+
+
 def _get_euclidean_distance(node1: Any, node2: Any, network: nx.Graph) -> float:
     """
     Calculate the Euclidean distance between two nodes in the network.

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/src/risk/_network/_graph/_summary.py

@@ -84,7 +84,7 @@ class Summary:
 
         Returns:
             pd.DataFrame: Processed DataFrame containing significance scores, p-values, q-values,
-                and annotation member information.
+                and matched annotation members information.
         """
         log_header("Loading analysis summary")
         # Calculate significance and depletion q-values from p-value matrices in annotation
@@ -109,9 +109,9 @@ class Summary:
         # Add minimum p-values and q-values to DataFrame
         results[
             [
-                "Enrichment P-Value",
+                "Enrichment P-value",
                 "Enrichment Q-value",
-                "Depletion P-Value",
+                "Depletion P-value",
                 "Depletion Q-value",
             ]
         ] = results.apply(
@@ -126,13 +126,13 @@ class Summary:
             axis=1,
             result_type="expand",
         )
-        # Add annotation members and their counts
-        results["Annotation Members in Network"] = results["Annotation"].apply(
+        # Add matched annotation members and their counts
+        results["Matched Members"] = results["Annotation"].apply(
             lambda desc: self._get_annotation_members(desc)
         )
-        results["Annotation Members in Network Count"] = results[
-            "Annotation Members in Network"
-        ].apply(lambda x: len(x.split(";")) if x else 0)
+        results["Matched Count"] = results["Matched Members"].apply(
+            lambda x: len(x.split(";")) if x else 0
+        )
 
         # Reorder columns and drop rows with NaN values
         results = (
@@ -140,12 +140,12 @@ class Summary:
                 [
                     "Domain ID",
                     "Annotation",
-                    "Annotation Members in Network",
-                    "Annotation Members in Network Count",
+                    "Matched Members",
+                    "Matched Count",
                     "Summed Significance Score",
-                    "Enrichment P-Value",
+                    "Enrichment P-value",
                     "Enrichment Q-value",
-                    "Depletion P-Value",
+                    "Depletion P-value",
                     "Depletion Q-value",
                 ]
             ]
@@ -159,20 +159,18 @@ class Summary:
         results = pd.merge(ordered_annotation, results, on="Annotation", how="left").fillna(
             {
                 "Domain ID": -1,
-                "Annotation Members in Network": "",
-                "Annotation Members in Network Count": 0,
+                "Matched Members": "",
+                "Matched Count": 0,
                 "Summed Significance Score": 0.0,
-                "Enrichment P-Value": 1.0,
+                "Enrichment P-value": 1.0,
                 "Enrichment Q-value": 1.0,
-                "Depletion P-Value": 1.0,
+                "Depletion P-value": 1.0,
                 "Depletion Q-value": 1.0,
             }
         )
-        # Convert "Domain ID" and "Annotation Members in Network Count" to integers
+        # Convert "Domain ID" and "Matched Count" to integers
         results["Domain ID"] = results["Domain ID"].astype(int)
-        results["Annotation Members in Network Count"] = results[
-            "Annotation Members in Network Count"
-        ].astype(int)
+        results["Matched Count"] = results["Matched Count"].astype(int)
 
         return results
 

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/src/risk/_network/_io.py

@@ -164,7 +164,7 @@ class NetworkIO:
         Args:
             compute_sphere (bool, optional): Whether to map nodes to a sphere. Defaults to True.
             surface_depth (float, optional): Surface depth for the sphere. Defaults to 0.0.
-            min_edges_per_node (int, optional): Minimum number of edges per node. Defaults to 0.
+            min_edges_per_node (int, optional): Minimum number of edges per node (k-core threshold). Defaults to 0.
         """
         self.compute_sphere = compute_sphere
         self.surface_depth = surface_depth
@@ -440,20 +440,14 @@ class NetworkIO:
         num_initial_edges = G.number_of_edges()
         # Remove self-loops to ensure correct edge count
         G.remove_edges_from(nx.selfloop_edges(G))
-        # Iteratively remove nodes with fewer edges than the threshold
-        while True:
-            nodes_to_remove = [
-                node
-                for node, degree in dict(G.degree()).items()
-                if degree < self.min_edges_per_node
-            ]
-            if not nodes_to_remove:
-                break  # Exit loop if no nodes meet the condition
-            G.remove_nodes_from(nodes_to_remove)
-
-        # Remove isolated nodes
-        isolates = list(nx.isolates(G))
-        G.remove_nodes_from(isolates)
+        # Apply canonical node k-core pruning if requested
+        if self.min_edges_per_node > 0:
+            # networkx.k_core returns a subgraph; to preserve in-place behavior, copy back
+            core = nx.k_core(G, k=self.min_edges_per_node)
+            # Rebuild G in-place to keep external references valid
+            G.clear()
+            G.add_nodes_from(core.nodes(data=True))
+            G.add_edges_from(core.edges(data=True))
 
         # Log the number of nodes and edges before and after cleaning
         num_final_nodes = G.number_of_nodes()

{risk_network-0.0.14b1 → risk_network-0.0.14b3/src/risk_network.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: risk-network
-Version: 0.0.14b1
+Version: 0.0.14b3
 Summary: A Python package for scalable network analysis and high-quality visualization.
 Author-email: Ira Horecka <ira89@icloud.com>
 License: GPL-3.0-or-later

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/tests/test_load_graph.py

@@ -378,6 +378,94 @@ def test_pop_domain(graph):
         ), f"{domain_id_to_remove} should be removed from node_id_to_domain_ids_and_significance_map['significances']"
 
 
+@pytest.mark.parametrize(
+    "bad_kwargs",
+    [
+        {"linkage_method": "not_a_method"},
+        {"linkage_metric": "not_a_metric"},
+        {"linkage_threshold": "bad"},
+        {"linkage_threshold": 0.0},  # out of (0, 1]
+        {"linkage_threshold": 1.5},  # out of (0, 1]
+    ],
+)
+def test_invalid_clustering_args_raise(risk_obj, cytoscape_network, json_annotation, bad_kwargs):
+    """
+    Validate that invalid clustering options raise a ValueError (user error).
+
+    Args:
+        risk_obj: The RISK object instance used for loading neighborhoods and graphs.
+        cytoscape_network: The network object to be used for neighborhood and graph generation.
+        json_annotation: The JSON annotation associated with the network.
+        bad_kwargs: A dict containing an intentionally invalid clustering parameter.
+    """
+    neighborhoods = risk_obj.load_neighborhoods_binom(
+        network=cytoscape_network,
+        annotation=json_annotation,
+        distance_metric="louvain",
+        louvain_resolution=1.0,
+        fraction_shortest_edges=0.75,
+        null_distribution="network",
+        random_seed=888,
+    )
+
+    with pytest.raises(ValueError):
+        risk_obj.load_graph(
+            network=cytoscape_network,
+            annotation=json_annotation,
+            neighborhoods=neighborhoods,
+            tail="right",
+            pval_cutoff=0.05,
+            fdr_cutoff=1.0,
+            impute_depth=1,
+            prune_threshold=0.1,
+            linkage_criterion="distance",
+            linkage_method=bad_kwargs.get("linkage_method", "average"),
+            linkage_metric=bad_kwargs.get("linkage_metric", "yule"),
+            linkage_threshold=bad_kwargs.get("linkage_threshold", 0.2),
+            min_cluster_size=5,
+            max_cluster_size=1000,
+        )
+
+
+def test_off_criterion_bypasses_invalid_options(risk_obj, cytoscape_network, json_annotation):
+    """
+    Verify that setting linkage_criterion='off' cleanly bypasses clustering validation and does not raise.
+
+    Args:
+        risk_obj: The RISK object instance used for loading neighborhoods and graphs.
+        cytoscape_network: The network object to be used for neighborhood and graph generation.
+        json_annotation: The JSON annotation associated with the network.
+    """
+    neighborhoods = risk_obj.load_neighborhoods_binom(
+        network=cytoscape_network,
+        annotation=json_annotation,
+        distance_metric="louvain",
+        louvain_resolution=1.0,
+        fraction_shortest_edges=0.75,
+        null_distribution="network",
+        random_seed=888,
+    )
+
+    graph = risk_obj.load_graph(
+        network=cytoscape_network,
+        annotation=json_annotation,
+        neighborhoods=neighborhoods,
+        tail="right",
+        pval_cutoff=0.05,
+        fdr_cutoff=1.0,
+        impute_depth=1,
+        prune_threshold=0.1,
+        linkage_criterion="off",
+        linkage_method="not_a_method",
+        linkage_metric="not_a_metric",
+        linkage_threshold="bad",
+        min_cluster_size=5,
+        max_cluster_size=1000,
+    )
+
+    _validate_graph(graph)
+
+
 def _validate_graph(graph):
     """
     Validate that the graph is not None and contains nodes and edges.

{risk_network-0.0.14b1 → risk_network-0.0.14b3}/tests/test_load_network.py

@@ -251,7 +251,7 @@ def test_attribute_fallback_mechanism(risk_obj, data_path):
 @pytest.mark.parametrize("min_edges", [1, 5, 10])
 def test_load_network_min_edges(risk_obj, data_path, min_edges):
     """
-    Test loading a Cytoscape network with varying min_edges_per_node.
+    Test loading a Cytoscape network with varying min_edges_per_node using canonical k-core pruning.
 
     Args:
         risk_obj: The RISK object instance used for loading the network.
@@ -399,7 +399,7 @@ def test_missing_node_attributes(risk_obj, cytoscape_network):
 
 def test_remove_isolates_does_not_raise(risk_obj, dummy_network):
     """
-    Test that loading a network with isolated nodes does not raise an error.
+    Test that canonical k-core removal (via min_edges_per_node) handles isolated nodes without error.
 
     Args:
         risk_obj: The RISK object instance used for loading the network.