---
title: "Visualization with built-in plots"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{visualization}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
options(rmarkdown.html_vignette.check_title = FALSE)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 5,
  fig.height = 4
)
```

```{r load}
library(MOSuite)
```

## Default plots from main functions

Default plots can be printed to the screen and/or saved to the disk.

```{r options}
# set options to print & save the plots
options(moo_print_plots = TRUE)
options(moo_save_plots = TRUE)
# when moo_save_plots is TRUE, plots are saved to this directory:
options(moo_plots_dir = "./figures")
```

See `?MOSuite::options` for more information.

### clean

```{r nidap_data_clean}
moo <- create_multiOmicDataSet_from_dataframes(
  sample_metadata = as.data.frame(nidap_sample_metadata),
  counts_dat = as.data.frame(nidap_raw_counts)
) |>
  clean_raw_counts()
```

### filter

```{r nidap_filter}
moo <- moo |>
  filter_counts(group_colname = "Group")
```

### normalize

```{r nidap_norm}
moo <- moo |>
  normalize_counts(group_colname = "Group")
```

### batch correct

```{r nidap_batch}
moo <- moo |>
  batch_correct_counts(
    covariates_colname = "Group",
    batch_colname = "Batch",
    label_colname = "Label"
  )
```

### differential expression

```{r diff_counts}
moo <- moo |>
  diff_counts(
    count_type = "filt",
    covariates_colnames = c("Group", "Batch"),
    contrast_colname = c("Group"),
    contrasts = c("B-A", "C-A", "B-C"),
    input_in_log_counts = FALSE,
    return_mean_and_sd = FALSE,
    voom_normalization_method = "quantile",
  )
```

### filter differential features

```{r filter_diff}
moo <- moo |> filter_diff()
```

## Specialized plots

### 3D PCA

```{r pca_3D}
plot_pca_3d(
  moo,
  count_type = "batch",
  principal_components = c(1, 2, 3),
  group_colname = "Group",
  label_colname = "Label"
)
```

### Expression Heatmap

```{r expr_heatmap}
heatmap_plot <- plot_expr_heatmap(
  moo,
  count_type = "norm",
  sub_count_type = "voom",
  group_colname = "Group"
)
# print(heatmap_plot)
```

### Volcano

#### Enhanced

Create an enhanced volcano plot for each contrast:

```{r volcano_enhanced, fig.height=7}
dat_volcano_enhanced <- moo |>
  plot_volcano_enhanced()
```

or plot only one contrast at a time by selecting the contrast from the `analyses` slot:

```{r volcano_enhanced_single_contrast, fig.height=7}
dat_volcano_enhanced_B_A <- moo@analyses$diff[["B-A"]] |>
  plot_volcano_enhanced(
    feature_id_colname = "GeneName",
    change_colname = "logFC",
    signif_colname = "adjpval"
  )
```

#### Summary

Create an enhanced volcano plot for each contrast and compose them in one figure:

```{r volcano_summary, fig.height=10, fig.width=8}
dat_volcano_summary <- moo |>
  plot_volcano_summary()

head(dat_volcano_summary)
```

### Venn Diagram

```{r venn_diagram, fig.width=7, fig.height=7}
venn_dat <- dat_volcano_summary |> plot_venn_diagram()
head(venn_dat)
```

## Customizing plots

```{r print-plots-false, echo = FALSE}
options(moo_print_plots = FALSE)
options(moo_save_plots = FALSE)
```

### Plots from main functions

You can create the plots generated by the main analysis functions directly
so you can customize them to fit your needs.

See the [visualization reference](https://ccbr.github.io/MOSuite/reference/index.html#visualization)
for a full list of plotting functions.

#### Examples

Plot the read depth of the clean counts, using either the `Group` column or the `Batch` column from the metadata for the fill colors:

```{r plot_read_depth}
plot_read_depth(
  moo,
  count_type = "clean",
  group_colname = "Group"
)
plot_read_depth(
  moo,
  count_type = "clean",
  group_colname = "Batch"
)
```


### Customizing ggplot objects

Plotting functions that use ggplot2 return ggplot objects.
You can customize them by adding more ggplot layers, just like any other ggplot.

```{r ggplot2_pca_2D}
plot_pca_2d(
  moo,
  count_type = "batch",
  principal_components = c(1, 2),
  group_colname = "Batch",
  label_colname = "Label"
) +
  ggplot2::labs(
    title = "Principle components of batch-corrected counts",
    caption = "Normalized counts were batch-corrected using svg::ComBat()"
  )
```

### Custom colors

MOSuite comes bundled with a default palette:
```{r display_palette, fig.height=1.5, fig.width=7}
display_palette()
```

When creating a multiOmicDataSet object such as with `create_multiOmicDataSet_from_dataframes()`,
default colors are automatically picked from `mosuite_palette` and set in the analyses slot.
You can access the defaults directly:

```{r colors_slot}
moo@analyses$colors
```

The plotting functions access these colors by default, unless overridden
with the `color_values` argument:

```{r plot_read_depth_custom_colors}
# color palette accessed from moo@analyses$colors[['Group']]
plot_read_depth(
  moo,
  count_type = "clean",
  group_colname = "Group"
)

# color palette overridden by color_values
plot_read_depth(
  moo,
  count_type = "clean",
  group_colname = "Group",
  color_values = c(A = "red", B = "green", C = "blue")
)
```

You can change the default colors in the multiOmicDataSet so that all plotting
functions will use your chosen color palette.

```{r custom_palette}
moo@analyses$colors[["Batch"]] <- c("1" = "#0E7175", "2" = "#C35BCA")
moo@analyses$colors[["Replicate"]] <- c(
  "1" = "#89973D",
  "2" = "#E8B92F",
  "3" = "#A45E41"
)
moo@analyses$colors[["Group"]] <- c(A = "#E69F00", B = "#56B4E9", C = "#009E73")
```

View the colors in a multiOmicDataSet with `display_colors()`:
```{r display_colors, fig.height=5, fig.width=8}
display_colors(moo)
```

Plotting functions will then use the custom colors set in `moo@analyses$colors`:

```{r plots_custom_palette}
plot_read_depth(
  moo,
  count_type = "clean",
  group_colname = "Group"
)
plot_pca_2d(
  moo,
  count_type = "batch",
  group_colname = "Batch"
)
plot_expr_heatmap(
  moo,
  count_type = "norm",
  sub_count_type = "voom",
  group_colname = "Group"
)
```