cc-mapping 0.2.5__tar.gz → 0.2.7__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 (26) hide show
  1. cc_mapping-0.2.7/PKG-INFO +229 -0
  2. cc_mapping-0.2.7/README.md +192 -0
  3. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/pyproject.toml +3 -2
  4. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/__init__.py +1 -1
  5. cc_mapping-0.2.7/src/cc_mapping/core.py +180 -0
  6. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/__init__.py +41 -0
  7. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_base.py +2 -1
  8. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_persistence.py +1 -1
  9. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_preprocessing.py +15 -8
  10. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_random_forest.py +5 -0
  11. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_training.py +3 -1
  12. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/manifold.py +73 -32
  13. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/plot.py +165 -44
  14. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/base.py +177 -106
  15. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/sequential.py +17 -17
  16. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/single.py +35 -66
  17. cc_mapping-0.2.5/PKG-INFO +0 -230
  18. cc_mapping-0.2.5/README.md +0 -194
  19. cc_mapping-0.2.5/src/cc_mapping/core.py +0 -347
  20. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/LICENSE +0 -0
  21. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_plotting.py +0 -0
  22. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/preprocess.py +0 -0
  23. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/pseudotime.py +0 -0
  24. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/__init__.py +0 -0
  25. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/utils.py +0 -0
  26. {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/utils_v0.py +0 -0
@@ -0,0 +1,229 @@
1
+ Metadata-Version: 2.1
2
+ Name: cc-mapping
3
+ Version: 0.2.7
4
+ Summary: Gaussian Mixture Model-based thresholding for single-cell gene expression analysis
5
+ Home-page: https://github.com/StallaertLab/cc_mapping
6
+ License: BSD-3-Clause
7
+ Keywords: single-cell,gaussian-mixture-model,thresholding,gene-expression,cell-cycle,anndata,bioinformatics,computational-biology
8
+ Author: ddpoe
9
+ Author-email: dap182@pitt.edu
10
+ Requires-Python: >=3.10,<4.0
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: License :: OSI Approved :: BSD License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
19
+ Provides-Extra: manifold
20
+ Provides-Extra: persistence
21
+ Requires-Dist: anndata (>=0.10.0,<0.11.0)
22
+ Requires-Dist: kneed (>=0.8.5,<0.9.0)
23
+ Requires-Dist: matplotlib (>=3.7.0,<4.0.0)
24
+ Requires-Dist: mpl-scatter-density (>=0.8,<0.9)
25
+ Requires-Dist: numpy (>=1.24.0)
26
+ Requires-Dist: pandas (>=2.0.0,<3.0.0)
27
+ Requires-Dist: phate (>=1.0.0,<3.0.0) ; extra == "manifold"
28
+ Requires-Dist: pydantic (>=2.10.0,<3.0.0)
29
+ Requires-Dist: scikit-learn (>=1.3.0,<2.0.0)
30
+ Requires-Dist: scipy (>=1.11.0,<2.0.0)
31
+ Requires-Dist: skops (>=0.13.0,<0.14.0) ; extra == "persistence"
32
+ Requires-Dist: tqdm (>=4.67.1,<5.0.0)
33
+ Project-URL: Documentation, https://cc-mapping.readthedocs.io
34
+ Project-URL: Repository, https://github.com/StallaertLab/cc_mapping
35
+ Description-Content-Type: text/markdown
36
+
37
+ # cc_mapping
38
+
39
+ [![PyPI version](https://img.shields.io/pypi/v/cc-mapping.svg)](https://pypi.org/project/cc-mapping/)
40
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
41
+ [![Documentation](https://readthedocs.org/projects/cc-mapping/badge/?version=latest)](https://cc-mapping.readthedocs.io)
42
+ [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/StallaertLab/cc_mapping/blob/main/LICENSE)
43
+
44
+ **Gaussian Mixture Model-based thresholding and cell cycle mapping for single-cell data**
45
+
46
+ `cc_mapping` categorizes cells by fitting Gaussian Mixture Models (GMMs) to
47
+ single-cell feature measurements stored in an [AnnData](https://anndata.readthedocs.io)
48
+ object. It was developed for cell cycle analysis, and it works for any
49
+ single-cell feature you want to split into populations (for example, low and high).
50
+
51
+ ## Features
52
+
53
+ - **Single-feature thresholding**: fit a GMM to one feature and label each cell from the fitted decision boundaries
54
+ - **Sequential thresholding**: refine one label at a time with further features, like a gating strategy
55
+ - **Manual overrides**: set thresholds by hand when you need to
56
+ - **Plots**: histograms and strip plots with the fitted components and decision boundaries
57
+ - **Feature selection**: random forest selectors that find the features that best separate your labels
58
+ - **Cell cycle maps**: PHATE embeddings of the selected features (optional dependency)
59
+ - **AnnData throughout**: labels go to `adata.obs`, and the fitted models and thresholds go to `adata.uns`
60
+
61
+ ## Installation
62
+
63
+ ```bash
64
+ pip install cc-mapping
65
+ ```
66
+
67
+ Optional extras:
68
+
69
+ ```bash
70
+ pip install "cc-mapping[manifold]" # PHATE, for cell cycle maps
71
+ pip install "cc-mapping[persistence]" # skops, to save and load fitted feature selectors
72
+ ```
73
+
74
+ To install from source:
75
+
76
+ ```bash
77
+ git clone https://github.com/StallaertLab/cc_mapping.git
78
+ cd cc_mapping
79
+ pip install -e .
80
+ ```
81
+
82
+ ## Quick start
83
+
84
+ ```python
85
+ import anndata as ad
86
+ from cc_mapping import GMMThresholding
87
+
88
+ adata = ad.read_h5ad("your_data.h5ad")
89
+
90
+ # Threshold one feature (a name in adata.var_names)
91
+ gmm = GMMThresholding(
92
+ adata=adata,
93
+ feature="PCNA",
94
+ label_obs_save_str="PCNA_category",
95
+ )
96
+
97
+ # Fit a two-component GMM and label the cells
98
+ gmm.fit(n_components=2)
99
+ gmm.categorize_samples(ordered_labels=["Low", "High"])
100
+
101
+ # Plot the histogram with the fitted components and the decision boundary
102
+ gmm.plot_hist_distribution_with_boundaries(save_path="pcna_thresholding.png")
103
+
104
+ # Get a copy of the AnnData with the labels in adata.obs["PCNA_category"]
105
+ adata = gmm.return_adata()
106
+ ```
107
+
108
+ `GMMThresholding` works on a copy of your AnnData, so call `return_adata()`
109
+ to get the labelled result.
110
+
111
+ To set the threshold yourself, pass `manual_thresholds`. No fit is needed:
112
+
113
+ ```python
114
+ gmm.categorize_samples(ordered_labels=["Low", "High"], manual_thresholds=[0.05])
115
+ ```
116
+
117
+ ## Sequential thresholding
118
+
119
+ `SequentialGMM` thresholds the whole dataset once, then refines one label at
120
+ a time using other features. Each step has a name and is recorded in `adata.uns`.
121
+
122
+ ```python
123
+ from cc_mapping import SequentialGMM
124
+
125
+ seq_gmm = SequentialGMM(adata=adata)
126
+
127
+ # Step 1: split every cell on DNA content
128
+ seq_gmm.threshold_entire_dataset(
129
+ feature="DNA_content",
130
+ label_obs_save_str="cell_cycle",
131
+ n_components=2,
132
+ ordered_labels=["2N", "4N"],
133
+ operation_name="DNA_threshold",
134
+ )
135
+
136
+ # Step 2: split only the 2N cells on pRB
137
+ seq_gmm.refine_labels_with_gmm(
138
+ feature="pRB",
139
+ obs_label="cell_cycle",
140
+ value_to_refine="2N",
141
+ n_components=2,
142
+ ordered_labels=["G0", "G1"],
143
+ operation_name="pRB_refinement",
144
+ )
145
+
146
+ adata = seq_gmm.return_adata()
147
+ ```
148
+
149
+ Use `refine_labels_with_manual_thresholds` to refine a label with thresholds
150
+ you choose.
151
+
152
+ ## Combining labels
153
+
154
+ `create_boolean_label_combination` combines two categorical `adata.obs`
155
+ columns with boolean logic:
156
+
157
+ ```python
158
+ from cc_mapping import create_boolean_label_combination
159
+
160
+ adata = create_boolean_label_combination(
161
+ adata=adata,
162
+ obs_key_1="treatment",
163
+ match_values_1=["control"],
164
+ obs_key_2="cell_cycle",
165
+ match_values_2=["G0"],
166
+ operator="AND",
167
+ output_obs_key="control_G0",
168
+ true_label="control_G0",
169
+ false_label="other",
170
+ )
171
+ ```
172
+
173
+ ## Feature selection and cell cycle maps
174
+
175
+ `cc_mapping.feature_selection` selects the features that best separate a set
176
+ of labels, and `cc_mapping.manifold` embeds the cells on those features with PHATE:
177
+
178
+ ```python
179
+ from cc_mapping.feature_selection import RFMinMaxSelector
180
+ from cc_mapping.manifold import run_phate
181
+
182
+ # Find the smallest feature set that keeps classification accuracy high
183
+ selector = RFMinMaxSelector(threshold=0.05, stable_iterations=5)
184
+ selector.fit_adata(adata, adata.var_names, "cell_cycle")
185
+ selector.transform_adata(adata, var_key="selected_features")
186
+
187
+ # Embed the cells with PHATE (needs the "manifold" extra)
188
+ adata = run_phate(adata, feature_set="selected_features", layer="z_score")
189
+ # coordinates are in adata.obsm["X_phate"]
190
+ ```
191
+
192
+ `run_phate` reads from `adata.layers`, so `layer` must name a layer in your AnnData.
193
+
194
+ ## Documentation
195
+
196
+ The full documentation, tutorials and API reference are at
197
+ [cc-mapping.readthedocs.io](https://cc-mapping.readthedocs.io).
198
+
199
+ Example notebooks are in [`notebooks/`](https://github.com/StallaertLab/cc_mapping/tree/main/notebooks):
200
+
201
+ - [Single thresholding](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/Single_Thresholding_Workflow.ipynb)
202
+ - [Sequential thresholding](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/Sequential_Thresholding_Workflow.ipynb)
203
+ - [CSV to AnnData](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/CSV_to_Anndata.ipynb)
204
+ - [Cell cycle maps](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/Cell_Cycle_Map_Workflow.ipynb) (random forest feature selection and PHATE)
205
+
206
+ ## Requirements
207
+
208
+ Python 3.10 or later. `pip` installs the dependencies: numpy, pandas, scipy,
209
+ scikit-learn, matplotlib, anndata, pydantic, kneed, mpl-scatter-density and tqdm.
210
+
211
+ ## Citation
212
+
213
+ If you use `cc_mapping` in your research, please cite this repository:
214
+ <https://github.com/StallaertLab/cc_mapping>
215
+
216
+ ## Contributing
217
+
218
+ Contributions are welcome. Please open an issue or submit a pull request.
219
+
220
+ ## License
221
+
222
+ `cc_mapping` is released under the BSD 3-Clause License. See
223
+ [LICENSE](https://github.com/StallaertLab/cc_mapping/blob/main/LICENSE).
224
+
225
+ ## Support
226
+
227
+ - **Bug reports and questions**: [GitHub Issues](https://github.com/StallaertLab/cc_mapping/issues)
228
+ - **Email**: dap182@pitt.edu
229
+
@@ -0,0 +1,192 @@
1
+ # cc_mapping
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/cc-mapping.svg)](https://pypi.org/project/cc-mapping/)
4
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
5
+ [![Documentation](https://readthedocs.org/projects/cc-mapping/badge/?version=latest)](https://cc-mapping.readthedocs.io)
6
+ [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/StallaertLab/cc_mapping/blob/main/LICENSE)
7
+
8
+ **Gaussian Mixture Model-based thresholding and cell cycle mapping for single-cell data**
9
+
10
+ `cc_mapping` categorizes cells by fitting Gaussian Mixture Models (GMMs) to
11
+ single-cell feature measurements stored in an [AnnData](https://anndata.readthedocs.io)
12
+ object. It was developed for cell cycle analysis, and it works for any
13
+ single-cell feature you want to split into populations (for example, low and high).
14
+
15
+ ## Features
16
+
17
+ - **Single-feature thresholding**: fit a GMM to one feature and label each cell from the fitted decision boundaries
18
+ - **Sequential thresholding**: refine one label at a time with further features, like a gating strategy
19
+ - **Manual overrides**: set thresholds by hand when you need to
20
+ - **Plots**: histograms and strip plots with the fitted components and decision boundaries
21
+ - **Feature selection**: random forest selectors that find the features that best separate your labels
22
+ - **Cell cycle maps**: PHATE embeddings of the selected features (optional dependency)
23
+ - **AnnData throughout**: labels go to `adata.obs`, and the fitted models and thresholds go to `adata.uns`
24
+
25
+ ## Installation
26
+
27
+ ```bash
28
+ pip install cc-mapping
29
+ ```
30
+
31
+ Optional extras:
32
+
33
+ ```bash
34
+ pip install "cc-mapping[manifold]" # PHATE, for cell cycle maps
35
+ pip install "cc-mapping[persistence]" # skops, to save and load fitted feature selectors
36
+ ```
37
+
38
+ To install from source:
39
+
40
+ ```bash
41
+ git clone https://github.com/StallaertLab/cc_mapping.git
42
+ cd cc_mapping
43
+ pip install -e .
44
+ ```
45
+
46
+ ## Quick start
47
+
48
+ ```python
49
+ import anndata as ad
50
+ from cc_mapping import GMMThresholding
51
+
52
+ adata = ad.read_h5ad("your_data.h5ad")
53
+
54
+ # Threshold one feature (a name in adata.var_names)
55
+ gmm = GMMThresholding(
56
+ adata=adata,
57
+ feature="PCNA",
58
+ label_obs_save_str="PCNA_category",
59
+ )
60
+
61
+ # Fit a two-component GMM and label the cells
62
+ gmm.fit(n_components=2)
63
+ gmm.categorize_samples(ordered_labels=["Low", "High"])
64
+
65
+ # Plot the histogram with the fitted components and the decision boundary
66
+ gmm.plot_hist_distribution_with_boundaries(save_path="pcna_thresholding.png")
67
+
68
+ # Get a copy of the AnnData with the labels in adata.obs["PCNA_category"]
69
+ adata = gmm.return_adata()
70
+ ```
71
+
72
+ `GMMThresholding` works on a copy of your AnnData, so call `return_adata()`
73
+ to get the labelled result.
74
+
75
+ To set the threshold yourself, pass `manual_thresholds`. No fit is needed:
76
+
77
+ ```python
78
+ gmm.categorize_samples(ordered_labels=["Low", "High"], manual_thresholds=[0.05])
79
+ ```
80
+
81
+ ## Sequential thresholding
82
+
83
+ `SequentialGMM` thresholds the whole dataset once, then refines one label at
84
+ a time using other features. Each step has a name and is recorded in `adata.uns`.
85
+
86
+ ```python
87
+ from cc_mapping import SequentialGMM
88
+
89
+ seq_gmm = SequentialGMM(adata=adata)
90
+
91
+ # Step 1: split every cell on DNA content
92
+ seq_gmm.threshold_entire_dataset(
93
+ feature="DNA_content",
94
+ label_obs_save_str="cell_cycle",
95
+ n_components=2,
96
+ ordered_labels=["2N", "4N"],
97
+ operation_name="DNA_threshold",
98
+ )
99
+
100
+ # Step 2: split only the 2N cells on pRB
101
+ seq_gmm.refine_labels_with_gmm(
102
+ feature="pRB",
103
+ obs_label="cell_cycle",
104
+ value_to_refine="2N",
105
+ n_components=2,
106
+ ordered_labels=["G0", "G1"],
107
+ operation_name="pRB_refinement",
108
+ )
109
+
110
+ adata = seq_gmm.return_adata()
111
+ ```
112
+
113
+ Use `refine_labels_with_manual_thresholds` to refine a label with thresholds
114
+ you choose.
115
+
116
+ ## Combining labels
117
+
118
+ `create_boolean_label_combination` combines two categorical `adata.obs`
119
+ columns with boolean logic:
120
+
121
+ ```python
122
+ from cc_mapping import create_boolean_label_combination
123
+
124
+ adata = create_boolean_label_combination(
125
+ adata=adata,
126
+ obs_key_1="treatment",
127
+ match_values_1=["control"],
128
+ obs_key_2="cell_cycle",
129
+ match_values_2=["G0"],
130
+ operator="AND",
131
+ output_obs_key="control_G0",
132
+ true_label="control_G0",
133
+ false_label="other",
134
+ )
135
+ ```
136
+
137
+ ## Feature selection and cell cycle maps
138
+
139
+ `cc_mapping.feature_selection` selects the features that best separate a set
140
+ of labels, and `cc_mapping.manifold` embeds the cells on those features with PHATE:
141
+
142
+ ```python
143
+ from cc_mapping.feature_selection import RFMinMaxSelector
144
+ from cc_mapping.manifold import run_phate
145
+
146
+ # Find the smallest feature set that keeps classification accuracy high
147
+ selector = RFMinMaxSelector(threshold=0.05, stable_iterations=5)
148
+ selector.fit_adata(adata, adata.var_names, "cell_cycle")
149
+ selector.transform_adata(adata, var_key="selected_features")
150
+
151
+ # Embed the cells with PHATE (needs the "manifold" extra)
152
+ adata = run_phate(adata, feature_set="selected_features", layer="z_score")
153
+ # coordinates are in adata.obsm["X_phate"]
154
+ ```
155
+
156
+ `run_phate` reads from `adata.layers`, so `layer` must name a layer in your AnnData.
157
+
158
+ ## Documentation
159
+
160
+ The full documentation, tutorials and API reference are at
161
+ [cc-mapping.readthedocs.io](https://cc-mapping.readthedocs.io).
162
+
163
+ Example notebooks are in [`notebooks/`](https://github.com/StallaertLab/cc_mapping/tree/main/notebooks):
164
+
165
+ - [Single thresholding](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/Single_Thresholding_Workflow.ipynb)
166
+ - [Sequential thresholding](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/Sequential_Thresholding_Workflow.ipynb)
167
+ - [CSV to AnnData](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/CSV_to_Anndata.ipynb)
168
+ - [Cell cycle maps](https://github.com/StallaertLab/cc_mapping/blob/main/notebooks/Cell_Cycle_Map_Workflow.ipynb) (random forest feature selection and PHATE)
169
+
170
+ ## Requirements
171
+
172
+ Python 3.10 or later. `pip` installs the dependencies: numpy, pandas, scipy,
173
+ scikit-learn, matplotlib, anndata, pydantic, kneed, mpl-scatter-density and tqdm.
174
+
175
+ ## Citation
176
+
177
+ If you use `cc_mapping` in your research, please cite this repository:
178
+ <https://github.com/StallaertLab/cc_mapping>
179
+
180
+ ## Contributing
181
+
182
+ Contributions are welcome. Please open an issue or submit a pull request.
183
+
184
+ ## License
185
+
186
+ `cc_mapping` is released under the BSD 3-Clause License. See
187
+ [LICENSE](https://github.com/StallaertLab/cc_mapping/blob/main/LICENSE).
188
+
189
+ ## Support
190
+
191
+ - **Bug reports and questions**: [GitHub Issues](https://github.com/StallaertLab/cc_mapping/issues)
192
+ - **Email**: dap182@pitt.edu
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "cc-mapping"
3
- version = "0.2.5"
3
+ version = "0.2.7"
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.7"
@@ -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