---
title: "Introduction to SCONE"
author: "Michael Cole and Davide Risso"
date: "`r Sys.Date()`"
bibliography: bibFile.bib
output:
  BiocStyle::html_document:
    toc: true
vignette: >
  %\VignetteEncoding{UTF-8}
---

<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{Introduction to SCONE}
-->

```{r options, include=FALSE, cache=FALSE, results='hide', message=FALSE}

knitr::opts_chunk$set(fig.align="center", cache=FALSE,error=FALSE,
                      fig.width=6,fig.height=6,autodep=TRUE,
                      out.width="600px", out.height="600px",
                      results="markup", echo=TRUE, eval=TRUE)

options(getClass.msg=FALSE)

set.seed(6473) ## for reproducibility

library(scone)
library(RColorBrewer)

```

# Introduction

Single-cell RNA sequencing (scRNA-Seq) technologies are opening the way for
transcriptome-wide profiling across diverse and complex mammalian tissues,
facilitating unbiased identification of novel cell sub-populations and
discovery of novel cellular function. As in other high-throughput analyses, a
large fraction of the variability observed in scRNA-Seq data results from batch
effects and other technical artifacts [@hicks2015]. In particular, a unique
reliance on minuscule amounts of starting mRNA can lead to widespread “drop-out
effects,” in which expressed transcripts are missed during library preparation
and sequencing. Due to the biases inherent to these assays, data normalization
is an essential step prior to many downstream analyses. As we face a growing
cohort of scRNA-Seq technologies, diverse biological contexts, and novel
experimental designs, we cannot reasonably expect to find a one-size-fits-all
solution to data normalization.

`scone` supports a rational, data-driven framework for assessing the efficacy
of various normalization workflows, encouraging users to explore trade-offs
inherent to their data prior to finalizing their data normalization strategy.
We provide an interface for running multiple normalization workflows in
parallel, and we offer tools for ranking workflows and visualizing
study-specific trade-offs.

This package was originally developed to address normalization problems
specific to scRNA-Seq expression data, but it should be emphasized that its use
is not limited to scRNA-Seq data normalization. Analyses based on other
high-dimensional data sets - including bulk RNA-Seq data sets - can utilize
tools implemented in the `scone` package.

## Human Neurogenesis

We will demonstrate the basic `scone` workflow by using an early scRNA-Seq data
set [@pollen2014]. We focus on a set of 65 human cells sampled from four
biological conditions: Cultured neural progenitor cells ("NPC") derived from
pluripotent stem cells, primary cortical samples at gestation weeks 16 and 21
("GW16" and "GW21" respectively) and late cortical samples cultured for 3 weeks
("GW21+3"). Gene-level expression data for these cells can be loaded directly
from the `scRNAseq` package on 
[Bioconductor](http://bioconductor.org/packages/scRNAseq/).

```{r datain, message=FALSE}

library(scRNAseq)

## ----- Load Example Data -----
fluidigm <- ReprocessedFluidigmData(assays = "rsem_counts")
assay(fluidigm) <- as.matrix(assay(fluidigm))
```

The `rsem_counts` assay contains expected gene-level read counts via RSEM
[@li2011] quantification of 130 single-cell libraries aligned to the hg38
RefSeq transcriptome. The data object also contains library transcriptome
alignment metrics obtained from
[Picard](http://broadinstitute.github.io/picard/) and other basic tools.

```{r showqc}

## ----- List all QC fields -----

# List all qc fields (accessible via colData())
metadata(fluidigm)$which_qc

```

All cell-level metadata, such as cell origin and sequence coverage ("low" vs
"high" coverage) can be accessed using `colData()`:

```{r biocoverage}

# Joint distribution of "biological condition"" and "coverage type""
table(colData(fluidigm)$Coverage_Type,
      colData(fluidigm)$Biological_Condition)

```

Each cell had been sequenced twice, at different levels of coverage. In this
vignette we will focus on the high-coverage data. Before we get started we will
do some preliminary filtering to remove the low-coverage replicates and
undetected gene features:

```{r prefilter}

# Preliminary Sample Filtering: High-Coverage Only
is_select = colData(fluidigm)$Coverage_Type == "High"
fluidigm = fluidigm[,is_select]

# Retain only detected transcripts
fluidigm = fluidigm[which(apply(assay(fluidigm) > 0,1,any)),]

```

## Visualizing Technical Variability and Batch Effects

One of our alignment quality readouts is the fraction of reads aligned to the
transcriptome. We can use simple bar plots to visualize how this metric relates
to the biological batch.

```{r ralign}

# Define a color scheme
cc <- c(brewer.pal(9, "Set1"))

# One batch per Biological Condition
batch = factor(colData(fluidigm)$Biological_Condition)

# Alignment Quality Metrics
qc = colData(fluidigm)[,metadata(fluidigm)$which_qc]

# Barplot of read proportion mapping to human transcriptome
ralign = qc$RALIGN
o = order(ralign)[order(batch[order(ralign)])] # Order by batch, then value

barplot(ralign[o], col=cc[batch][o], 
        border=cc[batch][o], main="Percentage of reads mapped")
legend("bottomleft", legend=levels(batch), fill=cc,cex=0.4)

```

We can see modest differences between batches, and we see that there is one
GW21 cell with a particularly low alignment rate relative to the rest of the
GW21 batch. These types of observations can inform us of "poor-quality"
libraries or batches. We may alternatively consider the number of reads for
each library:

```{r nreads}

# Barplot of total read number
nreads = qc$NREADS
o = order(nreads)[order(batch[order(nreads)])] # Order by batch, then value

barplot(nreads[o], col=cc[batch][o], 
        border=cc[batch][o], main="Total number of reads")
legend("topright", legend=levels(batch), fill=cc, cex=0.4)

```

We see that read coverage varies substantially between batches as well as
within batches. These coverage differences and other technical features can
induce non-intuitive biases upon expression estimates. Though some biases can
be addressed with simple library-size normalization and cell-filtering, demand
for greater cell numbers may require more sophisticated normalization methods
in order to compare multiple batches of cells. Batch-specific biases are
impossible to address directly in this study as biological origin and sample
preparation are completely confounded.

While it can be very helpful to visualize distributions of single quality
metrics it should be noted that QC metrics are often correlated. In some cases
it may be more useful to consider Principal Components (PCs) of the quality
matrix, identifying latent factors of protocol variation:

```{r qpc}

## ----- PCA of QC matrix -----
qpc = prcomp(qc,center = TRUE,scale. = TRUE)
barplot((qpc$sdev^2)/sum(qpc$sdev^2), border="gray", 
        xlab="PC", ylab="Proportion of Variance", main="Quality PCA")

```

Even though 19 different QC metrics have been quantified in this analysis, PCA
shows us that only a small number of PCs are needed to described a majority of
the QC variance (e.g. 3 to explain 76%). We will now visualize the distribution
of the first PC in the context of batch:

```{r qpc_view}

# Barplot of PC1 of the QC matrix
qc1 = as.vector(qpc$x[,1])
o = order(qc1)[order(batch[order(qc1)])]

barplot(qc1[o], col=cc[batch][o], 
        border=cc[batch][o], main="Quality PC1")
legend("bottomright", legend=levels(batch), 
       fill=cc, cex=0.8)

```

This first PC appears to represent both inter-batch and intra-batch sample
heterogeneity, similar the the total number of reads. If this latent factor
reflects variation in sample preparation, we may expect expression artifacts to
trace this factor as well: in other words, we should be very skeptical of genes
for which expression correlates strongly with the first PC of quality metrics.
In this vignette we will show how latent factors like this can be applied to
the normalization problem.

## Drop-out Characteristics

Before we move on to normalization, let's briefly consider a uniquely
single-cell problem: "drop-outs." One of the greatest challenges in modeling
drop-out effects is modeling both i) technical drop-outs and ii) biological
expression heterogeneity. One way to simplify the problem is to focus on genes
for which we have strong prior belief in true expression. The `scone` package
contains lists of genes that are believed to be ubiquitously and even uniformly
expressed across human tissues. If we assume these genes are truly expressed in
all cells, we can label all zero abundance observations as drop-out events. We
model detection failures as a logistic function of mean expression, in line
with the standard logistic model for drop-outs employed by the field:

```{r fnr_fit}

# Extract Housekeeping Genes
data(housekeeping)
hk = intersect(housekeeping$V1,rownames(assay(fluidigm)))

# Mean log10(x+1) expression
mu_obs = rowMeans(log10(assay(fluidigm)[hk,]+1))

# Assumed False Negatives
drop_outs = assay(fluidigm)[hk,] == 0

# Logistic Regression Model of Failure
ref.glms = list()
for (si in 1:dim(drop_outs)[2]){
  fit = glm(cbind(drop_outs[,si],1 - drop_outs[,si]) ~ mu_obs,
            family=binomial(logit))
  ref.glms[[si]] = fit$coefficients
}

```

The list `ref.glm` contains the intercept and slope of each fit. We can now
visualize the fit curves and the corresponding Area Under the Curves (AUCs):

```{r fnr_vis,fig.width=8,fig.height=4,out.width="800px",out.height="400px"}

par(mfrow=c(1,2))

# Plot Failure Curves and Calculate AUC
plot(NULL, main = "False Negative Rate Curves",
     ylim = c(0,1),xlim = c(0,6), 
     ylab = "Failure Probability", xlab = "Mean log10 Expression")
x = (0:60)/10
AUC = NULL
for(si in 1:ncol(assay(fluidigm))){
  y = 1/(exp(-ref.glms[[si]][1] - ref.glms[[si]][2] * x) + 1)
  AUC[si] = sum(y)/10
  lines(x, 1/(exp(-ref.glms[[si]][1] - ref.glms[[si]][2] * x) + 1),
        type = 'l', lwd = 2, col = cc[batch][si])
}

# Barplot of FNR AUC
o = order(AUC)[order(batch[order(AUC)])]

barplot(AUC[o], col=cc[batch][o], border=cc[batch][o], main="FNR AUC")
legend("topright", legend=levels(batch), fill=cc, cex=0.4)

```

Model-based metrics such as these may be more interpretable with respect to
upstream sample preparation, and can be very useful for assessing single-cell
library quality.

## The `scone` Workflow

So far we have only described potential problems with single-cell expression
data. Now we will take steps to address problems with our example data set. The
basic QC and normalization pipeline we will use in this vignette allows us to:

* Filter out poor libraries using the `metric_sample_filter` function.
* Run and score many different normalization workflows 
  (different combinations of normalization modules)
  using the main `scone` function.
* Browse top-ranked methods and visualize trade-offs with the
  `biplot_color` and `sconeReport` function.

In order to run many different workflows, SCONE relies on a normalization
workflow template composed of 3 modules:

1) Data imputation: replacing zero-abundance values with expected values under
a prior drop-out model. As we will see below, this module may be used as a
modifier for module 2, without passing imputed values forward to downstream
analyses. 2) Scaling or quantile normalization: either i) normalization that
scales each sample's transcriptome abundances by a single factor or ii) more
complex offsets that match quantiles across samples. Examples: TMM or DESeq
scaling factors, upper quartile normalization, or full-quantile normalization.
3) Regression-based approaches for removing unwanted correlated variation from
the data, including batch effects. Examples: RUVg [@risso2014] or regression on
Quality Principal Components described above.

# Sample Filtering with `metric_sample_filter`

The most basic sample filtering function in `scone` is the
`metric_sample_filter`. The function takes a consensus approach, retaining
samples that pass multiple data-driven criteria.

`metric_sample_filter` takes as input an expression matrix. The output depends
on arguments provided, but generally consists of a list of 4 logicals
designating each sample as having failed (TRUE) or passed (FALSE)
threshold-based filters on 4 sample metrics:

* Number of reads.
* Ratio of reads aligned to the genome. 
  Requires the `ralign` argument.
* "Transcriptome breadth" - Defined here as the proportion of "high-quality"
  genes detected in the sample. Requires the `gene_filter` argument.
* FNR AUC. Requires the `pos_controls` argument.

If required arguments are missing for any of the 4, the function will simply
return NA instead of the corresponding logical.

```{r metric_sample_filter, fig.height= 10,out.height="1000px"}

# Initial Gene Filtering: 
# Select "common" transcripts based on proportional criteria.
num_reads = quantile(assay(fluidigm)[assay(fluidigm) > 0])[4]
num_cells = 0.25*ncol(fluidigm)
is_common = rowSums(assay(fluidigm) >= num_reads ) >= num_cells

# Metric-based Filtering
mfilt = metric_sample_filter(assay(fluidigm),
                             nreads = colData(fluidigm)$NREADS,
                             ralign = colData(fluidigm)$RALIGN,
                             gene_filter = is_common,
                             pos_controls = rownames(fluidigm) %in% hk,

                             zcut = 3, mixture = FALSE,
                             plot = TRUE)

# Simplify to a single logical
mfilt = !apply(simplify2array(mfilt[!is.na(mfilt)]),1,any)

```

In the call above, we have set the following parameters:

* zcut = 3. Filter leniency (see below).
* mixture = FALSE. Mixture modeling will not be used (see below).
* plot = TRUE. Plot distributions of metrics before and after filtering.

## On Threshold Selection

Let's take a closer look at the computation behind selecting the ralign filter.
In choosing a threshold value 67.7, `metric_sample_filter` is taking 4 values
into account:

1) `hard_ralign`, the default "hard" threshold at 15 - rather forgiving... 2) 3
(`zcut`) times the standard deviation below the mean `ralign` value. 3) 3
(`zcut`) times the MAD below the median `ralign` value. 4) `suff_ralign`, the
sufficient threshold set to NULL by default.

```{r thresh,fig.width= 6, fig.height= 4, out.width="600px",out.height="400px"}

hist(qc$RALIGN, breaks = 0:100)
# Hard threshold
abline(v = 15, col = "yellow", lwd = 2)
# 3 (zcut) standard deviations below the mean ralign value
abline(v = mean(qc$RALIGN) - 3*sd(qc$RALIGN), col = "green", lwd = 2)
# 3 (zcut) MADs below the median ralign value
abline(v = median(qc$RALIGN) - 3*mad(qc$RALIGN), col = "red", lwd = 2)
# Sufficient threshold
abline(v = NULL, col = "grey", lwd = 2)

# Final threshold is the minimum of 
# 1) the sufficient threshold and 
# 2) the max of all others
thresh = min(NULL,
             max(c(15,mean(qc$RALIGN) - 3*sd(qc$RALIGN),
                   median(qc$RALIGN) - 3*mad(qc$RALIGN))))
abline(v = thresh, col = "blue", lwd = 2, lty = 2)

legend("topleft",legend = c("Hard","SD","MAD","Sufficient","Final"),
       lwd = 2, col = c("yellow","green","red","grey","blue"),
       lty = c(1,1,1,1,2), cex = .5)

```

We see here that the 3rd "MAD" threshold exceeds the first two thresholds
("Hard" and "SD"), and as the "Sufficient" threshold is NULL
`metric_sample_filter` settles for the the third threshold. If the "Sufficient"
threshold was not NULL and was exceeded by any of the other three thresholds
("Hard","SD","MAD"), `metric_sample_filter` would settle for the "Sufficient"
threshold. Note also that if `mixture=TRUE` an additional criterion is
considered: distributions may be fit to a two-component mixture model, and a
threshold is defined with respect to the mean and standard deviation of the
"best" component.

As `metric_sample_filter` relies on a maximum of candidate thresholds, we
recommend users treat this function as a stringent sample filter.

## Applying the sample filter

With the `metric_sample_filter` output in hand, it is fairly straightforward to
remove the one "poor" sample from our study:

```{r filterCount}

goodDat = fluidigm[,mfilt]

# Final Gene Filtering: Highly expressed in at least 5 cells
num_reads = quantile(assay(fluidigm)[assay(fluidigm) > 0])[4]
num_cells = 5
is_quality = rowSums(assay(fluidigm) >= num_reads ) >= num_cells


```

# Running and Scoring Normalization Workflows with `scone`

Not only does `scone` normalize expression data, but it also provides a
framework for evaluating the performance of normalization workflows.

## Creating a SconeExperiment Object

Prior to running main `scone` function we will want to define a
`SconeExperiment` object that contains the primary expression data,
experimental metadata, and control gene sets.

```{r scone_init}


# Expression Data (Required)
expr = assay(goodDat)[is_quality,]

# Biological Origin - Variation to be preserved (Optional)
bio = factor(colData(goodDat)$Biological_Condition)

# Processed Alignment Metrics - Variation to be removed (Optional)
qc = colData(goodDat)[,metadata(goodDat)$which_qc]
ppq = scale(qc[,apply(qc,2,sd) > 0],center = TRUE,scale = TRUE)

# Positive Control Genes - Prior knowledge of DE (Optional)
poscon = intersect(rownames(expr),strsplit(paste0("ALS2, CDK5R1, CYFIP1,",
                                                  " DPYSL5, FEZ1, FEZ2, ",
                                                  "MAPT, MDGA1, NRCAM, ",
                                                  "NRP1, NRXN1, OPHN1, ",
                                                  "OTX2, PARD6B, PPT1, ",
                                                  "ROBO1, ROBO2, RTN1, ",
                                                  "RTN4, SEMA4F, SIAH1, ",
                                                  "SLIT2, SMARCA1, THY1, ",
                                                  "TRAPPC4, UBB, YWHAG, ",
                                                  "YWHAH"),split = ", ")[[1]])

# Negative Control Genes - Uniformly expressed transcripts (Optional)
negcon = intersect(rownames(expr),hk)

# Creating a SconeExperiment Object
my_scone <- SconeExperiment(expr,
                qc=ppq, bio = bio,
                negcon_ruv = rownames(expr) %in% negcon,
                poscon = rownames(expr) %in% poscon
)

```

## Defining Normalization Modules

Before we can decide which workflows (normalizations) we will want to compare,
we will also need to define the types of scaling functions we will consider in
the comparison of normalizations:

```{r scone_in2}

## ----- User-defined function: Dividing by number of detected genes -----

EFF_FN = function (ei)
{
  sums = colSums(ei > 0)
  eo = t(t(ei)*sums/mean(sums))
  return(eo)
}

## ----- Scaling Argument -----

scaling=list(none=identity, # Identity - do nothing

             eff = EFF_FN, # User-defined function

             sum = SUM_FN, # SCONE library wrappers...
             tmm = TMM_FN, 
             uq = UQ_FN,
             fq = FQT_FN,
             psi = PSINORM_FN,
             deseq = DESEQ_FN)

```

If imputation is to be included in the comparison, imputation arguments must
also be provided by the user:

```{r scone_in3, eval=FALSE}

# Simple FNR model estimation with SCONE::estimate_ziber
fnr_out = estimate_ziber(x = expr, bulk_model = TRUE,
                         pos_controls = rownames(expr) %in% hk,
                         maxiter = 10000)

## ----- Imputation List Argument -----
imputation=list(none=impute_null, # No imputation
                expect=impute_expectation) # Replace zeroes

## ----- Imputation Function Arguments -----
# accessible by functions in imputation list argument
impute_args = list(p_nodrop = fnr_out$p_nodrop, mu = exp(fnr_out$Alpha[1,]))

my_scone <- scone(my_scone,
                imputation = imputation, impute_args = impute_args,
                scaling=scaling,
                k_qc=3, k_ruv = 3,
                adjust_bio="no",
                run=FALSE)
```

Note, that because the imputation step is quite slow, we do not run it here,
but will run scone without imputation.

## Selecting SCONE Workflows

The main `scone` method arguments allow for a lot of flexibility, but a user
may choose to run very specific combinations of modules. For this purpose,
`scone` can be run in `run=FALSE` mode, generating a list of workflows to be
performed and storing this list within a `SconeExperiment` object. After
running this command the list can be extracted using the `get_params` method.

```{r scone_params}

my_scone <- scone(my_scone,
                scaling=scaling,
                k_qc=3, k_ruv = 3,
                adjust_bio="no",
                run=FALSE)

head(get_params(my_scone))

```

In the call above, we have set the following parameter arguments:

* k_ruv = 3. 
  The maximum number of RUVg factors to consider.
* k_qc = 3. 
  The maximum number of quality PCs (QPCs) to be included in a linear model,
  analogous to RUVg normalization. The qc argument must be provided.
* adjust_bio = "no." Biological origin will NOT be included in RUVg or QPC
  regression models. The bio argument will be provided for evaluation purposes.

These arguments translate to the following set of options:

```{r scone_params_view}

apply(get_params(my_scone),2,unique)

```

Some scaling methods, such as scaling by gene detection rate (`EFF_FN()`), will
not make sense within the context of imputed data, as imputation replaces
zeroes with non-zero values. We can use the `select_methods` method to produce
a `SconeExperiment` object initialized to run only meaningful normalization
workflows.

```{r scone_params_filt, eval=FALSE}

is_screened = ((get_params(my_scone)$imputation_method == "expect") &
                 (get_params(my_scone)$scaling_method %in% c("none",
                                                             "eff")))

my_scone = select_methods(my_scone,
                          rownames(get_params(my_scone))[!is_screened ])

```

## Calling `scone` with `run=TRUE`

Now that we have selected our workflows, we can run `scone` in `run=TRUE` mode.
As well as arguments used in `run=FALSE` mode, this mode relies on a few
additional arguments. In order to understand these arguments, we must first
understand the 8 metrics used to evaluate each normalization. The first 6
metrics rely on a reduction of the normalized data down to 3 dimensions via PCA
(default). Each metric is taken to have a positive (higher is better) or
negative (lower is better) signature.

* BIO_SIL: Preservation of Biological Difference. 
  The average silhouette width of clusters defined by `bio`, defined with
  respect to a Euclidean distance metric over the first 3 expression PCs.
  Positive signature.
* BATCH_SIL: Removal of Batch Structure.
  The average silhouette width of clusters defined by `batch`, defined with
  respect to a Euclidean distance metric over the first 3 expression PCs.
  Negative signature.
* PAM_SIL: Preservation of Single-Cell Heterogeneity.
  The maximum average silhouette width of clusters defined by PAM clustering,
  defined with respect to a Euclidean distance metric over the first 3 
  expression PCs. 
  Positive signature.
* EXP_QC_COR: Removal of Alignment Artifacts. 
  R^2 measure for regression of first 3 expression PCs on 
  first `k_qc` QPCs. 
  Negative signature.
* EXP_UV_COR: Removal of Expression Artifacts. 
  R^2 measure for regression of first 3 expression PCs on 
  first 3 PCs of the negative control (specified by `eval_negcon` or 
  `ruv_negcon` by default) sub-matrix of the original (raw) data. 
  Negative signature.
* EXP_WV_COR: Preservation of Biological Variance.
  R^2 measure for regression of first 3 expression PCs on 
  first 3 PCs of the positive control (specified by `eval_poscon`) 
  sub-matrix of the original (raw) data. 
  Positive signature.
* RLE_MED: Reduction of Global Differential Expression.
  The mean squared-median Relative Log Expression (RLE). 
  Negative signature.
* RLE_IQR: Reduction of Global Differential Variability.
  The variance of the inter-quartile range (IQR) of the RLE. 
  Negative signature.

```{r scone_run}

BiocParallel::register(
  BiocParallel::SerialParam()
) # Register BiocParallel Serial Execution

my_scone <- scone(my_scone,
                  scaling=scaling,
                  run=TRUE,
                  eval_kclust = 2:6,
                  stratified_pam = TRUE,
                  return_norm = "in_memory",
                  zero = "postadjust")

```

In the call above, we have set the following parameter arguments:

* eval_kclust = 2:6. 
  For PAM_SIL, range of k (# of clusters) to use when computing 
  maximum average silhouette width of PAM clusterings.
* stratified_pam = TRUE.
  For PAM_SIL, apply separate PAM clusterings to each biological 
  batch rather than across all batches. Average is weighted by 
  batch group size.
* return_norm = "in_memory".
  Store all normalized matrices in addition to evaluation data. 
  Otherwise normalized data is not returned in the resulting 
  object.
* zero = "postadjust". 
  Restore data entries that are originally zeroes / negative after 
  normalization to zero after the adjustment step.

The output will contain various updated elements:

```{r scone_view1}

# View Metric Scores
head(get_scores(my_scone))

# View Mean Score Rank
head(get_score_ranks(my_scone))

# Extract normalized data from top method
out_norm = get_normalized(my_scone,
                          method = rownames(get_params(my_scone))[1])

```

`get_scores` returns the 8 raw metrics for each normalization multiplied by
their signature - or "scores." `get_score_ranks` returns the mean score rank
for each normalization. Both of these are sorted in decreasing order by mean
score rank. Finally `get_normalized` returns the normalized expression data for
the requested method. If the normalized data isn't stored in the object it will
be recomputed.

# Step 3: Selecting a normalization for downstream analysis

Based on our sorting criteria, it would appear that
`none,uq,ruv_k=1,no_bio,no_batch` performs well compared to other normalization
workflows. A useful way to visualize this method with respect to others is the
`biplot_color` function

```{r biplot_color}

pc_obj = prcomp(apply(t(get_scores(my_scone)),1,rank),
                center = TRUE,scale = FALSE)
bp_obj = biplot_color(pc_obj,y = -get_score_ranks(my_scone),expand = .6)

```

We have colored each point above according the corresponding method's mean
score rank (yellow vs blue ~ good vs bad), and we can see that workflows span a
continuum of metric performance. Most importantly - and perhaps to no surprise
- there is evidence of strong trade-offs between i) Preserving clustering and
wanted variation and ii) removing unwanted variation. At roughly 90 degrees to
this axis is a direction in which distributional properties of relative
log-expression (RLE_MED and RLE_IQR) improve. Let's visualize the
top-performing method and it's relation to un-normalized data ("no-op"
normalization):

```{r biplot_color4}

bp_obj = biplot_color(pc_obj,y = -get_score_ranks(my_scone),expand = .6)

points(t(bp_obj[1,]), pch = 1, col = "red", cex = 1)
points(t(bp_obj[1,]), pch = 1, col = "red", cex = 1.5)

points(t(bp_obj[rownames(bp_obj) == "none,none,no_uv,no_bio,no_batch",]),
       pch = 1, col = "blue", cex = 1)
points(t(bp_obj[rownames(bp_obj) == "none,none,no_uv,no_bio,no_batch",]),
       pch = 1, col = "blue", cex = 1.5)

arrows(bp_obj[rownames(bp_obj) == "none,none,no_uv,no_bio,no_batch",][1],
       bp_obj[rownames(bp_obj) == "none,none,no_uv,no_bio,no_batch",][2],
       bp_obj[1,][1],
       bp_obj[1,][2],
       lty = 2, lwd = 2)

```

The arrow we've added to the plot traces a line from the "no-op" normalization
to the top-ranked normalization in SCONE. We see that SCONE has selected a
method in-between the two extremes, reducing the signal of unwanted variation
while preserving biological signal.

Finally, another useful function for browsing results is `sconeReport`. This
function launches a shiny app for evaluating performance of specific
normalization workflows.

```{r sconeReport, eval=FALSE}

# Methods to consider
scone_methods = c(rownames(get_params(my_scone))[1:12],
                  "none,none,no_uv,no_bio,no_batch")

# Shiny app
sconeReport(my_scone,methods = scone_methods,
            qc = ppq,
            bio = bio,
            negcon = negcon, poscon = poscon)

```


# Session Info

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