risk-network 0.0.9b35__py3-none-any.whl → 0.0.9b37__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.9-beta.35"
+__version__ = "0.0.9-beta.37"

risk/neighborhoods/domains.py

@@ -5,12 +5,12 @@ risk/neighborhoods/domains
 
 from contextlib import suppress
 from itertools import product
-from typing import Tuple
+from typing import Tuple, Union
 
 import numpy as np
 import pandas as pd
 from scipy.cluster.hierarchy import linkage, fcluster
-from sklearn.metrics import silhouette_score
+from sklearn.metrics import calinski_harabasz_score, davies_bouldin_score, silhouette_score
 from tqdm import tqdm
 
 from risk.annotations import get_weighted_description
@@ -18,12 +18,19 @@ from risk.constants import GROUP_LINKAGE_METHODS, GROUP_DISTANCE_METRICS
 from risk.log import logger
 
 
+class LinkageThresholdError(Exception):
+    """Exception raised for errors in the linkage threshold optimization process."""
+
+    pass
+
+
 def define_domains(
     top_annotations: pd.DataFrame,
     significant_neighborhoods_significance: np.ndarray,
     linkage_criterion: str,
     linkage_method: str,
     linkage_metric: str,
+    linkage_threshold: Union[str, float],
 ) -> pd.DataFrame:
     """Define domains and assign nodes to these domains based on their significance scores and clustering,
     handling errors by assigning unique domains when clustering fails.
@@ -31,12 +38,19 @@ def define_domains(
     Args:
         top_annotations (pd.DataFrame): DataFrame of top annotations data for the network nodes.
         significant_neighborhoods_significance (np.ndarray): The binary significance matrix below alpha.
-        linkage_criterion (str): The clustering criterion for defining groups.
-        linkage_method (str): The linkage method for clustering.
-        linkage_metric (str): The linkage metric for clustering.
+        linkage_criterion (str): The clustering criterion for defining groups. Use "distance" for distance-based
+            clustering or "maxclust" for a fixed number of clusters. Use "off" to skip clustering.
+        linkage_method (str): The linkage method for clustering. Use "auto" to try multiple methods.
+        linkage_metric (str): The linkage metric for clustering. Use "auto" to try multiple metrics.
+        linkage_threshold (float): The linkage threshold for clustering, or one of "silhouette", "calinski_harabasz",
+            or "davies_bouldin" to optimize the threshold.
 
     Returns:
         pd.DataFrame: DataFrame with the primary domain for each node.
+
+    Raises:
+        ValueError: If an improper value is passed for linkage_threshold. Acceptable values are "silhouette",
+            "calinski_harabasz", "davies_bouldin", or a float value.
     """
     try:
         if linkage_criterion == "off":
@@ -47,8 +61,10 @@ def define_domains(
         # 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
+        best_linkage, best_metric, best_threshold = (
+            _optimize_linkage_threshold_across_methods_and_metrics(
+                m, linkage_criterion, linkage_method, linkage_metric, linkage_threshold
+            )
         )
         # Perform hierarchical clustering
         Z = linkage(m, method=best_linkage, metric=best_metric)
@@ -74,6 +90,9 @@ def define_domains(
                 f"Error encountered. Skipping clustering and assigning {n_rows} unique domains."
             )
         top_annotations["domain"] = range(1, n_rows + 1)  # Assign unique domains
+    except LinkageThresholdError as e:
+        # If a LinkageThresholdError is encountered, raise a ValueError with the original exception
+        raise ValueError(e) from e
 
     # Create DataFrames to store domain information
     node_to_significance = pd.DataFrame(
@@ -195,125 +214,178 @@ def _safeguard_matrix(matrix: np.ndarray) -> np.ndarray:
     return matrix
 
 
-def _optimize_silhouette_across_linkage_and_metrics(
-    m: np.ndarray, linkage_criterion: str, linkage_method: str, linkage_metric: str
+def _optimize_linkage_threshold_across_methods_and_metrics(
+    m: np.ndarray,
+    linkage_criterion: str,
+    linkage_method: str,
+    linkage_metric: str,
+    linkage_threshold: Union[str, float],
 ) -> Tuple[str, str, float]:
-    """Optimize silhouette score across different linkage methods and distance metrics.
+    """Optimize the linkage method, metric, and threshold for hierarchical clustering. If the threshold is
+    a string, optimize the threshold using the specified metric; otherwise, use the provided threshold.
 
     Args:
         m (np.ndarray): Data matrix.
-        linkage_criterion (str): Clustering criterion.
-        linkage_method (str): Linkage method for clustering.
-        linkage_metric (str): Linkage metric for clustering.
+        linkage_criterion (str): Criterion for fcluster (typically "distance").
+        linkage_method (str): Linkage method for clustering, or "auto" to try multiple methods.
+        linkage_metric (str): Distance metric for clustering, or "auto" to try multiple metrics.
+        linkage_threshold (Union[str, float]): Either a numeric threshold or one of
+            "silhouette", "calinski_harabasz", or "davies_bouldin" to trigger optimization.
 
     Returns:
         Tuple[str, str, float]:
-            - Best linkage method (str)
-            - Best linkage metric (str)
-            - Best threshold (float)
+            - The chosen linkage method.
+            - The chosen linkage metric.
+            - The optimized threshold (a float).
+
+    Raises:
+        ValueError: If linkage_threshold is neither one of the supported keywords nor convertible to float.
     """
-    best_overall_method = linkage_method
-    best_overall_metric = linkage_metric
+    # Supported linkage threshold metrics
+    supported_linkage_thresholds = {"silhouette", "calinski_harabasz", "davies_bouldin"}
+
+    # If linkage_threshold is a string:
+    if isinstance(linkage_threshold, str):
+        if linkage_threshold in supported_linkage_thresholds:
+            opt_metric = linkage_threshold
+        else:
+            try:
+                threshold_float = float(linkage_threshold)
+            except (TypeError, ValueError):
+                raise LinkageThresholdError(
+                    f"linkage_threshold must be one of {', '.join(supported_linkage_thresholds)} or a float value."
+                )
+            return linkage_method, linkage_metric, threshold_float
+    else:
+        # If not a string, try to convert it to float.
+        try:
+            threshold_float = float(linkage_threshold)
+        except (TypeError, ValueError):
+            raise LinkageThresholdError(
+                f"linkage_threshold must be one of {', '.join(supported_linkage_thresholds)} or a float value."
+            )
+        return linkage_method, linkage_metric, threshold_float
+
+    # Otherwise, perform optimization using the specified metric (opt_metric).
+    best_overall_method = None
+    best_overall_metric = None
+    best_overall_threshold = None
     best_overall_score = -np.inf
-    best_overall_threshold = 1
 
-    linkage_methods = GROUP_LINKAGE_METHODS if linkage_method == "auto" else [linkage_method]
-    linkage_metrics = GROUP_DISTANCE_METRICS if linkage_metric == "auto" else [linkage_metric]
-    total_combinations = len(linkage_methods) * len(linkage_metrics)
+    # Use the provided lists if "auto" is specified.
+    methods = GROUP_LINKAGE_METHODS if linkage_method == "auto" else [linkage_method]
+    metrics = GROUP_DISTANCE_METRICS if linkage_metric == "auto" else [linkage_metric]
+    total_combinations = len(methods) * len(metrics)
 
-    # Evaluating optimal linkage method and metric
     for method, metric in tqdm(
-        product(linkage_methods, linkage_metrics),
+        product(methods, metrics),
         desc="Evaluating optimal linkage method and metric",
         total=total_combinations,
         bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}]",
     ):
-        # Some linkage methods and metrics may not work with certain data
         with suppress(ValueError):
             Z = linkage(m, method=method, metric=metric)
-            threshold, score = _find_best_silhouette_score(Z, m, metric, linkage_criterion)
+            threshold, score = _find_optimal_linkage_threshold(
+                Z, m, metric, linkage_criterion, opt_metric=opt_metric
+            )
             if score > best_overall_score:
                 best_overall_score = score
                 best_overall_threshold = threshold
                 best_overall_method = method
                 best_overall_metric = metric
 
+    if best_overall_method is None or best_overall_metric is None or best_overall_threshold is None:
+        raise ValueError("Optimization failed to determine an optimal threshold.")
     return best_overall_method, best_overall_metric, best_overall_threshold
 
 
-def _find_best_silhouette_score(
+def _find_optimal_linkage_threshold(
     Z: np.ndarray,
     m: np.ndarray,
     linkage_metric: str,
     linkage_criterion: str,
-    lower_bound: float = 0.001,
-    upper_bound: float = 1.0,
-    resolution: float = 0.001,
+    opt_metric: str = "silhouette",
 ) -> Tuple[float, float]:
-    """Find the best silhouette score using binary search.
+    """Find the optimal linkage threshold coefficient (multiplier for np.max(Z[:, 2])) via binary search.
+    The threshold is chosen to optimize clustering quality, as measured by the chosen metric.
 
     Args:
         Z (np.ndarray): Linkage matrix.
         m (np.ndarray): Data matrix.
-        linkage_metric (str): Linkage metric for silhouette score calculation.
-        linkage_criterion (str): Clustering criterion.
-        lower_bound (float, optional): Lower bound for search. Defaults to 0.001.
-        upper_bound (float, optional): Upper bound for search. Defaults to 1.0.
-        resolution (float, optional): Desired resolution for the best threshold. Defaults to 0.001.
+        linkage_metric (str): The metric used for clustering quality calculation.
+        linkage_criterion (str): The criterion to pass to fcluster (typically "distance").
+        opt_metric (str): The metric to optimize; one of "silhouette", "calinski_harabasz", or "davies_bouldin".
+            For "silhouette" and "calinski_harabasz", higher is better; for "davies_bouldin", lower is better.
 
     Returns:
         Tuple[float, float]:
-            - Best threshold (float): The threshold that yields the best silhouette score.
-            - Best silhouette score (float): The highest silhouette score achieved.
+            - best_threshold: The optimal linkage coefficient for np.max(Z[:, 2]).
+            - best_metric_value: The clustering quality metric achieved (with higher being better for
+              "silhouette" and "calinski_harabasz", and lower for "davies_bouldin").
     """
-    best_score = -np.inf
-    best_threshold = None
-
-    # Test lower bound
-    max_d_lower = np.max(Z[:, 2]) * lower_bound
-    clusters_lower = fcluster(Z, max_d_lower, criterion=linkage_criterion)
-    try:
-        score_lower = silhouette_score(m, clusters_lower, metric=linkage_metric)
-    except ValueError:
-        score_lower = -np.inf
-
-    # Test upper bound
-    max_d_upper = np.max(Z[:, 2]) * upper_bound
-    clusters_upper = fcluster(Z, max_d_upper, criterion=linkage_criterion)
-    try:
-        score_upper = silhouette_score(m, clusters_upper, metric=linkage_metric)
-    except ValueError:
-        score_upper = -np.inf
-
-    # Determine initial bounds for binary search
-    if score_lower > score_upper:
-        best_score = score_lower
+    max_d = np.max(Z[:, 2])
+    lower_bound = 0.0
+    upper_bound = 1.0
+    resolution = 1e-6
+
+    def compute_objective(coefficient: float) -> float:
+        """Compute the objective function for a given linkage threshold coefficient."""
+        threshold_val = coefficient * max_d
+        clusters = fcluster(Z, threshold_val, criterion=linkage_criterion)
+        unique_clusters = np.unique(clusters)
+        # Return a heavy penalty if the clustering is trivial.
+        if len(unique_clusters) <= 1 or len(unique_clusters) == m.shape[0]:
+            return 1e6
+        try:
+            if opt_metric == "silhouette":
+                score = silhouette_score(m, clusters, metric=linkage_metric)
+                return -score  # We want to maximize the silhouette score.
+            elif opt_metric == "calinski_harabasz":
+                score = calinski_harabasz_score(m, clusters)
+                return -score  # Higher is better.
+            elif opt_metric == "davies_bouldin":
+                score = davies_bouldin_score(m, clusters)
+                return score  # Lower is better.
+            else:
+                raise LinkageThresholdError(f"Unknown optimization metric: {opt_metric}.")
+        except Exception:
+            return 1e6
+
+    # Initialize the bounds and the best objective value
+    obj_lower = compute_objective(lower_bound)
+    obj_upper = compute_objective(upper_bound)
+    # Determine the initial direction of the search
+    if obj_lower < obj_upper:
+        best_obj = obj_lower
         best_threshold = lower_bound
-        upper_bound = (lower_bound + upper_bound) / 2
+        lower = lower_bound
+        upper = (lower_bound + upper_bound) / 2
     else:
-        best_score = score_upper
+        best_obj = obj_upper
         best_threshold = upper_bound
-        lower_bound = (lower_bound + upper_bound) / 2
-
-    # Binary search loop
-    while upper_bound - lower_bound > resolution:
-        mid_threshold = (upper_bound + lower_bound) / 2
-        max_d_mid = np.max(Z[:, 2]) * mid_threshold
-        clusters_mid = fcluster(Z, max_d_mid, criterion=linkage_criterion)
-        try:
-            score_mid = silhouette_score(m, clusters_mid, metric=linkage_metric)
-        except ValueError:
-            score_mid = -np.inf
-
-        # Update best score and threshold if mid-point is better
-        if score_mid > best_score:
-            best_score = score_mid
-            best_threshold = mid_threshold
-
-        # Adjust bounds based on the scores
-        if score_lower > score_upper:
-            upper_bound = mid_threshold
+        lower = (lower_bound + upper_bound) / 2
+        upper = upper_bound
+
+    # Perform binary search to find the optimal linkage threshold coefficient
+    while (upper - lower) > resolution:
+        mid = (upper + lower) / 2
+        obj_mid = compute_objective(mid)
+        if obj_mid < best_obj:
+            best_obj = obj_mid
+            best_threshold = mid
+
+        # Update the bounds based on the objective value
+        obj_left = compute_objective((lower + mid) / 2)
+        obj_right = compute_objective((mid + upper) / 2)
+        if obj_left < obj_right:
+            upper = mid
         else:
-            lower_bound = mid_threshold
+            lower = mid
+
+    # If the optimization metric is silhouette or calinski_harabasz, return the negative value
+    if opt_metric in ["silhouette", "calinski_harabasz"]:
+        best_metric_value = -best_obj
+    else:
+        best_metric_value = best_obj
 
-    return best_threshold, float(best_score)
+    return best_threshold, float(best_metric_value)

risk/network/graph/api.py

@@ -42,6 +42,7 @@ class GraphAPI:
         linkage_criterion: str = "distance",
         linkage_method: str = "average",
         linkage_metric: str = "yule",
+        linkage_threshold: float = 0.2,
         min_cluster_size: int = 5,
         max_cluster_size: int = 1000,
     ) -> Graph:
@@ -59,6 +60,7 @@ class GraphAPI:
             linkage_criterion (str, optional): Clustering criterion for defining domains. Defaults to "distance".
             linkage_method (str, optional): Clustering method to use. Defaults to "average".
             linkage_metric (str, optional): Metric to use for calculating distances. Defaults to "yule".
+            linkage_threshold (float, optional): Threshold for clustering. Defaults to 0.2.
             min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
             max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
 
@@ -76,6 +78,7 @@ class GraphAPI:
             linkage_criterion=linkage_criterion,
             linkage_method=linkage_method,
             linkage_metric=linkage_metric,
+            linkage_threshold=linkage_threshold,
             min_cluster_size=min_cluster_size,
             max_cluster_size=max_cluster_size,
         )
@@ -130,6 +133,7 @@ class GraphAPI:
             linkage_criterion=linkage_criterion,
             linkage_method=linkage_method,
             linkage_metric=linkage_metric,
+            linkage_threshold=linkage_threshold,
         )
         # Trim domains and top annotations based on cluster size constraints
         domains, trimmed_domains = trim_domains(

{risk_network-0.0.9b35.dist-info → risk_network-0.0.9b37.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: risk-network
-Version: 0.0.9b35
+Version: 0.0.9b37
 Summary: A Python package for biological network analysis
 Author: Ira Horecka
 Author-email: Ira Horecka <ira89@icloud.com>

{risk_network-0.0.9b35.dist-info → risk_network-0.0.9b37.dist-info}/RECORD

@@ -1,4 +1,4 @@
-risk/__init__.py,sha256=r0xnE00ojEe_XG3ZBNV_1n3-vl0XWYuOA9-na0o5v2w,127
+risk/__init__.py,sha256=T82k1TIYSqPy3KdA5kWb-5ZtqtksCWdHZ4e5vTYhTSY,127
 risk/constants.py,sha256=XInRaH78Slnw_sWgAsBFbUHkyA0h0jL0DKGuQNbOvjM,550
 risk/risk.py,sha256=s827_lRknFseOP9O4zW8sP-IcCd2EzrpV_tnVY_tz5s,1104
 risk/annotations/__init__.py,sha256=parsbcux1U4urpUqh9AdzbDWuLj9HlMidycMPkpSQFo,179
@@ -10,13 +10,13 @@ risk/log/parameters.py,sha256=VtwfMzLU1xI4yji3-Ch5vHjH-KdwTfwaEMmi7hFQTs0,5716
 risk/neighborhoods/__init__.py,sha256=Q74HwTH7okI-vaskJPy2bYwb5sNjGASTzJ6m8V8arCU,234
 risk/neighborhoods/api.py,sha256=ywngw2TQVV27gYlWDXcs8-qnmeepnvb-W9ov6J6VEPM,23341
 risk/neighborhoods/community.py,sha256=5Q_-VAJC-5SY5EUsB8gIlemeDoAL85uLjyl16pItHiQ,16699
-risk/neighborhoods/domains.py,sha256=jMJ4-Qzwgmo6Hya8h0E2_IcMaLpbuH_FWlmSjJl2ikc,12832
+risk/neighborhoods/domains.py,sha256=lMEKwZaOcFIVFqCPPgER1GQQR_ANIWaNk5m2zRdUH08,16774
 risk/neighborhoods/neighborhoods.py,sha256=l9FhADB1C-OxM8E9QXOcA4osUDgA1vs4ud-OCGKKybc,21457
 risk/network/__init__.py,sha256=oVi3FA1XXKD84014Cykq-9bpX4_s0F3aAUfNOU-07Qw,73
 risk/network/geometry.py,sha256=eVtGHMgBf9fEqQZUFdHWjw-zFYYpfUONoHFSAxoRkug,6219
 risk/network/io.py,sha256=RCH4nQdgYDXcNwMfpSz7qEmPO0pJ1p9fL0rNQptsQrc,21673
 risk/network/graph/__init__.py,sha256=ziGJew3yhtqvrb9LUuneDu_LwW2Wa9vd4UuhoL5l1CA,91
-risk/network/graph/api.py,sha256=t5Mh5_lD2uTLioEJFfCRe7ncc5iLNYzxd6r05wSiv7s,8169
+risk/network/graph/api.py,sha256=9yoviP7EqFU1okLJZlaLBZzFNmjOHv30B1JgDFNP1bg,8399
 risk/network/graph/graph.py,sha256=qEWyZvuaGT_vvjhreBdmRPX3gst2wQFaXhFAvikPSqw,12158
 risk/network/graph/summary.py,sha256=Y_0rL2C1UoQeZQIPVe5LbaCO356Mcc8HisnrXwQsRm8,10289
 risk/network/plotter/__init__.py,sha256=4gWtQHGzQVNHmEBXi31Zf0tX0y2sTcE66J_yGnn7268,99
@@ -34,8 +34,8 @@ risk/stats/stat_tests.py,sha256=tj0ri9w89_1fsjGLuafTWpfBEwZXpSLn7Ej2aAQ5lxk,1177
 risk/stats/permutation/__init__.py,sha256=OLmYLm2uj96hPsSaUs0vUqFYw6Thwch_aHtpL7L0ZFw,127
 risk/stats/permutation/permutation.py,sha256=BWjgdBpLVcHvmwHy0bmD4aJFccxifNBSrrCBPppyKf4,10569
 risk/stats/permutation/test_functions.py,sha256=KlECWTz1EZ6EPF_OAgHb0uznaIhopiVYb_AKUKuC4no,3120
-risk_network-0.0.9b35.dist-info/LICENSE,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
-risk_network-0.0.9b35.dist-info/METADATA,sha256=0rVbcV_Dh2DepCIKj-AbFry3t8J1yPNLyY_Kluq141A,47627
-risk_network-0.0.9b35.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-risk_network-0.0.9b35.dist-info/top_level.txt,sha256=NX7C2PFKTvC1JhVKv14DFlFAIFnKc6Lpsu1ZfxvQwVw,5
-risk_network-0.0.9b35.dist-info/RECORD,,
+risk_network-0.0.9b37.dist-info/LICENSE,sha256=jOtLnuWt7d5Hsx6XXB2QxzrSe2sWWh3NgMfFRetluQM,35147
+risk_network-0.0.9b37.dist-info/METADATA,sha256=5tQlDkFQSqNgXhv-_TZSfraFKAseXh7LCHciBQIR4CQ,47627
+risk_network-0.0.9b37.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+risk_network-0.0.9b37.dist-info/top_level.txt,sha256=NX7C2PFKTvC1JhVKv14DFlFAIFnKc6Lpsu1ZfxvQwVw,5
+risk_network-0.0.9b37.dist-info/RECORD,,