---
title: 'disgenet2r: An R package to explore the molecular underpinnings of human diseases'
author: IBI group
date: "`r Sys.Date()`"
output:
  prettydoc::html_pretty:
    highlight: github
    toc: yes
  pdf_document:
    toc: yes
  html_document:
    df_print: paged
    toc: yes
bibliography: disgenet2r.bib
biblio-style: apalike
vignette: |
  
  %\usepackage[utf8]{inputenc} %\VignetteEncoding{UTF-8} %\VignetteIndexEntry{disgenet2r: An R package to explore the molecular underpinnings of human diseases} %\VignetteEngine{knitr::rmarkdown}
---

```{r style, echo=FALSE, results="asis", message=FALSE}
knitr::opts_chunk$set(tidy = FALSE,
                      warning = FALSE,
                      message = FALSE,
                      cache = F)
```


# Introduction

\noindent The **disgenet2r** package contains a set of functions to retrieve, visualize and expand [DisGeNET](www.disgenet.org) data. DisGeNET is a discovery platform that contains information about the genetic basis of human diseases [@Pinero2015; @Pinero2017; @Pinero2019]. DisGeNET integrates data from several expert curated databases and from text-mining the biomedical literature.   

\noindent The current version of DisGeNET (v7.0) contains 1134942 gene-disease associations (GDAs), between 21671 genes and 30170 diseases, disorders, traits, and clinical or abnormal human phenotypes, and 369554 variant-disease associations (VDAs), between 194515 variants and 14155 diseases, traits, and phenotypes.



\noindent The information in DisGeNET is organized according to the original data source (Table 1). 
Diseases are identified using the UMLS concept unique identifier (CUI), but mappings to commonly employed biomedical vocabularies such as MeSH, OMIM, DO, HPO, and ICD-9 are also provided. The genes are identified using the NCBI Entrez Identifier, but annotations to the official gene symbol, the UniProt identifier, and the Panther Protein Class are also supplied. Finally, the GDAs and VDAs can be ranked using the DisGeNET score. The DisGeNET score ranges from 0 to 1, and takes into account the evidence supporting the association (See more information at [http://disgenet.org/dbinfo/](http://disgenet.org/dbinfo/ "DisGeNET's information"))

\noindent DisGeNET data is also represented as a Resource Description Framework (RDF), which provides new opportunities for data integration, making possible to link DisGeNET data to other external RDF datasets [@Queralt-Rosinach2016]. 

Table: Sources of DisGeNET data

```{r echo=FALSE,  message=FALSE}
library(kableExtra)
table1 <- data.frame(
  Source_Name = 
    c("CTD_human", "CGI", "CLINGEN", "GENOMICS_ENGLAND", "ORPHANET", "PSYGENET",  "HPO",
           "UNIPROT", "CLINVAR", "GWASCAT", "GWASDB" ,
        "CTD_mouse",   "MGD", "CTD_rat", "RGD", 
        "BEFREE",  "LHGDN",
        "CURATED", "INFERRED", "ANIMAL_MODELS", "ALL"), 
  Type_of_data= c("GDAs","GDAs","GDAs", "GDAs", "GDAs", "GDAs", "GDAs",
                  "GDAs/VDAs", "GDAs/VDAs", "GDAs/VDAs", "GDAs/VDAs", 
                  "GDAs",  "GDAs", "GDAs","GDAs",
                  "GDAs/VDAs", "GDAs", 
                  "GDAs/VDAs", "GDAs", "GDAs", "GDAs/VDAs"), 
  Description =c("The Comparative Toxicogenomics Database, human data", 
               "The Cancer Genome Interpreter",
               "The Clinical Genome Resource", 
               "The Genomics England PanelApp", "The portal for rare diseases and orphan drugs", 
               "Psychiatric disorders Gene association NETwork",
               "Human Phenotype Ontology",
               "The Universal Protein Resource", 
               "ClinVar, public archive of relationships among sequence variation and human phenotype",
               "The NHGRI-EBI GWAS Catalog", "The GWas Database",
               "The Comparative Toxicogenomics Database, Mus musculus data",
               "The Mouse Genome Database", 
               "The Comparative Toxicogenomics Database, Rattus norvergicus data",
               "The Rat Genome Database", 
               "Data from text mining medline abstracts using the BeFree System [@Bravo2015]" ,
               "Literature-derived human gene-disease network generated by text mining NCBI GeneRIFs [@Bundschus2008]" ,
            "Human curated sources: CTD, ClinGen, CGI, UniProt, Orphanet, PsyGeNET,  Genomics England PanelApp", "Inferred data from: HPO,ClinVar, GWASCat, GwasDB", 
               "Data from animal models: CTD_rat, RGD, CTD_mouse, MGD", 
               "All data sources"
               )) 
 
kable(table1) %>%   kable_styling(bootstrap_options = "striped", full_width = F)
                               

```


# Contact
For questions regarding **disgenet2r**, contact our support account at <support@disgenet.org>.


# Installation and first run 

\noindent The package **disgenet2r** is available through Bitbucket.
The package requires an R version > 3.5. Additionally, the following packages are needed:
VennDiagram, stringr, tidyr, SPARQL, RCurl, igraph, ggplot2, and reshape2.

\noindent Install **disgenet2r** by typing in R:

```{r   message=FALSE, eval=F, warning=F}
library(devtools)
install_bitbucket("ibi_group/disgenet2r")
``` 

 To load the package:

```{r warning = FALSE, message = FALSE}
library(disgenet2r)
``` 

To be able to use the **disgenet2r** package, you need to register for a free account [here](http://disgenet.org/signup). Once you have completed the registration process, use the **get_disgenet_api_key** to retrieve your API key.


```{r warning = FALSE, eval =F, message = FALSE}

disgenet_api_key <- get_disgenet_api_key(
                  email = "user@email.com", 
                  password = "myspwd" )

``` 

After retrieving the API key, run the line below so the key is available for all the **disgenet2r** functions. 


```{r, warning = FALSE, message = FALSE, eval=F}
Sys.setenv(DISGENET_API_KEY= disgenet_api_key)
```


 In the following document, we illustrate how to use the **disgenet2r** package through a series of examples. 

# Retrieving Gene-Disease Associations from DisGeNET

## Searching by gene

\noindent The **gene2disease** function retrieves the GDAs in DisGeNET for a given gene, or a for a list of genes. The gene(s) can be identified by either the NCBI gene identifier, or the official Gene Symbol, and the type of identifier used must be specified using the parameter `vocabulary`. By default, `vocabulary = "HGNC"`, to switch to Entrez NCBI Gene identifiers, set vocabulary to *ENTREZ*. 

\noindent The function also requires the user to specify the source database using the argument `database`. By default, all the functions in the **disgenet2r** package use as source database *CURATED*, which includes GDAs from CTD (human data), PsyGeNET, the HPO, Genomics England PanelApp, ClinGen, CGI, UniProt, and Orphanet.

\noindent The information can be filtered using the DisGeNET score. The argument `score` is filled with a range of score to perform the search. The score is entered as a vector which first position is the initial value of score, and the second argument is the final value of score. Both values will always be included. By default, `score=c(0,1)`.


\noindent In the example, the query for the Leptin Receptor (Gene Symbol `LEPR`, and Entrez NCBI Identifier `3953`) is performed in all databases in DisGeNET (`database = "ALL"`). 

```{r, warning = FALSE, message = FALSE}
data1 <- gene2disease( gene = 3953, vocabulary = "ENTREZ",
                       database = "CURATED")
```

\noindent The function **gene2disease** produces an object `DataGeNET.DGN` that contains the results of the query.

```{r, warning = FALSE, message = FALSE}
class(data1)
```

\noindent Type the name of the object to display its attributes: the input parameters such as whether a single entity, or a list were searched (`single` or `list`), the type of entity (`gene-disease`), the selected database (`ALL`), the score range used in the search (`0-1`), and the gene NCBI identifier (`3953`).

```{r, warning = FALSE, message = FALSE}
data1


```

\noindent To obtain the data frame with the results of the query, apply the **extract** function:

```{r, warning = FALSE, message = FALSE}
results <- extract(data1)
head( results, 3 )
```

\noindent The same query can be performed using the Gene Symbol (`LEPR`). Additionally, a minimum threshold for the score can be defined. In the example, a cutoff of `score=c(0.2,1)` is used. Notice how the number of diseases associated to the Leptin Receptor drops from 264 to 68 when the score is restricted. 


```{r, warning = T, echo=F, message = FALSE}
data1 <- gene2disease( gene = "LEPR",
                        vocabulary = "HGNC",
                       database = "ALL",
                       score =c(0.3,1))
data1
results <- extract(data1)

```

### Visualizing the diseases associated to a single gene

\noindent The **disgenet2r** package offers two options to visualize the results of querying DisGeNET for a single gene: a  network showing the diseases associated to the gene of interest (`Gene-Disease Network`), and a network showing the MeSH Disease Classes of the diseases associated to the gene (`Gene-Disease Class Network`). These graphics can be obtained by changing the `class` argument in the plot function.

\noindent By default, the **plot** function produces a `Gene-Disease Network` on a `DataGeNET.DGN` object (Figure 1). In the `Gene-Disease Network` the blue nodes are diseases, the pink nodes are genes, and the width of the edges is proportional to the score of the association. The `prop` parameter allows to adjust the width of the edges while keeping the proportionality to the score. 

 
```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 1: The **Gene-Disease Network** for the Leptin Receptor gene"}

plot( data1,
      class = "Network",
      prop = 20)


```


\noindent The results can also be visualized in a network in which diseases are grouped by the MeSH Disease Class if the `class` argument is set to "DiseaseClass" (`Gene-Disease Class Network`, Figure 2). In the `Gene-Disease Class Network`, the node size of is proportional to the fraction of diseases in the disease class, with respect to the total number of diseases with disease classes associated to the gene. In the example, the Lepin Receptor is associated mainly to Nutritional and Metabolic Diseases. There is 1 disease in the example that does not have annotations to MeSH disease class (Shown as a warning).

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 2: The **Disease Class Network** for the Leptin Receptor Gene"}
plot( data1,
      class = "DiseaseClass",
      prop = 3)

```

### Exploring the evidences associated to a gene

You can extract the evidences associated to a particular gene using the function  **gene2evidence**. Additionally, you can explore the evidences for a specific gene-disease pair by specifying the disease identifier using the argument  `disease`.

```{r, warning = T, echo=T, message = FALSE}
data1 <- gene2evidence( gene = "LEPR",
                        vocabulary = "HGNC",
               disease ="C3554225",
                       database = "ALL",
                       score =c(0.3,1))
data1
results <- extract(data1)

```

The results are shown in the table below. 
```{r, warning = T, echo=F, message = FALSE}

kable(results[, c("pmid", "year", "sentence")], caption = "Evidences supporting the association between LEPR & C3554225") %>%   kable_styling(bootstrap_options = "striped", full_width = F)

```

 
## Searching multiple genes

\noindent The **gene2disease** function can also receive a list of genes as input, either as NCBI Gene Identifiers or Gene Symbols. In the example, we show how to create a vector with the Gene Symbols of several genes belonging to the family of voltage-gated potassium channels (Table 2) and then, we apply the function **gene2disease**.

Table 2: Example of voltage-gated potassium channel family members

```{r echo=FALSE,  message=FALSE,}
table1 <- data.frame(
  Name = c("KCNE1", "KCNE2", "KCNH1",  "KCNH2", "KCNG1"), 
  Description =c(
    "potassium channel, voltage gated subfamily E regulatory beta subunit 1", 
    "potassium channel, voltage gated subfamily E regulatory beta subunit 2",
    "potassium channel, voltage gated eag related subfamily H, member 1", 
    "potassium channel, voltage gated eag related subfamily H, member 2", 
    "potassium voltage-gated channel modifier subfamily G member 1"     )) 
kable(table1) %>%   kable_styling(bootstrap_options = "striped", full_width = F)
                               

```

\noindent Creating the vector with the list of genes belonging to the voltage-gated potassium channel family. 

```{r, warning = T, echo=T, message = FALSE}
myListOfGenes <- c( "KCNE1", "KCNE2", "KCNH1", "KCNH2", "KCNG1")
```


\noindent The **gene2disease** function also requires the user to specify the source database using the argument `database`, and optionally, the DisGeNET `score` can also be applied to filter the results.

```{r, warning = T, echo=T, message = FALSE}
data2 <- gene2disease(
  gene     = myListOfGenes,
  score =c(0.2, 1),
  verbose  = TRUE
)

data2
```

### Visualizing  the diseases associated to multiple genes

\noindent By default, plotting a `DataGeNET.DGN` resulting of the query with a list of genes produces a `Gene-Disease Network` where the blue nodes are diseases, the pink nodes are genes, and the width of the edges is proportional to the score of the association (Figure 3).


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 3: The **Gene-Disease Network** for a list of genes belonging to the voltage-gated potassium channel family"}
plot( data2,
      class = "Network",
      prop = 10)
```


\noindent Setting the argument `class` to "Heatmap" produces a `Gene-Disease Heatmap` (Figure 4), where the scale of colors is proportional to the score of the GDA. The argument `limit` can be used to limit the number of rows to the top scoring GDAs. The argument `nchars` can be used to limit the length of the name of the disease. By default, the plot shows the 50 highest scoring GDAs.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 4: The **Gene-Disease Heatmap** for a list of genes belonging to the voltage-gated potassium channel family"}
plot( data2,
      class  ="Heatmap",
      limit  = 100, nchars = 50 )
```


\noindent These results can also be visualized as a `Gene-Disease Class Heatmap` by setting the argument `class` to "DiseaseClass" (Figure 5). In this case, diseases are grouped by the their MeSH disease classes, and the color scale is proportional to the percentage of diseases in each MeSH disease class. In the example, genes are associated mainly to *Cardiovascular Diseases*, and to *Congenital, Hereditary, and Neonatal Diseases and Abnormalities*.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 5: The **Gene-Disease Class Heatmap** for a list of genes belonging to the voltage-gated potassium channel family"}
plot( data2,
      class="DiseaseClass", nchars=60)
```

## Retrieving the identifier for a disease of interest
To retrieve the concept unique identifier for the disease of interest, you can use  the **get_umls_from_vocabulary** function with the parameter vocabulary set to "NAME". This will retrieve all diseases in DisGeNET that contain the keyword used as an input. 

```{r, warning = T, echo=T, message = FALSE, eval=T}
diseases <- get_umls_from_vocabulary( "Schizophrenia", vocabulary = "NAME" )
kable(diseases, caption = "CUIs associated to Schizophrenia") %>%   kable_styling(bootstrap_options = "striped", full_width = F)


```


## Searching by disease

\noindent The **disease2gene** function allows to retrieve the genes associated to a disease, or a list of diseases. The function uses as input the disease, or list of diseases of interest (as UMLS CUI, MeSH, OMIM, Disease Ontology, ICD9CM, NCIt, EFO, or Orphanet Identifiers), the disease vocabulary employed (`OMIM` (OMIM), `MESH` (MeSH),`ICD9CM` (ICD9-CM), `DO` (Disease Ontology), `NCI` (NCI thesaurus), `ORDO` (Orphanet), or `EFO` (EFO)  and the database (by default, `CURATED`). A threshold value for the score can be set, like in the **gene2disease** function.

\noindent In the example, we will use the **disease2gene** function to retrieve the genes associated to the UMLS CUI *C0036341*. This function also receives as input the database, in the example, *CURATED*, and a score range, in the example, from 0.4 to 1. 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data3 <- disease2gene( disease  = "C0036341",
                          database = "CURATED",
                          score    = c( 0.4,1 ) )
data3
```

\noindent  The same results are obtained when querying DisGeNET with the MeSH identifier for Schizophrenia (*D012559*). 

```{r, warning = T, echo=F, message = FALSE, eval=T}
data4 <- disease2gene( disease  = "D012559", vocabulary = "MESH",
                          database = "CURATED",
                          score    = c(0.4,1 ) )
data4
```

\noindent  The same results are obtained when querying DisGeNET with the OMIM identifier for Schizophrenia (*181500*). 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data4 <- disease2gene( disease  = "181500", vocabulary = "OMIM",
                          database = "CURATED",
                          score    = c(0.4,1 ) )
data4
	
```

\noindent  The same results are obtained when querying DisGeNET with the ICD9-CM identifier for Schizophrenia (*295*). 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data4 <- disease2gene( disease  = "295", vocabulary = "ICD9CM",
                          database = "CURATED",
                          score    = c(0.4,1 ) )
data4
	
```

\noindent  The same results are obtained when querying DisGeNET with the NCI identifier for Schizophrenia (*C3362*). 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data4 <- disease2gene( disease  = "C3362", vocabulary = "NCI",
                          database = "CURATED",
                          score    = c(0.4,1 ) )
data4
	
```

\noindent  The same results are obtained when querying DisGeNET with the DO identifier for Schizophrenia (*5419*). 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data4 <- disease2gene( disease  = "HP:0100753", vocabulary = "HPO",
                          database = "CURATED",
                          score    = c(0.4,1 ) )
data4

```

### Visualizing the genes associated to a single disease

\noindent There are two options to visualize the results from searching a single disease: a `Gene-Disease Network` showing the genes related to the disease of interest (Figure 6), and a `Disease-Protein Class Network` with the genes grouped by Panther Protein Class (Figure 7). 

\noindent Figure 6 shows the default `Gene-Disease Network` for Schizophrenia. As in the case of the **gene2disease** function, the blue nodes is the disease, the pink nodes are genes, and the width of the edges is proportional to the score of the association.

```{r, fig.align="center",echo=T, fig.width=6, fig.height=6, fig.cap="Figure 6: The **Gene-Disease Network** for genes associated to Schizophrenia"}

plot ( data3,
       prop = 10)
``` 


\noindent Alternatively, in the `Disease-Protein Class Network`, genes are grouped by the Panther Protein Class (Figure 7). This is a better choice when there is a large number of genes associated to the disease. This plot uses as `class` argument "ProteinClass". The resulting network  will show in blue the disease, and in green the Protein Classes of the genes associated to the disease. The node size is proportional to the number of genes in the Panther Protein Class. In the example, the largest proportion of the genes associated to Schizophrenia are receptors. Notice again that not all genes have annotations to Panther Protein classes (69 genes in Figure 7)

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 7: The **Protein Class-Disease Network** for genes associated to Schizophrenia", eval=T}
plot( data3,
      class="ProteinClass"
)
```

### Exploring the evidences associated to a disease

To explore the evidences supporting the associations for Schizophrenia using the function  **disease2evidence**.


```{r, warning = T, echo=T, message = FALSE, eval=T}
data3 <- disease2evidence( disease  = "C0036341",
                           type = "GDA",
                          database = "CURATED",
                          score    = c( 0.4,1 ) )
data3

```

 Additionally, you can explore the evidences for a specific gene-disease pair by specifying the gene identifier using the argument  `gene`.

```{r, warning = T, echo=T, message = FALSE, eval=T}
data3 <- disease2evidence( disease  = "C0036341",
                           gene = c("DRD2", "DRD3"),
                           type = "GDA",
                          database = "CURATED",
                          score    = c( 0.4,1 ) )
data3
results <- extract(data3)

```

The results are shown in the table below.  

```{r, warning = T, echo=F, message = FALSE}

kable(results[, c("pmid", "year", "sentence")], caption = "Evidences supporting the association between C0036341 & DRD2,DRD3") %>%   kable_styling(bootstrap_options = "striped", full_width = F)

```


## Searching multiple diseases

\noindent The **disease2gene** function also accepts as input a list of diseases  (as UMLS CUI, MeSH, OMIM, Disease Ontology, Orphanet, Dechipher, or ICD9CM Identifiers), the database (by default, *CURATED*), and optionally, a value range for the score. In the example, we have selected a list of 10 diseases. Table 3 shows the UMLS CUIs and the corresponding disease names. 

Table 3: Disease list selected for illustrating the **disease2gene** multiple search 

```{r echo=FALSE,  message=FALSE,}
table1 <- data.frame(
  UMLS_CUI = c("C0036341", "C0036341", "C0030567", "C0005586"), 
  Disease_Name =c("Schizophrenia", 
               "Alzheimer's Disease",
               "Parkinson Disease", 
               "Bipolar Disorder")) 
 
kable(table1) %>%   kable_styling(bootstrap_options = "striped", full_width = F)
                               

```


\noindent Creating the vector with the list of diseases.   

```{r, warning = T, echo=T, message = FALSE, eval=T}
diseasesOfInterest <- c("C0036341", "C0002395", "C0030567","C0005586")
```

\noindent In the example, we will search in *CURATED* data, using a score range of 0.4-1.

```{r, warning = T, echo=T, message = FALSE, eval=T}
data5 <- disease2gene(
  disease = diseasesOfInterest,
  database = "CURATED",
  score =c(0.4,1),
  verbose  = TRUE )
```


### Visualizing the genes associated to multiple diseases

\noindent The default plot of the results of querying DisGeNET with a list of diseases produces a `Gene-Disease Network` where the blue nodes are diseases, the pink nodes are genes, and the width of the edges is proportional to the score of the association (Figure 8).

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 8: **The Gene-Disease Network** for genes associated to a list of diseases", eval=T}
plot( data5,
      class = "Network",
      prop = 10)
```

 

\noindent To visualize the results as a `Gene-Disease Heatmap` (Figure 9) change the argument `class` to "Heatmap". In this plot, the scale of colors is proportional to the score of the GDA. The argument `limit` can be used to limit the number of rows to the top scoring GDAs when the results are large. By default, the plot shows the 50 highest scoring GDAs.


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 9: The **Gene-Disease Heatmap** for genes associated to a list of diseases", eval=T}
plot( data5,
      class="Heatmap",
      limit =30,
      cutoff=0.2)
```


\noindent A third visualization option is a `Protein Class-Disease Heatmap` (Figure 10), in which genes are grouped by protein class. This plot is obtained by setting the `class` argument to "ProteinClass". In this case, the color of the heatmap is proportional to the percentage of genes for each disease in each protein class. This heatmap displays the protein classes associated to each disease. 

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 10: The **Protein Class-Disease** Heatmap for genes associated to a list of diseases", eval=T}
plot( data5,
      class="ProteinClass" )
```


# Retrieving Variant-Disease Associations from DisGeNET

## Searching by variant

\noindent The **variant2disease** function receives a variant, or a list of variants as input, identified by the dbSNP identifier. It produces an object `DataGeNET.DGN`, with `Type = "variant-disease"`.

```{r, warning = T, echo=T, message = FALSE, eval=T}
data6 <- variant2disease( variant= "rs121913279",
                         database = "CURATED")
data6
```

### Visualizing the diseases associated to a single variant

\noindent The **disgenet2r** package offers several options to visualize the results of querying DisGeNET for a single variant: a `Variant-Disease Network` showing the diseases associated to the variant of interest, a `Variant-Gene-Disease Network` showing the genes, diseases, and variant of interest, and a network showing the MeSH Disease Classes of the diseases associated to the variant (`Variant-Disease Class Network`). These graphics can be obtained by changing the `class` argument in the **plot** function.

\noindent By default, the **plot** function produces a `Variant-Disease Network` on a `DataGeNET.DGN` object (Figure 11). In the `Variant-Disease Network` the blue nodes are diseases, the yellow nodes are variants, the blue nodes are diseases, and the width of the edges is proportional to the score of the association. 

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 11: The **Variant-Disease Network** for the variant rs121913279", eval=T}
plot( data6, 
      class = "Network",
      prop  = 10)

```


\noindent The results can also be visualized in a network in which diseases are grouped by the MeSH Disease Class if the `class` argument is set to "DiseaseClass" (Figure 12). In the `Variant-Disease Class Network`, the node size of is proportional to the fraction of diseases in the disease class, with respect to the total number of diseases with disease class associated to the gene. In the example, the variant is associated mainly to Neoplasms.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 12: The **Variant- Disease Class Network** for the variant rs121913279", eval=T}
plot( data6,
      class = "DiseaseClass",
      prop = 3)
```


### Exploring the evidences associated to a variant

You can extract the evidences associated to a particular variant using the function  **variant2evidence**. Additionally, you can explore the evidences for a specific variant-disease pair by specifying the argument  `disease`.

```{r, warning = T, echo=F, message = FALSE}
data6 <- variant2evidence( variant = "rs121913279",
                disease ="C0009402",
                       database = "ALL",
                       score =c(0,1))
data6
results <- extract(data6)

```


The results are shown in the table below.  

```{r, warning = T, echo=F, message = FALSE}

kable(results[, c("pmid", "year", "sentence")], caption = "Evidences supporting the association between C0009402 & rs121913279") %>%   kable_styling(bootstrap_options = "striped", full_width = F)

```



## Searching multiple variants

\noindent The **variant2disease** function retrieves the information in DisGeNET for a list of variants identified by the dbSNP identifier. The function also requires the user to specify the source database using the argument `database`. By default, **variant2disease** function uses as source database *CURATED*.


```{r, warning = T, echo=T, message = FALSE, eval=T}
data7 <- variant2disease(
         variant = c("rs121913013", "rs1060500621",
              "rs199472709", "rs72552293",
              "rs74315445", "rs199472795"),
         database = "ALL")
```


### Visualizing the diseases associated to multiple variants

\noindent The results of querying DisGeNET with a list of variants can be visualized as a `Variant-Disease Network` (Figure 13), as a `Variant-Gene-Disease Network` (Figure 15) and as heatmap (`Variant-Disease Class Heatmap`, Figure 16). 
Below, the `Variant-Disease Network`. 

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 13: The **Variant-Disease Network** for a list of variants", eval=T}
plot( data7,
      class = "Network",
      prop = 10)
``` 


\noindent To obtain the `Variant-Gene-Disease Network`, Figure 14), change the `showGenes` argument to "TRUE".

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 14: The **Variant-Gene-Disease Network** for a list of variants", eval=T}
plot( data7,
      class = "Network",
      showGenes = T)
```

\noindent The results of querying DisGeNET variant information with a list of diseases can be visualized as a `Variant-Disease Heatmap` by changing the `class` argument to `Heatmap` (Figure 15).


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 15: The **Variant-Disease Heatmap** for a list of variants", eval=T}
plot( data7,
      class = "Heatmap",
      prop = 10)
``` 

\noindent The results of querying DisGeNET variant information with a list of diseases can also be visualized as a `Variant-Disease Class Network`.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 16: The **Variant-Disease Class Heatmap** for a list of variants", eval=T}
plot( data7,
      class = "DiseaseClass")

```


## Searching by disease


\noindent The **disease2variant** function allows to retrieve the variants associated to a disease, or a list of diseases. The function uses as input the disease, or list of diseases of interest (as UMLS CUI, MeSH, OMIM, Disease Ontology, ICD9CM, NCIt, EFO, or Orphanet Identifiers), the disease vocabulary employed (`OMIM` (OMIM), `MESH` (MeSH),`ICD9CM` (ICD9-CM), `DO` (Disease Ontology), `NCI` (NCI thesaurus), `ORDO` (Orphanet), or `EFO` (EFO)  and the database (by default, `CURATED`). A threshold value for the score can be set, like in the **gene2disease** function.


```{r, warning = T, echo=T, message = FALSE, eval=T}
data8 <- disease2variant(disease = c("C0752166"),
                       database = "CLINVAR", 
                       score = c(0, 1) )
data8
```


### Visualizing the variants associated to a single disease

\noindent The results of querying DisGeNET variant information with a list of diseases can be visualized as a `Variant-Disease Network` (Figure 17).

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 17: The **Variant-Disease Network** for a single disease", eval=T}
plot( data8,     
      class = "Network")
```

### Explore the evidences associated to a single disease

To explore the evidences supporting the VDAs for Schizophrenia, run the **disease2evidence** function. You can use the argument variant to inspect the evidences for a particular variant and Schizophrenia. You can also specify a year range for the publications

```{r, warning = T, echo=T, message = FALSE, eval=T}
data8 <- disease2evidence( disease  = "C0036341",
                               variant = "rs1344706",
                           type = "VDA",
                           year = c(2019, 2020),
                          database = "ALL",
                          score    = c( 0.1,1 ) )
data8
```


```{r, warning = T, echo=F, message = FALSE, eval=T}
results <- extract(data8)
results <- results[ order(-results$year),]
kable(results[, c("pmid", "year", "sentence")], caption = "Evidences supporting associations between C0036341 & rs1344706") %>%   kable_styling(bootstrap_options = "striped", full_width = F)
```

If you want to inspect the evidences for Schizophrenia, and all the variants in a particular gene, use the argument `gene`. 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data8 <- disease2evidence( disease  = "C0036341",
                               gene = "CACNA1C",
                           type = "VDA",
                          database = "BEFREE",
                          score    = c( 0.1,1 ) )
data8
results <- extract(data8)
```


```{r, warning = T, echo=F, message = FALSE, eval=T}

results <- results[ order(-results$year),][1:5,]
kable(results[, c("pmid", "year", "sentence")], caption = "Selection of evidences supporting associations between C0036341 & CACNA1C") %>%   kable_styling(bootstrap_options = "striped", full_width = F)

```


## Searching multiple diseases 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data8 <- disease2variant(
              disease = c("C3150943",  "C1859062", "C2678485", "C4015695"),
              database = "CURATED", 
              score = c(0.75, 1) )
data8
```

### Visualizing the variants associated to multiple diseases

\noindent The results of querying DisGeNET variant information with a list of diseases can be visualized as a `Variant-Disease Network`, or as a `Variant-Disease Heatmap`, Figure 18), by changing the `class` argument from "Network" to "Heatmap".

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 18: The **Variant-Disease Network** for a list of diseases", eval=T}
plot( data8,     
      class = "Network")
```

\noindent The `Variant-Disease Network` can be displayed as a `Variant-Disease-Gene Network`, by setting the `showGenes` parameter to `TRUE`. 


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 19: The **Variant-Gene-Disease Network** for a list of diseases", eval=T}
plot( data8, 
      class = "Network",
      showGenes = T)
```

The results can be visualized as a Heatmap. 

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 20: The **Variant-Disease Heatmap** for a list of diseases", eval=T}
plot( data8,
      class = "Heatmap",
      prop = 10)

``` 


# Retrieving Disease-Disease Associations from DisGeNET

\noindent The **disgenet2r** package also allows to obtain a list of diseases that share genes or variants with a particular disease, or disease list (disease-disease associations, or DDAs). 

## Searching DDAs by genes for a single disease

\noindent To obtain disease-disease associations, use the **disease2disease_by_gene** function. This function uses as input a disease, in the same format that in **disease2gene**, the database to perform the search (by default, *CURATED*), and the argument `ndiseases`, the number of diseases that share genes with the disease(s) of interest. By default `ndiseases = 10`. The output is a `DataGeNET.DGN` object that contains the top 10 diseases that share genes with the disease that has been searched. 

```{r, warning = T, echo=T, message = FALSE, eval=T}
data9 <- disease2disease_by_gene(
  disease  = "C0010674",
  database = "CURATED", ndiseases = 5 )
data9

qr <- extract(data9)
head(qr[c("disease1_name", "disease2_name","jaccard_genes","ngenes", "pvalue")])
```

\noindent The `DataGeNET.DGN` object produced by the **disease2disease_by_gene** function also contains the Jaccard Index, also known as the Jaccard similarity coefficient for each disease pair. The Jaccard Coefficient is a similarity metric, computed as as the size of the intersection divided by the size of the union of two sample sets, in this case, the genes associates to each disease: 

\begin{equation*}
J(A, B) = \frac{\mid A \cap B \mid}{\mid A \cup B \mid}
\end{equation*}

\noindent The `pvalue` column estimates the significance of the Jaccard coefficient for a list of disease pairs. The estimation of the pvalue is estimated by randomizing 1000 times. 


### Visualizing the diseases associated to a single disease

\noindent The **plot** function applied to the `DataGeNET.DGN` object generated by the **disease2disease_by_gene** function results in a `Disease-Disease Network`, where the node in dark blue is the disease of interest and nodes in ligth blue are the diseases that share genes with it (Figure 21). The node size is proportional to the number of genes associated to each disease.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 21: The **Disease-Disease Network** by shared genes for MELAS Syndrome", eval=T}
plot( data9, 
      class = "Network",
      layout="layout.lgl" ,
      prop = 0.4 )
```



\noindent To obtain the fully connected network, set the `class` argument of the **plot** function to `Diseasome`(Figure 22). In this network, the nodes are the diseases of interest, and the node size is proportional to the number of genes associated with them, and the edges size is proportional to the number of genes that are shared between the diseases they are connecting. The nodes in dark blue are the query diseases, and in light blue, the diseases that share genes with them. 

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 22: The **Diseasome plot** for MELAS Syndrome", eval=T}
plot( data9, 
      class = "Diseasome",
      layout="layout.lgl" ,
      prop = 5 )

```

\noindent A second option to visualize the results of **disease2disease_by_gene** is as a `Disease-Disease Barplot` (Figure 23), obtained by setting the `class` argument to `Barplot`. The `Disease-Disease Barplot` shows the top **n** diseases that share genes with the disease of interest. This barplot also provides the jaccard index for each disease pair.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 23: **Disease-Disease Barplot** visualizing the top 5 diseases associated to MELAS Syndrome", eval=T}
plot( data9,
      class="Barplot")
```


## Searching DDAs via genes for multiple diseases

### Visualizing the diseases associated to multiple diseases 

\noindent The function **disease2disease_by_gene** can receive a list of diseases as input, in any of the previously described vocabularies. It will retrieve the top 10 diseases that share genes with each of the diseases in the input list. This results can be visualized as a `Disease-Disease Network`, a `Diseasome plot`, or as a `Barplot`. 

Table 4: Disease list selected for illustrating the **disease2disease_by_gene** function 

```{r echo=FALSE,  message=FALSE, eval=T}
table1 <- data.frame(
  UMLS_CUI = c("C0162671", "C0023264", "C0917796"), 
  Disease_Name =c("MELAS Syndrome", "Leigh Disease" , "Optic Atrophy, Hereditary, Leber")) 
 
kableExtra::kable(table1) %>%  kableExtra::kable_styling(bootstrap_options = "striped", full_width = F)
                               

```



```{r,  echo=T,  message=FALSE, eval=T}
diseasesOfInterest <-  c("C0013182", "C0013221", "C3658290", "C0860207", "C1274933")
data10 <- disease2disease_by_gene(
  disease = diseasesOfInterest,
  database = "CURATED", ndiseases =  5)

```

\noindent To obtain the network, set the `class` argument of the **plot** function to `Network`(Figure 24). In this network, the nodes are the diseases of interest, and the node size is proportional to the number of genes associated with them. On the other hand, the edges size is proportional to the number of genes that are shared between the diseases they are connecting.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 24: The **Disease-Disease Network** by shared genes for a list of diseases", eval=T}
plot( data10,
      class = "Network",
      prop  = 0.1)
```



\noindent To obtain the fully connected network, set the `class` argument of the **plot** function to `Diseasome`(Figure 25). In this network, the nodes are the diseases of interest, and the node size is proportional to the number of genes associated with them. On the other hand, the edges size is proportional to the number of genes that are shared between the diseases they are connecting.

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 25: The **Diseasome plot** for a list of diseases", eval=T}
plot( data10,
      class = "Diseasome",
      prop  = 0.1)
```


\noindent To further inspect the relationship between a pair of diseases, create a Venn Diagram by setting the `class` argument of the **plot** function to `Venn` (Figure 26).

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 26: The **Venn Diagram** for 3 diseases", eval=T}
plot( data10,
      class="Venn")

```

The Venn diagram for 4 diseases


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 27: The **Venn Diagram** for a list of 4 diseases", eval=T}
data11 <- disease2disease_by_gene(
  disease =  c("C0018801", "C0028754", "C0004153", "C0011849"),
  database = "CURATED",
  ndiseases = 5)
plot( data11,
      class="Venn"
)
```



The Venn diagram for 5 diseases


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 28: The **Venn Diagram** for a list of 5 diseases", eval=T}
data11 <- disease2disease_by_gene(
  disease =  c("C0018801", "C0028754", "C0004153", "C0011849", "C0021368"),
  database = "CURATED",
  ndiseases = 5)
plot( data11,
      class="Venn"
)

```

## Searching DDAs via shared variants for a single disease

\noindent To obtain disease-disease associations, use the **disease2disease_by_variant** function. This function uses as input a disease, in the same format that in **disease2disease_by_gene**, the database to perform the search (by default, *CURATED*), and the argument `ndiseases`, the number of diseases that share genes with the disease(s) of interest. By default `ndiseases = 10`. The output is a `DataGeNET.DGN` object that contains the top 10 diseases that share genes with the disease that has been searched. 

```{r, warning = T, echo=T, message = T, eval=T}
data12 <- disease2disease_by_variant(
  disease  = "C0011860",
  database = "CURATED", ndiseases = 3 )
data12

```


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 29: An example of **Disease-Disease Network**", eval=T}
plot( data12, layout="layout.lgl" ,
      prop = 0.2 )
```


```{r, warning = T, echo=T, message = FALSE, eval=T}
data13 <- disease2disease_by_variant(
  disease  = c("C0018801", "C0020538"),
  database = "CURATED", ndiseases = 5 )

data13


```


```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure 30: The **Diseasome plot** by shared variants for Muscular Dystrophy, Duchenne", eval=T}
plot( data13, layout="layout.lgl" ,
      class = "Diseasome",
      prop = 0.02)
```

# Performing a disease enrichment


\noindent The **disease_enrichment** function receives a list of genes and performs an enrichment analysis over the diseases in DisGeNET. The input list of genes should be identified with HGNC symbols, or Entrez Gene Identifiers. The vocabulary should be specified using the parameter `vocabulary`. By default, `vocabulary = "HGNC"`. The function has other optional argument: the source database (by default, `database = “CURATED”`). The background for the Fisher test are all the genes in DisGeNET. The p-values resulting from the multiple Fisher tests are corrected for false discovery rate using the Benjamini-Hochberg method.

To perform the enrichment, run:


```{r,  eval=T}
list_of_genes <- disease2gene(disease = "C0004352", database = "GENOMICS_ENGLAND")

list_of_genes <- list_of_genes@qresult$gene_symbol

res_enrich <-disease_enrichment( entities =list_of_genes, vocabulary = "HGNC",
                             database = "CURATED" )

table1 <- res_enrich@qresult[1:10, c("Description", "FDR", "Ratio",  "BgRatio")]
```
The column Ratio represents the number of genes from the input list that are associated to the disease. The BgRatio are the number of genes associated to the disease from the length of the universe, in the example, all genes in DisGeNET curated (9703). 


```{r, results='asis', warning= F, echo=FALSE, message=FALSE ,fig.width= 10, fig.height= 10, eval=T}
kableExtra::kable(table1, row.names = F) %>%  kableExtra::kable_styling(bootstrap_options = "striped", full_width = F)
```


To visualize the results of the enrichment, use the function **plot**. Use the argument `cutoff` to set a minimum p value threshold, and the argument `limit` to reduce the number of records shown. By default, `limit=50`.  Use the argument `nchars` to control the lenght of the disease name. 

```{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure : The **Enrichment plot** for a list of genes", eval=T}
plot( res_enrich, class = "Enrichment", count =3,  cutoff= 0.05, nchars=70)

```




```{r,  eval=T}

res_enrich <-disease_enrichment( entities =list_of_genes, vocabulary = "HGNC",
                             database = "ALL" )

table1 <- res_enrich@qresult[1:10, c("Description", "FDR", "Ratio",  "BgRatio")]
```


```{r, results='asis', warning= F, echo=FALSE, message=FALSE ,fig.width= 10, fig.height= 10, eval=T}
kableExtra::kable(table1, row.names = F) %>%  kableExtra::kable_styling(bootstrap_options = "striped", full_width = F)
```


\noindent A **disease_enrichment** for a list of variants can also be performed. The input list of variants should be identified with dbSNP identifiers and the vocabulary should be specified using the parameter vocabulary = `"DBSNP"`. The function has other optional argument: the source database (by default, `database = “CURATED”`). The background for the Fisher test are all the genes in DisGeNET. The p-values resulting from the multiple Fisher tests are corrected for false discovery rate using the Benjamini-Hochberg method.

To perform the enrichment, run:


```{r,  eval=T}
list_of_variants <- disease2variant(disease = "C0004352", database = "CLINVAR")

list_of_variants <- as.character(list_of_variants@qresult$variantid)

res_enrich <-disease_enrichment( entities =list_of_variants, vocabulary = "DBSNP",
                             database = "CURATED" )

table1 <- res_enrich@qresult[1:10, c("Description", "FDR", "Ratio",  "BgRatio")]

```

```{r, results='asis', warning= F, echo=FALSE, message=FALSE ,fig.width= 10, fig.height= 10, eval=T}
kableExtra::kable(table1, row.names = F) %>%  kableExtra::kable_styling(bootstrap_options = "striped", full_width = F)
```


To visualize the results of the enrichment, use the function **plot**. Use the argument `cutoff` to set a minimum p value threshold, and the argument `limit` to reduce the number of records shown. By default, `limit=50`.   

```{r, fig.align="center", fig.width=8, fig.height=8, fig.cap="Figure : The **Enrichment plot** for a list of genes", eval=T}
plot( res_enrich, class = "Enrichment", count =6,  cutoff= 0.05)

```


# Expanding DisGeNET data with other resources available in the LOD cloud 

Currently, Wikipathways-RDF has issues and these federated queries do not work! 

## Retrieving the pathways associated to a disease 

To obtain the pathways from WikiPathways associated to a disease, use the **disease2pathway** function.  

```{r,  eval=F}
library("SPARQL")
dis2path <- disease2pathway( disease = "C0018801" ,
                             database = "ALL", score = c(0.5, 1))
dis2path
# head(dis2path@qresult)
# qr <- extract(dis2path)
# head(qr, 3)

``` 

## Retrieving the diseases associated to a given pathway

To obtain the pathways from WikiPathways associated to a disease, use the **disease2pathway** function.  

```{r,  eval=F}
path2dis <- pathway2disease( pathway = "WP1591" ,
                             database = "CURATED",
                             score = c(0.9, 1))
path2dis
head(path2dis@qresult)
qr <- extract(path2dis)
head(qr, 3)

``` 



## Retrieve the drug targets for a disease 

The function **disease2compound** allows retrieved the chemicals in ChEMBL that target the genes associated to the given disease, or list of diseases. The function produces a DataGeNET.RDF object with the input disease(s), the associated genes, the DisGeNET score, and the chemicals associated to the disease proteins. If there were no chemicals found, the genes are still included in the output. It is important to higlight that because of ChEMBL restrictions for their SPARQL endpoint if 1000 compounds are retrieved for a single protein it probably means that there are more than 1000. (See more information about ChEMBL SPARQL endpoint at  https://www.ebi.ac.uk/rdf/what-are-limitations-sparql-endpoints).  


```{r,  eval=F}

dis2com <- disease2compound(
  disease = c("C0020538"),
  database = "CURATED" )
dis2com
qr <- extract(dis2com)
head(qr, 3)


```

## Retrieving Gene Ontology data for a gene 

```{r,  eval=F}
 
gene2bp <- gene2biologicalprocess(gene = "351")
head(gene2bp@qresult)
gene2cc <- gene2cellcomponent(gene = "351")
head(gene2cc@qresult)
gene2mf <- gene2molecularfunction(gene = "351")
head(gene2mf@qresult)
gene2indi <- gene2indication( gene = "1588" )
head(gene2indi@qresult)
```


## Retrieving Gene Ontology data for a disease 

The functions **disease2biologicalprocess**, **disease2molecularfunction**, and **disease2cellcomponent** can retrieve the Gene Ontology (GO) molecular function, GO biological process and GO cellular component of the genes associated to a disease or a list of diseases.  

### Retrieving the biological processes associated to a disease

For a disease, the biological process information can be retrieved in GO terms using the function **disease2biologicalprocess** that receives as input an NCBI gene identfier. The function produces a DataGeNET.RDF object containing the disease, the genes and their GOBP terms.  


```{r, eval=F}

disease2bp <- disease2biologicalprocess(
  disease = "C0036341",
  database = "CURATED",
  score = c( 0.6,1)
)
disease2bp
disease2bp <- extract(disease2bp)
head(disease2bp[c("gene_product_label","go_label")])

```

### Retrieving the molecular functions of the genes associated to a disease}

For a particular disease, the molecular activities of associated genes can be retrieved as GO terms using the function **disease2molecularfunction**. The function produces a DataGeNET.RDF object containing the disease, the genes and their GOMF terms.  


```{r,  eval=F}
disease2mf <- disease2molecularfunction(
  disease = "C0002395",
  database = "UNIPROT"
)

disease2mf
disease2mf <- extract(disease2mf)
head(disease2mf[c("gene_product_label", "go_label")])

```


### Retrieving the molecular functions of the genes associated to a disease

For a given gene, the cell component information (i.e. where gene products are active) can be retrieved as GO terms using the function **gene2cellcomponent** that receives as input an NCBI gene identfier. The function produces a DataGeNET.RDF object containing the disease, the genes and their GO CC terms. 


```{r,  eval=F}
disease2cc <- disease2cellcomponent(  disease = "C0002395",
                                      database = "MGD")

disease2cc <- extract(disease2cc)
head(disease2cc[c("gene_product_label", "go_label")])


``` 

# Get DisGeNET data version

```{r}

get_disgenet_version()

```

# COPYRIGHT

Copyright (C) 2021, IBI group.

disgenet2r is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

disgenet2r is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program.  If not, see <http://www.gnu.org/licenses/>.

# How to cite disgenet2r

Piñero, J., Ramírez-Anguita, J. M., Saüch-Pitarch, J., Ronzano, F., Centeno, E., Sanz, F., & Furlong, L. I. (2020). The DisGeNET knowledge platform for disease genomics: 2019 update. Nucleic Acids Research, 48(D1), D845-D855.


```{r, eval=F, echo=F}
# rmarkdown::render('/home/janet/Documents/disgenet2r/vignettes/disgenet2r.Rmd')

```

# References
