---
title: "Visualize data sets and clustering results with `iSEE`"
author: 
- name: Angelo Duò
- name: Mark D Robinson
- name: Charlotte Soneson
date: "`r Sys.Date()`"
package: DuoClustering2018
output:
  BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Visualize data sets and clustering results with iSEE}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: duoclustering2018.bib
editor_options: 
  chunk_output_type: console
---

# Introduction

In this vignette we describe how to generate a `SingleCellExperiment` object
combining observed values and clustering results for a data set from the
`DuoClustering2018` package, and how the resulting object can be explored and
visualized with the `iSEE` package [@Rue-Albrecht2018-wz].

# Load the necessary packages

```{r}
suppressPackageStartupMessages({
  library(SingleCellExperiment)
  library(DuoClustering2018)
  library(dplyr)
  library(tidyr)
})
```

# Retrieve a data set

The different ways of retrieving a data set from the package are described in
the `plot_performance` vignette. Here, we will load a data set using the
shortcut function provided in the package.

```{r}
dat <- sce_filteredExpr10_Koh()
```

# Read a set of clustering results

For this data set, we also load a set of clustering results obtained using
different clustering methods.

```{r}
res <- clustering_summary_filteredExpr10_Koh_v2()
```

# Merge data and clustering results

We add the cluster labels for one run and for a set of different imposed number
of clusters to the data set.

```{r}
res <- res %>% dplyr::filter(run == 1 & k %in% c(3, 5, 9)) %>%
  dplyr::group_by(method, k) %>% 
  dplyr::filter(is.na(resolution) | resolution == resolution[1]) %>%
  dplyr::ungroup() %>% 
  tidyr::unite(col = method_k, method, k, sep = "_", remove = TRUE) %>% 
  dplyr::select(cell, method_k, cluster) %>%
  tidyr::spread(key = method_k, value = cluster)

colData(dat) <- DataFrame(
  as.data.frame(colData(dat)) %>%
    dplyr::left_join(res, by = c("Run" = "cell"))
)
head(colData(dat))
```

# Visualize with `iSEE`

The resulting `SingleCellExperiment` can be interactively explored using, e.g.,
the `iSEE` package. This can be useful to gain additional understanding of the
partitions inferred by the different clustering methods, to visualize these in
low-dimensional representations (PCA or t-SNE), and to investigate how well they
agree with known or inferred groupings of the cells.

```{r, eval=FALSE}
if (require(iSEE)) {
  iSEE(dat)
}
```

# Session info

```{r}
sessionInfo()
```

# References