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.
- cc_mapping-0.2.7/PKG-INFO +229 -0
- cc_mapping-0.2.7/README.md +192 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/pyproject.toml +3 -2
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/__init__.py +1 -1
- cc_mapping-0.2.7/src/cc_mapping/core.py +180 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/__init__.py +41 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_base.py +2 -1
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_persistence.py +1 -1
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_preprocessing.py +15 -8
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_random_forest.py +5 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_training.py +3 -1
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/manifold.py +73 -32
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/plot.py +165 -44
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/base.py +177 -106
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/sequential.py +17 -17
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/single.py +35 -66
- cc_mapping-0.2.5/PKG-INFO +0 -230
- cc_mapping-0.2.5/README.md +0 -194
- cc_mapping-0.2.5/src/cc_mapping/core.py +0 -347
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/LICENSE +0 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/feature_selection/_plotting.py +0 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/preprocess.py +0 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/pseudotime.py +0 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/thresholding/__init__.py +0 -0
- {cc_mapping-0.2.5 → cc_mapping-0.2.7}/src/cc_mapping/utils.py +0 -0
- {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
|
+
[](https://pypi.org/project/cc-mapping/)
|
|
40
|
+
[](https://www.python.org/downloads/)
|
|
41
|
+
[](https://cc-mapping.readthedocs.io)
|
|
42
|
+
[](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
|
+
[](https://pypi.org/project/cc-mapping/)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](https://cc-mapping.readthedocs.io)
|
|
6
|
+
[](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.
|
|
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 = "
|
|
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"
|
|
@@ -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
|