The output object's tables provide a host of information. The rats package also includes some visualisation aides.
This function allows you to visualise what's going on in any particular gene. Both the absolute counts and the relative -proportions are plotted for each transcript. This is a very useful function for inspecting a gne if interest. It enables -quick visual evaluation of the dispersion of the replicate measurements, the magnitude of the proportion change, the -presence of outliers, and the consistency among the replicates.
- -# Proportion and count changes for all the transcripts of the "MIX6" gene.
-plot_gene(mydtu, "MIX6", style="lines") # default
-
Several styles of this plot are available. The recommended style is set as default. The other options represent older -styles that have been kept for backwards compatibility, but may get deprecated eventually:
- -plot_gene(mydtu, "MIX6", style="points")
-plot_gene(mydtu, "MIX6", style="rainbow")
-plot_gene(mydtu, "MIX6", style="merged")
-plot_gene(mydtu, "MIX6", style="dashed")
-Our simulated dataset is too small to properly demonstrate what these plots typically look like. -So each one is accompanied by a static image of the same plot created with a real and much larger dataset.
- -Several of these plots are likely to display warnings about missing or non-finite values. These are due to the
-presence of NA in the tables, where entries did not pass the thresholds, and can be ignored.
Possibly the most common plot in differential expression is the volcano plot, which plots the effect size against -the statistical significance. As it is difficult to define a single p-value and a single effect size at the gene level, -the volcano can only be plotted at the transcript level.
- -# Proportion change VS significance.
-plot_overview(mydtu, type="volcano")
-## Warning: Removed 11 rows containing missing values (geom_point).
-
This is what it looks like on a larger dataset:
-
The next command plots the largest change in proportion seen within each gene, against the number of genes showing -such change. This is a way to inspect what effect sizes are present in the data. As an additional layer of information, -they are colour-coded by their DTU call.
- -# Distribution of maximum proportion change.
-plot_overview(mydtu, type="maxdprop")
-
This is what it looks like on a larger dataset:
-
If you prefer picking points from a plot than sorting through tables, the volcano plot is also available through
-a shiny app, that brings up the relevant abundance changes plot for any point in the volcano plot.
# Start the interactive volcano plot.
-plot_shiny_volcano(mydtu)
-This is what it looks like for the example data (remember that the emulated data example has very few transcripts).
- -
You will need to close down the app to return to your R terminal.
- -You can save any of the plots as a ggplot2 object and use ggplot2 manipulations on it, such as changing the axis scales.
-Other ggplot2 customisations include the axis tick marks, axis values, labels, titles, colours… Consult the ggplot2
-documentation for more help on these.
library(ggplot2)
-
-myplot <- plot_overview(mydtu, "volcano")
-myplot # display
-## Warning: Removed 11 rows containing missing values (geom_point).
-
# Change title.
-myplot2 <- myplot + ggtitle("MY EPIC TITLE")
-myplot2
-## Warning: Removed 11 rows containing missing values (geom_point).
-
The rats R package was developed within The Barton Group at The University of Dundee
diff --git a/inst/doc/plots.R b/inst/doc/plots.R
new file mode 100644
index 0000000..3d23df3
--- /dev/null
+++ b/inst/doc/plots.R
@@ -0,0 +1,80 @@
+## ----setup, include=FALSE------------------------------------------------
+knitr::opts_chunk$set(echo = TRUE)
+
+## ------------------------------------------------------------------------
+library(rats)
+
+# Simulate some data.
+simdat <- sim_sleuth_data(cnames = c("controls", "patients"))
+# For convenience let's assign the contents of the list to separate variables.
+myslo <- simdat$slo
+myannot <- simdat$annot
+
+# Call DTU
+mydtu <- call_DTU(annot = myannot, slo = myslo, name_A = "controls", name_B = "patients",
+ varname= "condition", verbose= FALSE,
+ description="Comparison of two conditions using a simulated sleuth object
+ for the purposes of the tutorial. Simulated using built-in functionality
+ of RATs.")
+
+## ------------------------------------------------------------------------
+# Split by condition for easier view of the overall gene profile.
+plot_gene(mydtu, "MIX6", style="plain")
+
+## ------------------------------------------------------------------------
+# Isoforms paired up for easier individual comparisons.
+plot_gene(mydtu, "MIX6", style="paired")
+
+## ------------------------------------------------------------------------
+# Split by condition.
+plot_gene(mydtu, "MIX6", style="points")
+
+## ------------------------------------------------------------------------
+# Paired by isoform.
+plot_gene(mydtu, "MIX6", style="pairedpnt")
+
+## ------------------------------------------------------------------------
+# Split by condition.
+# This is the DEFAULT view if the style is omitted, as it is the most informative.
+plot_gene(mydtu, "MIX6", style="lines")
+
+## ------------------------------------------------------------------------
+# A cleaner version, although it no longer shows which isoforms are DTU.
+plot_gene(mydtu, "MIX6", style="linesonly")
+
+## ------------------------------------------------------------------------
+# You can change the information that is colour-coded.
+plot_gene(mydtu, "MIX6", style="plain", fillby="DTU")
+plot_gene(mydtu, "MIX6", style="points", fillby="isoform", colourby="replicate")
+plot_gene(mydtu, "MIX6", style="pairedpnt", colourby="isoform", shapeby="replicate")
+
+# For a less colourful look, the layered information can be disabled.
+plot_gene(mydtu, "MIX6", style="points", fillby="none", colourby="none", shapeby="none")
+
+## ------------------------------------------------------------------------
+# You can also customise the colours used by specifying new values for
+# condcolvec, replcolvec, isofcolvec, dtucolvec and nonecol.
+plot_gene(mydtu, "MIX6", style="lines", fillby="condition", condcolvec=c("magenta", "cyan"))
+
+## ------------------------------------------------------------------------
+# Proportion change VS significance.
+plot_overview(mydtu, type="volcano")
+
+## ------------------------------------------------------------------------
+# Distribution of maximum proportion change.
+plot_overview(mydtu, type="maxdprop")
+
+## ---- eval=FALSE---------------------------------------------------------
+# # Start the interactive volcano plot.
+# plot_shiny_volcano(mydtu)
+
+## ------------------------------------------------------------------------
+library(ggplot2)
+
+myplot <- plot_overview(mydtu, "volcano")
+myplot # display
+
+# Change title.
+myplot2 <- myplot + ggtitle("MY EPIC TITLE")
+myplot2
+
diff --git a/inst/doc/plots.Rmd b/inst/doc/plots.Rmd
new file mode 100644
index 0000000..b3c9c28
--- /dev/null
+++ b/inst/doc/plots.Rmd
@@ -0,0 +1,214 @@
+---
+title: "RATs: Plots"
+author: "Kimon Froussios"
+date: "04 APR 2017"
+output:
+ html_document:
+ fig_caption: no
+ keep_md: yes
+ theme: readable
+ toc: yes
+vignette: >
+ %\VignetteIndexEntry{RATs Output and Plots}
+ %\VignetteEngine{knitr::knitr}
+ \usepackage[utf8]{inputenc}
+
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+```
+
+***
+
+Set up an example.
+
+```{r}
+library(rats)
+
+# Simulate some data.
+simdat <- sim_sleuth_data(cnames = c("controls", "patients"))
+# For convenience let's assign the contents of the list to separate variables.
+myslo <- simdat$slo
+myannot <- simdat$annot
+
+# Call DTU
+mydtu <- call_DTU(annot = myannot, slo = myslo, name_A = "controls", name_B = "patients",
+ varname= "condition", verbose= FALSE,
+ description="Comparison of two conditions using a simulated sleuth object
+ for the purposes of the tutorial. Simulated using built-in functionality
+ of RATs.")
+```
+
+
+***
+
+
+# Visualisation of results
+
+
+The output object's tables provide a host of information. But a good plot is worth a thousand numbers.
+
+
+## Isoform abundances for a given gene
+
+This function allows you to visualise what's going on in any particular gene. Both the absolute counts and the relative
+proportions are plotted for each transcript. This is a very useful function for inspecting a gene of interest. It enables
+quick visual evaluation of the dispersion of the replicate measurements, the magnitude of the proportion change, the
+presence of outliers, and the consistency among the replicates. There are several styles for this plot, depending on your preferences.
+
+The simplest option is to represent the measurements from your replicates as boxplots:
+
+```{r}
+# Split by condition for easier view of the overall gene profile.
+plot_gene(mydtu, "MIX6", style="plain")
+```
+
+```{r}
+# Isoforms paired up for easier individual comparisons.
+plot_gene(mydtu, "MIX6", style="paired")
+```
+
+Boxplots, however, can hide the real distribution of your data, which could be multi-modal. Adding the actual measurements
+resolves that:
+
+```{r}
+# Split by condition.
+plot_gene(mydtu, "MIX6", style="points")
+```
+
+```{r}
+# Paired by isoform.
+plot_gene(mydtu, "MIX6", style="pairedpnt")
+```
+
+Finally, relative abundance measurements are not independent. The measurements from each replicate are tied together.
+Connecting the measurements of each replicate reveals the level of consistency of the relative abundances across the replicates.
+
+```{r}
+# Split by condition.
+# This is the DEFAULT view if the style is omitted, as it is the most informative.
+plot_gene(mydtu, "MIX6", style="lines")
+```
+
+```{r}
+# A cleaner version, although it no longer shows which isoforms are DTU.
+plot_gene(mydtu, "MIX6", style="linesonly")
+```
+
+
+### Customisation of the gene plot
+
+There are options to change the colour coding of the gene plot. Bear in mind that, some
+of the options are not available for all styles. If neither `fillby` and `colourby` is
+set to `"DTU"`, and `shapeby` is undefined, the role of encoding DTU is automatically
+assigned to `shapeby`.
+
+```{r}
+# You can change the information that is colour-coded.
+plot_gene(mydtu, "MIX6", style="plain", fillby="DTU")
+plot_gene(mydtu, "MIX6", style="points", fillby="isoform", colourby="replicate")
+plot_gene(mydtu, "MIX6", style="pairedpnt", colourby="isoform", shapeby="replicate")
+
+# For a less colourful look, the layered information can be disabled.
+plot_gene(mydtu, "MIX6", style="points", fillby="none", colourby="none", shapeby="none")
+```
+
+```{r}
+# You can also customise the colours used by specifying new values for
+# condcolvec, replcolvec, isofcolvec, dtucolvec and nonecol.
+plot_gene(mydtu, "MIX6", style="lines", fillby="condition", condcolvec=c("magenta", "cyan"))
+```
+
+
+
+
+## Plots of overall run
+
+Our simulated dataset is too small to properly demonstrate what these plots typically look like.
+So each one is accompanied by a static image of the same plot created with a real and much larger dataset.
+
+Several of these plots are **likely to display warnings** about missing or non-finite values. These are due to the
+presence of `NA` in the tables, where entries did not pass the thresholds, and can be ignored.
+
+Possibly the most common plot in differential expression is the volcano plot, which plots the effect size against
+the statistical significance. As it is difficult to define a single p-value and a single effect size at the gene level,
+the volcano can only be plotted at the transcript level.
+
+```{r}
+# Proportion change VS significance.
+plot_overview(mydtu, type="volcano")
+```
+
+This is what it looks like on a larger dataset:
+
+
+The next command plots the largest change in proportion seen within each gene, against the number of genes showing
+such change. This is a way to inspect what effect sizes are present in the data. As an additional layer of information,
+they are colour-coded by their DTU result.
+
+```{r}
+# Distribution of maximum proportion change.
+plot_overview(mydtu, type="maxdprop")
+```
+
+This is what it looks like on a larger dataset:
+
+
+
+### Interactive plots
+
+If you prefer picking points from a plot than sorting through tables, the volcano plot is also available through
+a `shiny` app, that brings up the relevant abundance changes plot for any point in the volcano plot.
+
+1. By hovering over points on the volcano plot in the app, you can see the respective transcript identifier(s).
+2. Clicking will pull up information on the effect size, significance and confidence of the point(s), as well as
+the respective isoform abundance changes plot for the point nearest to the click.
+
+```{r, eval=FALSE}
+# Start the interactive volcano plot.
+plot_shiny_volcano(mydtu)
+```
+
+This is what it looks like for the example data (remember that the emulated data example has very few transcripts).
+
+
+
+You will need to close down the app to return to your R terminal.
+
+
+## Plot customisation
+
+You can save any of the plots as a `ggplot2` object and use [ggplot2](http://ggplot2.org) manipulations on it, such as changing the axis scales.
+Other `ggplot2` customisations include the axis tick marks, axis values, labels, titles, colours... Consult the [ggplot2](http://ggplot2.org)
+documentation for more help on these.
+
+```{r}
+library(ggplot2)
+
+myplot <- plot_overview(mydtu, "volcano")
+myplot # display
+
+# Change title.
+myplot2 <- myplot + ggtitle("MY EPIC TITLE")
+myplot2
+```
+
+
+***
+
+
+# Contact information
+
+The `rats` R package was developed within [The Barton Group](http://www.compbio.dundee.ac.uk) at [The University of Dundee](http://www.dundee.ac.uk)
+by Dr. Kimon Froussios, Dr. Kira Mourão and Dr. Nick Schurch.
+
+To **report problems** or **ask for assistance**, please raise a new issue [on the project's support forum](https://github.com/bartongroup/Rats/issues).
+Providing a *reproducible working example* that demonstrates your issue is strongly encouraged to help us understand the problem. Also, be sure
+to **read the vignette(s)**, and browse/search the support forum before posting a new issue, in case your question is already answered there.
+
+Enjoy!
+
+
+
+
diff --git a/inst/doc/plots.html b/inst/doc/plots.html
new file mode 100644
index 0000000..cede938
--- /dev/null
+++ b/inst/doc/plots.html
@@ -0,0 +1,420 @@
+
+
+
Set up an example.
+ +library(rats)
+
+# Simulate some data.
+simdat <- sim_sleuth_data(cnames = c("controls", "patients"))
+# For convenience let's assign the contents of the list to separate variables.
+myslo <- simdat$slo
+myannot <- simdat$annot
+
+# Call DTU
+mydtu <- call_DTU(annot = myannot, slo = myslo, name_A = "controls", name_B = "patients",
+ varname= "condition", verbose= FALSE,
+ description="Comparison of two conditions using a simulated sleuth object
+ for the purposes of the tutorial. Simulated using built-in functionality
+ of RATs.")
+The output object's tables provide a host of information. But a good plot is worth a thousand numbers.
+ +This function allows you to visualise what's going on in any particular gene. Both the absolute counts and the relative +proportions are plotted for each transcript. This is a very useful function for inspecting a gene of interest. It enables +quick visual evaluation of the dispersion of the replicate measurements, the magnitude of the proportion change, the +presence of outliers, and the consistency among the replicates. There are several styles for this plot, depending on your preferences.
+ +The simplest option is to represent the measurements from your replicates as boxplots:
+ +# Split by condition for easier view of the overall gene profile.
+plot_gene(mydtu, "MIX6", style="plain")
+
# Isoforms paired up for easier individual comparisons.
+plot_gene(mydtu, "MIX6", style="paired")
+
Boxplots, however, can hide the real distribution of your data, which could be multi-modal. Adding the actual measurements +resolves that:
+ +# Split by condition.
+plot_gene(mydtu, "MIX6", style="points")
+
# Paired by isoform.
+plot_gene(mydtu, "MIX6", style="pairedpnt")
+
Finally, relative abundance measurements are not independent. The measurements from each replicate are tied together. +Connecting the measurements of each replicate reveals the level of consistency of the relative abundances across the replicates.
+ +# Split by condition.
+# This is the DEFAULT view if the style is omitted, as it is the most informative.
+plot_gene(mydtu, "MIX6", style="lines")
+
# A cleaner version, although it no longer shows which isoforms are DTU.
+plot_gene(mydtu, "MIX6", style="linesonly")
+
There are options to change the colour coding of the gene plot. Bear in mind that, some
+of the options are not available for all styles. If neither fillby and colourby is
+set to "DTU", and shapeby is undefined, the role of encoding DTU is automatically
+assigned to shapeby.
# You can change the information that is colour-coded.
+plot_gene(mydtu, "MIX6", style="plain", fillby="DTU")
+
plot_gene(mydtu, "MIX6", style="points", fillby="isoform", colourby="replicate")
+
plot_gene(mydtu, "MIX6", style="pairedpnt", colourby="isoform", shapeby="replicate")
+
# For a less colourful look, the layered information can be disabled.
+plot_gene(mydtu, "MIX6", style="points", fillby="none", colourby="none", shapeby="none")
+
# You can also customise the colours used by specifying new values for
+# condcolvec, replcolvec, isofcolvec, dtucolvec and nonecol.
+plot_gene(mydtu, "MIX6", style="lines", fillby="condition", condcolvec=c("magenta", "cyan"))
+
Our simulated dataset is too small to properly demonstrate what these plots typically look like. +So each one is accompanied by a static image of the same plot created with a real and much larger dataset.
+ +Several of these plots are likely to display warnings about missing or non-finite values. These are due to the
+presence of NA in the tables, where entries did not pass the thresholds, and can be ignored.
Possibly the most common plot in differential expression is the volcano plot, which plots the effect size against +the statistical significance. As it is difficult to define a single p-value and a single effect size at the gene level, +the volcano can only be plotted at the transcript level.
+ +# Proportion change VS significance.
+plot_overview(mydtu, type="volcano")
+## Warning: Removed 11 rows containing missing values (geom_point).
+
This is what it looks like on a larger dataset:
+
The next command plots the largest change in proportion seen within each gene, against the number of genes showing +such change. This is a way to inspect what effect sizes are present in the data. As an additional layer of information, +they are colour-coded by their DTU result.
+ +# Distribution of maximum proportion change.
+plot_overview(mydtu, type="maxdprop")
+
This is what it looks like on a larger dataset:
+
If you prefer picking points from a plot than sorting through tables, the volcano plot is also available through
+a shiny app, that brings up the relevant abundance changes plot for any point in the volcano plot.
# Start the interactive volcano plot.
+plot_shiny_volcano(mydtu)
+This is what it looks like for the example data (remember that the emulated data example has very few transcripts).
+ +
You will need to close down the app to return to your R terminal.
+ +You can save any of the plots as a ggplot2 object and use ggplot2 manipulations on it, such as changing the axis scales.
+Other ggplot2 customisations include the axis tick marks, axis values, labels, titles, colours… Consult the ggplot2
+documentation for more help on these.
library(ggplot2)
+
+myplot <- plot_overview(mydtu, "volcano")
+myplot # display
+## Warning: Removed 11 rows containing missing values (geom_point).
+
# Change title.
+myplot2 <- myplot + ggtitle("MY EPIC TITLE")
+myplot2
+## Warning: Removed 11 rows containing missing values (geom_point).
+
The rats R package was developed within The Barton Group at The University of Dundee
+by Dr. Kimon Froussios, Dr. Kira Mourão and Dr. Nick Schurch.
To report problems or ask for assistance, please raise a new issue on the project's support forum. +Providing a reproducible working example that demonstrates your issue is strongly encouraged to help us understand the problem. Also, be sure +to read the vignette(s), and browse/search the support forum before posting a new issue, in case your question is already answered there.
+ +Enjoy!
+ +