|
1 | 1 | # HiTME :dart: :facepunch: |
2 | 2 |
|
| 3 | +<p align="center"> |
| 4 | + |
| 5 | +<img src="docs/HiTME_logo.png" height="100"/> |
| 6 | + |
| 7 | +</p> |
| 8 | + |
3 | 9 | ## High-resolution Tumor Micro-Environment cell type classification |
4 | 10 |
|
5 | 11 | HiTME is designed for precise cell type classification within the complex tumor microenvironment (TME), providing high accuracy and interpretability in cell type identification. |
6 | 12 |
|
7 | | -Find a vignette describing its main functions in [html](https://carmonalab.github.io/HiTME_CaseStudies/HiTME_demo.html) and its [code (repository)](https://github.com/carmonalab/HiTME_CaseStudies). |
| 13 | +Find a vignette describing its main functions in [html](https://carmonalab.github.io/HiTME_CaseStudies/HiTME_GetStarted.html) and its [code (repository)](https://github.com/carmonalab/HiTME_CaseStudies). |
8 | 14 |
|
9 | | -### Installation |
| 15 | +## Installation |
10 | 16 |
|
11 | 17 | ``` r |
12 | 18 | # install.packages("remotes") |
13 | 19 | remotes::install_github("carmonalab/HiTME") |
14 | 20 | ``` |
15 | 21 |
|
16 | | -<br> |
17 | | - |
18 | | -# Cell type annotation |
19 | | - |
20 | | -**HiTME is an R package that combines [scGate](https://github.com/carmonalab/scGate) and [ProjecTILs](https://github.com/carmonalab/ProjecTILs) to classify cell types in single-cell RNA-seq data at high resolution and with large flexibility (e.g. easy to include new cell types).** |
21 | | - |
22 | | -The function takes as input `Seurat` objects (or list of them). These should be split by sample to avoid batch effects, or split internally in `Run.HitME` by indicating the parameter `split.by`. |
23 | | - |
24 | | -This wrapper firstly runs [scGate](https://github.com/carmonalab/scGate) (easily customizable) marker-based classification, resulting in a coarse-grained cell type classification (CD4T, B cell, Dendritic cell...). Next, it runs for each broad cell type [ProjecTILs](https://github.com/carmonalab/ProjecTILs) for a finer cell type classification (CD4+ TFH, Tex CD8+, cDC1...) based on cell mapping onto expert-curated single-cell reference maps. |
| 22 | +## Usage |
25 | 23 |
|
26 | 24 | ``` r |
27 | | -library(scGate) |
28 | 25 | library(ProjecTILs) |
29 | 26 | library(HiTME) |
30 | 27 |
|
31 | | -# If multiple samples are within the same Seurat object, split by sample. |
32 | | -# obj.list <- SplitObject(obj, split.by = "Sample") |
| 28 | +# Fetch reference maps |
| 29 | +ref.maps <- ref.maps <- get.reference.maps(collection = "human") |
33 | 30 |
|
34 | | -# Define scGate model if other than default is wanted |
35 | | -scGate_models_DB <- get_scGateDB(branch = "master") |
36 | | -models.TME <- scGate_models_DB$human$HiTME |
| 31 | +# Cell type classification on a Seurat object |
| 32 | +query <- Run.HiTME(query, |
| 33 | + ref.maps = ref.maps[["human"]]) |
37 | 34 |
|
38 | | -# Load ProjecTILs reference maps |
39 | | -path_ref <- "~/reference_atlases" |
40 | | -ref.maps <- list(CD8 = load.reference.map(file.path(path_ref, "CD8T_human_ref_v1.rds")), |
41 | | - CD4 = load.reference.map(file.path(path_ref, "CD4T_human_ref_v2.rds")), |
42 | | - DC = load.reference.map(file.path(path_ref, "DC_human_ref_v1.rds")), |
43 | | - MoMac = load.reference.map(file.path(path_ref, "MoMac_human_v1.rds")) |
44 | | - ) |
| 35 | +# Seurat object metadata has been updated with cell type classification at different granularity levels (layers) |
45 | 36 | ``` |
46 | 37 |
|
| 38 | +### How to cite HiTME |
| 39 | +Please note that the publication describing HiTME is currently in preparation. In the meantime, we kindly ask that you cite the two primary components of HiTME in your work: |
| 40 | + |
| 41 | +- [scGate](https://github.com/carmonalab/scGate): Andreatta, Massimo, Ariel J. Berenstein, and Santiago J. Carmona. 2022. “scGate: Marker-Based Purification of Cell Types from Heterogeneous Single-Cell RNA-Seq Datasets.” Bioinformatics 38 (April): 2642–44. https://doi.org/10.1093/BIOINFORMATICS/BTAC141. |
| 42 | +- [ProjecTILs](https://github.com/carmonalab/ProjecTILs): Andreatta, Massimo, Jesus Corria-Osorio, Sören Müller, Rafael Cubas, George Coukos, and Santiago J. Carmona. 2021. “Interpretation of t Cell States from Single-Cell Transcriptomics Data Using Reference Atlases.” Nature Communications 2021 12:1 12 (May): 1–19. https://doi.org/10.1038/s41467-021-23324-4. |
| 43 | + |
47 | 44 | <br> |
48 | 45 |
|
49 | | -By default [scGate](https://github.com/carmonalab/scGate) (layer 1) will return the [cell ontology ID](https://www.ebi.ac.uk/ols4/ontologies/cl) for each predicted cell type. This ID will be then used to link each coarse cell type with its respective reference map for finer cell type classification using [ProjecTILs](https://github.com/carmonalab/ProjecTILs). Hence, we need to indicate each respective cell ontology ID(s) for each reference map. |
| 46 | +# Cell type annotation by HiTME |
50 | 47 |
|
51 | | -If alternative cell type link are used between the coarse and finer cell type classification, this must be specified in `Run.HiTME` using `layer1_link` parameter. |
| 48 | +**HiTME is an R package that combines [scGate](https://github.com/carmonalab/scGate) and [ProjecTILs](https://github.com/carmonalab/ProjecTILs) to classify cell types in single-cell RNA-seq data at high resolution and with large flexibility (e.g. easy to include new cell types).** |
52 | 49 |
|
53 | | -``` r |
54 | | -# add scGate_link to ref.maps |
55 | | -# Include a slot in @misc with the cell name output by scGate |
56 | | -# By default scGate returns cell ontology ID |
57 | | - |
58 | | -layer1.links <- list("CD8" = "CL:0000625", |
59 | | - "CD4" = "CL:0000624", |
60 | | - "DC" = "CL:0000451", |
61 | | - "MoMac" = "CL:0000576_CL:0000235" |
62 | | - ) |
63 | | - |
64 | | -for(a in names(ref.maps)){ |
65 | | - ref.maps[[a]]@misc$layer1_link <- layer1.links[[a]] |
66 | | -} |
67 | | -``` |
| 50 | +The function takes as input `Seurat` objects (or list of them). These should be split by sample to avoid batch effects, or split internally in `Run.HitME` by indicating the parameter `split.by`. |
68 | 51 |
|
69 | | -``` r |
70 | | -# Run HiTME |
71 | | -annotated.obj <- Run.HiTME(object = obj, |
72 | | - scGate.model = models.TME, |
73 | | - ref.maps = ref.maps) |
74 | | - |
75 | | -annotated.obj <- Run.HiTME(obj, |
76 | | - scGate.model = models.TME, |
77 | | - ref.maps = ref.maps, |
78 | | - # already split object |
79 | | - split.by = NULL, |
80 | | - # if splitting or providing list, whether to return a single merged object |
81 | | - remerge = FALSE, |
82 | | - # link between scGate and ProjecTILs |
83 | | - layer1_link = "CellOntology_ID", |
84 | | - # extra signatures to be computed per celltype |
85 | | - additional.signatures = additional.signatures, |
86 | | - # paralelization parameters |
87 | | - ncores = 4, |
88 | | - progressbar = TRUE |
89 | | - ) |
90 | | -``` |
| 52 | +**HiTME** firstly runs [scGate](https://github.com/carmonalab/scGate) (easily customizable) marker-based classification, resulting in a coarse-grained cell type classification (CD4T, B cell, Dendritic cell...). Next, it runs for each broad cell type [ProjecTILs](https://github.com/carmonalab/ProjecTILs) for a finer cell type classification (CD4+ TFH, Tex CD8+, cDC1...) based on cell mapping onto expert-curated single-cell reference maps. Finally, cell subtype are further classified based on gene programs such as cell cycling, IFN or HSP-response scoring, using [UCell](https://github.com/carmonalab/UCell). |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +<p align="center"> |
| 57 | + |
| 58 | +<img src="docs/HiTME_logo.png" height="100"/> |
| 59 | + |
| 60 | +</p> |
0 commit comments