---
title: "Visualization of ColocBoost Results"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Visualization of ColocBoost Results}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dpi = 80
)
```

This vignette demonstrates how to visualize and interpret the output of ColocBoost results.

```{r setup}
library(colocboost)
```

**Causal variants (simulated)**

The dataset features two causal variants with indices 194 and 589.

- Causal variant 194 is associated with traits 1, 2, 3, and 4.
- Causal variant 589 is associated with traits 2, 3, and 5.

```{r run-colocboost}
# Loading the Dataset
data(Ind_5traits)
# Run colocboost 
res <- colocboost(X = Ind_5traits$X, Y = Ind_5traits$Y)
```

## 1. Default plot function

The default plot of the colocboost results provides a visual representation of the colocalization events.

- The x-axis indicates the indices of variants, and the y-axis indicates the -log10(p-value) from marginal associations.
- The colors of the points represent the colocalization events, with different colors indicating different colocalization events.

```{r basic-plot}
colocboost_plot(res)
```

**Parameters to adjust plot**

- `plot_cols = 2` (default) indicates the number of columns in the plot.
- `y = "log10p"` (default) with optional 
    - `y = "z_original"` for z-scores
    - `y = "vcp"` for variant colocalization probabilities (single plot for all variants),
    - `y = "coef"` for regression coefficients estimated from the ColocBoost model.
    - `y = "cos_vcp"` for variant colocalization probabilities (multiple plots for each CoS - only draw VCP for variants in CoS to the colocalized traits).
- `plot_cos_idx = NULL` (default) indicates all colocalization events are plotted. `plot_cos_idx = 1` can be specified to plot the 1st colocalization event, and so on.
- `outcome_idx = NULL` (default) indicates only the traits with colocalization are plotted. `outcome_idx = c(1,2,5)` can be specified to plot the traits 1, 2, and 5.
- `plot_all_outcome = FALSE` (default) indicates only the traits with colocalization are plotted. If `TRUE`, it will plot all traits.
- `cos_color = NULL` (default) indicates the colors of the colocalization events. Specify a vector of colors to customize the plot.


## 2. Advanced options

There are several advanced options available for customizing the plot by deepening the visualization of the colocboost results.

### 2.1. Plot with a zoom-in region

You can specify a zoom-in region by providing a `grange` argument, which is a vector indicating the indices of the region to be zoomed in.

```{r zoomin-plot}
colocboost_plot(res, grange = c(1:400))
```


### 2.2. Plot with marked top variants

You can highlight the top variants in the plot by setting `show_top_variables = TRUE`. This will add a red circle to top variants with highest VCP for each CoS.

```{r top-plot}
colocboost_plot(res, show_top_variables = TRUE)
```


### 2.3. Plot CoS variants to uncolocalized traits to diagnostic the colocalization.

There are three options available for plotting the CoS variants to uncolocalized traits:

- `show_cos_to_uncoloc = FALSE` (default), if `TRUE` will plot all CoS variants to all uncolocalized traits.
- `show_cos_to_uncoloc_idx = NULL` (default), if specified, will plot the specified CoS variants to all uncolocalized traits.
- `show_cos_to_uncoloc_outcome = NULL` (default), if specified, will plot the all CoS variants to the specified uncolocalized traits.

```{r ucos-plot}
colocboost_plot(res, show_cos_to_uncoloc = TRUE)
```

### 2.4. Plot with an added vertical line

You can add a vertical line to the plot by setting `add_vertical = TRUE` and `add_vertical_idx = **`. This will add a vertical line at the specified index.
For example, to add a vertical line at true causal variants, you can set `add_vertical_idx = unique(unlist(Ind_5traits$true_effect_variants))`.
Following plot also shows the top variants.


```{r vertical-plot}
colocboost_plot(
  res, show_top_variables = TRUE, 
  add_vertical = TRUE, 
  add_vertical_idx = unique(unlist(Ind_5traits$true_effect_variants))
)
```


### 2.5. Plot with trait-specific sets if exists

There are two options available for plotting the trait-specific (uncolocalized) variants:

- `plot_ucos = FALSE` (default), if `TRUE` will plot all trait-specific (uncolocalized) sets.
- `plot_ucos_idx = NULL` (default) indicates all confidence sets are plotted. `plot_ucos_idx = 1` can be specified to plot the 1st uncolocalized confidence sets, and so on.

*Important Note*: You should use `colocboost(..., output_level = 2)` to obtain the trait-specific (uncolocalized) information.

```{r trait-specific}
# Create a mixed dataset
data(Ind_5traits)
data(Heterogeneous_Effect)
X <- Ind_5traits$X[1:3]
Y <- Ind_5traits$Y[1:3]
X1 <- Heterogeneous_Effect$X
Y1 <- Heterogeneous_Effect$Y[,1,drop=F]

# Run colocboost
res <- colocboost(X = c(X, list(X1)), Y = c(Y, list(Y1)), output_level = 2)
colocboost_plot(res, plot_ucos = TRUE)
```

In this example, there are two colocalized sets (<span style="color:blue">blue</span> and <span style="color:orange">orange</span>) and
two trait-specific sets for trait 4 only (<span style="color:green">green</span> and <span style="color:purple">purple</span>).
For comprehensive tutorials on result interpretation, please visit our tutorials portal 
at [Interpret ColocBoost Output](https://statfungen.github.io/colocboost/articles/Interpret_ColocBoost_Output.html).



### 2.6 Plot with focal trait for disease prioritized colocalization

There are three options available for plotting the results from disease prioritized colocalization, considering a focal trait:

- `plot_focal_only = FALSE` (default), if `TRUE` will only plot CoS with focal trait and ignoring other CoS.
- `plot_focal_cos_outcome_only = FALSE` (default) and **recommend** for visualization for disease prioritized colocalization.
If `TRUE` will plot all CoS colocalized with at least on traits within CoS of focal traits.

```{r focal-colocalization}
# Create a mixed dataset
data(Ind_5traits)
data(Sumstat_5traits) 
X <- Ind_5traits$X[1:3]
Y <- Ind_5traits$Y[1:3]
sumstat <- Sumstat_5traits$sumstat[4]
LD <- get_cormat(Ind_5traits$X[[1]])

# Run colocboost
res <- colocboost(X = X, Y = Y, 
                  sumstat = sumstat, LD = LD, 
                  focal_outcome_idx = 4)

# Only plot CoS with focal trait
colocboost_plot(res, plot_focal_only = TRUE)
# Plot all CoS including at least one traits colocalized with focal trait
colocboost_plot(res, plot_focal_cos_outcome_only = TRUE)
```