---
title: "distinct: a method for differential analyses via hierarchical permutation tests"
author:
- name: Simone Tiberi
  affiliation:
  - &IMLS Institute for Molecular Life Sciences, University of Zurich, Switzerland
  - &SIB SIB Swiss Institute of Bioinformatics, University of Zurich, Switzerland
  email: simone.tiberi@uzh.ch
- name: Mark D. Robinson
  affiliation:
  - *IMLS
  - *SIB
package: "`r BiocStyle::pkg_ver('distinct')`"
date: "`r format(Sys.Date(), '%m/%d/%Y')`"
bibliography: References.bib
vignette: >
  %\VignetteIndexEntry{distinct: a method for differential analyses via hierarchical permutation tests}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output: 
  BiocStyle::html_document
---

---

```{r setup, echo=FALSE, results="hide"}
knitr::opts_chunk$set(tidy=FALSE, cache=TRUE,
dev="png",
message=TRUE, error=FALSE, warning=TRUE)
```

# Introduction
*distinct* is a statistical method to perform differential testing between two or more groups of distributions; differential testing is performed via hierarchical non-parametric permutation tests on the cumulative distribution functions (cdfs) of each sample.
While most methods for differential expression target differences in the mean abundance between conditions, *distinct*, by comparing full cdfs, identifies, both, differential patterns involving changes in the mean, as well as more subtle variations that do not involve the mean (e.g., unimodal vs. bi-modal distributions with the same mean).
*distinct* is a general and flexible tool: due to its fully non-parametric nature, which makes no assumptions on how the data was generated, it can be applied to a variety of datasets.
It is particularly suitable to perform differential state analyses on single cell data (e.g., differential analyses within sub-populations of cells), such as single cell RNA sequencing (scRNA-seq) and high-dimensional flow or mass cytometry (HDCyto) data.

At present, covariates are not allowed, and only 2-group comparisons are implemented.
In future releases, we will allow for covariates and for differential testing between more than 2 groups.

A pre-print will follow in the coming months.

To access the R code used in the vignettes, type:
```{r vignettes, eval=FALSE} 
browseVignettes("distinct")
```

Questions relative to *distinct* should be either written to the *[Bioconductor support site](https://support.bioconductor.org)*, tagging the question with "distinct", or reported as a new issue at *[BugReports](https://github.com/SimoneTiberi/distinct/issues)* (preferred choice).

To cite *distinct*, type:
```{r citation, eval=FALSE} 
citation("distinct")
```

## Bioconductor installation
*distinct* is available on [Bioconductor](https://www.bioconductor.org/packages/release/bioc/html/distinct.html) and can be installed with the command:
```{r Bioconductor_installation, eval=FALSE}
if (!requireNamespace("BiocManager", quietly=TRUE))
  install.packages("BiocManager")
BiocManager::install("distinct")
```

## Devel installation from github
To install the package from github, use `devtools` (available [here](https://github.com/hadley/devtools)):
```{r github_installation, eval=FALSE}
devtools::install_github("SimoneTiberi/distinct")
```

To install the package jointly with its vignette remove `--no-build-vignettes` from `build_opts`:
```{r github_installation_2, eval=FALSE}
devtools::install_github("SimoneTiberi/distinct",
                         build_opts = c("--no-resave-data", "--no-manual"))
```

# Differential State analysis
Differential state analyses aim at investigating differential patterns between conditions in sub-populations of cells.
To use *distinct* one needs data from two or more groups of samples (i.e., experimental conditions), with at least 2 samples (i.e., biological replicates) per group.
Given a single-cell RNA-sequencing (scRNA-seq) or a high dimensional flow or mass cytometry (HDCyto) dataset, cells need first to be clustered in groups via some form of clustering algorithms; *distinct* is then applied to identify differential patterns between groups, within each cluster of cells.

## Input data
Load the example dataset, consisting of a subset of 6 samples (3 individuals observed across 2 conditions) and 100 genes selected from the `Kang18_8vs8()` object of the *muscData* package.
```{r load-example-data, message = FALSE}
data("Kang_subset", package = "distinct")
Kang_subset
```

Columns `ind` and `stim` of the `colData` indicate the indivual id and the experimental condition (control or stimulated) of each cell, while column `sample_id` shows the sample id, needed for the differential anlyses.
Column `cell` represents the cell type, which defines the clustering structure of cells: differential testing between conditions is performed separately for each cluster of cells.
Note that, if cell clustering label was unknown, we would need to cluster cells into groups via some clustering algorithm.
```{r visualize colData}
colData(Kang_subset)
```

The experimental design compares two groups (stim vs ctrl) with 3 biological replicates each.
```{r visualize experimental design}
metadata(Kang_subset)$experiment_info
```

Visually inspect the data, via tSNE plots, coloured by cell-type.
```{r t-SNE plot, message = FALSE}
library(scater)
plotTSNE(Kang_subset, colour_by = "cell")
```

## Differential analyses within sub-populations of cells
Load *distinct*.
```{r load_distinct, message=FALSE}
library(distinct)
```

Perform differential state testing between conditions.
Parameter `name_assays_expression` specifies the input data (counts) in `assays(x)`, while `name_cluster`, `name_group`, `name_sample` define the column names of `colData(x)` containing the clustering of cells (cell), the grouping of samples (stim) and the id of individual samples (sample_id).
As today *distinct* does not accept sparce matrices:
```{r differential-analyses}
set.seed(61217)
res = distinct_test(
  x = Kang_subset, 
  name_assays_expression = "counts",
  name_cluster = "cell",
  name_group = "stim",
  name_sample = "sample_id",
  P = 10^3, 
  min_non_zero_cells = 20)
```

Results are reported as a `data.frame`, where columns `gene` and `cluster_id` contain the gene and cell-cluster name, while `p_val`, `p_adj.loc` and `p_adj.glb` report the raw p-values, locally and globally adjusted p-values, via Benjamini and Hochberg (BH) correction.
In locally adjusted p-values (`p_adj.loc`) BH correction is applied in each cluster separately, while in globally adjusted p-values (`p_adj.glb`) BH correction is performed to the results from all clusters.
```{r visualize-results}
head(res)
```

## Visualizing results:
Visualize the concordance of differential results between cell clusters.
We select as significant genes with globally adjusted p-value below 0.01.
```{r UpsetR plot}
library(UpSetR)
res_by_cluster = split( ifelse(res$p_adj.glb < 0.01, 1, 0), res$cluster_id)
upset(data.frame(do.call(cbind, res_by_cluster)))
```

Violin plots of significant genes in `Dendritic cells` cluster.
```{r plotExpression}
# select cluster of cells:
cluster = "Dendritic cells"
sel_cluster = res$cluster_id == cluster
sel_column = Kang_subset$cell == cluster

# select significant genes:
sel_genes = res$p_adj.glb < 0.01
genes = as.character(res$gene[sel_cluster & sel_genes])

# make violin plots:
library(scater)
plotExpression(Kang_subset[,sel_column],
                     features = genes, exprs_values = "logcounts",
                     log2_values = FALSE,
                     x = "sample_id", colour_by = "stim", ncol = 3) +
        guides(fill = guide_legend(override.aes = list(size = 5, alpha = 1))) +
        theme(axis.text.x = element_text(angle = 45, hjust = 1))
```

# Session info
```{r sessionInfo}
sessionInfo()
```
