query_download.Rmd

---
title: '1. xQTLbiolinks: query and download'
author: "RuoFan Daing"
date: "2023-05-03"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{query_download}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
lang: en-US
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  echo=TRUE,
  progress =FALSE,
  comment = "#>"
)
options(rmarkdown.html_vignette.check_title = FALSE)
```


## Load packages:
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=TRUE}
library(xQTLbiolinks)
library(data.table)
library(stringr)
```

```{r, message=FALSE, warning=FALSE, include=FALSE}
temp1 <- tempfile(fileext=".zip")
download.file("http://bioinfo.szbl.ac.cn/xQTL_biolinks/xqtl_data/query_download_vignette_2.zip", temp1)
load(unz(temp1,"query_download_vignette.RData"))
close(file(temp1))
rm(temp1)
```

## xQTL Query:

### Query eQTLs:

####  **Query significant eQTL associations with a variant id across all tissues:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eQTL_sig1 <- xQTLquery_eqtlSig("rs201327123")
eQTL_sig1 <- xQTLquery_eqtlSig("chr1_14677_G_A_b38")
# Query significant eQTL associations with a variant id in a specified tissue:
eQTL_sig1 <- xQTLquery_eqtlSig("chr1_14677_G_A_b38",
                    tissueSiteDetail="Skin - Sun Exposed (Lower leg)")
```
```{r, eval=TRUE}
eQTL_sig1
```
                   
#### **Query eQTL associations for multiple variants:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
varInfo <-  xQTLquery_varPos(chrom="chr1", pos=c(1102708))
eQTL_sig2 <- xQTLquery_eqtlSig(variantName=varInfo$snpId)
```
```{r, eval=TRUE}
head(eQTL_sig2)
```

#### **Query eQTL associations by genes or tissues:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eQTL_sig3 <- xQTLquery_eqtlSig(genes="ATAD3B")
eQTL_sig3 <- xQTLquery_eqtlSig(genes=c("TP53", "SLC35E2B"), tissueSiteDetail= "Brain - Cerebellum")
eQTL_sig3 <- xQTLquery_eqtlSig(genes="ENSG00000141510.16")
```
```{r, eval=TRUE}
head(eQTL_sig3)
```

#### **Query eQTL associations with a variant-gene pair:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eQTL_sig4 <- xQTLquery_eqtlSig(variantName="rs1641513", genes="TP53")
eQTL_sig4 <- xQTLquery_eqtlSig(variantName="chr1_1667948_A_G_b38",
                     genes="SLC35E2B", tissueSiteDetail="Kidney - Cortex")
```
```{r, eval=TRUE}
eQTL_sig4
```

**Multi-tissue eQTL metasoft results for a given gene and variant can be also queried using `xQTLquery_eqtl`, the results include: m-value (mValue), normalized effect size (nes), p-value (pValue) and standard error (se).**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
# Query with a gene symbol:
eqtlMeta <- xQTLquery_eqtl(gene="TP53")
# Query with a variant-gene pair:
eqtlMeta <- xQTLquery_eqtl(variantName="rs1641513",gene="TP53")
```
```{r, eval=TRUE}
head(eqtlMeta)
```

### Query sQTLs:

#### **Query sQTL associations with rsid:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sQTL_sig1 <- xQTLquery_sqtlSig(variantName="rs201327123")
sQTL_sig1 <- xQTLquery_sqtlSig(variantName="chr1_14677_G_A_b38", tissueSiteDetail="Whole Blood")
```
```{r, eval=TRUE}
sQTL_sig1
```

#### **Query sQTL associations with gene symbol and gencode ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sQTL_sig2 <- xQTLquery_sqtlSig(genes="ENSG00000141510.16", tissueSiteDetail="Lung" )
sQTL_sig2 <- xQTLquery_sqtlSig(genes=c("ATAD3B", "MLH1"))
```
```{r, eval=TRUE}
sQTL_sig2
```

#### **Query sQTL associations with the variant-genes pair:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sQTL_sig3 <- xQTLquery_sqtlSig(variantName="rs201327123", genes=c("WASH7P","RP11-206L10.2"))
sQTL_sig3 <- xQTLquery_sqtlSig(variantName="chr17_7465085_A_G_b38", genes="TP53", 
                               tissueSiteDetail="Lung")
```
```{r, eval=TRUE}
sQTL_sig3
```

## xQTLs Download
### eQTL Download:
#### **Download all eQTL associations for MLH1-rs13315355 pair in all tissues from all studies:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eqtlAssos <- xQTLdownload_eqtlAllAsso(gene="MLH1", variantName = "rs13315355", study="")
```

#### **Download all eQTL associations for gene ATP11B in Muscle - Skeletal from GTEx_V8:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eqtlAssos <- xQTLdownload_eqtlAllAsso("ATP11B", tissueLabel="Muscle - Skeletal")
```
##### **A more fast way to download eQTL association for a given gene is using "liLab" data source with paramater `data_source="liLab"` (only support GTEx tissues)**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eqtlAssos <- xQTLdownload_eqtlAllAsso("ATP11B", tissueLabel="Muscle - Skeletal", data_source = "liLab")
# gencode ID is recommended:
eqtlAssos <- xQTLdownload_eqtlAllAsso("ENSG00000058063.15", tissueLabel="Muscle - Skeletal", data_source = "liLab")
```

#### **Download all eQTL associations for SNP rs11568818 in all tissues from all supported studies:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eqtlAssos <- xQTLdownload_eqtlAllAsso(variantName="rs11568818", study="")
```

#### **Download all eQTL associations of SNP rs11568818 in Muscle - Skeletal from GTEx_V8:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eqtlAssos <- xQTLdownload_eqtlAllAsso(variantName="chr11_102530930_T_C_b38",
                                   tissueLabel="Muscle - Skeletal", study="GTEx_V8")
```

#### **Download all eQTL associations for gene ATP11B in CD4+ T cell from all supported studies:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eqtlAssos <- xQTLdownload_eqtlAllAsso(gene="MMP7",tissueLabel = "CD4+ T cell", study="")
```

```{r, eval=TRUE}
eqtlAssos
```

### sQTL Download:
#### **Download all sQTL associations for gene MMP7 and TP53 in Lung:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sqtlAssos<-xQTLdownload_sqtlAllAsso(genes=c("MMP7","TP53"), geneType = "geneSymbol",  tissue="Lung")
```
```{r, eval=TRUE}
sqtlAssos
```

### 3'aQTL Download:
#### **Download all 3'aQTL associations for gene MMP7 in Lung:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
aqtlAssos <- xQTLdownload_xqtlAllAsso(genes=c("MMP7"), tissue="Lung")
```
```{r, eval=TRUE}
aqtlAssos
```


### mQTL Download:
#### **Download all mQTL associations with cgp_id "cg00000221" in Prostate:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
mQTL_meta<- xQTLdownload_mqtlmeta("Prostate")
mQTL_dt <- xQTLdownload_mQTL(cpg_id="cg00000221", tissue_name="Prostate")
```
```{r, eval=TRUE}
mQTL_dt
```



### hQTL Download:
#### **Download all hQTL associations for H3K4ME1 in T cell:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
hqtlmeta <- xQTLdownload_hqtlmeta(histone_type="H3K4ME1", cell_type="T cell")
hQTL_dt <- xQTLdownload_hqtl(phenotype_id="10:10458128-10465096", 
                             histone_type="H3K4ME1", cell_type="T cell")
```
```{r, eval=TRUE}
hQTL_dt
```


### Single-cell eQTLs (sc-eQTLs) Download:
#### **Download Cell-type eQTLs for gene TP53 in B cell from study `Resztak2022biorxiv`:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
# Get details of sc-eQTL study:
study_info <- xQTLquery_scInfo()
sceQTL_dt <- xQTLdownload_sc(gene="TP53", cell_type = "B Cell", cell_state="-",
                qtl_type="Cell-type-specific eQTL", study_name = "Resztak2022biorxiv")
```
```{r, eval=TRUE}
sceQTL_dt
```

## Query details of gene, variant, tissue and samples in GTEx:

#### **Query gene details with gene symbols, versioned or unversioned gencode ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
geneInfo <- xQTLquery_gene("TP53")
geneInfo <- xQTLquery_gene(c("tp53","naDK","SDF4") )
geneInfo <- xQTLquery_gene(c("ENSG00000210195.2","ENSG00000078808"))
```
```{r, eval=TRUE}
geneInfo
```

#### **Query variants using dbSNP ID or variant ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
varInfo <- xQTLquery_varId("rs12596338")
varInfo <- xQTLquery_varId("chr11_66561248_T_C_b38")
varInfo <- xQTLquery_varPos(chrom="chr1", pos=c(1102708,1105739))
```
```{r, eval=TRUE}
varInfo
```

#### **Query tissue using tissue name:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
tissueAll <- xQTLquery_tissue() # fetch all tissues in GTEx
Brain <- xQTLquery_tissue("Brain")
```
```{r, eval=TRUE}
Brain
```


#### **Query sample using tissue name or sample ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sampleInfo <- xQTLquery_sampleByTissue("Brain - Amygdala" )
sampleInfo <- xQTLquery_sampleByTissue(tissueSiteDetail="Liver", pathologyNotesCategories=TRUE)
sampleIds <- c("GTEX-11NUK-0011-R4a-SM-DO12B", "GTEX-11ONC-0011-R4b-SM-DO93H",
               "GTEX-11DXY-0526-SM-5EGGQ", "GTEX-13OVJ-1026-SM-5IFGI")
sampleInfo <- xQTLquery_sampleBySampleId(sampleIds)
```
```{r, eval=TRUE}
sampleInfo
```

## xQTL expression download
### Download normalized expression of gene for a eQTL pair.
#### **Download exp with variant-gene pair in different tissues:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eQTLexp <- xQTLdownload_eqtlExp(variantName="rs1641513",gene="TP53", tissueSiteDetail="Liver")
```

#### **Download expression using variant ID and gencode ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eQTLexp <- xQTLdownload_eqtlExp(variantName="chr1_14677_G_A_b38",gene="ENSG00000228463.9",
                                tissueSiteDetail="Stomach")
```
```{r, eval=TRUE}
eQTLexp
```

### Download normalized intron-excision ratio of intron for a sQTL pair.
#### **Download normalized intron-excision ratio in different tissues:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sQTLratio <- xQTLdownload_sqtlExp(variantName="rs1450891501",
                                phenotypeId="chr1:497299:498399:clu_54863:ENSG00000239906.1",
                                tissueSiteDetail="Lung")
```

#### **Dowload normalized intron-excision ratio using variant ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sQTLratio <- xQTLdownload_sqtlExp(variantName="chr1_1259424_T_C_b38",
                                phenotypeId=" chr1:1487914:1489204:clu_52051:ENSG00000160072.19",
                                tissueSiteDetail="Adipose - Subcutaneous")
```
```{r, eval=TRUE}
sQTLratio
```

## eGene/sGene download
### Download details of eGenes (eQTL Genes) for a specified gene or a tissue.
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
eGeneInfo <- xQTLdownload_egene(tissueSiteDetail="Prostate", recordPerChunk=2000)
eGeneInfo <- xQTLdownload_egene("TP53")
```
```{r, eval=TRUE}
eGeneInfo
```


### Download details of sGenes (sQTL Genes) for a specified gene or a tissue.
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
sGeneInfo <- xQTLdownload_sgene(tissueSiteDetail="Liver")
sGeneInfo <- xQTLdownload_sgene(gene="DDX11", tissueSiteDetail="Liver" )
```
```{r, eval=TRUE}
eGeneInfo
```



## Gene expression download
### Download normalized gene expression at the sample level in a specified tissue:

#### **Download gene expression with a genecode ID:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
expProfiles <- xQTLdownload_exp("ENSG00000210195.2", tissueSiteDetail="Liver")
```

#### **Download gene expression into a SummarizedExperiment object:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
expProfiles <- xQTLdownload_exp("ENSG00000210195.2", tissueSiteDetail="Liver",
               toSummarizedExperiment=TRUE)
# extract expression profile from SummarizedExperiment object:
expDT <- SummarizedExperiment::assay(expProfiles)
# extract samples' detail from SummarizedExperiment object:
sampleDT <- SummarizedExperiment::colData(expProfiles)
```

#### **Download gene expression profiles for multiple genes:**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
expProfiles <- xQTLdownload_exp(c("tp53","naDK","SDF4"),
                                tissueSiteDetail="Artery - Coronary",
                                pathologyNotesCategories=TRUE)
```

#### **Download using versioned and unversioned gencode Id.**
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
expProfiles <- xQTLdownload_exp(c("ENSG00000141510.16","ENSG00000008130.15","ENSG00000078808"),
                               tissueSiteDetail="Artery - Coronary")
```
```{r, eval=TRUE}
expProfiles[,1:12]
```


### Download median expression of all samples for specified genes across tissues.
```{r, results = 'hide', echo=TRUE, message=FALSE, warning=FALSE, eval=FALSE}
geneMedExp <- xQTLdownload_geneMedExp(genes=c("TP53", "IRF5"))
```
```{r, eval=TRUE}
geneMedExp
```