cc-mapping 0.1.0__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.
@@ -0,0 +1,1446 @@
1
+ """
2
+ Base classes and models for Gaussian Mixture Model (GMM) based thresholding.
3
+
4
+ This module provides:
5
+ - Pydantic models for storing GMM information, decision boundaries, and thresholding events
6
+ - GaussianMixtureModelBase: Base class with shared utilities for GMM operations
7
+
8
+ Classes:
9
+ _GaussianMixtureModelInfo: Pydantic model for GMM parameters and results
10
+ _DecisionBoundariesModel: Pydantic model for decision boundary thresholds
11
+ _SingleThresholdingEventModel: Pydantic model for complete thresholding event data
12
+ GaussianMixtureModelBase: Base class providing shared utilities and plotting methods
13
+ """
14
+
15
+ from typing import Dict, List, Optional, Tuple, Union
16
+ import warnings
17
+ from pathlib import Path
18
+
19
+ import anndata as ad
20
+ from kneed import KneeLocator
21
+ from matplotlib import axes
22
+ from matplotlib.figure import Figure
23
+ import matplotlib as mpl
24
+ import matplotlib.pyplot as plt
25
+ import matplotlib.gridspec as gridspec
26
+ import matplotlib.patches as mpatches
27
+ import mpl_scatter_density
28
+ from mpl_toolkits.axes_grid1 import make_axes_locatable
29
+ import numpy as np
30
+ import pandas as pd
31
+ import scipy.stats as st
32
+ from pydantic import BaseModel, Field, field_validator
33
+ from sklearn.mixture import GaussianMixture
34
+
35
+
36
+ def _validate_save_path(save_path: Optional[Union[str, Path]]) -> Optional[Path]:
37
+ """
38
+ Validate that the directory of the save_path exists.
39
+
40
+ Parameters
41
+ ----------
42
+ save_path : str or Path or None
43
+ Path where the figure should be saved. Can be str or Path.
44
+
45
+ Returns
46
+ -------
47
+ Path or None
48
+ Path object if save_path is provided, None otherwise.
49
+
50
+ Raises
51
+ ------
52
+ FileNotFoundError
53
+ If the parent directory of save_path doesn't exist.
54
+
55
+ Examples
56
+ --------
57
+ >>> path = _validate_save_path('results/sequential/figure.png')
58
+ >>> # Raises error if 'results/sequential/' doesn't exist
59
+ """
60
+ if save_path is None:
61
+ return None
62
+
63
+ save_path = Path(save_path)
64
+ parent_dir = save_path.parent
65
+
66
+ if not parent_dir.exists():
67
+ raise FileNotFoundError(
68
+ f"Directory '{parent_dir}' does not exist. "
69
+ f"Please create it before saving the figure."
70
+ )
71
+
72
+ return save_path
73
+
74
+
75
+ class _GaussianMixtureModelInfo(BaseModel):
76
+ """
77
+ Model to store Gaussian Mixture Model (GMM) information.
78
+
79
+ Attributes
80
+ ----------
81
+ gmm_kwargs : dict or None
82
+ Keyword arguments used for the Gaussian Mixture Model.
83
+ means : list of float or None
84
+ Means of the GMM components.
85
+ covs : list of float or None
86
+ Covariances of the GMM components.
87
+ weights : list of float or None
88
+ Weights of the GMM components.
89
+ n_components : int or None
90
+ Number of GMM components.
91
+ data_probs : list of list of float or None
92
+ Probability of each data point belonging to each gmm component.
93
+ condensed_data_probs : list of list of float or None
94
+ Condensed data probabilities after handling duplicates (optional).
95
+ """
96
+
97
+ gmm_kwargs: Optional[Dict] = Field(
98
+ default=None,
99
+ description="Keyword arguments used for the Gaussian Mixture Model.",
100
+ )
101
+ means: Optional[List[float]] = Field(
102
+ default=None, description="Means of the GMM components."
103
+ )
104
+ covs: Optional[List[float]] = Field(
105
+ default=None, description="Covariances of the GMM components."
106
+ )
107
+ weights: Optional[List[float]] = Field(
108
+ default=None, description="Weights of the GMM components."
109
+ )
110
+ n_components: Optional[int] = Field(
111
+ default=None, description="Number of GMM components."
112
+ )
113
+ data_probs: Optional[List[List[float]]] = Field(
114
+ default=None,
115
+ description="Probability of each data point belonging to each gmm component.",
116
+ )
117
+ condensed_data_probs: Optional[List[List[float]]] = Field(
118
+ default=None,
119
+ description="Condensed data probabilities after handling duplicates (optional).",
120
+ )
121
+
122
+ @field_validator("*", mode="before") # Apply validator to all fields
123
+ @classmethod
124
+ def convert_numpy_to_list(cls, value):
125
+ """
126
+ Converts NumPy arrays to lists for Pydantic validation/serialization.
127
+
128
+ Parameters
129
+ ----------
130
+ value : any
131
+ Value to convert.
132
+
133
+ Returns
134
+ -------
135
+ any
136
+ Converted value (list if input was numpy array, otherwise unchanged).
137
+ """
138
+ if isinstance(value, np.ndarray):
139
+ return value.tolist()
140
+ return value
141
+
142
+
143
+ class _DecisionBoundariesModel(BaseModel):
144
+ """
145
+ Model to store decision boundary information.
146
+
147
+ Attributes
148
+ ----------
149
+ thresholds : list of float
150
+ List of decision boundary thresholds.
151
+ """
152
+
153
+ thresholds: List[float] = Field(description="List of decision boundary thresholds.")
154
+
155
+
156
+ class _SingleThresholdingEventModel(BaseModel):
157
+ """
158
+ Model to store all information for a single thresholding event.
159
+
160
+ Attributes
161
+ ----------
162
+ gmm_info : _GaussianMixtureModelInfo or None
163
+ Gaussian Mixture Model information.
164
+ ordered_gmm_labels : list of str or None
165
+ Ordered labels corresponding to the gmm components.
166
+ decision_boundaries : _DecisionBoundariesModel or None
167
+ Decision boundary information (optional).
168
+ condensed_labels : list of str or None
169
+ Condensed labels after handling duplicates (optional).
170
+ feature_name : str
171
+ Name of the feature that was thresholded.
172
+ gmm_obs_label : str
173
+ Observation label in anndata object to store gmm phase labels.
174
+ """
175
+
176
+ gmm_info: Optional[_GaussianMixtureModelInfo] = Field(
177
+ description="Gaussian Mixture Model information.",
178
+ default=None,
179
+ )
180
+ ordered_gmm_labels: Optional[List[str]] = Field(
181
+ description="Ordered labels corresponding to the gmm components.",
182
+ default=None
183
+ )
184
+ decision_boundaries: Optional[_DecisionBoundariesModel] = Field(
185
+ default=None, description="Decision boundary information (optional)."
186
+ )
187
+ condensed_labels: Optional[List[str]] = Field(
188
+ default=None,
189
+ description="Condensed labels after handling duplicates (optional).",
190
+ )
191
+ feature_name: str = Field(description="Name of the feature that was thresholded.")
192
+ gmm_obs_label: str = Field(
193
+ description="Observation label in anndata object to store gmm phase labels."
194
+ )
195
+
196
+
197
+ class GaussianMixtureModelBase:
198
+ """
199
+ Base class providing shared utilities for GMM-based thresholding operations.
200
+
201
+ This class contains utility methods and plotting functions that are common
202
+ to both single-dataset thresholding and sequential refinement operations.
203
+ It should not be instantiated directly; use GMMThresholding
204
+ or SequentialGMM instead.
205
+
206
+ The class provides:
207
+ - Utility methods for data manipulation and label handling
208
+ - BIC calculation and component optimization
209
+ - Parameterized plotting methods for visualizing GMM results
210
+ - Decision boundary calculation utilities
211
+ """
212
+
213
+ def _ensure_list(self, value: any) -> list:
214
+ """
215
+ Ensures that the input value is a list.
216
+
217
+ Parameters
218
+ ----------
219
+ value : any
220
+ Value to convert to list.
221
+
222
+ Returns
223
+ -------
224
+ list
225
+ Input value as a list.
226
+ """
227
+ if isinstance(value, list):
228
+ return value
229
+ return [value.item()] if hasattr(value, "item") else [value]
230
+
231
+ def _handle_duplicate_labels(
232
+ self, data_probs: np.ndarray, ordered_gmm_labels: list
233
+ ) -> tuple:
234
+ """
235
+ Handles duplicate labels in the gmm results.
236
+
237
+ Parameters
238
+ ----------
239
+ data_probs : np.ndarray
240
+ Probability matrix (samples x components).
241
+ ordered_gmm_labels : list
242
+ List of label names for each component.
243
+
244
+ Returns
245
+ -------
246
+ tuple of (np.ndarray, list)
247
+ Condensed probability matrix and condensed label list.
248
+ """
249
+ df_probs = pd.DataFrame(data_probs, columns=ordered_gmm_labels)
250
+ # Use sort=False to preserve the original order of labels
251
+ grouped = df_probs.T.groupby(level=0, sort=False)
252
+ condensed_data_probs = grouped.max().T.values
253
+ condensed_labels = grouped.first().index.tolist()
254
+ return condensed_data_probs, condensed_labels
255
+
256
+ def _calculate_decision_boundaries_from_probs(
257
+ self,
258
+ feature_values: np.ndarray,
259
+ data_probs: np.ndarray,
260
+ ordered_labels: list[str] | None = None
261
+ ) -> _DecisionBoundariesModel:
262
+ """
263
+ Calculate decision boundaries from any probability array.
264
+
265
+ This method works with both original GMM probabilities and condensed
266
+ probabilities from collapsed labels. It finds class transitions and
267
+ calculates threshold midpoints.
268
+
269
+ Parameters
270
+ ----------
271
+ feature_values : np.ndarray
272
+ Array of feature values for all samples.
273
+ data_probs : np.ndarray
274
+ Probability matrix (samples x components) from GMM or
275
+ condensed from duplicate label collapsing.
276
+ ordered_labels : list of str or None, optional
277
+ List of label names corresponding to components.
278
+ If provided, used to make warning messages more interpretable.
279
+
280
+ Returns
281
+ -------
282
+ _DecisionBoundariesModel
283
+ Contains calculated thresholds.
284
+
285
+ Warns
286
+ -----
287
+ UserWarning
288
+ If backward transitions are detected (likely due to outliers
289
+ or overlapping components).
290
+ """
291
+ # Sort feature values and get sort indices
292
+ sort_index = np.argsort(feature_values)
293
+ sorted_feature_values = feature_values[sort_index]
294
+ sorted_probabilities = data_probs[sort_index]
295
+
296
+ # Determine the predicted class for each data point
297
+ predicted_classes = np.argmax(sorted_probabilities, axis=1)
298
+
299
+ # Calculate the difference between consecutive predicted classes
300
+ class_differences = np.diff(predicted_classes)
301
+
302
+ # Find indices where class changes occur (any non-zero change)
303
+ change_indices = np.where(class_differences != 0)[0]
304
+
305
+ # Filter out backward transitions (non-increasing component indices)
306
+ # This handles outliers that cause the argmax to "jump back" to earlier components
307
+ forward_transitions = []
308
+ backward_transitions = []
309
+
310
+ for idx in change_indices:
311
+ from_class = predicted_classes[idx]
312
+ to_class = predicted_classes[idx + 1]
313
+
314
+ if to_class > from_class:
315
+ # Forward transition - keep it
316
+ forward_transitions.append(idx)
317
+ else:
318
+ # Backward transition - record but don't use
319
+ transition_location = sorted_feature_values[idx]
320
+ backward_transitions.append((from_class, to_class, transition_location))
321
+
322
+ # Warn user if backward transitions were detected
323
+ if backward_transitions:
324
+ n_components = data_probs.shape[1]
325
+ expected_thresholds = n_components - 1
326
+
327
+ # Build detailed transition descriptions with label names if available
328
+ transition_details = []
329
+ for fr, to, loc in backward_transitions:
330
+ if ordered_labels is not None:
331
+ from_label = ordered_labels[fr]
332
+ to_label = ordered_labels[to]
333
+ transition_details.append(
334
+ f" • {from_label} (component {fr}) → {to_label} (component {to}) at x ≈ {loc:.3f}"
335
+ )
336
+ else:
337
+ transition_details.append(f" • component {fr} → {to} at x ≈ {loc:.3f}")
338
+
339
+ transition_str = "\n".join(transition_details)
340
+
341
+ warnings.warn(
342
+ f"\nDetected {len(backward_transitions)} backward transition(s) in sorted data:\n"
343
+ f"{transition_str}\n"
344
+ f"This suggests overlapping components or outliers.\n"
345
+ f"These transitions are being ignored, keeping only {len(forward_transitions)} "
346
+ f"forward transitions (expected {expected_thresholds}).\n"
347
+ f"Review your plots and .uns metadata to verify the boundaries are appropriate.",
348
+ UserWarning
349
+ )
350
+
351
+ # Calculate midpoints at forward class transitions
352
+ return _DecisionBoundariesModel(
353
+ thresholds=[
354
+ (sorted_feature_values[i] + sorted_feature_values[i + 1]) / 2
355
+ for i in forward_transitions
356
+ ]
357
+ )
358
+
359
+ def _calculate_bic_for_component_range(
360
+ self,
361
+ adata: ad.AnnData,
362
+ feature: str,
363
+ component_range: int,
364
+ layer: Optional[str],
365
+ gmm_kwargs: dict,
366
+ ) -> List[Union[int, float]]:
367
+ """
368
+ Run Bayesian Information Criterion (BIC) on the gene expression data.
369
+
370
+ Parameters
371
+ ----------
372
+ adata : ad.AnnData
373
+ AnnData object containing the data.
374
+ feature : str
375
+ Name of the feature to analyze.
376
+ component_range : int
377
+ Maximum number of components to test (tests 1 to component_range).
378
+ layer : str or None
379
+ Optional layer name to use instead of .X.
380
+ gmm_kwargs : dict
381
+ Keyword arguments for GaussianMixture.
382
+
383
+ Returns
384
+ -------
385
+ list of (int or float)
386
+ BIC values for each number of components tested.
387
+ """
388
+ if not isinstance(component_range, int):
389
+ raise ValueError("component_range must be an integer.")
390
+
391
+ # Get feature data with layer support
392
+ if layer is None:
393
+ gene_x = adata[:, feature].X
394
+ else:
395
+ gene_x = adata[:, feature].layers[layer]
396
+
397
+ bic_list = []
398
+ for component_num in range(component_range):
399
+ gmm = GaussianMixture(n_components=component_num + 1, **gmm_kwargs)
400
+ _ = gmm.fit(gene_x).predict(gene_x)
401
+ bic = gmm.bic(gene_x)
402
+ bic_list.append(bic)
403
+
404
+ return bic_list
405
+
406
+ def determine_optimal_number_components(
407
+ self,
408
+ adata: ad.AnnData,
409
+ feature: str,
410
+ component_range: int,
411
+ layer: Optional[str] = None,
412
+ gmm_kwargs: Optional[dict] = None,
413
+ metric: str = "bic",
414
+ curve: str = "convex",
415
+ direction: str = "decreasing",
416
+ return_bic_list: bool = False,
417
+ ) -> Union[int, Tuple[int, List[Union[int, float]]]]:
418
+ """
419
+ Determine the optimal number of components for the GMM.
420
+
421
+ Parameters
422
+ ----------
423
+ adata : ad.AnnData
424
+ AnnData object containing the data.
425
+ feature : str
426
+ Name of the feature to analyze.
427
+ component_range : int
428
+ Maximum number of components to test.
429
+ layer : str or None, optional
430
+ Optional layer name to use instead of .X. Default is None.
431
+ gmm_kwargs : dict or None, optional
432
+ Keyword arguments for GaussianMixture. If None, uses defaults.
433
+ Default is None.
434
+ metric : str, optional
435
+ Metric to use for optimization (currently only 'bic' supported).
436
+ Default is 'bic'.
437
+ curve : str, optional
438
+ Type of curve for knee detection ('convex' or 'concave').
439
+ Default is 'convex'.
440
+ direction : str, optional
441
+ Direction of curve ('decreasing' or 'increasing').
442
+ Default is 'decreasing'.
443
+ return_bic_list : bool, optional
444
+ If True, returns tuple of (optimal_n, bic_list). Default is False.
445
+
446
+ Returns
447
+ -------
448
+ int or tuple of (int, list of (int or float))
449
+ Optimal number of components, or tuple of (optimal_n, bic_list)
450
+ if return_bic_list=True.
451
+ """
452
+ if not isinstance(component_range, int):
453
+ raise ValueError("component_range must be an integer.")
454
+
455
+ if metric != "bic":
456
+ raise ValueError("Currently, only BIC is supported.")
457
+
458
+ if gmm_kwargs is None:
459
+ gmm_kwargs = {'init_params': 'k-means++', 'n_init': 10, 'max_iter': 1000, 'random_state': 42}
460
+
461
+ bic_list = self._calculate_bic_for_component_range(
462
+ adata, feature, component_range, layer, gmm_kwargs
463
+ )
464
+ optimal_component_number = KneeLocator(
465
+ x=range(1, component_range + 1),
466
+ y=bic_list,
467
+ curve=curve,
468
+ direction=direction,
469
+ )
470
+ if return_bic_list:
471
+ return optimal_component_number.knee, bic_list
472
+ else:
473
+ return optimal_component_number.knee
474
+
475
+ def plot_bayesian_information_criterion_curve(
476
+ self,
477
+ adata: ad.AnnData,
478
+ feature: str,
479
+ component_range: int,
480
+ layer: Optional[str] = None,
481
+ gmm_kwargs: Optional[dict] = None,
482
+ curve: str = "convex",
483
+ direction: str = "decreasing",
484
+ ax: plt.Axes = None,
485
+ save_path: Optional[Union[str, Path]] = None,
486
+ ) -> None:
487
+ """
488
+ Plot the BIC curve.
489
+
490
+ Parameters
491
+ ----------
492
+ adata : ad.AnnData
493
+ AnnData object containing the data.
494
+ feature : str
495
+ Name of the feature to analyze.
496
+ component_range : int
497
+ Maximum number of components to test.
498
+ layer : str or None, optional
499
+ Optional layer name to use instead of .X. Default is None.
500
+ gmm_kwargs : dict or None, optional
501
+ Keyword arguments for GaussianMixture. If None, uses defaults.
502
+ Default is None.
503
+ curve : str, optional
504
+ Type of curve for knee detection ('convex' or 'concave').
505
+ Default is 'convex'.
506
+ direction : str, optional
507
+ Direction of curve ('decreasing' or 'increasing').
508
+ Default is 'decreasing'.
509
+ ax : matplotlib.pyplot.Axes or None, optional
510
+ Optional matplotlib axes to plot on. If None, creates new figure.
511
+ Default is None.
512
+ save_path : str or Path or None, optional
513
+ Optional path to save the figure. Parent directory must exist.
514
+ Default is None.
515
+
516
+ Raises
517
+ ------
518
+ FileNotFoundError
519
+ If save_path parent directory doesn't exist.
520
+ """
521
+ if not isinstance(component_range, int):
522
+ raise ValueError("component_range must be an integer.")
523
+
524
+ # Validate save path before generating the figure
525
+ save_path = _validate_save_path(save_path)
526
+
527
+ optimal_component_number, bic_list = self.determine_optimal_number_components(
528
+ adata, feature, component_range, layer, gmm_kwargs, curve=curve, direction=direction, return_bic_list=True
529
+ )
530
+
531
+ if ax is None:
532
+ _, ax = plt.subplots(figsize=(5, 5))
533
+
534
+ ax.plot(range(1, component_range + 1), bic_list, marker="o", color="black")
535
+ ax.axvline(optimal_component_number, color="red", linestyle="--",
536
+ label=f"Optimal Number of Components = {optimal_component_number}")
537
+
538
+ ax.set_title("Bayesian Information Criterion (BIC) Curve")
539
+ ax.set_xticks(np.arange(1, component_range + 1, 1))
540
+ ax.set_xlabel("Number of Components")
541
+ ax.set_ylabel("BIC Value")
542
+
543
+ if save_path:
544
+ plt.savefig(save_path, bbox_inches='tight', dpi=300)
545
+ print(f"Figure saved to: {save_path}")
546
+
547
+ def _plot_gmm_components(
548
+ self,
549
+ ax: axes.Axes,
550
+ adata: ad.AnnData,
551
+ feature: str,
552
+ internal_data: _SingleThresholdingEventModel,
553
+ num_std: int,
554
+ resolution: int,
555
+ cmap: plt.cm.ScalarMappable
556
+ ) -> axes.Axes:
557
+ """
558
+ Plot the Gaussian probability density functions (PDFs) and their means.
559
+
560
+ Parameters
561
+ ----------
562
+ ax : matplotlib.axes.Axes
563
+ Matplotlib axes to plot on.
564
+ adata : ad.AnnData
565
+ AnnData object (not currently used but kept for consistency).
566
+ feature : str
567
+ Name of the feature being plotted.
568
+ internal_data : _SingleThresholdingEventModel
569
+ Thresholding event model containing GMM info and boundaries.
570
+ num_std : int
571
+ Number of standard deviations to plot for each component.
572
+ resolution : int
573
+ Number of points to use for plotting each Gaussian curve.
574
+ cmap : matplotlib.pyplot.cm.ScalarMappable
575
+ Colormap for coloring the categories.
576
+
577
+ Returns
578
+ -------
579
+ matplotlib.axes.Axes
580
+ Modified axes object with GMM components plotted.
581
+
582
+ Raises
583
+ ------
584
+ ValueError
585
+ If decision boundaries have not been calculated.
586
+ """
587
+ if internal_data.decision_boundaries is None:
588
+ raise ValueError(
589
+ "Decision boundaries have not been calculated. Please call calculate_decision_boundaries() first."
590
+ )
591
+
592
+ threshold_list = internal_data.decision_boundaries.thresholds
593
+
594
+ means: list = self._ensure_list(internal_data.gmm_info.means)
595
+ covs: list = self._ensure_list(internal_data.gmm_info.covs)
596
+ weights: list = self._ensure_list(internal_data.gmm_info.weights)
597
+ ordered_labels = internal_data.ordered_gmm_labels
598
+
599
+ num_components = len(means)
600
+
601
+ # Determine number of final categories for color mapping
602
+ if internal_data.condensed_labels is not None:
603
+ num_final_categories = len(internal_data.condensed_labels)
604
+ elif ordered_labels is not None:
605
+ num_final_categories = len(set(ordered_labels))
606
+ else:
607
+ num_final_categories = len(threshold_list) + 1
608
+
609
+ # Use final category colors for background and mean lines
610
+ category_colors = cmap(np.linspace(0, 1, num_final_categories))
611
+
612
+ for gaus_idx in range(num_components):
613
+ g_mean = means[gaus_idx]
614
+ g_cov = covs[gaus_idx]
615
+ g_weight = weights[gaus_idx]
616
+
617
+ std = np.sqrt(g_cov)
618
+ x_min = g_mean - num_std * std
619
+ x_max = g_mean + num_std * std
620
+ x_axis = np.linspace(x_min, x_max, resolution)
621
+ y_axis = st.norm.pdf(x_axis, loc=g_mean, scale=std) * g_weight
622
+
623
+ # Color the GMM curve segments by which category they fall into
624
+ bin_indices = np.digitize(x_axis, threshold_list)
625
+ bin_indices = np.clip(bin_indices, 0, num_final_categories - 1)
626
+ x_colors = category_colors[bin_indices]
627
+
628
+ ax.scatter(x_axis, y_axis, lw=1, c=x_colors, zorder=3, s=1)
629
+
630
+ # Color the component mean line by spatial position (which region it falls in)
631
+ # This ensures mean lines match the background shaded regions
632
+ mean_bin_idx = np.digitize([g_mean], threshold_list)[0]
633
+ mean_bin_idx = np.clip(mean_bin_idx, 0, num_final_categories - 1)
634
+ mean_line_color = category_colors[mean_bin_idx]
635
+
636
+ ax.axvline(g_mean, c=mean_line_color, lw=2, ls="--", zorder=4)
637
+
638
+ return ax
639
+
640
+ def _plot_sample_catergory_legend(
641
+ self,
642
+ ax: axes.Axes,
643
+ internal_data: _SingleThresholdingEventModel,
644
+ cmap: plt.cm.ScalarMappable,
645
+ legend_kwargs: Optional[dict] = None
646
+ ) -> axes.Axes:
647
+ """
648
+ Plot legend showing category labels and colors.
649
+
650
+ Parameters
651
+ ----------
652
+ ax : matplotlib.axes.Axes
653
+ Matplotlib axes to add legend to.
654
+ internal_data : _SingleThresholdingEventModel
655
+ Thresholding event model containing label information.
656
+ cmap : matplotlib.pyplot.cm.ScalarMappable
657
+ Colormap used for category colors.
658
+ legend_kwargs : dict or None, optional
659
+ Optional kwargs to pass to ax.legend(). Default is None.
660
+
661
+ Returns
662
+ -------
663
+ matplotlib.axes.Axes
664
+ Modified axes object with legend added.
665
+ """
666
+ if internal_data.condensed_labels is not None:
667
+ ordered_labels = internal_data.condensed_labels
668
+ else:
669
+ ordered_labels = internal_data.ordered_gmm_labels
670
+ patch_list = []
671
+
672
+ component_colors = cmap(np.linspace(0, 1, len(ordered_labels)))
673
+ for label, color in zip(ordered_labels, component_colors):
674
+ patch = mpatches.Patch(
675
+ facecolor=color, label=label, alpha=0.8, edgecolor="black"
676
+ )
677
+ patch_list.append(patch)
678
+
679
+ if legend_kwargs is None:
680
+ legend_kwargs = {}
681
+
682
+ ax.legend(handles=patch_list, **legend_kwargs)
683
+
684
+ return ax
685
+
686
+ def _plot_hist_base(
687
+ self,
688
+ adata: ad.AnnData,
689
+ feature: str,
690
+ layer: Optional[str],
691
+ hist_kwargs: Optional[Dict] = None,
692
+ ax: plt.Axes = None,
693
+ x_axis_limits: Optional[tuple] = None,
694
+ ) -> axes.Axes:
695
+ """
696
+ Base function for plotting GMM distributions.
697
+
698
+ Parameters
699
+ ----------
700
+ adata : ad.AnnData
701
+ AnnData object containing the data.
702
+ feature : str
703
+ Name of the feature to plot.
704
+ layer : str or None
705
+ Optional layer name to use instead of .X.
706
+ hist_kwargs : dict or None, optional
707
+ Optional kwargs to pass to ax.hist(). Default is None.
708
+ ax : matplotlib.pyplot.Axes or None, optional
709
+ Optional matplotlib axes. If None, creates new figure. Default is None.
710
+ x_axis_limits : tuple or None, optional
711
+ Optional tuple of (x_min, x_max) for plot limits. Default is None.
712
+
713
+ Returns
714
+ -------
715
+ matplotlib.axes.Axes
716
+ Axes object with histogram plotted.
717
+ """
718
+ # Get feature data with layer support
719
+ if layer is None:
720
+ gene_x = adata[:, feature].X.copy()
721
+ else:
722
+ gene_x = adata[:, feature].layers[layer].copy()
723
+
724
+ if gene_x.shape[1] != 1:
725
+ raise ValueError("plot_gmm_distribution is only for 1d data.")
726
+
727
+ if x_axis_limits is not None:
728
+ x_lower_lim, x_upper_lim = x_axis_limits
729
+ # Handle None values in limits by using data min/max
730
+ if x_lower_lim is None:
731
+ x_lower_lim = np.min(gene_x)
732
+ if x_upper_lim is None:
733
+ x_upper_lim = np.max(gene_x)
734
+ # Validate limits after handling None values
735
+ if x_lower_lim >= x_upper_lim:
736
+ raise ValueError(f'{x_lower_lim} must be less than {x_upper_lim} in x_lims.')
737
+ else:
738
+ x_lower_lim = np.min(gene_x)
739
+ x_upper_lim = np.max(gene_x)
740
+
741
+ if ax is None:
742
+ _, ax = plt.subplots(figsize=(5, 5))
743
+
744
+ if hist_kwargs is None:
745
+ hist_kwargs = {"bins": 100, 'color': "black"}
746
+
747
+ if "density" in hist_kwargs:
748
+ hist_kwargs.pop("density")
749
+ print("density is set to True by default and cannot be altered.")
750
+
751
+ ax.hist(gene_x, density=True, zorder=2, **hist_kwargs)
752
+
753
+ ax.set_xlim(x_lower_lim, x_upper_lim)
754
+
755
+ return ax
756
+
757
+ def _plot_vertical_linear_decision_boundaries(
758
+ self,
759
+ ax: axes.Axes,
760
+ internal_data: _SingleThresholdingEventModel,
761
+ resolution: int,
762
+ cmap: plt.cm.ScalarMappable,
763
+ ) -> axes.Axes:
764
+ """
765
+ Plots decision boundaries as a background with category colors.
766
+
767
+ Parameters
768
+ ----------
769
+ ax : matplotlib.axes.Axes
770
+ Matplotlib axes to plot on.
771
+ internal_data : _SingleThresholdingEventModel
772
+ Thresholding event model containing boundaries and labels.
773
+ resolution : int
774
+ Number of points for smooth color gradients.
775
+ cmap : matplotlib.pyplot.cm.ScalarMappable
776
+ Colormap for category colors.
777
+
778
+ Returns
779
+ -------
780
+ matplotlib.axes.Axes
781
+ Modified axes object with decision boundaries plotted.
782
+
783
+ Raises
784
+ ------
785
+ ValueError
786
+ If decision boundaries have not been calculated.
787
+ """
788
+ if internal_data.decision_boundaries is None:
789
+ raise ValueError(
790
+ "Decision boundaries have not been calculated. Please call calculate_decision_boundaries() first."
791
+ )
792
+
793
+ thresholds = internal_data.decision_boundaries.thresholds
794
+
795
+ # Determine number of final categories based on unique labels
796
+ if internal_data.condensed_labels is not None:
797
+ num_final_categories = len(internal_data.condensed_labels)
798
+ elif internal_data.ordered_gmm_labels is not None:
799
+ num_final_categories = len(set(internal_data.ordered_gmm_labels))
800
+ else:
801
+ num_final_categories = len(thresholds) + 1
802
+
803
+ component_colors = cmap(np.linspace(0, 1, num_final_categories))
804
+
805
+ x_min, x_max = ax.get_xlim()
806
+ _, y_max = ax.get_ylim()
807
+ x_axis = np.linspace(x_min, x_max, resolution)
808
+
809
+ bin_indices = np.digitize(x_axis, thresholds)
810
+
811
+ x_axis_colors_rgba = np.array(component_colors)[bin_indices]
812
+ rgba_decision_boundary_grid = np.repeat(x_axis_colors_rgba[np.newaxis, :, :], 2, axis=0)
813
+
814
+ ax.imshow(
815
+ rgba_decision_boundary_grid,
816
+ extent=[x_min, x_max, 0, y_max],
817
+ origin="lower",
818
+ aspect="auto",
819
+ alpha=0.2,
820
+ )
821
+
822
+ for idx, threshold in enumerate(thresholds):
823
+ axvline_color = (component_colors[idx] + component_colors[idx+1])/2
824
+ ax.axvline(threshold, color=axvline_color, zorder=5)
825
+
826
+ return ax
827
+
828
+ def _plot_horizontal_linear_decision_boundaries(
829
+ self,
830
+ ax: axes.Axes,
831
+ internal_data: _SingleThresholdingEventModel,
832
+ resolution: int,
833
+ cmap: plt.cm.ScalarMappable,
834
+ ) -> axes.Axes:
835
+ """
836
+ Plots horizontal decision boundaries with category colors.
837
+
838
+ Parameters
839
+ ----------
840
+ ax : matplotlib.axes.Axes
841
+ Matplotlib axes to plot on.
842
+ internal_data : _SingleThresholdingEventModel
843
+ Thresholding event model containing boundaries and labels.
844
+ resolution : int
845
+ Number of points for smooth color gradients.
846
+ cmap : matplotlib.pyplot.cm.ScalarMappable
847
+ Colormap for category colors.
848
+
849
+ Returns
850
+ -------
851
+ matplotlib.axes.Axes
852
+ Modified axes object with horizontal decision boundaries plotted.
853
+ """
854
+ thresholds = internal_data.decision_boundaries.thresholds
855
+
856
+ # Determine number of final categories based on unique labels
857
+ if internal_data.condensed_labels is not None:
858
+ num_final_categories = len(internal_data.condensed_labels)
859
+ elif internal_data.ordered_gmm_labels is not None:
860
+ num_final_categories = len(set(internal_data.ordered_gmm_labels))
861
+ else:
862
+ num_final_categories = len(thresholds) + 1
863
+
864
+ component_colors = cmap(np.linspace(0, 1, num_final_categories))
865
+ thresholds = sorted(thresholds) # Ensure sorted
866
+
867
+ # Get plot limits
868
+ x_min, x_max = ax.get_xlim()
869
+ y_min, y_max = ax.get_ylim()
870
+
871
+ # Create a grid for the Y-axis
872
+ y_axis_grid = np.linspace(y_min, y_max, resolution)
873
+
874
+ # Digitize based on Y-thresholds
875
+ bin_indices = np.digitize(y_axis_grid, thresholds)
876
+
877
+ # Get colors for the Y-axis grid
878
+ y_axis_colors_rgba = np.array(component_colors)[bin_indices]
879
+
880
+ color_grid = np.repeat(y_axis_colors_rgba[:, np.newaxis, :], 2, axis=1)
881
+
882
+ ax.imshow(
883
+ color_grid,
884
+ extent=[x_min, x_max, y_min, y_max],
885
+ origin="lower",
886
+ aspect="auto",
887
+ alpha=0.2,
888
+ )
889
+
890
+ # Plot horizontal lines at thresholds
891
+ for idx, threshold in enumerate(thresholds):
892
+ axhline_color = (component_colors[idx] + component_colors[idx+1])/2
893
+ ax.axhline(threshold, color=axhline_color, zorder=5)
894
+
895
+ return ax
896
+
897
+ def _plot_strip_plot_base(
898
+ self,
899
+ adata: ad.AnnData,
900
+ feature: str,
901
+ layer: Optional[str],
902
+ obs_label: Optional[str] = None,
903
+ ordered_labels: Optional[List[str]] = None,
904
+ scatter_density: bool = True,
905
+ y_axis_limits: Optional[Tuple[float, float]] = None,
906
+ hist_kwargs: Optional[Dict] = None,
907
+ strip_plot_kwargs: Optional[Dict] = None,
908
+ cmap: mpl.cm.ScalarMappable = mpl.colormaps['plasma'],
909
+ vmax: Optional[Union[int, float]] = None,
910
+ ) -> Tuple[Figure, axes.Axes, axes.Axes]:
911
+ """
912
+ Base method for creating strip plot + histogram WITHOUT decision boundaries.
913
+
914
+ This method handles the core plotting logic for strip plots with histograms,
915
+ but does not add decision boundaries or legends. It's designed to be called
916
+ by both exploratory methods (before thresholding) and final visualization
917
+ methods (with thresholding).
918
+
919
+ Parameters
920
+ ----------
921
+ adata : ad.AnnData
922
+ AnnData object containing the data.
923
+ feature : str
924
+ Feature name to plot.
925
+ layer : str or None
926
+ Layer to use for data access. If None, uses adata.X.
927
+ obs_label : str or None, optional
928
+ Optional column in adata.obs containing categorical labels.
929
+ Required when scatter_density=False to color by labels.
930
+ ordered_labels : list of str or None, optional
931
+ Optional ordered list of label names (low to high).
932
+ Required when scatter_density=False for label-colored scatter.
933
+ scatter_density : bool, optional
934
+ If True, color by density; if False, color by labels. Default is True.
935
+ y_axis_limits : tuple of float or None, optional
936
+ Y-axis limits (min, max). If None, uses data min/max. Default is None.
937
+ hist_kwargs : dict or None, optional
938
+ Kwargs for histogram. Default is None.
939
+ strip_plot_kwargs : dict or None, optional
940
+ Kwargs for strip plot scatter (e.g., s, alpha, marker).
941
+ Only used when scatter_density=False. Default is None.
942
+ cmap : matplotlib.pyplot.cm.ScalarMappable, optional
943
+ Colormap for density or label colors. Default is 'plasma'.
944
+ vmax : int or float or None, optional
945
+ Maximum density value for colormap. If None, auto-calculated. Default is None.
946
+
947
+ Returns
948
+ -------
949
+ tuple of (Figure, matplotlib.axes.Axes, matplotlib.axes.Axes)
950
+ Figure and the two axes objects (scatter plot and histogram).
951
+
952
+ Raises
953
+ ------
954
+ ValueError
955
+ If scatter_density=False but obs_label or ordered_labels not provided.
956
+
957
+ Warns
958
+ -----
959
+ UserWarning
960
+ If vmax is provided when scatter_density=False.
961
+ """
962
+ # Get feature data
963
+ if layer is None:
964
+ feature_array = adata[:, feature].X.copy().squeeze()
965
+ else:
966
+ feature_array = adata[:, feature].layers[layer].copy().squeeze()
967
+
968
+ # Validate inputs
969
+ if not scatter_density:
970
+ if obs_label is None or ordered_labels is None:
971
+ raise ValueError(
972
+ "When scatter_density=False, both obs_label and ordered_labels must be provided."
973
+ )
974
+ if vmax is not None:
975
+ warnings.warn(
976
+ "vmax is only used when scatter_density is set to True. Ignoring vmax.",
977
+ UserWarning,
978
+ )
979
+
980
+ if y_axis_limits is None:
981
+ y_axis_limits = (np.min(feature_array), np.max(feature_array))
982
+
983
+ # Auto-calculate vmax if needed for density mode
984
+ if scatter_density and vmax is None:
985
+ filtered_feature_array = feature_array[feature_array < y_axis_limits[1]]
986
+ filtered_x = np.random.uniform(0, 1, size=filtered_feature_array.shape[0])
987
+ temp_fig, density_ax = plt.subplots(figsize=(5, 5), subplot_kw={'projection': 'scatter_density'})
988
+
989
+ with warnings.catch_warnings():
990
+ warnings.filterwarnings(
991
+ action='ignore',
992
+ message='All-NaN slice encountered',
993
+ category=RuntimeWarning
994
+ )
995
+ density_object = density_ax.scatter_density(
996
+ filtered_x, filtered_feature_array, cmap=cmap, dpi=100, vmin=1, zorder=1, alpha=0.0
997
+ )
998
+
999
+ temp_fig.canvas.draw()
1000
+ vmax = density_object.get_array().max()
1001
+
1002
+ if len(feature_array) / vmax > 5000:
1003
+ print("Warning: The maximum density value is less than 1.")
1004
+ print("This may indicate that the y_axis limits are not set properly or your data is sparse.")
1005
+
1006
+ plt.close(temp_fig) # Close the temporary figure
1007
+
1008
+ # Create figure with proper grid for colorbar
1009
+ fig = plt.figure(figsize=(6, 6))
1010
+ if scatter_density:
1011
+ # Create 3-column grid: strip plot, histogram, colorbar space
1012
+ # Increased colorbar width from 0.15 to 0.25 and spacing from 0.05 to 0.15
1013
+ gs = gridspec.GridSpec(1, 3, width_ratios=[3, 1, 0.25], wspace=0.15)
1014
+ else:
1015
+ # Create 2-column grid: strip plot, histogram (no colorbar needed)
1016
+ gs = gridspec.GridSpec(1, 2, width_ratios=[3, 1], wspace=0)
1017
+
1018
+ # Add subplots
1019
+ ax_scatter = fig.add_subplot(gs[0, 0], projection='scatter_density')
1020
+ ax_hist_y = fig.add_subplot(gs[0, 1], sharey=ax_scatter)
1021
+
1022
+ # Generate random x-coordinates for strip plot
1023
+ x = np.random.uniform(0, 1, size=feature_array.shape[0])
1024
+
1025
+ cmap.set_under('white', alpha=1.0)
1026
+
1027
+ # Plot scatter (density or label-colored)
1028
+ if scatter_density:
1029
+ with warnings.catch_warnings():
1030
+ warnings.filterwarnings(
1031
+ action='ignore',
1032
+ message='All-NaN slice encountered',
1033
+ category=RuntimeWarning
1034
+ )
1035
+ density = ax_scatter.scatter_density(
1036
+ x, feature_array, cmap=cmap, dpi=100, vmin=1, vmax=vmax, zorder=1
1037
+ )
1038
+ else:
1039
+ component_colors = mpl.colormaps['rainbow'](np.linspace(0, 1, len(ordered_labels)))
1040
+
1041
+ sample_labels = adata.obs[obs_label].values
1042
+ sample_label_color_mapping = {
1043
+ label: color for label, color in zip(ordered_labels, component_colors)
1044
+ }
1045
+ sample_colors = np.array([sample_label_color_mapping[label] for label in sample_labels])
1046
+
1047
+ # Set default strip plot kwargs
1048
+ if strip_plot_kwargs is None:
1049
+ strip_plot_kwargs = {'s': 5}
1050
+
1051
+ # Validate strip_plot_kwargs
1052
+ if 'c' in strip_plot_kwargs or 'color' in strip_plot_kwargs:
1053
+ warnings.warn(
1054
+ "Color parameters in strip_plot_kwargs will be ignored. Colors are determined by labels.",
1055
+ UserWarning
1056
+ )
1057
+ strip_plot_kwargs.pop('c', None)
1058
+ strip_plot_kwargs.pop('color', None)
1059
+
1060
+ if 'zorder' in strip_plot_kwargs:
1061
+ warnings.warn(
1062
+ "zorder in strip_plot_kwargs will be ignored. zorder is set to 1 by default.",
1063
+ UserWarning
1064
+ )
1065
+ strip_plot_kwargs.pop('zorder', None)
1066
+
1067
+ density = ax_scatter.scatter(x, feature_array, c=sample_colors, zorder=1, **strip_plot_kwargs)
1068
+
1069
+ # Style scatter plot
1070
+ ax_scatter.tick_params(axis='x', which='both', right=False, labelright=False,
1071
+ bottom=False, labelbottom=False)
1072
+ ax_scatter.spines['top'].set_visible(False)
1073
+ ax_scatter.spines['bottom'].set_visible(False)
1074
+ ax_scatter.spines['right'].set_visible(False)
1075
+ ax_scatter.spines['left'].set_visible(False)
1076
+ ax_scatter.set_ylabel(f"{feature}")
1077
+ ax_scatter.set_ylim(y_axis_limits)
1078
+
1079
+ # Plot histogram
1080
+ if hist_kwargs is None:
1081
+ hist_kwargs = {"bins": 1000, 'color': "black"}
1082
+
1083
+ if "orientation" in hist_kwargs:
1084
+ hist_kwargs.pop("orientation")
1085
+ print("orientation is set to horizontal by default and cannot be altered.")
1086
+
1087
+ if "density" in hist_kwargs:
1088
+ hist_kwargs.pop("density")
1089
+ print("density is set to True by default and cannot be altered.")
1090
+
1091
+ ax_hist_y.hist(feature_array, orientation='horizontal', density=True, **hist_kwargs)
1092
+ ax_hist_y.axis('off')
1093
+
1094
+ # Add colorbar for density mode in dedicated third column
1095
+ if scatter_density:
1096
+ cax = fig.add_subplot(gs[0, 2])
1097
+ cbar = fig.colorbar(
1098
+ density, cax=cax, label='Sample Density',
1099
+ extend='min'
1100
+ )
1101
+
1102
+ return fig, ax_scatter, ax_hist_y
1103
+
1104
+ def _plot_strip_plot_histogram_with_decision_boundaries(
1105
+ self,
1106
+ adata: ad.AnnData,
1107
+ feature: str,
1108
+ layer: Optional[str],
1109
+ obs_label: str,
1110
+ ordered_labels: List[str],
1111
+ internal_data: _SingleThresholdingEventModel,
1112
+ cmap: mpl.cm.ScalarMappable = mpl.colormaps['plasma'],
1113
+ y_axis_limits: Optional[Tuple[float, float]] = None,
1114
+ resolution: int = 1000,
1115
+ scatter_density: bool = True,
1116
+ vmax: Optional[Union[int, float]] = None,
1117
+ hist_kwargs: Optional[Dict] = None,
1118
+ strip_plot_kwargs: Optional[Dict] = None,
1119
+ title: Optional[str] = None,
1120
+ ) -> Figure:
1121
+ """
1122
+ Generate a 1D strip plot with histogram and decision boundaries.
1123
+
1124
+ This is the base implementation used by both single and sequential classes.
1125
+ Creates a figure with a scatter density strip plot (or label-colored scatter)
1126
+ alongside a horizontal histogram showing the distribution and decision boundaries.
1127
+
1128
+ Parameters
1129
+ ----------
1130
+ adata : ad.AnnData
1131
+ AnnData object containing the data.
1132
+ feature : str
1133
+ Feature name to plot.
1134
+ layer : str or None
1135
+ Layer to use for data access. If None, uses adata.X.
1136
+ obs_label : str
1137
+ Column in adata.obs containing categorical labels.
1138
+ ordered_labels : list of str
1139
+ Ordered list of label names (low to high).
1140
+ internal_data : _SingleThresholdingEventModel
1141
+ Thresholding event model with decision boundaries and GMM info.
1142
+ cmap : matplotlib.pyplot.cm.ScalarMappable, optional
1143
+ Colormap for density or label colors. Default is 'plasma'.
1144
+ y_axis_limits : tuple of float or None, optional
1145
+ Y-axis limits (min, max). If None, uses data min/max. Default is None.
1146
+ resolution : int, optional
1147
+ Resolution for boundary plotting. Default is 1000.
1148
+ scatter_density : bool, optional
1149
+ If True, color by density; if False, color by labels. Default is True.
1150
+ vmax : int or float or None, optional
1151
+ Maximum density value for colormap. If None, auto-calculated. Default is None.
1152
+ hist_kwargs : dict or None, optional
1153
+ Kwargs for histogram. Default is None.
1154
+ strip_plot_kwargs : dict or None, optional
1155
+ Kwargs for strip plot scatter (e.g., s, alpha, marker).
1156
+ Only used when scatter_density=False. Default is None.
1157
+ title : str or None, optional
1158
+ Title for the plot. If not provided, defaults to feature name.
1159
+ Pass empty string '' to suppress title. Default is None.
1160
+
1161
+ Returns
1162
+ -------
1163
+ matplotlib.figure.Figure
1164
+ The matplotlib figure object.
1165
+ """
1166
+ # Call base method to create strip plot and histogram
1167
+ fig, ax_scatter, ax_hist_y = self._plot_strip_plot_base(
1168
+ adata=adata,
1169
+ feature=feature,
1170
+ layer=layer,
1171
+ obs_label=obs_label if not scatter_density else None,
1172
+ ordered_labels=ordered_labels if not scatter_density else None,
1173
+ scatter_density=scatter_density,
1174
+ y_axis_limits=y_axis_limits,
1175
+ hist_kwargs=hist_kwargs,
1176
+ strip_plot_kwargs=strip_plot_kwargs,
1177
+ cmap=cmap,
1178
+ vmax=vmax,
1179
+ )
1180
+
1181
+ # Add decision boundaries
1182
+ ax_hist_y = self._plot_horizontal_linear_decision_boundaries(
1183
+ ax=ax_hist_y,
1184
+ internal_data=internal_data,
1185
+ resolution=resolution,
1186
+ cmap=mpl.colormaps['rainbow']
1187
+ )
1188
+
1189
+ # Add legend
1190
+ ax_hist_y = self._plot_sample_catergory_legend(
1191
+ ax=ax_hist_y,
1192
+ internal_data=internal_data,
1193
+ cmap=mpl.colormaps['rainbow'],
1194
+ legend_kwargs={'loc': 'upper center', 'fontsize': 9}
1195
+ )
1196
+
1197
+ # Add title (default to feature name, allow override or suppression)
1198
+ if title is None:
1199
+ title = feature
1200
+ if title: # Only add title if not empty string
1201
+ plt.suptitle(title)
1202
+
1203
+ return fig
1204
+
1205
+ def generate_thresholding_report(
1206
+ self,
1207
+ output_format: str = 'text',
1208
+ ) -> Union[str, pd.DataFrame]:
1209
+ """
1210
+ Generate a human-readable report of all thresholding operations.
1211
+
1212
+ Reads thresholding metadata from adata.uns and creates a summary showing:
1213
+ - Operation names and order
1214
+ - Features used
1215
+ - Number of components
1216
+ - Thresholds calculated
1217
+ - Labels assigned
1218
+ - Parent operations (for refinements)
1219
+ - Cell counts per category (captured at operation time)
1220
+
1221
+ Note: Cell counts reflect the state immediately after each operation was performed,
1222
+ not the current state of the data. This is important because subsequent refinement
1223
+ operations may change labels, but the historical counts are preserved.
1224
+
1225
+ Parameters
1226
+ ----------
1227
+ output_format : str, default 'text'
1228
+ 'text' for formatted string, 'dataframe' for pandas DataFrame.
1229
+
1230
+ Returns
1231
+ -------
1232
+ Union[str, pd.DataFrame]
1233
+ Formatted report string or DataFrame.
1234
+
1235
+ Raises
1236
+ ------
1237
+ KeyError
1238
+ If thresholding_events_key doesn't exist in adata.uns.
1239
+ ValueError
1240
+ If output_format is not 'text' or 'dataframe'.
1241
+ TypeError
1242
+ If adata.uns[thresholding_events_key] is not a dict.
1243
+
1244
+ Examples
1245
+ --------
1246
+ Generate text report::
1247
+
1248
+ >>> gmm = GMMThresholding(adata, feature='gene1', label_obs_save_str='gene1_cat')
1249
+ >>> gmm.fit(n_components=2)
1250
+ >>> gmm.categorize_samples(['Low', 'High'])
1251
+ >>> report = gmm.generate_thresholding_report()
1252
+ >>> print(report)
1253
+ Thresholding Report
1254
+ ==================================================
1255
+
1256
+ 1. gene1_thresholding (Standard Thresholding)
1257
+ ----------------------------------------------
1258
+ Feature: gene1
1259
+ Layer: None
1260
+ Obs column: gene1_cat
1261
+ Components: 2
1262
+ Thresholds: [0.0450]
1263
+ Labels: ['Low', 'High']
1264
+ Cell counts: Low=1234, High=5678
1265
+
1266
+ Generate DataFrame report::
1267
+
1268
+ >>> report_df = gmm.generate_thresholding_report(
1269
+ ... output_format='dataframe'
1270
+ ... )
1271
+ >>> report_df.head()
1272
+ """
1273
+ from collections import OrderedDict
1274
+
1275
+ # Use the instance's thresholding_events_key
1276
+ thresholding_events_key = self.thresholding_events_key
1277
+
1278
+ # Validate thresholding_events_key exists
1279
+ if thresholding_events_key not in self.adata.uns:
1280
+ raise KeyError(
1281
+ f"thresholding_events_key '{thresholding_events_key}' not found in adata.uns. "
1282
+ f"Available keys: {list(self.adata.uns.keys())}"
1283
+ )
1284
+
1285
+ # Validate it's a dict-like structure
1286
+ events = self.adata.uns[thresholding_events_key]
1287
+ if not isinstance(events, (dict, OrderedDict)):
1288
+ raise TypeError(
1289
+ f"adata.uns['{thresholding_events_key}'] must be a dict or OrderedDict, "
1290
+ f"got {type(events)}"
1291
+ )
1292
+
1293
+ # Validate output_format
1294
+ valid_formats = ['text', 'dataframe']
1295
+ if output_format not in valid_formats:
1296
+ raise ValueError(
1297
+ f"output_format must be one of {valid_formats}, got '{output_format}'"
1298
+ )
1299
+
1300
+ if len(events) == 0:
1301
+ if output_format == 'text':
1302
+ return "No thresholding operations found."
1303
+ else:
1304
+ return pd.DataFrame()
1305
+
1306
+ # Build report data
1307
+ report_data = []
1308
+
1309
+ for idx, (op_name, op_data) in enumerate(events.items(), 1):
1310
+ # Extract basic info
1311
+ feature = op_data.get('feature_name', 'N/A')
1312
+ layer = op_data.get('layer', None)
1313
+ obs_label = op_data.get('gmm_obs_label', 'N/A')
1314
+ ordered_labels = op_data.get('ordered_gmm_labels', [])
1315
+
1316
+ # Extract GMM info
1317
+ gmm_info = op_data.get('gmm_info', {})
1318
+ if gmm_info is not None:
1319
+ n_components = gmm_info.get('n_components', 'N/A')
1320
+ else:
1321
+ n_components = 'N/A (manual thresholds)'
1322
+
1323
+ # Extract thresholds
1324
+ decision_boundaries = op_data.get('decision_boundaries', {})
1325
+ thresholds = decision_boundaries.get('thresholds', []) if decision_boundaries else []
1326
+
1327
+ # Extract operation type and hierarchy
1328
+ operation_type = op_data.get('operation_type', 'standard')
1329
+ parent_operation = op_data.get('parent_operation', None)
1330
+ refined_from_labels = op_data.get('refined_from_labels', None)
1331
+
1332
+ # Get cell counts - prefer stored counts from operation time
1333
+ cell_counts = op_data.get('cell_counts_after_operation', {})
1334
+
1335
+ # Fallback to current obs counts if not stored (backward compatibility)
1336
+ if not cell_counts and obs_label in self.adata.obs.columns:
1337
+ counts = self.adata.obs[obs_label].value_counts()
1338
+ # Only include labels from this operation
1339
+ for label in ordered_labels:
1340
+ if label in counts.index:
1341
+ cell_counts[label] = int(counts[label])
1342
+
1343
+ # Store data for this operation
1344
+ op_info = {
1345
+ 'operation_number': idx,
1346
+ 'operation_name': op_name,
1347
+ 'operation_type': operation_type,
1348
+ 'feature': feature,
1349
+ 'layer': str(layer),
1350
+ 'obs_label': obs_label,
1351
+ 'n_components': n_components,
1352
+ 'thresholds': thresholds,
1353
+ 'labels': ordered_labels,
1354
+ 'parent_operation': parent_operation,
1355
+ 'refined_from_labels': refined_from_labels,
1356
+ 'cell_counts': cell_counts,
1357
+ }
1358
+ report_data.append(op_info)
1359
+
1360
+ # Generate output based on format
1361
+ if output_format == 'dataframe':
1362
+ # Create DataFrame
1363
+ df_data = []
1364
+ for op in report_data:
1365
+ df_data.append({
1366
+ 'Operation': f"{op['operation_number']}. {op['operation_name']}",
1367
+ 'Type': op['operation_type'],
1368
+ 'Feature': op['feature'],
1369
+ 'Layer': op['layer'],
1370
+ 'Obs Label': op['obs_label'],
1371
+ 'Components': str(op['n_components']),
1372
+ 'Thresholds': ', '.join(f"{t:.4f}" for t in op['thresholds']) if op['thresholds'] else 'N/A',
1373
+ 'Labels': ', '.join(op['labels']),
1374
+ 'Parent': str(op['parent_operation']),
1375
+ 'Refined From': ', '.join(op['refined_from_labels']) if op['refined_from_labels'] else 'N/A',
1376
+ 'Total Cells': sum(op['cell_counts'].values()) if op['cell_counts'] else 'N/A',
1377
+ })
1378
+ return pd.DataFrame(df_data)
1379
+
1380
+ else: # text format
1381
+ lines = []
1382
+ lines.append("Thresholding Report")
1383
+ lines.append("=" * 50)
1384
+ lines.append("")
1385
+
1386
+ for op in report_data:
1387
+ # Header
1388
+ if op['operation_type'] == 'refinement' or op['operation_type'] == 'refinement_manual':
1389
+ header = f"{op['operation_number']}. {op['operation_name']} (Refinement)"
1390
+ if op['parent_operation']:
1391
+ header += f" of {op['parent_operation']}"
1392
+ else:
1393
+ header = f"{op['operation_number']}. {op['operation_name']} (Standard Thresholding)"
1394
+
1395
+ lines.append(header)
1396
+ lines.append("-" * len(header))
1397
+
1398
+ # Basic info
1399
+ lines.append(f" Feature: {op['feature']}")
1400
+ lines.append(f" Layer: {op['layer']}")
1401
+ lines.append(f" Obs column: {op['obs_label']}")
1402
+
1403
+ # GMM info
1404
+ lines.append(f" Components: {op['n_components']}")
1405
+
1406
+ # Thresholds
1407
+ if op['thresholds']:
1408
+ threshold_str = ', '.join(f"{t:.4f}" for t in op['thresholds'])
1409
+ lines.append(f" Thresholds: [{threshold_str}]")
1410
+ else:
1411
+ lines.append(f" Thresholds: None")
1412
+
1413
+ # Labels
1414
+ labels_str = ', '.join(f"'{label}'" for label in op['labels'])
1415
+ lines.append(f" Labels: [{labels_str}]")
1416
+
1417
+ # Refinement-specific info
1418
+ if op['refined_from_labels']:
1419
+ refined_str = ', '.join(f"'{label}'" for label in op['refined_from_labels'])
1420
+ lines.append(f" Refined from: [{refined_str}]")
1421
+
1422
+ # Cell counts
1423
+ if op['cell_counts']:
1424
+ count_strs = [f"{label}={count}" for label, count in op['cell_counts'].items()]
1425
+ lines.append(f" Cell counts: {', '.join(count_strs)}")
1426
+ else:
1427
+ lines.append(f" Cell counts: Not available (obs column may have been modified)")
1428
+
1429
+ lines.append("")
1430
+
1431
+ # Summary
1432
+ lines.append("=" * 50)
1433
+ lines.append(f"Total operations: {len(report_data)}")
1434
+
1435
+ # Count operation types
1436
+ type_counts = {}
1437
+ for op in report_data:
1438
+ op_type = op['operation_type']
1439
+ type_counts[op_type] = type_counts.get(op_type, 0) + 1
1440
+
1441
+ if type_counts:
1442
+ lines.append("Operation types:")
1443
+ for op_type, count in type_counts.items():
1444
+ lines.append(f" - {op_type}: {count}")
1445
+
1446
+ return '\n'.join(lines)