risk-network 0.0.3b1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
risk/risk.py ADDED
@@ -0,0 +1,382 @@
1
+ """
2
+ risk/risk
3
+ ~~~~~~~~~
4
+ """
5
+
6
+ from typing import Any, Dict
7
+
8
+ import networkx as nx
9
+ import pandas as pd
10
+
11
+ from risk.annotations import AnnotationsIO, define_top_annotations
12
+ from risk.log import params, print_header
13
+ from risk.neighborhoods import (
14
+ define_domains,
15
+ get_network_neighborhoods,
16
+ process_neighborhoods,
17
+ trim_domains_and_top_annotations,
18
+ )
19
+ from risk.network import NetworkIO, NetworkGraph, NetworkPlotter
20
+ from risk.stats import compute_permutation, calculate_significance_matrices
21
+
22
+
23
+ class RISK(NetworkIO, AnnotationsIO):
24
+ """RISK: A class for network analysis and visualization.
25
+
26
+ The RISK class integrates functionalities for loading networks, processing annotations,
27
+ and performing network-based statistical analysis, such as neighborhood significance testing.
28
+ """
29
+
30
+ def __init__(
31
+ self,
32
+ compute_sphere: bool = True,
33
+ surface_depth: float = 0.0,
34
+ distance_metric: str = "dijkstra",
35
+ louvain_resolution: float = 0.1,
36
+ min_edges_per_node: int = 0,
37
+ edge_length_threshold: float = 0.5,
38
+ include_edge_weight: bool = True,
39
+ weight_label: str = "weight",
40
+ ):
41
+ """Initialize the RISK class with configuration settings.
42
+
43
+ Args:
44
+ compute_sphere (bool, optional): Whether to map nodes to a sphere. Defaults to True.
45
+ surface_depth (float, optional): Surface depth for the sphere. Defaults to 0.0.
46
+ distance_metric (str, optional): Distance metric to use in network analysis. Defaults to "dijkstra".
47
+ louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
48
+ min_edges_per_node (int, optional): Minimum number of edges per node. Defaults to 0.
49
+ edge_length_threshold (float, optional): Edge length threshold for analysis. Defaults to 0.5.
50
+ include_edge_weight (bool, optional): Whether to include edge weights in calculations. Defaults to True.
51
+ weight_label (str, optional): Label for edge weights. Defaults to "weight".
52
+ """
53
+ # Initialize and log network parameters
54
+ params.initialize()
55
+ params.log_network(
56
+ compute_sphere=compute_sphere,
57
+ surface_depth=surface_depth,
58
+ distance_metric=distance_metric,
59
+ louvain_resolution=louvain_resolution,
60
+ min_edges_per_node=min_edges_per_node,
61
+ edge_length_threshold=edge_length_threshold,
62
+ include_edge_weight=include_edge_weight,
63
+ weight_label=weight_label,
64
+ )
65
+ # Initialize parent classes
66
+ NetworkIO.__init__(
67
+ self,
68
+ compute_sphere=compute_sphere,
69
+ surface_depth=surface_depth,
70
+ distance_metric=distance_metric,
71
+ louvain_resolution=louvain_resolution,
72
+ min_edges_per_node=min_edges_per_node,
73
+ edge_length_threshold=edge_length_threshold,
74
+ include_edge_weight=include_edge_weight,
75
+ weight_label=weight_label,
76
+ )
77
+ AnnotationsIO.__init__(self)
78
+
79
+ # Set class attributes
80
+ self.compute_sphere = compute_sphere
81
+ self.surface_depth = surface_depth
82
+ self.distance_metric = distance_metric
83
+ self.louvain_resolution = louvain_resolution
84
+ self.min_edges_per_node = min_edges_per_node
85
+ self.edge_length_threshold = edge_length_threshold
86
+ self.include_edge_weight = include_edge_weight
87
+ self.weight_label = weight_label
88
+
89
+ @property
90
+ def params(self):
91
+ """Access the logged parameters."""
92
+ return params
93
+
94
+ def load_neighborhoods(
95
+ self,
96
+ network: nx.Graph,
97
+ annotations: Dict[str, Any],
98
+ score_metric: str = "sum",
99
+ null_distribution: str = "network",
100
+ num_permutations: int = 1000,
101
+ random_seed: int = 888,
102
+ max_workers: int = 1,
103
+ ) -> Dict[str, Any]:
104
+ """Load significant neighborhoods for the network.
105
+
106
+ Args:
107
+ network (nx.Graph): The network graph.
108
+ annotations (pd.DataFrame): The matrix of annotations associated with the network.
109
+ score_metric (str, optional): Scoring metric for neighborhood significance. Defaults to "sum".
110
+ null_distribution (str, optional): Distribution used for permutation tests. Defaults to "network".
111
+ num_permutations (int, optional): Number of permutations for significance testing. Defaults to 1000.
112
+ random_seed (int, optional): Seed for random number generation. Defaults to 888.
113
+ max_workers (int, optional): Maximum number of workers for parallel computation. Defaults to 1.
114
+
115
+ Returns:
116
+ dict: Computed significance of neighborhoods.
117
+ """
118
+ print_header("Running permutation test")
119
+ # Log neighborhood analysis parameters
120
+ params.log_neighborhoods(
121
+ score_metric=score_metric,
122
+ null_distribution=null_distribution,
123
+ num_permutations=num_permutations,
124
+ random_seed=random_seed,
125
+ max_workers=max_workers,
126
+ )
127
+
128
+ # Display the chosen distance metric
129
+ if self.distance_metric == "louvain":
130
+ for_print_distance_metric = f"louvain (resolution={self.louvain_resolution})"
131
+ else:
132
+ for_print_distance_metric = self.distance_metric
133
+ print(f"Distance metric: '{for_print_distance_metric}'")
134
+ # Compute neighborhoods based on the network and distance metric
135
+ neighborhoods = get_network_neighborhoods(
136
+ network,
137
+ self.distance_metric,
138
+ self.edge_length_threshold,
139
+ louvain_resolution=self.louvain_resolution,
140
+ random_seed=random_seed,
141
+ )
142
+
143
+ # Log and display permutation test settings
144
+ print(f"Null distribution: '{null_distribution}'")
145
+ print(f"Neighborhood scoring metric: '{score_metric}'")
146
+ print(f"Number of permutations: {num_permutations}")
147
+ # Run the permutation test to compute neighborhood significance
148
+ neighborhood_significance = compute_permutation(
149
+ neighborhoods=neighborhoods,
150
+ annotations=annotations["matrix"],
151
+ score_metric=score_metric,
152
+ null_distribution=null_distribution,
153
+ num_permutations=num_permutations,
154
+ random_seed=random_seed,
155
+ max_workers=max_workers,
156
+ )
157
+
158
+ return neighborhood_significance
159
+
160
+ def load_graph(
161
+ self,
162
+ network: nx.Graph,
163
+ annotations: Dict[str, Any],
164
+ neighborhoods: Dict[str, Any],
165
+ tail: str = "right", # OPTIONS: "right" (enrichment), "left" (depletion), "both"
166
+ pval_cutoff: float = 0.01, # OPTIONS: Any value between 0 to 1
167
+ fdr_cutoff: float = 0.9999, # OPTIONS: Any value between 0 to 1
168
+ impute_depth: int = 1,
169
+ prune_threshold: float = 0.0,
170
+ linkage_criterion: str = "distance",
171
+ linkage_method: str = "average",
172
+ linkage_metric: str = "yule",
173
+ min_cluster_size: int = 5,
174
+ max_cluster_size: int = 1000,
175
+ ) -> NetworkGraph:
176
+ """Load and process the network graph, defining top annotations and domains.
177
+
178
+ Args:
179
+ network (nx.Graph): The network graph.
180
+ annotations (pd.DataFrame): DataFrame containing annotation data for the network.
181
+ neighborhoods (dict): Neighborhood enrichment data.
182
+ tail (str, optional): Type of significance tail ("right", "left", "both"). Defaults to "right".
183
+ pval_cutoff (float, optional): P-value cutoff for significance. Defaults to 0.01.
184
+ fdr_cutoff (float, optional): FDR cutoff for significance. Defaults to 0.9999.
185
+ impute_depth (int, optional): Depth for imputing neighbors. Defaults to 1.
186
+ prune_threshold (float, optional): Distance threshold for pruning neighbors. Defaults to 0.0.
187
+ linkage_criterion (str, optional): Clustering criterion for defining domains. Defaults to "distance".
188
+ linkage_method (str, optional): Clustering method to use. Defaults to "average".
189
+ linkage_metric (str, optional): Metric to use for calculating distances. Defaults to "yule".
190
+ min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
191
+ max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
192
+
193
+ Returns:
194
+ NetworkGraph: A fully initialized and processed NetworkGraph object.
195
+ """
196
+ # Log the parameters and display headers
197
+ print_header("Finding significant neighborhoods")
198
+ params.log_graph(
199
+ tail=tail,
200
+ pval_cutoff=pval_cutoff,
201
+ fdr_cutoff=fdr_cutoff,
202
+ impute_depth=impute_depth,
203
+ prune_threshold=prune_threshold,
204
+ linkage_criterion=linkage_criterion,
205
+ linkage_method=linkage_method,
206
+ linkage_metric=linkage_metric,
207
+ min_cluster_size=min_cluster_size,
208
+ max_cluster_size=max_cluster_size,
209
+ )
210
+
211
+ print(f"P-value cutoff: {pval_cutoff}")
212
+ print(f"FDR BH cutoff: {fdr_cutoff}")
213
+ print(
214
+ f"Significance tail: '{tail}' ({'enrichment' if tail == 'right' else 'depletion' if tail == 'left' else 'both'})"
215
+ )
216
+ # Calculate significant neighborhoods based on the provided parameters
217
+ significant_neighborhoods = calculate_significance_matrices(
218
+ neighborhoods["depletion_pvals"],
219
+ neighborhoods["enrichment_pvals"],
220
+ tail=tail,
221
+ pval_cutoff=pval_cutoff,
222
+ fdr_cutoff=fdr_cutoff,
223
+ )
224
+
225
+ print_header("Processing neighborhoods")
226
+ # Process neighborhoods by imputing and pruning based on the given settings
227
+ processed_neighborhoods = process_neighborhoods(
228
+ network=network,
229
+ neighborhoods=significant_neighborhoods,
230
+ impute_depth=impute_depth,
231
+ prune_threshold=prune_threshold,
232
+ )
233
+
234
+ print_header("Finding top annotations")
235
+ print(f"Min cluster size: {min_cluster_size}")
236
+ print(f"Max cluster size: {max_cluster_size}")
237
+ # Define top annotations based on processed neighborhoods
238
+ top_annotations = self._define_top_annotations(
239
+ network=network,
240
+ annotations=annotations,
241
+ neighborhoods=processed_neighborhoods,
242
+ min_cluster_size=min_cluster_size,
243
+ max_cluster_size=max_cluster_size,
244
+ )
245
+
246
+ print_header(f"Optimizing distance threshold for domains")
247
+ # Define domains in the network using the specified clustering settings
248
+ domains = self._define_domains(
249
+ neighborhoods=processed_neighborhoods,
250
+ top_annotations=top_annotations,
251
+ linkage_criterion=linkage_criterion,
252
+ linkage_method=linkage_method,
253
+ linkage_metric=linkage_metric,
254
+ )
255
+ # Trim domains and top annotations based on cluster size constraints
256
+ top_annotations, domains, trimmed_domains = trim_domains_and_top_annotations(
257
+ domains=domains,
258
+ top_annotations=top_annotations,
259
+ min_cluster_size=min_cluster_size,
260
+ max_cluster_size=max_cluster_size,
261
+ )
262
+
263
+ # Prepare node mapping and enrichment sums for the final NetworkGraph object
264
+ ordered_nodes = annotations["ordered_nodes"]
265
+ node_label_to_id = dict(zip(ordered_nodes, range(len(ordered_nodes))))
266
+ node_enrichment_sums = processed_neighborhoods["node_enrichment_sums"]
267
+
268
+ # Return the fully initialized NetworkGraph object
269
+ return NetworkGraph(
270
+ network=network,
271
+ top_annotations=top_annotations,
272
+ domains=domains,
273
+ trimmed_domains=trimmed_domains,
274
+ node_label_to_id_map=node_label_to_id,
275
+ node_enrichment_sums=node_enrichment_sums,
276
+ )
277
+
278
+ def load_plotter(
279
+ self,
280
+ graph: NetworkGraph,
281
+ figsize: tuple = (10, 10),
282
+ background_color: str = "white",
283
+ plot_outline: bool = True,
284
+ outline_color: str = "black",
285
+ outline_scale: float = 1.00,
286
+ ) -> NetworkPlotter:
287
+ """Get a NetworkPlotter object for plotting.
288
+
289
+ Args:
290
+ graph (NetworkGraph): The graph to plot.
291
+ figsize (tuple, optional): Size of the figure. Defaults to (10, 10).
292
+ background_color (str, optional): Background color of the plot. Defaults to "white".
293
+ plot_outline (bool, optional): Whether to plot the network outline. Defaults to True.
294
+ outline_color (str, optional): Color of the outline. Defaults to "black".
295
+ outline_scale (float, optional): Scaling factor for the outline. Defaults to 1.00.
296
+
297
+ Returns:
298
+ NetworkPlotter: A NetworkPlotter object configured with the given parameters.
299
+ """
300
+ print_header("Loading plotter")
301
+ # Log the plotter settings
302
+ params.log_plotter(
303
+ figsize=figsize,
304
+ background_color=background_color,
305
+ plot_outline=plot_outline,
306
+ outline_color=outline_color,
307
+ outline_scale=outline_scale,
308
+ )
309
+ # Initialize and return a NetworkPlotter object
310
+ return NetworkPlotter(
311
+ graph,
312
+ figsize=figsize,
313
+ background_color=background_color,
314
+ plot_outline=plot_outline,
315
+ outline_color=outline_color,
316
+ outline_scale=outline_scale,
317
+ )
318
+
319
+ def _define_top_annotations(
320
+ self,
321
+ network: nx.Graph,
322
+ annotations: Dict[str, Any],
323
+ neighborhoods: Dict[str, Any],
324
+ min_cluster_size: int = 5,
325
+ max_cluster_size: int = 1000,
326
+ ) -> pd.DataFrame:
327
+ """Define top annotations for the network.
328
+
329
+ Args:
330
+ network (nx.Graph): The network graph.
331
+ annotations (dict): Annotations data for the network.
332
+ neighborhoods (dict): Neighborhood enrichment data.
333
+ min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
334
+ max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
335
+
336
+ Returns:
337
+ dict: Top annotations identified within the network.
338
+ """
339
+ # Extract necessary data from annotations and neighborhoods
340
+ ordered_annotations = annotations["ordered_annotations"]
341
+ neighborhood_enrichment_sums = neighborhoods["neighborhood_enrichment_counts"]
342
+ neighborhoods_binary_enrichment_matrix = neighborhoods["binary_enrichment_matrix"]
343
+ # Call external function to define top annotations
344
+ return define_top_annotations(
345
+ network=network,
346
+ ordered_annotation_labels=ordered_annotations,
347
+ neighborhood_enrichment_sums=neighborhood_enrichment_sums,
348
+ binary_enrichment_matrix=neighborhoods_binary_enrichment_matrix,
349
+ min_cluster_size=min_cluster_size,
350
+ max_cluster_size=max_cluster_size,
351
+ )
352
+
353
+ def _define_domains(
354
+ self,
355
+ neighborhoods: Dict[str, Any],
356
+ top_annotations: pd.DataFrame,
357
+ linkage_criterion: str,
358
+ linkage_method: str,
359
+ linkage_metric: str,
360
+ ) -> pd.DataFrame:
361
+ """Define domains in the network based on enrichment data.
362
+
363
+ Args:
364
+ neighborhoods (dict): Enrichment data for neighborhoods.
365
+ top_annotations (pd.DataFrame): Enrichment matrix for top annotations.
366
+ linkage_criterion (str): Clustering criterion for defining domains.
367
+ linkage_method (str): Clustering method to use.
368
+ linkage_metric (str): Metric to use for calculating distances.
369
+
370
+ Returns:
371
+ pd.DataFrame: Matrix of defined domains.
372
+ """
373
+ # Extract the significant enrichment matrix from the neighborhoods data
374
+ significant_neighborhoods_enrichment = neighborhoods["significant_enrichment_matrix"]
375
+ # Call external function to define domains based on the extracted data
376
+ return define_domains(
377
+ top_annotations=top_annotations,
378
+ significant_neighborhoods_enrichment=significant_neighborhoods_enrichment,
379
+ linkage_criterion=linkage_criterion,
380
+ linkage_method=linkage_method,
381
+ linkage_metric=linkage_metric,
382
+ )
risk/stats/__init__.py ADDED
@@ -0,0 +1,6 @@
1
+ """
2
+ risk/stats
3
+ ~~~~~~~~~~
4
+ """
5
+
6
+ from .stats import calculate_significance_matrices, compute_permutation
@@ -0,0 +1,88 @@
1
+ """
2
+ risk/stats/permutation
3
+ ~~~~~~~~~~~~~~~~~~~~~~
4
+ """
5
+
6
+ import numpy as np
7
+
8
+ # Note: Cython optimizations provided minimal performance benefits.
9
+ # The final version with Cython is archived in the `cython_permutation` branch.
10
+
11
+
12
+ def compute_neighborhood_score_by_sum(
13
+ neighborhoods_matrix: np.ndarray, annotation_matrix: np.ndarray
14
+ ) -> np.ndarray:
15
+ """Compute the sum of attribute values for each neighborhood.
16
+
17
+ Args:
18
+ neighborhoods_matrix (np.ndarray): Binary matrix representing neighborhoods.
19
+ annotation_matrix (np.ndarray): Matrix representing annotation values.
20
+
21
+ Returns:
22
+ np.ndarray: Sum of attribute values for each neighborhood.
23
+ """
24
+ # Calculate the neighborhood score as the dot product of neighborhoods and annotations
25
+ neighborhood_score = np.dot(neighborhoods_matrix, annotation_matrix)
26
+ return neighborhood_score
27
+
28
+
29
+ def compute_neighborhood_score_by_stdev(
30
+ neighborhoods_matrix: np.ndarray, annotation_matrix: np.ndarray
31
+ ) -> np.ndarray:
32
+ """Compute the standard deviation of neighborhood scores.
33
+
34
+ Args:
35
+ neighborhoods_matrix (np.ndarray): Binary matrix representing neighborhoods.
36
+ annotation_matrix (np.ndarray): Matrix representing annotation values.
37
+
38
+ Returns:
39
+ np.ndarray: Standard deviation of the neighborhood scores.
40
+ """
41
+ # Calculate the neighborhood score as the dot product of neighborhoods and annotations
42
+ neighborhood_score = np.dot(neighborhoods_matrix, annotation_matrix)
43
+ # Calculate the number of elements in each neighborhood
44
+ N = np.sum(neighborhoods_matrix, axis=1)
45
+ # Compute the mean of the neighborhood scores
46
+ M = neighborhood_score / N[:, None]
47
+ # Compute the mean of squares (EXX) directly using squared annotation matrix
48
+ EXX = np.dot(neighborhoods_matrix, annotation_matrix**2) / N[:, None]
49
+ # Calculate variance as EXX - M^2
50
+ variance = EXX - M**2
51
+ # Compute the standard deviation as the square root of the variance
52
+ stdev = np.sqrt(variance)
53
+ return stdev
54
+
55
+
56
+ def compute_neighborhood_score_by_z_score(
57
+ neighborhoods_matrix: np.ndarray, annotation_matrix: np.ndarray
58
+ ) -> np.ndarray:
59
+ """Compute Z-scores for neighborhood scores.
60
+
61
+ Args:
62
+ neighborhoods_matrix (np.ndarray): Binary matrix representing neighborhoods.
63
+ annotation_matrix (np.ndarray): Matrix representing annotation values.
64
+
65
+ Returns:
66
+ np.ndarray: Z-scores for each neighborhood.
67
+ """
68
+ # Calculate the neighborhood score as the dot product of neighborhoods and annotations
69
+ neighborhood_score = np.dot(neighborhoods_matrix, annotation_matrix)
70
+ # Calculate the number of elements in each neighborhood
71
+ N = np.dot(
72
+ neighborhoods_matrix, np.ones(annotation_matrix.shape[1], dtype=annotation_matrix.dtype)
73
+ )
74
+ # Compute the mean of the neighborhood scores
75
+ M = neighborhood_score / N
76
+ # Compute the mean of squares (EXX)
77
+ EXX = np.dot(neighborhoods_matrix, annotation_matrix**2) / N
78
+ # Calculate the standard deviation for each neighborhood
79
+ variance = EXX - M**2
80
+ std = np.sqrt(variance)
81
+ # Calculate Z-scores, handling cases where std is 0 or N is less than 3
82
+ with np.errstate(divide="ignore", invalid="ignore"):
83
+ z_scores = M / std
84
+ z_scores[(std == 0) | (N < 3)] = (
85
+ np.nan
86
+ ) # Handle division by zero and apply minimum threshold
87
+
88
+ return z_scores