rounding.Rmd

---
title: "Rounding numeric values"
author: 
  - name: Kevin Rue-Albrecht
    affiliation:
    - University of Oxford
    email: kevin.rue-albrecht@imm.ox.ac.uk
output: 
  BiocStyle::html_document:
    self_contained: yes
    toc: true
    toc_float: true
    toc_depth: 2
    code_folding: show
date: "`r doc_date()`"
package: "`r pkg_ver('iSEEde')`"
vignette: >
  %\VignetteIndexEntry{Rounding numeric values}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html
)
options(width = 100)
```

```{r, eval=!exists("SCREENSHOT"), include=FALSE}
SCREENSHOT <- function(x, ...) knitr::include_graphics(x)
```

```{r vignetteSetup, echo=FALSE, message=FALSE, warning = FALSE}
## Track time spent on making the vignette
startTime <- Sys.time()

## Bib setup
library("RefManageR")

## Write bibliography information
bib <- c(
    R = citation(),
    BiocStyle = citation("BiocStyle")[1],
    knitr = citation("knitr")[1],
    RefManageR = citation("RefManageR")[1],
    rmarkdown = citation("rmarkdown")[1],
    sessioninfo = citation("sessioninfo")[1],
    testthat = citation("testthat")[1],
    iSEEde = citation("iSEEde")[1]
)
```

# Example data

In this example, we use the `?airway` data set.

We briefly adjust the reference level of the treatment factor to the untreated condition.

```{r, message=FALSE, warning=FALSE}
library("airway")
data("airway")
airway$dex <- relevel(airway$dex, "untrt")
```

# Differential expression

To generate some example results, we run a standard `r BiocStyle::Biocpkg("edgeR")` analysis using `glmFit()` and
`glmLRT()`.

The differential expression results are fetched using `topTags()`.

```{r, message=FALSE, warning=FALSE}
library("edgeR")

design <- model.matrix(~ 0 + dex + cell, data = colData(airway))

fit <- glmFit(airway, design, dispersion = 0.1)
lrt <- glmLRT(fit, contrast = c(-1, 1, 0, 0, 0))
res_edger <- topTags(lrt, n = Inf)
head(res_edger)
```

Then, we embed this set of differential expression results in the `airway`
object using the `embedContrastResults()` method.

The results embedded in the airway object can be accessed using the `contrastResults()` function.

```{r, message=FALSE}
library(iSEEde)
airway <- embedContrastResults(res_edger, airway, name = "edgeR")
contrastResults(airway)
contrastResults(airway, "edgeR")
```

# Set a default rounding configuration

Differential expression methods generally return precise numeric values with several digits after the decimal point.
This level of precision can be unnecessarily overwhelming and users may wish to round numeric values to a limited number of significant digits.

The builtin default configuration for rounding in `r BiocStyle::Biocpkg("iSEEde")` is `RoundDigit = FALSE` and `SignifDigits = 3`.
In other words, numeric values are not rounded, and if users do activate the rounding functionality, numeric values are rounded to three significant digits.

Those defaults can be changed using the `panelDefaults()` function.

```{r}
panelDefaults(RoundDigits = TRUE, SignifDigits = 2L)
```

With the default panel settings configured, we use the `DETable()` function to display the contrast results with rounded numeric values.

```{r, message=FALSE}
library(iSEE)
app <- iSEE(airway, initial = list(
  DETable(ContrastName="edgeR", HiddenColumns = c("logCPM", "LR"),
          PanelWidth = 12L)
))

if (interactive()) {
  shiny::runApp(app)
}
```

```{r, echo=FALSE, out.width="100%"}
SCREENSHOT("screenshots/rounding_default.png", delay = 20)
```

# Configuring rounding in individual panels

The default rounding configuration can be overridden in individual panel configurations.

The slots `RoundDigits` and `SignifDigits` can be set directly in the individual calls to the `DETable()` constructor function.

In the example below, we add two tables, one rounding numeric values to the default value of two significant digits set above, the other rounding the same values to three significant digits.

```{r, message=FALSE}
library(iSEE)
app <- iSEE(airway, initial = list(
  DETable(ContrastName="edgeR", HiddenColumns = c("logCPM", "LR"),
          PanelWidth = 6L, RoundDigits = TRUE),
  DETable(ContrastName="edgeR", HiddenColumns = c("logCPM", "LR"),
          PanelWidth = 6L, RoundDigits = TRUE, SignifDigits = 3L)
))

if (interactive()) {
  shiny::runApp(app)
}
```

```{r, echo=FALSE, out.width="100%"}
SCREENSHOT("screenshots/rounding_panel.png", delay = 20)
```

# Reproducibility

The `r Biocpkg("iSEEde")` package `r Citep(bib[["iSEEde"]])` was made possible
thanks to:

* R `r Citep(bib[["R"]])`
* `r Biocpkg("BiocStyle")` `r Citep(bib[["BiocStyle"]])`
* `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])`
* `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`
* `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])`
* `r CRANpkg("sessioninfo")` `r Citep(bib[["sessioninfo"]])`
* `r CRANpkg("testthat")` `r Citep(bib[["testthat"]])`

This package was developed using `r BiocStyle::Biocpkg("biocthis")`.


Code for creating the vignette

```{r createVignette, eval=FALSE}
## Create the vignette
library("rmarkdown")
system.time(render("rounding.Rmd", "BiocStyle::html_document"))

## Extract the R code
library("knitr")
knit("rounding.Rmd", tangle = TRUE)
```

Date the vignette was generated.

```{r reproduce1, echo=FALSE}
## Date the vignette was generated
Sys.time()
```

Wallclock time spent generating the vignette.

```{r reproduce2, echo=FALSE}
## Processing time in seconds
totalTime <- diff(c(startTime, Sys.time()))
round(totalTime, digits = 3)
```

`R` session information.

```{r reproduce3, echo=FALSE}
## Session info
library("sessioninfo")
options(width = 120)
session_info()
```



# Bibliography

This vignette was generated using `r Biocpkg("BiocStyle")` `r
Citep(bib[["BiocStyle"]])` with `r CRANpkg("knitr")` `r Citep(bib[["knitr"]])`
and `r CRANpkg("rmarkdown")` `r Citep(bib[["rmarkdown"]])` running behind the
scenes.

Citations made with `r CRANpkg("RefManageR")` `r Citep(bib[["RefManageR"]])`.

```{r vignetteBiblio, results = "asis", echo = FALSE, warning = FALSE, message = FALSE}
## Print bibliography
PrintBibliography(bib, .opts = list(hyperlink = "to.doc", style = "html"))
```

<!-- Links -->

[scheme-wikipedia]: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax
[iana-uri]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml