single cell Mapper (scMappR)

Dustin Sokolowski


Install and load scMappR

Currently, there is only a development version. scMappR relies on the following dependencies which should be downloaded/updated with scMappR automatically. Please ensure that these packages are not open when installing scMappR.

Install GSVA and pcaMethods from bioconductor first, as devtools::install_githb() will automatically install CRAN.

  1. Github (Development Version)
if (!requireNamespace("BiocManager", quietly = TRUE))
if (!requireNamespace("devtools", quietly = TRUE))


  1. CRAN (Stable Release) – Currently not available
if (!requireNamespace("BiocManager", quietly = TRUE))
if (!requireNamespace("devtools", quietly = TRUE))



Downloading Files.

Before using scMappR, we strongly recommend that you download data files from “”. As a default, it is assumed that these rda files have been downloaded and stored in ~/scMappR/data. These data files can be downloaded anywhere as long as the ‘rda_data’ parameter is changed to this directory when using scMappR. When data are not downloaded, the Downloader R package will temporarily download data files they are required within functions. Naturally, stable internet is required for this.

Printing results.

Many of the functions in scMappR print files or even generate directories. To return the full output of scMappR, please change the ‘toSave’ parameters from FALSE to TRUE in any of the functions being used. Otherwise, the functions in scMappR will only return a small portion of what scMappR has to offer. Due to CRAN packages not allowing for their packages to print files/make directories, toSave is set to FALSE as default.

When toSave == TRUE, it is also required to set the directory where files can be saved. In this vignette, it is assumed that there is a directory called vignette_dir in the working directory. To change the directory where files are saved, change the path argument. This vignette sets path to tempdir(). When using scMappR, change tempdir() to the directories where files should be saved.

Introduction of the primary functionalists highlighted in the vignette.

Cell-type markers in a list of genes.

Given a tissue and an unranked list of genes (i.e. without a count matrix or summary statistics), the tissue_scMappR_custom() and tissue_scMappR_internal() functions visualizes cell-type markers contained within the gene-list and tests for the enrichment of cell-types within that tissue. When there is no custom signature matrix, providing a tissue present in “” will complete cell-type specific gene visualization and enrichment for every signature matrix in the tissue.

No custom signature matrix:


This function returns a list “internal”. Using the example of internal[[4]], the prophetic area of the hypothalamus, you can see four objects.

  • genesIn: genes in the signature matrix is tested.
  • genesNoIn: genes not in the signature matrix (empty).
  • geneHeat: Gene x cell-type matrix containing the cell-type rank of each gene in the signature matrix.
  • preferences: Cell-type marker genes sorted into each cell-type.
  • genesIn: Inputted genes that are also in the signature matrix.
  • genesNoIn: Inputted genes not in the signature matrix.
  • geneHeat: Gene x cell-type matrix containing the cell-type rank for inputted genes overlaying with genes in the signature matrix.
  • preferences: Inputted genes overlaying with signature matrix sorted into the cell-types where they’re preferentially expressed.
  • Output of the Fisher’s exact test for cell-type enrichment of inputted genes with every cell-type.
  • Identification and statistical enrichment of groups of cell-types containing the same cell-type marker genes.

Saved directory

When toSave == TRUE, a directory is generated with visualization of each signature matrix, the signature matrix subsetted by input genes, and statistical enrichment.

Custom signature matrix

tissue_scMappR_custom() assumes a custom signature matrix, or an inputted gene x cell-type matrix that is filled with the cell-type preferences of each gene (Rank is recommended but any value will suffice). If the value filling the matrix is not rank, you will need to change the gene_cutoff from 1 to whatever cutoff you need. Furthermore, if is_pvalue == TRUE, tissue_scMappR_custom() will transform the p-values into ranks rank := -1log10(Padj)*sign(FC). We strongly recommend that you generate these ranks before using tissue_scMappR_custom(); however, we assume that all fold changes are positive and therefore sign(FC) = 1.


The output is identical to that found in tissue_scMappR_internal() but with only one study, or the example shown above.

If you choose to set toSave = TRUE. This function will return a directory with a number of relevant files.

Saved Outputs

Saved directory

When toSave == TRUE, a directory is generated with visualization of each signature matrix, the signature matrix subsetted by input genes, and statistical enrichment.

cell-weighted Fold Changes (cwFold-changes) Generation

The scMappR_and_pathway_analysis() function generates cellWeighted_Foldchanges based on an inputted signature matrix, normalized RNA-seq count matrix, and list of differentially-expressed genes (DEGs) before creating cell-weighted Fold Changes (cwFold-changes) (cellWeighted_Foldchanges), visualizing these cellWeighted_Foldchange’s against the cell-type preferences of these DEGs, that are also cell-type markers, visualizing cellWeighted_Foldchange’s regardless of if the cellWeighted_Foldchange is cell-type markers, and if allowed, pathway enrichment of DEGs re-ranked by cell-type.   The example below has toSave = FALSE, up_and_downregulated = FALSE and internet = FALSE. When running scMappR yourself, it is strongly recommended to set all to TRUE. toSave = TRUE allows for the printing of folders, images, and files onto a desktop/cluster. up_and_downregulated = TRUE repeats pathway analysis for up and down-regulated genes separately. internet = TRUE allows for the completion of pathway analysis altogether. Tissue-types are available in data(scMappR_tissues), and the signature matrices themselves from



Saved outputs

Assuming toSave = T and up_and_downregulated = T, scMappR_and_pathway_analysis() will also generate a folder in your current directory with a considerable amount of data/figures.

Here, we will walk through the output of the above example sorting by name and working downwards. * scMappR_vignette_celltype_specific_cellWeighted_Foldchangess_upregulated_heatmap.pdf: Row-normalized cellWeighted_Foldchanges of upregulated genes that are also cell-type specific (in the signature matrix). * scMappR_vignette_celltype_specific_cellWeighted_Foldchangess_downregulated_heatmap.pdf: Row-normalized cellWeighted_Foldchanges of downregulated genes that are also cell-type specific (in the signature matrix). * scMappR_vignette__cellWeighted_Foldchangess_upregulated_DEGs_heatmap.pdf: row-normalized cellWeighted_Foldchanges of upregulated genes. * scMappR_vignette__cellWeighted_Foldchangess_downregulated_DEGs_heatmap.pdf: row-normalized cellWeighted_Foldchanges of downregulated genes. * scMappR_vignette_reordered_transcription_factors.Rdata: .Rdata file containing a list of outputs from gprofiler or gprofiler2 that are transcription factors enriched after re-ordering. * scMappR_vignette_reordered_pathways: .Rdata file containing list of outputs from gprofileR or gprofiler2 that are “GOBP”, “REAC”, and “KEGG” enrichments after re-ordering. * scMappR_vignette_leaveOneOut_gene_proportions.RData: Average cell-type proportion when gene is removed. * scMappR_vignette_celltype_specific_preferences_upregulated_DEGs_heatmap.pdf: Row-normalized .pdf of signature matrix intersecting with upregulated DEGs. * scMappR_vignette_celltype_specific_preferences_downregulated_DEGs_heatmap.pdf: Row-normalized .pdf of signature matrix intersecting with downregulated DEGs.
* scMappR_vignette_celltype_proportions.Rdata: Data matrix of cell-type proportions for each sample. * scMappR_vignette_cell_proportions_heatmap.pdf: Row-normalized heatmap of cell-type proportions. * scMappR_vignette_cell_proportion_changes_summary.tsv: Table of t-tests to interrogate differences in cell-type proportions. * scMappR_vignette_bulk_transcription_factors.Rdata: gprofiler enrichment of bulk transcription factors. * scMappR_vignette_bulk_pathways.Rdata: gprofiler enrichment of bulk GOBP, REAC, and KEGG. * scMappR_vignette_all_CT_markers_in_background.pdf: Signature matrix of all genes in the background. * Bulk_TF_enrichment.pdf: Barplot of bulk transcription factor enrichment. * Bulk_pathway_enrichment.pdf: Barplot of bulk pathway enrichment. * upregulated: Directory with the same pathway analysis specifically for upregulated genes. * downregulated: Directory with the same pathway analysis specifically for downregulated genes. * TF_barplot: Directory with .pdfs of re-ranked TF enrichment. * BP_barplot: Directory with .pdfs of re-ranked GOBP, KEGG, and REAC enrichment.

Tissue by cell-type enrichment.

scMappR allows for gene-set enrichment of every cell-type marker, sorted by cell-type, tissue, and study, curated while preprocessing all of the signature matrices for the functions within scMappR. The dataset may be downloaded from, processed into a gmt file using a number of packages (qusage, activepathways etc.) and then used with traditional gene-set-enrichment tools (GSEA, GSVA, gprofiler). Additionally, scMappR contains the “tissue_by_celltype_enrichment.R” function, that enriches a gene list against all cell-type markers using a Fisher’s exact test.


Here, we will investigate the tissue x cell-type enrichment of the top 100 genes in the Preoptic area signature matrix. #### NOTE: Fix dimensions of plot or don’t plot it at all.

Three types of outputs.

Processing scRNA-seq count data into a signature matrix.

scMappR inputs a list of count matrices (of class list, dCGMatrix, or matrix) and re-processes it using the standard Seurat V3 vignette (+ removal of cells with > 2 standard deviations of mt contamination than mean). Then, it finds cell-type markers and identifies potential cell-type names using the GSVA and fisher’s exact methods on the CellMarker and Panglao databases. Finally, it creates a signature matrix of odds ratios and ranks. There are options to save the Seurat object, gsva cell-type identities and list of cell-type markers. To identify what naming-preferences options are available, download and load


toProcess <- list(example = sm)

tst1 <- process_dgTMatrix_lists(toProcess, name = "testPropcess", species_name = -9,
naming_preference = "eye", rda_path = "", 
toSave = TRUE, saveSCObject = TRUE, path = tempdir())

It is recommended to set toSave == TRUE, allowing for important data objects to be saved. Here, the above function is repeated with toSave == TRUE and saveSCObject == TRUE, and the outputted files will be briefly discussed.

Here, the following objects are saved.

Processing scRNA-seq count data when cell-types are already named.

It may be common to generate a signature matrix when clusters and cell-types have already been given for every cell. These examples follow how to make this signature matrix from:

  1. A Seurat object with named cell-types
  2. A Count matrix with named cell-types.

Signature matrix from Seurat object with named cell-type

Generating the Seurat Object for example and making up cell-types. This example will be used from 1-2.

  1. A Seurat object with named cell-types. Markers for each cell-type are stored in the generes object and each signature matrix is in gene_out.
  1. A count matrix with named cell-types.

Manually making graphics.

scMappR generates heatmaps and barplots. The barplots are generated with plotBP and make_TF_barplot. The plotting code for plotBP is provided. Inputs are a matrix called ordered_back_all of -log10(padj) and term names with the column names log10 and term_name respectively.



Here, the heatmaps are for plotting cwFold-changes and cell-type proportions. The same heatmap is used so just an example of one is given.