---
title: "Summary Statistics Data Colocalization"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Summary Statistics Data Colocalization}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette demonstrates how to perform multi-trait colocalization analysis using summary statistics data, 
specifically focusing on the `Sumstat_5traits` dataset included in the package.


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


# 1. The `Sumstat_5traits` Dataset

The `Sumstat_5traits` dataset contains 5 simulated summary statistics, where it is directly derived from the `Ind_5traits` dataset using marginal association.
The dataset is specifically designed to evaluate and demonstrate the capabilities of ColocBoost in multi-trait colocalization analysis with summary association data.

- `sumstat`: A list of data.frames of summary statistics for different traits.
- `true_effect_variants`: True effect variants indices for each trait.
- Note that `LD` could be calculated from the `X` data in the `Ind_5traits` dataset, but it is not included in the `Sumstat_5traits` dataset.

### Causal variant structure
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.

This structure creates a realistic scenario in which multiple traits are influenced by different but overlapping sets of genetic variants.

```{r load-summary-data}
# Loading the Dataset
data("Sumstat_5traits")
names(Sumstat_5traits)
Sumstat_5traits$true_effect_variants
```

Due to the file size limitation of CRAN release, this is a subset of simulated data. See full dataset in [colocboost paper repo](https://github.com/StatFunGen/colocboost-paper).

### Important data format for summary data
`sumstat` must include the following columns:

- `z` or (`beta`, `sebeta`): either z-score or (effect size and standard error)
- `n`: sample size for the summary statistics. **Highly recommended**: Providing the sample size, or even a rough estimate of `n`,
is highly recommended. Without `n`, the implicit assumption is `n` is large (Inf) and the effect sizes are small (close to zero). 
- `variant`: required if `sumstat` for different outcomes do not have the same number of variables (multiple `sumstat` and multiple `LD`).


```{r summary-data-format}
class(Sumstat_5traits$sumstat[[1]])
head(Sumstat_5traits$sumstat[[1]])
```

# 2. Multiple summary statistics data with shared LD reference


The preferred format for colocalization analysis in ColocBoost using summary statistics data is where one LD matrix is provided for all traits, 
and the summary statistics are organized in a list. The **Basic format** is 

- `sumstat` is organized as a list of data.frames for all traits
- `LD` is a matrix of linkage disequilibrium (LD) information for all variants across all traits.


This function requires specifying summary statistics `sumstat` and LD matrix `LD` from the dataset:
```{r one-LD}
# Extract genotype (X) and calculate LD matrix
data("Ind_5traits")
LD <- get_cormat(Ind_5traits$X[[1]])

# Run colocboost
res <- colocboost(sumstat = Sumstat_5traits$sumstat, LD = LD)

# Identified CoS
res$cos_details$cos$cos_index

# Plotting the results
colocboost_plot(res)
```

Alternatively, you can provide the reference panel genotype matrix directly through `X_ref`, which avoids storing the full LD matrix:

```{r one-X-ref}
# Use reference genotype directly instead of precomputing LD
X_ref <- Ind_5traits$X[[1]]

# Run colocboost
res <- colocboost(sumstat = Sumstat_5traits$sumstat, X_ref = X_ref)

# Identified CoS
res$cos_details$cos$cos_index
```


### Results Interpretation

For comprehensive tutorials on result interpretation and advanced visualization techniques, please visit our tutorials portal 
at [Visualization of ColocBoost Results](https://statfungen.github.io/colocboost/articles/Visualization_ColocBoost_Output.html) and
[Interpret ColocBoost Output](https://statfungen.github.io/colocboost/articles/Interpret_ColocBoost_Output.html).


# 3. Other summary statistics and LD input combinations

## 3.1. Matched LD with multiple sumstat (Trait-specific LD)   

When studying multiple traits with their own trait-specific LD matrices, you could provide a list of LD matrices matched with a list of summary statistics.

- **Basic format**: `sumstat` and `LD` are organized as lists, matched by trait index,
    - `(sumstat[1], LD[1])` contains information for trait 1,
    - `(sumstat[2], LD[2])` contains information for trait 2,
    - And so on for each trait under analysis.
- **Cross-trait flexibility**: 
    - There is no requirement for the same variants across different traits. This allows for the analysis of traits with available variants.
    - This is particularly useful when you have a large dataset with many traits and want to focus on specific variants and trait-specific LD.

```{r matched-LD}
# Duplicate LD with matched summary statistics
LD_multiple <- lapply(1:length(Sumstat_5traits$sumstat), function(i) LD )

# Run colocboost
res <- colocboost(sumstat = Sumstat_5traits$sumstat, LD = LD_multiple)

# Identified CoS
res$cos_details$cos$cos_index
```


## 3.2. LD matrix is a superset of variants across different summary statistics

When the LD matrix includes a superset of variants across different summary statistics, with **Input Format**:

- `sumstat` is a list of data.frames for all traits
- `LD` is a matrix of linkage disequilibrium (LD) information for all variants across all traits.
- The LD matrix should contain superset of variants presented in the summary statistics data frames.
- This is particularly useful when you have a large LD matrix from a reference panel and want to use it for multiple summary statistics datasets. 
It allows for efficient analysis without redundancy.


```{r superset-LD}
# Create sumstat with different number of variants - remove 100 variants in each sumstat
LD_superset <- LD
sumstat <- lapply(Sumstat_5traits$sumstat, function(x) x[-sample(1:nrow(x), 20), , drop = FALSE])

# Run colocboost
res <- colocboost(sumstat = sumstat, LD = LD_superset)

# Identified CoS
res$cos_details$cos$cos_index
```


## 3.3. Arbitrary LD and sumstat with dictionary provided

When studying multiple traits with arbitrary LD matrices for different summary statistics, 
we also provide the interface for arbitrary LD matrices with multiple sumstat. 
This particularly benefits meta-analysis across heterogeneous datasets where, 
for different subsets of summary statistics, LD comes from different populations.

- **Input Format**:
    - `sumstat = list(sumstat1, sumstat2, sumstat3, sumstat4, sumstat5)` is a list of data.frames for all traits.
    - `LD = list(LD1, LD2)` is a list of LD matrices.
    - `dict_sumstatLD` is a dictionary matrix that index of sumstat to index of LD.


```{r dictionary-mapped}
# Create a simple dictionary for demonstration purposes
LD_arbitrary <- list(LD, LD) # traits 1 and 2 matched to the first genotype matrix; traits 3,4,5 matched to the third genotype matrix.
dict_sumstatLD = cbind(c(1:5), c(1,1,2,2,2))

# Display the dictionary
dict_sumstatLD

# Run colocboost
res <- colocboost(sumstat = Sumstat_5traits$sumstat, LD = LD_arbitrary, dict_sumstatLD = dict_sumstatLD)

# Identified CoS
res$cos_details$cos$cos_index
```


## 3.4. Using a reference panel genotype matrix (X_ref) instead of LD

When the number of variants P is very large, storing the full P x P LD matrix may be infeasible.
If you have the reference panel genotype matrix from which LD would be computed, you can pass it directly via `X_ref`.
ColocBoost will compute LD products on the fly, avoiding the P x P memory cost.

This is beneficial when the reference panel sample size (N_ref) is less than the number of variants (P).
When N_ref >= P, ColocBoost automatically precomputes the LD matrix internally for efficiency.

Provide either `LD` or `X_ref`, not both. The `dict_sumstatLD` dictionary works with `X_ref` the same way as with `LD`.

```{r x-ref-example}
# Use genotype matrix directly as reference panel
data("Ind_5traits")
X_ref <- Ind_5traits$X[[1]]

# Run colocboost with X_ref instead of LD
res <- colocboost(sumstat = Sumstat_5traits$sumstat, X_ref = X_ref)

# Identified CoS
res$cos_details$cos$cos_index
```


## 3.5. HyPrColoc compatible format: effect size and standard error matrices

ColocBoost also provides a flexibility to use HyPrColoc compatible format for summary statistics with and without LD matrix.

```{r hyprcoloc-compatible}
# Loading the Dataset
data(Ind_5traits)
X <- Ind_5traits$X
Y <- Ind_5traits$Y

# Coverting to HyPrColoc compatible format
effect_est <- effect_se <- effect_n <- c()
for (i in 1:length(X)){
  x <- X[[i]]
  y <- Y[[i]]
  effect_n[i] <- length(y)
  output <- susieR::univariate_regression(X = x, y = y)
  effect_est <- cbind(effect_est, output$beta)
  effect_se <- cbind(effect_se, output$sebeta)
}
colnames(effect_est) <- colnames(effect_se) <- c("Y1", "Y2", "Y3", "Y4", "Y5")
rownames(effect_est) <- rownames(effect_se) <- colnames(X[[1]])

# Run colocboost
LD <- get_cormat(Ind_5traits$X[[1]])
res <- colocboost(effect_est = effect_est, effect_se = effect_se, effect_n = effect_n, LD = LD)

# Identified CoS
res$cos_details$cos$cos_index
```

See more details about data format to implement LD-free ColocBoost and LD-mismatch diagnosis in [LD mismatch and LD-free Colocalization](https://statfungen.github.io/colocboost/articles/LD_Free_Colocalization.html)).

