Adding vignette about custom tracks

_pkgdown.yml

@@ -14,6 +14,8 @@ navbar:
         href: articles/hidecan-step-by-step.html
       - text: GWASpoly output
         href: articles/web_only/gwaspoly_output.html
+      - text: Adding custom tracks
+        href: articles/web_only/custom_tracks.html
       - text: Shiny app
         href: articles/web_only/shiny-app.html
 
@@ -33,6 +35,7 @@ reference:
   - GWAS_data
   - DE_data
   - CAN_data
+  - CUSTOM_data
 
 - title: "Constructors from packages output"
   contents:
@@ -42,6 +45,7 @@ reference:
   contents:
   - compute_chrom_length
   - combine_chrom_length
+  - .compute_chrom_length_markers
   - .compute_chrom_length_genes
 
 - title: "Applying threshold"
@@ -52,9 +56,13 @@ reference:
   contents:
   - hidecan_plot
   - create_hidecan_plot
+  - hidecan_aes
   - run_hidecan_shiny
   - hidecan_plot_from_gwaspoly
   - manhattan_plot
+  - .get_aes_type
+  - .get_plot_aes
+  - .add_data_type
 
 - title: "Example datasets"
   contents:
@@ -63,4 +71,6 @@ reference:
 - title: "Utils"
   contents:
   - .check_cols
+  - .check_chroms
+  - .check_chrom_limits
 

vignettes/hidecan.Rmd

@@ -17,6 +17,7 @@ library(tibble)
 library(dplyr)
 library(purrr)
 library(stringr)
+library(viridis)
 ```
 
 ```{r setup}
@@ -378,6 +379,63 @@ manhattan_plot(list("Trait A" = x[["GWAS"]],
                ncol = 1)
 ```
 
+## Controlling the aesthetics (colours, point shapes, labels) of the tracks
+
+The default look of the different data types (GWAS peaks, DE genes and candidate genes) in a HIDECAN plots is controlled by the arguments returned by `hidecan_aes()`. More specifically, the function controls:
+
+- the label of each data type on the x-axis (e.g. 'GWAS peaks' for GWAS results),
+
+- the colour of the vertical lines used to showcase the position of markers or genes,
+
+- the shape of the points,
+
+- whether the name of the markers/genes are displayed (by default, will only show for candidate genes),
+
+- the colour palette used for the score or log2 fold-change of the points.
+
+The default values used for these parameters have been chosen to ensure that the resulting plot is easily understandable. However, it is possible to change them. To do so, we'll start by saving the defaults returned by `hidecan_aes()`:
+
+```{r hidecan-aes}
+default_aes <- hidecan_aes()
+
+str(default_aes, max.level = 1)
+
+default_aes[[1]]
+```
+
+As we can see above, the function returns a list of the default aesthetics to use for GWAS results (the `GWAS_data_thr` element), for DE results (`DE_data_thr` element), for candidate genes (`CAN_data_thr` element), and for custom tracks (`CUSTOM_data_thr` element - see the [Adding custom tracks](web_only/custom_tracks.html) article for more information). Each element is itself a list, containing the value for each attribute mentioned above.
+
+Let's modify the label given to the GWAS peaks, and the colour palette used for DE score:
+
+```{r modify-hidecan-aes}
+library(viridis)
+
+default_aes$GWAS_data_thr$y_label <- "GWAS signif. markers"
+
+default_aes$DE_data_thr$fill_scale <- scale_fill_viridis(
+  "DE gene score",
+  option = "inferno",
+  guide = ggplot2::guide_colourbar(
+    title.position = "top",
+    title.hjust = 0.5,
+    order = 3 # ensures this legend is shown after the one for GWAS scores
+  )
+)
+```
+
+We can use these modified values by passing this list to `hidecan_plot()` through its `custom_aes` argument:
+
+```{r use-custom-aes, fig.width = 10, fig.height = 10}
+hidecan_plot(
+  gwas_list = x[["GWAS"]],
+  de_list = x[["DE"]],
+  can_list = x[["CAN"]],     
+  score_thr_gwas = -log10(0.0001),
+  score_thr_de = -log10(0.05),
+  log2fc_thr = 0,
+  custom_aes = default_aes
+)
+```
 
 
 ## Viewport error

vignettes/web_only/custom_tracks.Rmd

@@ -0,0 +1,207 @@
+---
+title: "Adding custom tracks"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Adding custom tracks}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+
+library(tibble)
+library(dplyr)
+library(purrr)
+library(stringr)
+library(viridis)
+```
+
+```{r setup}
+library(hidecan)
+library(dplyr)
+library(viridis)
+library(ggplot2)
+```
+
+While hidecan was designed with the goal of representing GWAS and DE results with lists of candidate genes, in principle it can be used to visualise any genomic feature that can be mapped to a physical location on the genome; for example significant QTLs, HiC data etc. To facilitate this, it is possible to add one or more custom data types into a hidecan plot.
+
+## Adding one custom data type
+
+Let us start by simulating a new set of results -- for simplicity we'll assume that we have results from a QTL mapping on the same markers that were used for the GWAS analysis:
+
+```{r simulating-qtl-results}
+x <- get_example_data()
+
+set.seed(586)
+x$QTL <- x$GWAS |> 
+  ## shuffling the scores around to get different "significant" markers
+  mutate(score = sample(score, n(), replace = FALSE))
+```
+
+We can add this new data to the hidecan plot through the `custom_list` argument of the `hidecan_plot()` function (we'll only look at two chromosomes for simplicity), and use the `score_thr_custom` argument to set the significance threshold on the score:
+
+```{r hidecan-plot, fig.width = 10, fig.height = 3}
+hidecan_plot(
+  gwas_list = x[["GWAS"]],
+  score_thr_gwas = -log10(0.0001),
+  chroms = c("ST4.03ch01", "ST4.03ch02"),
+  custom_list = x[["QTL"]],
+  score_thr_custom = -log10(0.0001)
+)
+```
+
+Importantly, the data-frame that is passed to `custom_list` must contain at least the following columns: `chromosome`, `position` and `score`. If the genomic features you want to add are genes for example (with a start and end position) you need to calculate the `position` column yourself.
+
+We can customise the labels and colours used for this custom track with the help of the `hidecan_aes()` function:
+
+```{r hidecan-aes}
+plot_aes <- hidecan_aes()
+
+str(plot_aes, max.level = 1)
+
+plot_aes[["CUSTOM_data_thr"]]
+```
+
+In particular, we will change the name given to the track, as well as the name used for the legend:
+
+```{r modify-aes}
+plot_aes$CUSTOM_data_thr$y_label <- "Signif. QTLs"
+
+plot_aes$CUSTOM_data_thr$fill_scale$name <- "QTL score"
+
+# We could also change the entire legend with:
+
+# default_aes$CUSTOM_data_thr$fill_scale <- scale_fill_viridis(
+#   "QTL score",
+#   option = "inferno",
+#   guide = guide_colourbar(
+#     title.position = "top",
+#     title.hjust = 0.5,
+#     order = 4 # ensures this legend is shown after the one for DE scores
+#   )
+# )
+```
+
+We will use these values in the hidecan plot by passing the list through the `custom_aes` argument:
+
+```{r hidecan-custom-aes, fig.width = 10, fig.height = 3}
+hidecan_plot(
+  gwas_list = x[["GWAS"]],
+  score_thr_gwas = -log10(0.0001),
+  chroms = c("ST4.03ch01", "ST4.03ch02"),
+  custom_list = x[["QTL"]],
+  score_thr_custom = -log10(0.0001),
+  custom_aes = plot_aes
+)
+```
+
+
+Note that, as for the other supported data types, we can pass more than one data-frame to `custom_list` to get several tracks of QTLs:
+
+```{r two-qtl-results, fig.width = 10, fig.height = 3}
+## Simulating a second set of QTL results
+set.seed(779)
+x$QTL2 <- x$QTL |> 
+  mutate(score = sample(score, n(), replace = FALSE))
+
+hidecan_plot(
+  gwas_list = x[["GWAS"]],    
+  score_thr_gwas = -log10(0.0001),
+  score_thr_de = -log10(0.05),
+  log2fc_thr = 0,
+  chroms = c("ST4.03ch01", "ST4.03ch02"),
+  custom_list = list("Trait 1" = x[["QTL"]],
+                     "Trait 2" = x[["QTL2"]]),
+  score_thr_custom = -log10(0.0001),
+  custom_aes = plot_aes
+)
+```
+
+By default, the values in the `score` column are shown as the points colour, but we can hide it by setting the `fill_scale` element of our aesthetics list to `NULL`. Also, we can add labels to the significant points, by adding a `name` column to the data-frame, and setting the `show_name` element of our aesthetics list to `TRUE`:
+
+```{r adding-names, fig.width = 10, fig.height = 3}
+## Creating fake names for the markers
+set.seed(342)
+x$QTL <- x$QTL |> 
+  mutate(name = sample(LETTERS, n(), replace = TRUE))
+
+plot_aes2 <- plot_aes
+
+plot_aes2$CUSTOM_data_thr$show_name <- TRUE
+plot_aes2$CUSTOM_data_thr$fill_scale <- NULL
+
+hidecan_plot(
+  gwas_list = x[["GWAS"]],
+  score_thr_gwas = -log10(0.0001),
+  chroms = c("ST4.03ch01", "ST4.03ch02"),
+  custom_list = x[["QTL"]],
+  score_thr_custom = -log10(0.0001),
+  custom_aes = plot_aes2
+)
+```
+
+
+## Adding several custom data types
+
+It is also possible to add more than one custom data type. For example, let's say that we want to add information about differentially methylated regions to the plot. We'll use the example DE data to simulate our methylated dataset:
+
+```{r}
+set.seed(554)
+x$METH <- x$DE |> 
+  mutate(
+    position = (start + end) / 2, ## need to calculate the position of the regions
+    score = sample(-log10(padj), n(), replace = FALSE),
+    name = sample(letters, n(), replace = TRUE)
+  )
+```
+
+Importantly, the significance threshold encoded by the `score_thr_custom` argument of `hidecan_plot()` will be used for all custom datasets, so if we don't want to use the same significance threshold on our QTL and methylation data, we need to perform the filtering of significant features by hand before and then set the threshold to 0:
+
+```{r apply-thr}
+x$QTL <- x$QTL |> 
+  filter(score >= -log10(0.0001))
+
+x$METH <- x$METH |> 
+  filter(score >= -log10(0.04))
+```
+
+
+The key to specifying that the two custom datasets are different data types is to add to the new data-frame an argument called `aes_type`, which is simply a label that tells the function which aesthetics settings it should use from the list passsed to `custom_aes`. We will retain the aesthetics we have set for the QTL scores, and create new aesthetics for the methylation data:
+
+```{r, fig.width = 10, fig.height = 3}
+## Adding the aes_type attribute to the methylation data
+attr(x$METH, "aes_type") <- "METH"
+
+## The name of the new element in the aesthetics list must match the value of
+## the aes_type attribute
+plot_aes$METH <- list(
+  y_label = "DMRs",
+  line_colour = "purple",
+  point_shape = 24,
+  show_name = TRUE,
+  fill_scale = scale_fill_viridis(
+    "DM score",
+    option = "mako",
+    guide = guide_colourbar(
+      title.position = "top",
+      title.hjust = 0.5,
+      order = 5
+    )
+  )
+)
+
+hidecan_plot(
+  gwas_list = x[["GWAS"]],
+  score_thr_gwas = -log10(0.0001),
+  chroms = c("ST4.03ch01", "ST4.03ch02"),
+  custom_list = list(x[["QTL"]], x[["METH"]]),
+  score_thr_custom = 0, ## no filtering, has been done manually
+  custom_aes = plot_aes
+)
+```
+
+There are no restrictions on the number of custom data types that can be added to a hidecan plot.