---
title: "Introduction to clustermole"
subtitle: "blindly digging for cell types in scRNA-seq clusters"
output:
  prettydoc::html_pretty:
    keep_md: true
    toc: true
    theme: hpstr
    highlight: github
    mathjax: null
    self_contained: true
vignette: >
  %\VignetteIndexEntry{Introduction to clustermole}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{css, echo=FALSE}
.header-title h2 {
  text-transform: none;
  font-style: italic;
  font-size: 1.2rem;
}
```

## Overview

A typical computational pipeline to process single-cell RNA sequencing (scRNA-seq) data includes clustering of cells as one of the steps. Assignment of cell type labels to those clusters is often a time-consuming process that involves manual inspection of the cluster marker genes complemented with a detailed literature search. This is especially challenging when unexpected or poorly described populations are present. The clustermole R package provides methods to query thousands of human and mouse cell identity markers sourced from a variety of databases.

The clustermole package provides three primary features:

* cell type prediction based on marker genes (`clustermole_overlaps`)
* cell type prediction based on a full expression matrix (`clustermole_enrichment`)
* a database of cell type markers (`clustermole_markers`)

## Usage

Install clustermole if it is not yet available on your system.

```{r install-package, eval=FALSE}
install.packages("clustermole")
```

Load clustermole.

```{r load-package, message=FALSE}
library(clustermole)
```

### `clustermole_overlaps()`: cell type prediction based on marker genes

If you have a set of genes, such as cluster markers, you can compare them to known cell type markers to see if they overlap any of the known cell type markers (overrepresentation analysis).

```{r overlaps}
my_genes = c("CD2", "CD3D", "CD3E", "IL7R", "IL32", "LTB", "LDHB", "CCR7")
my_overlaps = clustermole_overlaps(genes = my_genes, species = "hs")
my_overlaps
```

### `clustermole_enrichment()`: cell type enrichment in the full expression matrix

If you have a table of expression values, such as average expression across clusters, you can perform cell type enrichment based on a given gene expression matrix (log-transformed CPM/TPM/FPKM values). Genes are rows and clusters/samples are columns.

```{r enrichment, eval=FALSE}
clustermole_enrichment(expr_mat = my_expr_mat, species = "hs")
```

### `clustermole_markers()`: retrieve cell type markers

You can use `clustermole` as a simple database and get a data frame of all cell type markers.

```{r markers}
markers = clustermole_markers(species = "hs")
markers
```

Each row contains a gene and a cell type associated with it. The `gene` column is the gene symbol (human or mouse versions can be retrieved) and the `celltype_full` column contains the full cell type string, including the species and the original database.

If you need to convert the markers from a data frame to a list format for other applications, you can use `gene` as the values and `celltype_full` as the grouping variable.

```{r celltypes-list}
markers_list = split(x = markers$gene, f = markers$celltype_full)
```

## Database details

We will load dplyr to help with the summary statistics.

```{r load-dplyr, message=FALSE}
library(dplyr)
```

You can use `clustermole_markers()` to retrieve a data frame of all cell type markers in the collection.

```{r get-markers}
markers = clustermole_markers(species = "hs")
markers
```

Check the number of available cell types.

```{r celltypes-length}
markers %>% distinct(celltype_full) %>% nrow()
```

Check the number of available cell types per species (not available for every cell type).

```{r count-species}
markers %>% distinct(celltype_full, species) %>% count(species, sort = TRUE)
```

Check the number of available cell types per organ (not available for every cell type).

```{r count-organ}
markers %>% distinct(celltype_full, organ) %>% count(organ, sort = TRUE)
```

Check package version.

```{r package-version}
packageVersion("clustermole")
```

