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.
- cc_mapping/__init__.py +23 -0
- cc_mapping/core.py +360 -0
- cc_mapping/manifold.py +314 -0
- cc_mapping/plot.py +495 -0
- cc_mapping/preprocess.py +38 -0
- cc_mapping/pseudotime.py +284 -0
- cc_mapping/thresholding/__init__.py +60 -0
- cc_mapping/thresholding/base.py +1446 -0
- cc_mapping/thresholding/sequential.py +1441 -0
- cc_mapping/thresholding/single.py +828 -0
- cc_mapping/utils.py +192 -0
- cc_mapping/utils_v0.py +385 -0
- cc_mapping-0.1.0.dist-info/LICENSE +19 -0
- cc_mapping-0.1.0.dist-info/METADATA +226 -0
- cc_mapping-0.1.0.dist-info/RECORD +16 -0
- cc_mapping-0.1.0.dist-info/WHEEL +4 -0
|
@@ -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)
|