{"id":17892737,"url":"https://github.com/asmagen/robustsinglecell","last_synced_at":"2025-03-23T01:32:03.551Z","repository":{"id":67172504,"uuid":"163871827","full_name":"asmagen/robustSingleCell","owner":"asmagen","description":"Robust single cell clustering and comparison of population compositions across tissues and experimental models via similarity analysis.","archived":false,"fork":false,"pushed_at":"2023-07-16T20:49:55.000Z","size":7934,"stargazers_count":14,"open_issues_count":9,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T16:22:37.045Z","etag":null,"topics":["clustering","data-integration","scrnaseq","single-cell-genomics","single-cell-rna-seq"],"latest_commit_sha":null,"homepage":"http://dx.doi.org/10.1016/j.celrep.2019.10.131","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asmagen.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-01-02T17:50:43.000Z","updated_at":"2025-02-10T06:14:40.000Z","dependencies_parsed_at":"2024-01-14T04:40:57.105Z","dependency_job_id":"8914d45a-682e-4b7a-8d05-c0e468274515","html_url":"https://github.com/asmagen/robustSingleCell","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmagen%2FrobustSingleCell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmagen%2FrobustSingleCell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmagen%2FrobustSingleCell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asmagen%2FrobustSingleCell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asmagen","download_url":"https://codeload.github.com/asmagen/robustSingleCell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245044042,"owners_count":20551876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clustering","data-integration","scrnaseq","single-cell-genomics","single-cell-rna-seq"],"created_at":"2024-10-28T14:43:41.321Z","updated_at":"2025-03-23T01:32:02.811Z","avatar_url":"https://github.com/asmagen.png","language":"R","readme":"---\ntitle: robustSingleCell\noutput:\n  github_document\n---\n\n[![CRAN status](https://www.r-pkg.org/badges/version/robustSingleCell)](https://cran.r-project.org/package=robustSingleCell)\n[![Travis build status](https://travis-ci.org/asmagen/robustSingleCell.svg?branch=master)](https://travis-ci.org/asmagen/robustSingleCell)\n[![DOI](https://zenodo.org/badge/163871827.svg)](https://zenodo.org/badge/latestdoi/163871827)\n\n```{r setup, include=FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\",\n  eval = FALSE)\n```\n\n\n### Overview\n\nrobustSingleCell is a pipeline designed to identify robust cell subpopulations using scRNAseq data and compare population compositions across tissues and experimental models via similarity analysis as described in Magen et al. (2019) [*bioRxiv*](https://doi.org/10.1101/543199) [^3]. \n\n### Installation\n\nInstall the following dependencies before installing the package:\n\n```r\nif(!require(devtools))\n  install.packages(\"devtools\")\nif (!requireNamespace(\"BiocManager\", quietly = TRUE))\n  install.packages(\"BiocManager\")\n\nBiocManager::install(\"limma\")\nBiocManager::install(\"grimbough/biomaRt\")\n```\n\nYou can then install the stable version from CRAN:\n\n```r\ninstall.packages(\"robustSingleCell\")\n```\n\nTo access the latest features or bug fixes, you can install the development version from GitHub.\n\n```r\ndevtools::install_github(\"asmagen/robustsinglecell\")\n```\n\nThis pipeline currently supports [slurm](https://slurm.schedmd.com) for parallel batch jobs.\n\n### Getting help\n\nIf you identify a bug, please submit an [issue](https://github.com/asmagen/robustSingleCell/issues) with a reproducible example. \n\n\n### Tutorial\n\nWe used two replicates of CD44\u003csup\u003e+\u003c/sup\u003e T cell data sets from Ciucci et al. 2019 [^1] as an example to demonstrate the use of `robustSingleCell`. The analysis requires at least 8G of memory on *slurm* [^2] high performance computing workload manager (for example, you can start by requesting `srun --pty -p \u003cpartition\u003e --mem=8G -t 1:00:00 bash` to start an interactive session).\n\nWe first download the raw 10X data from GEO using `GEOquery`, which can be obtained using the following command if not already installed:\n\n```r\nsource(\"https://bioconductor.org/biocLite.R\")\nbiocLite(\"GEOquery\")\n```\n\nThe two datasets `LCMV1`, `LCMV2` will be downloaded into TMPDIR. Each folder will contain the `matrix.mtx`, `gene.tsv` and `barcode.tsv` files as in 10X genomics format.\n\n\n```{r download_data}\nlibrary(robustSingleCell)\ndownload_LCMV()\n```\n\n**Note:** when using your own data, the 10X genomics files (`matrix.mtx`, `gene.tsv` and `barcode.tsv`) will be typically located at ⁨`outs⁩/⁨filtered_gene_bc_matrices⁩/⁨mm10⁩`, depending on the genome used for alignment. Copy the contents of this directory to the working directory `data.path` specified in `initialize.project` below.\n\nWe cluster each dataset separately to account for dataset-specific technical and biological differences. Then, we measure the transcriptional similarity and divergence between the clusters identified in the two datasets using correlation analysis.\n\n## Individual analysis of LCMV1 and LCMV2\n\nFirst, we set up the directory where the results of the analysis will be stored. \n\n```{r initialize}\nLCMV1 \u003c- initialize.project(datasets = \"LCMV1\", \n                          origins = \"CD44+ cells\",\n                          experiments = \"Rep1\",\n                          data.path = file.path(tempdir(), \"LCMV\"),\n                          work.path = file.path(tempdir(), \"LCMV/LCMV_analysis\"))\n```\n\n`read.data` function reads the data in 10X genomics format and performs quality filtering as described in *Magen et al 2019*. We randomly downsampled the datasets to 500 cells to shorten the simplify this example.\n\n```{r read_LCMV1}\nLCMV1 \u003c- read.data(LCMV1, subsample = 500)\n```\n\nNext, we identify highly variable genes for the following PCA and clustering analyses. We also compute the activation of gene sets of interest, such as cell cycle genes, for confounder correction.\n\n```{r preprocess}\nLCMV1 \u003c- get.variable.genes(LCMV1) \nexhaustion_markers \u003c- c('Pdcd1', 'Cd244', 'Havcr2', 'Ctla4', 'Cd160', 'Lag3', 'Tigit', 'Cd96')\nLCMV1 \u003c- add.confounder.variables(LCMV1,\n\tribosomal.score = ribosomal.score(LCMV1),\n\tmitochondrial.score = mitochondrial.score(LCMV1),\n\tcell.cycle.score = cell.cycle.score(LCMV1),\n\tExhaustion = controlled.mean.score(LCMV1, exhaustion_markers))\n```\n\nFigure 1 shows the mitochondrial score versus number of UMIs, pre and post filtering.\n\n\u003cfigure\u003e\n  \u003cimg src=\"vignettes/figs/pre_stats.png\" width = \"700\"\u003e \n  \u003cimg src=\"vignettes/figs/post_stats.png\" width = \"700\"\u003e\n\u003cfigcaption\u003e Fig 1. Mitochondrial genes score vs. number of UMIs for pre (top) and post (bottom) quality control filtering.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nThe `PCA` function performs multiple simulation analyses of shuffled data to determine the appropriate number of PCs. You can also run each simulation in parallel using the option `local = F`.\n\n```{r PCA}\nLCMV1 \u003c- PCA(LCMV1, local = T)\n```\n\nWe then perform clustering analysis for a range of clustering resolutions. The analysis is repeated multiple times over shuffled data to estimate the appropriate clustering resolution and control for false discovery of clusters. At the end of the clustering, the function will prompt you to choose an optimal clustering resolution. We choose 0.05 for our KNN ratio, which is the smallest value tested with `mdlrty/mean.shfl` \u003e 2. \n\n```{r cluster}\nLCMV1 \u003c- cluster.analysis(LCMV1, local = T)\n```\n\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/Clustering.modularity.png\" width = \"700\"\u003e\n\u003cfigcaption\u003e Fig 2. Bar plot shows the clustering modularity of the original data versus shuffled data across multiple clustering resolutions. Numbers on top represent the fold change of original versus shuffled analysis for each resolution. \u003c/figcaption\u003e\n\u003c/figure\u003e\n\nWe select the appropriate resolution, typically the one where there is more than two (2) fold change modularity difference relative to the shuffled analysis.\n\nThe `summarize` function which performs differential expression analysis, computes tSNE and visualizes the results in the analysis folder. After differential expression analysis, `get.cluster.names` assigns clusters with names using a customized set of marker genes which users should adapt to their own data.\n\n```{r annotation}\ntypes = rbind(\n                data.frame(type='Tfh',gene=c('Tcf7','Cxcr5','Bcl6')),\n                data.frame(type='Th1',gene=c('Cxcr6','Ifng','Tbx21')),\n                data.frame(type='Tcmp',gene=c('Ccr7','Bcl2','Tcf7')),\n                data.frame(type='Treg',gene=c('Foxp3','Il2ra')),\n                data.frame(type='Tmem',gene=c('Il7r','Ccr7')),\n                data.frame(type='CD8',gene=c('Cd8a')),\n                data.frame(type='CD4', gene = c(\"Cd4\")),\n                data.frame(type='Cycle',gene=c('Mki67','Top2a','Birc5'))\n)\nsummarize(LCMV1, local = T)\nLCMV1_cluster_names \u003c- get.cluster.names(LCMV1, types, min.fold = 1.0, max.Qval = 0.01)\nLCMV1 \u003c- set.cluster.names(LCMV1, names = LCMV1_cluster_names)\nsummarize(LCMV1, local = T)\n```\n\nFigure 3 shows violin plots indicating the activation of the cell cycle genes. \n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/violin.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 3. Violin plot pf cell cycle score.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nFigure 4 places individual cells on a two dimensional grid corresponding to the scores of the first two PCs (note that the PCA figures are created in the next step via `summarize` function below).\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/PCA.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 4. Single cells placement on a 2D grid corresponding to the first two PCs.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nThe genes driving the PCs are visualized in figure 5 according to the PCA loadings after removing the lowly ranked genes.\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/rotation.png\" width = \"700\"\u003e\n\u003cfigcaption\u003e Fig 5. Top ranked genes contribution to PC1 and PC2 scores.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nThe average expression of genes driving the PCs can be visualized as a heatmap visualized in figure 6 according to the PCA loadings after removing the lowly ranked genes.\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/PC1_heatmap.png\" width=\"700\"\u003e\n\u003cfigcaption\u003e Fig 6. Heatmap shows loadings of the first PC.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nFigure 7 shows the tSNE visualization of the cells, color coded by cluster assignment. \n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/tsne.png\" width=\"700\"\u003e \n\u003cfigcaption\u003e Fig 7. t-SNE plot colored by cluster assignment.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nWe can also visualize the average expression of selected T cells marker genes for initial evaluation (Figure 8).\n\n```{r plotLCMV1}\ncanonical_genes \u003c- c(\"Cd8a\", \"Cd4\", \"Mki67\", \"Foxp3\", \"Il2ra\", \"Bcl6\",\n                     \"Cxcr5\", \"Cxcr6\", \"Ifng\", \"Tbx21\", \"Id2\", \"Rora\",\n                     \"Cxcr3\", \"Tcf7\", \"Ccr7\", \"Cxcr4\", \"Pdcd1\", \"Ctla4\")\nplot_simple_heatmap(LCMV1, name = \"canonical\", markers = canonical_genes, main = \"Expression of marker genes\")\n```\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/diff.genes.png\" width=\"700\"\u003e \n\u003cfigcaption\u003e Fig 8. Heatmap shows row-normalized average expression of selected marker genes per cluster.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\t\nWe repeat the same procedure for `LCMV2` dataset.\n\n```{r LCMV_2}\nLCMV2 \u003c- initialize.project(datasets = \"LCMV2\",\n                          origins = \"CD44+ cells\",\n                          experiments = \"Rep2\",\n                          data.path = file.path(tempdir(), \"LCMV\"),\n                          work.path = file.path(tempdir(), \"LCMV/LCMV_analysis\"))\nLCMV2 \u003c- read.data(LCMV2, subsample = 500)\nLCMV2 \u003c- get.variable.genes(LCMV2)\nLCMV2 \u003c- add.confounder.variables(\n  LCMV2, \n  ribosomal.score = ribosomal.score(LCMV2),\n  mitochondrial.score = mitochondrial.score(LCMV2),\n  cell.cycle.score = cell.cycle.score(LCMV2),\n  Exhaustion = controlled.mean.score(LCMV2, exhaustion_markers))\n\nLCMV2 \u003c- PCA(LCMV2, local = T)\nLCMV2 \u003c- cluster.analysis(LCMV2, local = T)\nsummarize(LCMV2, local = T)\nLCMV2_cluster_names \u003c- get.cluster.names(LCMV2, types, min.fold = 1.0, max.Qval = 0.01)\nLCMV2 \u003c- set.cluster.names(LCMV2, names = LCMV2_cluster_names)\nsummarize(LCMV2, local = T)\nplot_simple_heatmap(LCMV2, name = \"canonical\", markers = canonical_genes, main = \"Expression of marker genes\")\n```\n\n\n## Dataset Integration by Correlation Analysis\n\nWe then initialize the aggregate analysis of the two independent runs, providing the information of which analyses folders should be used to pull the data for integration.\n\n```{r initialize_pooled}\npooled_env \u003c- initialize.project(datasets = c(\"LCMV1\", \"LCMV2\"),\n                          origins = c(\"CD44+ cells\", \"CD44+ cells\"),\n                          experiments = c(\"Rep1\", \"Rep2\"),\n                          data.path = file.path(tempdir(), \"LCMV\"),\n                          work.path = file.path(tempdir(), \"LCMV/LCMV_analysis\"))\npooled_env \u003c- read.preclustered.datasets(pooled_env)\npooled_env \u003c- add.confounder.variables(\n  pooled_env, \n  ribosomal.score = ribosomal.score(pooled_env),\n  mitochondrial.score = mitochondrial.score(pooled_env),\n  cell.cycle.score = cell.cycle.score(pooled_env),\n  Exhaustion = controlled.mean.score(pooled_env, exhaustion_markers))\npooled_env \u003c- PCA(pooled_env, clear.previously.calculated.clustering = F, local = T)\nsummarize(pooled_env, contrast = \"datasets\", local = T)\n```\n\nWe assessed the similarity between pairs of clusters and identify reproducible subpopulations across the two replicates. Figure 9 shows the correlation between clusters' FC vectors across replicates (as described in *Magen et al 2019*).\n\n```{r pooled}\ncluster.similarity \u003c- assess.cluster.similarity(pooled_env)\nsimilarity \u003c- cluster.similarity$similarity\nmap \u003c- cluster.similarity$map\nfiltered.similarity \u003c- get.robust.cluster.similarity(\n  pooled_env, similarity, min.sd = qnorm(.9), max.q.val = 0.01, rerun = F\n  )\nrobust.clusters \u003c- sort(unique(c(filtered.similarity$cluster1,\n                                 filtered.similarity$cluster2)))\nvisualize.cluster.cors.heatmaps(pooled_env, pooled_env$work.path,\n                                filtered.similarity)\n```\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/LCMV1_LCMV2_similarity.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 9. Correlation between clusters' FC vectors across the two replicates.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\nFinally, the cluster similarity between all clusters integrated by this analysis is shown in Figure 10. Unlike the simplified example shown here, this analysis is typically used for estimating subpopulation similarity and divergence across multiple tissue-origins or experimental settings, including corresponding pre-clinical to clinical datasets as described in *Magen et al 2019*.\n\n```{r summary}\nsimilarity \u003c- filtered.similarity\nvisualize.cluster.similarity.stats(pooled_env, similarity)\n```\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/cor_FC.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 10. Correlation among all the clusters in the two datasets.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## Identification and visualization of robust novel marker genes\n\n```{r robust_markers}\ndifferential.expression.statistics = get.robust.markers(\n   pooled_env, cluster_group1 = c('LCMV2_Tfh_CD4', 'LCMV2_Tfh_Tcmp_CD4'),\n   cluster_group2 = c('LCMV2_CD8_1', 'LCMV2_CD8_2'),\n   group1_label = 'CD4 T Cells', group2_label = 'CD8 T Cells')\n```\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/robust.diff.detection.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 11. Scatter plot indicating gene activation across two independent groups of cells. X and Y axis values annotate fractions of cells expressing (\u003e0 UMIs) each gene.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n\nUsing the expression statistics output and the figure (generated to 'robust.diff.exp.pdf') you may identify genes showing exclusive expression in one (or more) selected population (cluster_group1) versus the others (cluster_group2). We can annotate the tSNE with the expression level of selected genes or draw contour plots resembling Flow Cytometric analysis.\n\n```{r tSNE_overlay}\nplot_contour_overlay_tSNE(pooled_env, genes = c('Cd4','Cd8a'))\n```\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/CD4.contour.tSNE.png\" width = \"700\"\u003e \u003cimg src=\"vignettes/figs/CD8.contour.tSNE.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 12. tSNE overlay with contour annotation of normalized expression level of CD4 and CD8a.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n```{r}\nplot_pair_scatter(pooled_env, gene1 = 'Cd4', gene2 = 'Cd8a',\n   cluster_group1 = c('LCMV2_Tfh_CD4', 'LCMV2_Tfh_Tcmp_CD4'),\n   cluster_group2 = c('LCMV2_CD8_1','LCMV2_CD8_2'),\n   group1_label = 'CD4 T Cells', group2_label = 'CD8 T Cells')\n```\n\n\u003cfigure\u003e\n\u003cimg src=\"vignettes/figs/contour.plot.png\" width = \"700\"\u003e \n\u003cfigcaption\u003e Fig 13. Contours of CD4 vs CD8 normalized expression level.\u003c/figcaption\u003e\n\u003c/figure\u003e\n\n\n[^1]: Ciucci, Thomas, et al. \"The Emergence and Functional Fitness of Memory CD4+ T Cells Require the Transcription Factor Thpok.\" _Immunity_ 50.1 (2019): 91-105.\n\n[^2]: [slurm](https://slurm.schedmd.com)\n\n[^3]: Magen *et al*. “Single-cell profiling of tumor-reactive CD4\u003csup\u003e+\u003c/sup\u003e T-cells reveals unexpected transcriptomic diversity” [*bioRxiv 543199*](https://doi.org/10.1101/543199)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasmagen%2Frobustsinglecell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasmagen%2Frobustsinglecell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasmagen%2Frobustsinglecell/lists"}