cc-mapping 0.2.4__tar.gz → 0.2.6__tar.gz

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.
Files changed (24) hide show
  1. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/PKG-INFO +7 -3
  2. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/README.md +3 -0
  3. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/pyproject.toml +3 -2
  4. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/__init__.py +1 -1
  5. cc_mapping-0.2.6/src/cc_mapping/core.py +180 -0
  6. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/__init__.py +41 -0
  7. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/_base.py +2 -1
  8. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/_persistence.py +1 -1
  9. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/_preprocessing.py +15 -8
  10. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/_random_forest.py +5 -0
  11. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/_training.py +3 -1
  12. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/manifold.py +73 -32
  13. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/plot.py +165 -44
  14. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/thresholding/base.py +177 -106
  15. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/thresholding/sequential.py +26 -27
  16. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/thresholding/single.py +35 -66
  17. cc_mapping-0.2.4/src/cc_mapping/core.py +0 -347
  18. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/LICENSE +0 -0
  19. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/feature_selection/_plotting.py +0 -0
  20. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/preprocess.py +0 -0
  21. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/pseudotime.py +0 -0
  22. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/thresholding/__init__.py +0 -0
  23. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/utils.py +0 -0
  24. {cc_mapping-0.2.4 → cc_mapping-0.2.6}/src/cc_mapping/utils_v0.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: cc-mapping
3
- Version: 0.2.4
3
+ Version: 0.2.6
4
4
  Summary: Gaussian Mixture Model-based thresholding for single-cell gene expression analysis
5
5
  Home-page: https://github.com/StallaertLab/cc_mapping
6
6
  License: BSD-3-Clause
@@ -17,17 +17,18 @@ Classifier: Programming Language :: Python :: 3.11
17
17
  Classifier: Programming Language :: Python :: 3.12
18
18
  Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
19
19
  Provides-Extra: manifold
20
+ Provides-Extra: persistence
20
21
  Requires-Dist: anndata (>=0.10.0,<0.11.0)
21
22
  Requires-Dist: kneed (>=0.8.5,<0.9.0)
22
23
  Requires-Dist: matplotlib (>=3.7.0,<4.0.0)
23
24
  Requires-Dist: mpl-scatter-density (>=0.8,<0.9)
24
25
  Requires-Dist: numpy (>=1.24.0)
25
26
  Requires-Dist: pandas (>=2.0.0,<3.0.0)
26
- Requires-Dist: phate (>=1.0.0,<2.0.0) ; extra == "manifold"
27
+ Requires-Dist: phate (>=1.0.0,<3.0.0) ; extra == "manifold"
27
28
  Requires-Dist: pydantic (>=2.10.0,<3.0.0)
28
29
  Requires-Dist: scikit-learn (>=1.3.0,<2.0.0)
29
30
  Requires-Dist: scipy (>=1.11.0,<2.0.0)
30
- Requires-Dist: skops (>=0.13.0,<0.14.0)
31
+ Requires-Dist: skops (>=0.13.0,<0.14.0) ; extra == "persistence"
31
32
  Requires-Dist: tqdm (>=4.67.1,<5.0.0)
32
33
  Project-URL: Documentation, https://cc-mapping.readthedocs.io
33
34
  Project-URL: Repository, https://github.com/StallaertLab/cc_mapping
@@ -189,6 +190,7 @@ For detailed documentation, tutorials, and API reference, visit [our documentati
189
190
  - **Single thresholding**: See `notebooks/Single_Thresholding_Workflow.ipynb`
190
191
  - **Sequential thresholding**: See `notebooks/Sequential_Thresholding_Workflow.ipynb`
191
192
  - **CSV to AnnData**: See `notebooks/CSV_to_Anndata.ipynb`
193
+ - **Cell cycle maps** (random forest feature selection + PHATE): See `notebooks/Cell_Cycle_Map_Workflow.ipynb`
192
194
 
193
195
  ## Requirements
194
196
 
@@ -200,6 +202,8 @@ For detailed documentation, tutorials, and API reference, visit [our documentati
200
202
  - matplotlib ≥ 3.7.0
201
203
  - scipy ≥ 1.11.0
202
204
  - pydantic ≥ 2.10.0
205
+ - phate (optional, for cell cycle maps): `pip install "cc-mapping[manifold]"`
206
+ - skops (optional, to save and load fitted feature selectors): `pip install "cc-mapping[persistence]"`
203
207
 
204
208
  ## Citation
205
209
 
@@ -154,6 +154,7 @@ For detailed documentation, tutorials, and API reference, visit [our documentati
154
154
  - **Single thresholding**: See `notebooks/Single_Thresholding_Workflow.ipynb`
155
155
  - **Sequential thresholding**: See `notebooks/Sequential_Thresholding_Workflow.ipynb`
156
156
  - **CSV to AnnData**: See `notebooks/CSV_to_Anndata.ipynb`
157
+ - **Cell cycle maps** (random forest feature selection + PHATE): See `notebooks/Cell_Cycle_Map_Workflow.ipynb`
157
158
 
158
159
  ## Requirements
159
160
 
@@ -165,6 +166,8 @@ For detailed documentation, tutorials, and API reference, visit [our documentati
165
166
  - matplotlib ≥ 3.7.0
166
167
  - scipy ≥ 1.11.0
167
168
  - pydantic ≥ 2.10.0
169
+ - phate (optional, for cell cycle maps): `pip install "cc-mapping[manifold]"`
170
+ - skops (optional, to save and load fitted feature selectors): `pip install "cc-mapping[persistence]"`
168
171
 
169
172
  ## Citation
170
173
 
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "cc-mapping"
3
- version = "0.2.4"
3
+ version = "0.2.6"
4
4
  description = "Gaussian Mixture Model-based thresholding for single-cell gene expression analysis"
5
5
  authors = ["ddpoe <dap182@pitt.edu>"]
6
6
  readme = "README.md"
@@ -43,10 +43,11 @@ kneed = "^0.8.5"
43
43
  mpl-scatter-density = "^0.8"
44
44
  tqdm = "^4.67.1"
45
45
  skops = {version = "^0.13.0", optional = true}
46
- phate = {version = "^1.0.0", optional = true}
46
+ phate = {version = ">=1.0.0,<3.0.0", optional = true}
47
47
 
48
48
  [tool.poetry.extras]
49
49
  manifold = ["phate"]
50
+ persistence = ["skops"]
50
51
 
51
52
  [tool.poetry.group.test.dependencies]
52
53
  pytest = "^8.3.5"
@@ -20,4 +20,4 @@ __all__ = [
20
20
  "create_boolean_label_combination",
21
21
  ]
22
22
 
23
- __version__ = "0.2.0"
23
+ __version__ = "0.2.6"
@@ -0,0 +1,180 @@
1
+ from typing import Optional
2
+ import warnings
3
+
4
+ warnings.simplefilter(action="ignore", category=FutureWarning)
5
+
6
+ import numpy as np # noqa: E402
7
+
8
+ np.seterr(all="ignore")
9
+
10
+ import re # noqa: E402
11
+ import anndata as ad # noqa: E402
12
+
13
+ from sklearn import metrics # noqa: E402
14
+ from sklearn.model_selection import train_test_split # noqa: E402
15
+ from sklearn.ensemble import RandomForestClassifier # noqa: E402
16
+
17
+ from .feature_selection import ( # noqa: E402
18
+ RFMinMaxSelector,
19
+ RFTopNSelector,
20
+ prepare_feature_matrix,
21
+ )
22
+
23
+
24
+ def train_random_forest_model(
25
+ features,
26
+ labels,
27
+ rf_params: dict,
28
+ random_state: int,
29
+ train_test_split_params: dict,
30
+ feature_set_description: str = "",
31
+ verbose: bool = True,
32
+ ):
33
+ """
34
+ Trains a random forest model using the given features and labels.
35
+
36
+ .. deprecated:: 0.2.6
37
+ Use :func:`cc_mapping.feature_selection.train_rf_model`. This function
38
+ will be removed in 0.3.0.
39
+
40
+ Parameters:
41
+ - features: The input features for training the model.
42
+ - labels: The target labels for training the model.
43
+ - rf_params: A dictionary of parameters for the random forest classifier.
44
+ - random_state: A boolean value indicating whether to use a random state for reproducibility.
45
+ - train_test_split_params: A dictionary of parameters for the train-test split.
46
+ - verbose: A boolean value indicating whether to print the classification report.
47
+
48
+ Returns:
49
+ - rf_classifier: The trained random forest classifier.
50
+ - accuracy: The accuracy of the model on the test set.
51
+ """
52
+ # DeprecationWarning, not FutureWarning: this module ignores FutureWarning.
53
+ warnings.warn(
54
+ "train_random_forest_model is deprecated and will be removed in cc-mapping "
55
+ "0.3.0. Use cc_mapping.feature_selection.train_rf_model instead.",
56
+ DeprecationWarning,
57
+ stacklevel=2,
58
+ )
59
+ train_features, test_features, train_labels, test_labels = train_test_split(
60
+ features, labels, random_state=random_state, **train_test_split_params
61
+ )
62
+ rf_classifier = RandomForestClassifier(random_state=random_state, **rf_params)
63
+
64
+ rf_classifier.fit(train_features, train_labels)
65
+
66
+ rf_pred_labels = rf_classifier.predict(test_features)
67
+
68
+ accuracy = metrics.accuracy_score(test_labels, rf_pred_labels)
69
+
70
+ if verbose:
71
+ print(
72
+ f"Classification Report for RF model trained with {feature_set_description} feature set"
73
+ )
74
+ print("##################################################################")
75
+ print()
76
+ print(metrics.classification_report(test_labels, rf_pred_labels))
77
+
78
+ return rf_classifier, accuracy
79
+
80
+
81
+ def random_forest_feature_selection(
82
+ adata: ad.AnnData,
83
+ training_feature_set: list[str],
84
+ training_labels: str,
85
+ feature_set_name: str = None,
86
+ method: str = "RF_min_max",
87
+ random_state: int = 42,
88
+ threshold: float = 0.01,
89
+ stable_counter: int = 3,
90
+ plot: bool = True,
91
+ verbose: bool = True,
92
+ save_path: str = None,
93
+ cutoff_method: str = "increment",
94
+ train_test_split_params: Optional[dict] = None,
95
+ rf_params: Optional[dict] = None,
96
+ show: bool = True,
97
+ ) -> ad.AnnData:
98
+ """
99
+ Trains a random forest classifier on the training feature set and labels using one of two methods:
100
+ RF_min_30: Selects the top 30 features based on the random forest feature importance
101
+ RF_min_max: Selects the minimum number of features that maximizes the accuracy of the random forest classifier
102
+ This is done by iteratively adding features to the feature set until the accuracy of the classifier
103
+ does not improve for x number of iterations
104
+
105
+ .. deprecated:: 0.2.6
106
+ Use :class:`~cc_mapping.feature_selection.RFMinMaxSelector` for
107
+ ``method="RF_min_max"`` and :class:`~cc_mapping.feature_selection.RFTopNSelector`
108
+ for ``method="RF_min_<N>"``. This function now wraps them and will be
109
+ removed in 0.3.0; :mod:`cc_mapping.feature_selection` shows how the
110
+ arguments map.
111
+
112
+ Args:
113
+ adata (ad.AnnData): The AnnData object containing the data.
114
+ training_feature_set (list[str]): Names of the features (entries of adata.var_names) to train on. Order does not matter.
115
+ training_labels (str): The name of the labels to be used for training.
116
+ feature_set_name (str, optional): The name of the feature set to be added to the .var attribute of the adata object. Defaults to None.
117
+ method (str, optional): The method to be used for feature selection. Defaults to 'RF_min_max'.
118
+ random_state (int, optional): The random state for reproducibility. Defaults to 42.
119
+ threshold (float, optional): The threshold for determining when to stop adding features. Defaults to 0.01.
120
+ stable_counter (int, optional): The number of stable iterations before stopping. Defaults to 3.
121
+ plot (bool, optional): Whether to plot the accuracy vs. number of features graph (RF_min_max only). Defaults to True.
122
+ save_path (str, optional): Path to save the accuracy plot to. Defaults to None.
123
+ cutoff_method (str, optional): The method for determining when to stop adding features. Defaults to 'increment'.
124
+ train_test_split_params (dict, optional): The parameters for train test split. Defaults to {'test_size':0.25}.
125
+ rf_params (dict, optional): The parameters for the random forest classifier. Defaults to {'min_samples_leaf':50, 'n_estimators':150, 'bootstrap':True, 'oob_score':True, 'n_jobs':-1}.
126
+ show (bool, optional): Whether to display the accuracy plot with plt.show(). If False, the plot is closed after it is saved. Defaults to True.
127
+
128
+ Returns:
129
+ ad.AnnData: The adata object with the feature set added to the .var attribute.
130
+
131
+ Raises:
132
+ ValueError: If any name in training_feature_set is not in adata.var_names,
133
+ or if method is neither 'RF_min_max' nor 'RF_min_<N>'.
134
+ """
135
+ # DeprecationWarning, not FutureWarning: this module ignores FutureWarning.
136
+ warnings.warn(
137
+ "random_forest_feature_selection is deprecated and will be removed in "
138
+ "cc-mapping 0.3.0. Use RFMinMaxSelector (method='RF_min_max') or "
139
+ "RFTopNSelector (method='RF_min_<N>') from cc_mapping.feature_selection.",
140
+ DeprecationWarning,
141
+ stacklevel=2,
142
+ )
143
+
144
+ top_n = re.search("(?<=RF_min_)[0-9]+", method)
145
+ if top_n is None and method != "RF_min_max":
146
+ raise ValueError(
147
+ f"Unknown method {method!r}; use 'RF_min_max' or 'RF_min_<N>' (e.g. 'RF_min_30')."
148
+ )
149
+
150
+ if feature_set_name is None:
151
+ feature_set_name = f"{method}_feature_set"
152
+
153
+ prepared = prepare_feature_matrix(
154
+ adata, training_feature_set, training_labels, verbose=verbose
155
+ )
156
+ shared = dict(
157
+ rf_params=rf_params,
158
+ train_test_split_params=train_test_split_params,
159
+ random_state=random_state,
160
+ verbose=verbose,
161
+ )
162
+ if top_n:
163
+ # RFTopNSelector raises when N exceeds the number of features; this
164
+ # function has always kept every feature instead.
165
+ n_features = min(int(top_n.group(0)), prepared.n_features)
166
+ selector = RFTopNSelector(n_features=n_features, **shared)
167
+ else:
168
+ selector = RFMinMaxSelector(
169
+ threshold=threshold,
170
+ stable_iterations=stable_counter,
171
+ cutoff_method=cutoff_method,
172
+ **shared,
173
+ )
174
+ selector.fit(prepared.X, prepared.y, prepared.feature_names)
175
+ selector.transform_adata(adata, var_key=feature_set_name)
176
+
177
+ if plot and not top_n:
178
+ selector.plot_accuracy_curve(save_path=save_path, show=show)
179
+
180
+ return adata
@@ -27,6 +27,47 @@ SelectionResult
27
27
  PreparedData
28
28
  Container for prepared feature matrix and metadata.
29
29
 
30
+ Notes
31
+ -----
32
+ ``cc_mapping.core.random_forest_feature_selection`` is deprecated. The
33
+ selectors use the same defaults and, given the same arguments, choose the
34
+ same features in the same order. For example::
35
+
36
+ # before
37
+ core.random_forest_feature_selection(
38
+ adata, adata.var_names, "phase", method="RF_min_max",
39
+ threshold=0.05, stable_counter=5, feature_set_name="fs",
40
+ )
41
+
42
+ # after
43
+ selector = RFMinMaxSelector(threshold=0.05, stable_iterations=5)
44
+ selector.fit_adata(adata, adata.var_names, "phase")
45
+ selector.transform_adata(adata, var_key="fs")
46
+ fig = selector.plot_accuracy_curve()
47
+
48
+ .. list-table:: Arguments of ``random_forest_feature_selection`` and their replacements
49
+ :header-rows: 1
50
+
51
+ * - ``random_forest_feature_selection``
52
+ - ``cc_mapping.feature_selection``
53
+ * - ``method="RF_min_max"``
54
+ - ``RFMinMaxSelector()``
55
+ * - ``method="RF_min_<N>"``
56
+ - ``RFTopNSelector(n_features=N)``, which raises if N exceeds the number
57
+ of features (the old function kept them all)
58
+ * - ``stable_counter``
59
+ - ``stable_iterations``
60
+ * - ``threshold``, ``cutoff_method``, ``random_state``, ``rf_params``,
61
+ ``train_test_split_params``, ``verbose``
62
+ - same names and defaults
63
+ * - ``training_feature_set``, ``training_labels``
64
+ - ``fit_adata(adata, feature_set_key, label_key)``
65
+ * - ``feature_set_name``
66
+ - ``transform_adata(adata, var_key=...)``; the default key is
67
+ ``"selected_features"`` instead of ``f"{method}_feature_set"``
68
+ * - ``plot``, ``save_path``, ``show``
69
+ - ``plot_accuracy_curve(save_path=..., show=...)``, called explicitly
70
+
30
71
  Examples
31
72
  --------
32
73
  Basic usage with numpy arrays:
@@ -174,7 +174,8 @@ class FeatureSelector(ABC):
174
174
  AnnData object containing the data.
175
175
  feature_set_key : str or list[str]
176
176
  Either a key in adata.var that marks features (boolean column),
177
- or a list of feature names.
177
+ or a list of feature names. Order does not matter: the columns
178
+ always follow adata.var_names.
178
179
  label_key : str
179
180
  Key in adata.obs containing target labels.
180
181
  drop_na : bool, default=True
@@ -68,7 +68,7 @@ def _check_skops_available() -> None:
68
68
  if not SKOPS_AVAILABLE:
69
69
  raise ImportError(
70
70
  "skops is required for saving/loading selectors. "
71
- "Install it with: pip install skops"
71
+ 'Install it with: pip install "cc-mapping[persistence]"'
72
72
  )
73
73
 
74
74
 
@@ -9,6 +9,7 @@ from typing import List
9
9
 
10
10
  import anndata as ad
11
11
  import numpy as np
12
+ from scipy import sparse
12
13
 
13
14
 
14
15
  @dataclass
@@ -111,10 +112,11 @@ def _get_feature_indices(
111
112
  f"Features not found in adata.var_names: {missing}"
112
113
  )
113
114
 
114
- # Get indices using dictionary lookup for efficiency
115
- var_name_to_idx = {name: idx for idx, name in enumerate(var_names)}
116
- indices = np.array([var_name_to_idx[name] for name in feature_set])
117
- feature_names = feature_set
115
+ # Take the columns in adata.var_names order, not list order: the forest's
116
+ # feature subsampling depends on column order, so the selection would
117
+ # otherwise change with how the caller happened to order the names.
118
+ indices = np.where(np.isin(var_names, feature_set))[0]
119
+ feature_names = var_names[indices]
118
120
 
119
121
  return indices, feature_names
120
122
 
@@ -141,7 +143,8 @@ def prepare_feature_matrix(
141
143
  AnnData object containing the data.
142
144
  feature_set : str or list[str] or np.ndarray
143
145
  Either a key in adata.var (boolean column marking features),
144
- or a list/array of feature names to use.
146
+ or a list/array of feature names to use. Order does not matter:
147
+ the columns always follow adata.var_names.
145
148
  labels : str
146
149
  Key in adata.obs containing target labels.
147
150
  drop_na : bool, default=True
@@ -198,8 +201,10 @@ def prepare_feature_matrix(
198
201
  # Get feature indices and names
199
202
  feature_indices, feature_names = _get_feature_indices(adata, feature_set)
200
203
 
201
- # Extract feature matrix and labels
202
- X = adata.X[:, feature_indices].copy()
204
+ # Extract feature matrix and labels. A sparse X is densified so the NaN/inf
205
+ # checks and the forest see the same values as for a dense X.
206
+ X = adata.X[:, feature_indices]
207
+ X = X.toarray() if sparse.issparse(X) else X.copy()
203
208
  y = adata.obs[labels].values.copy()
204
209
 
205
210
  n_original = len(y)
@@ -324,7 +329,9 @@ def validate_data(
324
329
  "Use prepare_feature_matrix() with drop_inf=True, or handle infinite values manually."
325
330
  )
326
331
 
327
- # Check for NaN in labels (only if y is numeric)
332
+ # Check for NaN in labels (only if y is numeric). Pandas Categorical labels
333
+ # have no numpy dtype, so look at them as a plain array.
334
+ y = np.asarray(y)
328
335
  if np.issubdtype(y.dtype, np.floating):
329
336
  if np.isnan(y).any():
330
337
  n_nan = np.isnan(y).sum()
@@ -495,6 +495,7 @@ class RFMinMaxSelector(FeatureSelector):
495
495
  self,
496
496
  save_path: str | None = None,
497
497
  figsize: tuple[int, int] = (12, 6),
498
+ show: bool = True,
498
499
  ):
499
500
  """
500
501
  Plot accuracy vs number of features.
@@ -505,6 +506,9 @@ class RFMinMaxSelector(FeatureSelector):
505
506
  Path to save the figure.
506
507
  figsize : tuple, default=(12, 6)
507
508
  Figure size.
509
+ show : bool, default=True
510
+ Whether to display the figure with plt.show(). If False, the
511
+ figure is closed after it is saved.
508
512
 
509
513
  Returns
510
514
  -------
@@ -525,6 +529,7 @@ class RFMinMaxSelector(FeatureSelector):
525
529
  cutoff_method=self.cutoff_method,
526
530
  save_path=save_path,
527
531
  figsize=figsize,
532
+ show=show,
528
533
  )
529
534
 
530
535
  def get_params(self) -> dict:
@@ -111,7 +111,9 @@ def train_rf_model(
111
111
  # Evaluate
112
112
  predictions = model.predict(X_test)
113
113
  accuracy = metrics.accuracy_score(y_test, predictions)
114
- report = metrics.classification_report(y_test, predictions)
114
+ # zero_division=0 gives the same 0.0 scores as the default, without warning
115
+ # about classes the forest never predicts (the report is built even when quiet)
116
+ report = metrics.classification_report(y_test, predictions, zero_division=0)
115
117
 
116
118
  if verbose:
117
119
  desc_str = f" ({description})" if description else ""
@@ -26,7 +26,9 @@ from tqdm import tqdm
26
26
  from .plot import (
27
27
  HyperparamGridBuilder,
28
28
  HyperparamGridConfig,
29
+ combine_figures_with_gridspec,
29
30
  get_legend,
31
+ to_scatter_colors,
30
32
  )
31
33
 
32
34
  np.seterr(all="ignore")
@@ -245,6 +247,7 @@ class PHATEVisualizer:
245
247
  phate_coords: np.ndarray,
246
248
  colors: np.ndarray | pd.Series,
247
249
  kwargs: Optional[dict] = None,
250
+ palette: Optional[list] = None,
248
251
  ) -> plt.Axes:
249
252
  """
250
253
  Plot PHATE embedding on given axes.
@@ -252,8 +255,14 @@ class PHATEVisualizer:
252
255
  Args:
253
256
  ax: Matplotlib axes to plot on.
254
257
  phate_coords: PHATE coordinates (n_cells, 2).
255
- colors: Color values for each cell.
258
+ colors: Color values for each cell. Numeric values are colormapped
259
+ ("rainbow", 1st-99th percentile); values that are all literal
260
+ colors (e.g. an obs column following the ``*_colors`` convention)
261
+ are used as-is; any other categorical/string values get one color
262
+ per category (see :func:`cc_mapping.plot.to_scatter_colors`).
256
263
  kwargs: Additional kwargs for scatter plot.
264
+ palette: Colors for the categories when ``colors`` is categorical,
265
+ one per category (e.g. ``adata.uns["phase_colors"]``).
257
266
 
258
267
  Returns:
259
268
  Modified axes object.
@@ -264,17 +273,17 @@ class PHATEVisualizer:
264
273
  kwargs = kwargs.copy()
265
274
 
266
275
  # Handle continuous vs categorical colors
267
- if not isinstance(colors, (pd.Categorical, pd.CategoricalDtype)):
268
- if colors.dtype != "object":
269
- vmin = np.percentile(colors, 1)
270
- vmax = np.percentile(colors, 99)
271
- kwargs.update(
272
- {
273
- "vmin": vmin,
274
- "vmax": vmax,
275
- "cmap": "rainbow",
276
- }
277
- )
276
+ colors, is_continuous = to_scatter_colors(colors, palette)
277
+ if is_continuous:
278
+ vmin = np.percentile(colors, 1)
279
+ vmax = np.percentile(colors, 99)
280
+ kwargs.update(
281
+ {
282
+ "vmin": vmin,
283
+ "vmax": vmax,
284
+ "cmap": "rainbow",
285
+ }
286
+ )
278
287
 
279
288
  ax.scatter(phate_coords[:, 0], phate_coords[:, 1], c=colors, **kwargs)
280
289
 
@@ -300,7 +309,12 @@ class PHATEVisualizer:
300
309
 
301
310
  Args:
302
311
  adata: AnnData object containing PHATE coordinates.
303
- color_name: Name of column in adata.obs to use for colors.
312
+ color_name: Name of a column in adata.obs (or a var name) to color by.
313
+ A categorical column such as "phase" is colored with
314
+ ``adata.uns[f"{color_name}_colors"]`` when present (scanpy
315
+ convention), otherwise a tab10/tab20 palette; a column of literal
316
+ colors such as "phase_colors" is used as-is; numeric values are
317
+ colormapped.
304
318
  obsm_embedding: Key for PHATE coordinates in adata.obsm.
305
319
  ax: Matplotlib axes to plot on. If None, creates new figure.
306
320
  unit_size: Size of the figure if creating new one.
@@ -320,8 +334,9 @@ class PHATEVisualizer:
320
334
 
321
335
  phate_coords = adata.obsm[obsm_embedding]
322
336
  colors = adata.obs_vector(color_name)
337
+ palette = adata.uns.get(f"{color_name}_colors")
323
338
 
324
- PHATEVisualizer.plot_embedding(ax, phate_coords, colors, kwargs)
339
+ PHATEVisualizer.plot_embedding(ax, phate_coords, colors, kwargs, palette=palette)
325
340
 
326
341
  if created_fig and return_fig:
327
342
  return fig, ax
@@ -337,7 +352,10 @@ class PHATEVisualizer:
337
352
  def plot_phate_hyperparam_cell(ax: plt.Axes, context: PHATEPlotContext) -> plt.Axes:
338
353
  """Plot a single cell in PHATE hyperparameter search grid."""
339
354
  colors = context.adata.obs_vector(context.color_name)
340
- PHATEVisualizer.plot_embedding(ax, context.phate_coords, colors, context.kwargs)
355
+ palette = context.adata.uns.get(f"{context.color_name}_colors")
356
+ PHATEVisualizer.plot_embedding(
357
+ ax, context.phate_coords, colors, context.kwargs, palette=palette
358
+ )
341
359
  return ax
342
360
 
343
361
 
@@ -348,7 +366,7 @@ def perform_phate_hyperparameter_search(
348
366
  hyperparam_grid: PHATEHyperparamGrid,
349
367
  base_config: PHATEConfig,
350
368
  color_name: str,
351
- final_grid_dims: tuple[int, int],
369
+ final_grid_dims: Optional[tuple[int, int]] = None,
352
370
  unit_size: int = 10,
353
371
  plot_kwargs: Optional[dict] = None,
354
372
  save_path: Optional[str] = None,
@@ -357,21 +375,29 @@ def perform_phate_hyperparameter_search(
357
375
  """
358
376
  Perform hyperparameter search for PHATE visualization.
359
377
 
378
+ One grid figure is built per value in ``hyperparam_grid.constant_param_values``.
379
+
360
380
  Args:
361
381
  adata: Annotated data object.
362
382
  feature_set: Name of the feature set.
363
383
  layer: Name of the layer.
364
384
  hyperparam_grid: Hyperparameter grid configuration.
365
385
  base_config: Base PHATE configuration.
366
- color_name: Name of color column for visualization.
367
- final_grid_dims: Dimensions (rows, cols) for final combined figure.
386
+ color_name: Name of color column for visualization (see
387
+ ``PHATEVisualizer.plot_from_adata`` for how colors are resolved).
388
+ final_grid_dims: Optional (rows, cols). When given, the per-constant-value
389
+ grids are combined into a single figure with this layout.
368
390
  unit_size: Size of each subplot unit.
369
391
  plot_kwargs: Additional kwargs for scatter plots.
370
- save_path: Path to save figures.
371
- show_legend: Whether to show legend.
392
+ save_path: Path to save figures. With ``final_grid_dims`` the combined
393
+ figure is saved to this path; otherwise each grid is saved as
394
+ ``<name>_<idx><ext>``.
395
+ show_legend: Whether to draw a category legend on each grid (categorical
396
+ ``color_name`` only).
372
397
 
373
398
  Returns:
374
- List of generated figures (one per constant parameter value).
399
+ List of generated figures: one per constant parameter value, or a single
400
+ combined figure when ``final_grid_dims`` is given.
375
401
  """
376
402
  if save_path is not None:
377
403
  save_dir = os.path.dirname(save_path)
@@ -436,22 +462,37 @@ def perform_phate_hyperparameter_search(
436
462
  )
437
463
  figure_list.append(fig)
438
464
 
439
- # Add legend if requested
465
+ # Add legend if requested, on the last (bottom-right) cell of every grid
440
466
  if color_name is not None and show_legend:
441
- color_vector = adata.obs_vector(color_name)
442
- if (
443
- isinstance(color_vector, (pd.Categorical, pd.CategoricalDtype))
444
- or color_vector.dtype == "object"
445
- ):
467
+ _, is_continuous = to_scatter_colors(adata.obs_vector(color_name))
468
+ if not is_continuous:
446
469
  patches, _ = get_legend(adata, color_name)
447
- plt.legend(handles=patches, fontsize=unit_size)
470
+ for fig in figure_list:
471
+ fig.axes[-1].legend(handles=patches, fontsize=unit_size)
472
+
473
+ # Combine the per-constant-value grids into one figure if requested
474
+ if final_grid_dims is not None:
475
+ combined_fig = combine_figures_with_gridspec(
476
+ figure_list, *final_grid_dims, unit_size=unit_size
477
+ )
478
+ for fig in figure_list:
479
+ plt.close(fig)
480
+ figure_list = [combined_fig]
448
481
 
449
482
  # Save if requested
450
483
  if save_path is not None:
451
- for idx, fig in enumerate(figure_list):
452
- path_base, path_ext = os.path.splitext(save_path)
453
- save_file = f"{path_base}_{idx}{path_ext}"
454
- fig.savefig(save_file, dpi=300, bbox_inches="tight")
484
+ if final_grid_dims is not None:
485
+ figure_list[0].savefig(save_path, dpi=300, bbox_inches="tight")
486
+ else:
487
+ for idx, fig in enumerate(figure_list):
488
+ path_base, path_ext = os.path.splitext(save_path)
489
+ save_file = f"{path_base}_{idx}{path_ext}"
490
+ fig.savefig(save_file, dpi=300, bbox_inches="tight")
491
+
492
+ # The returned figures stay usable (savefig, notebook display) but are removed
493
+ # from pyplot, so a later plt.show() doesn't display them a second time
494
+ for fig in figure_list:
495
+ plt.close(fig)
455
496
 
456
497
  return figure_list
457
498