---
title: "2.B: JASPAR & rbioapi"
author: "Moosa Rezwani"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
    anchor_sections: true
    number_sections: true
    self_contained: true
    dev: png
    encoding: 'UTF-8'

vignette: >
  %\VignetteIndexEntry{2.B: JASPAR & rbioapi}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r message=FALSE, include=FALSE, results="hide", setup, echo=FALSE}
knitr::opts_chunk$set(echo = TRUE,
                      eval = TRUE,
                      message = FALSE,
                      warning = FALSE,
                      collapse = TRUE,
                      tidy = FALSE,
                      cache = FALSE,
                      dev = "png",
                      comment = "#>")
library(rbioapi)
rba_options(timeout = 600, skip_error = TRUE)
```

------------------------------------------------------------------------

# Introduction {#introduction}

Directly quoting from Fornes O, Castro-Mondragon JA, Khan A, et al:

> JASPAR ([https://jaspar.genereg.net)](https://jaspar.genereg.net) is an open-access database of curated, non-redundant transcription factor (TF)-binding profiles stored as position frequency matrices (PFMs) for TFs across multiple species in six taxonomic groups. In this 8th release of JASPAR, the CORE collection has been expanded with 245 new PFMs (169 for vertebrates, 42 for plants, 17 for nematodes, 10 for insects, and 7 for fungi), and 156 PFMs were updated (125 for vertebrates, 28 for plants and 3 for insects). These new profiles represent an 18% expansion compared to the previous release.
>
> source:\
> Fornes O, Castro-Mondragon JA, Khan A, et al. JASPAR 2020: update of the open-access database of transcription factor binding profiles. *Nucleic Acids Res*. 2019; doi: [10.1093/nar/gkz1001](https://doi.org/10.1093/nar/gkz1001)

------------------------------------------------------------------------

# Data Organization in JASPAR

JASPAR is a database of transcription factor binding matrices with annotations and metadata. These entities are organized in a hierarchical fashion that we will explore next.

## Releases

In addition to the latest JASPAR database release (2020), other active releases are also available. Most of the rbioapi JASPAR functions have a `release` argument that allows you to use other database releases.

```{r release}
## Call the function without any arguments to get a list of releases
releases <- rba_jaspar_releases()
## Supply a release number for details:
release_7_info <- rba_jaspar_releases(7)
```

## Collections

Within a release, Matrix profiles are organized into collections, You can use `rba_jaspar_collections()` to get a list of available collections, or read "JASPAR Collections" section in [documentation page in JASPAR web-site](https://jaspar.genereg.net/docs/ "JASPAR Documentation") for a thorough review.

```{r collections}
## To get a list of available collection in release 2020:
rba_jaspar_collections(release = 2020)


## You can list information of all matrices available in a collection:
mat_in_core_2020 <- rba_jaspar_collections_matrices(collection = "CORE")
```

## Taxonomic Groups

Within each collection, the matrix profiles are organized based on main taxonomic groups:

```{r taxons}
## To get a list of taxonomic groups in release 2020:
rba_jaspar_taxons(release = 2020)


## You can list information of all matrices available in a taxonomic group:
mat_in_insects <- rba_jaspar_taxons_matrices(tax_group = "insects")
```

## Species

As we go down in the data organization hierarchy, Each taxonomic group consist of species:

```{r species}
## To get a list of species in release 2020:
species <- rba_jaspar_species(release = 2020)
head(species)

## You can list information of all matrices available in a specie:
mat_in_human <- rba_jaspar_species_matrices(tax_id = 9606)
```

------------------------------------------------------------------------

# Matrix Profiles

## Search Matrix Profiles

Retrieving a list of every matrix available in a given category is not the only option. You can also build a search query using `rba_jaspar_matrix_search`. Note that this is a search function, you are not required to fill every argument. You may use any combination of arguments you see fit to build your query. You can even call the function without any argument to get a list of all the matrix profiles. For instance:

```{r search, eval=FALSE}
## Get a list of all the available matrix profile:
all_matrices <- rba_jaspar_matrix_search()

## Search FOX:
FOX_matrices <- rba_jaspar_matrix_search(term = "FOX")

## Transcription factors named FOXP3
FOXP3_matrices <- rba_jaspar_matrix_search(term = "FOXP3")

## Transcription factors of Zipper-Type Class
zipper_matrices <- rba_jaspar_matrix_search(tf_class = "Zipper-Type")

## Transcription factors of Zipper-Type Class in PBM collection
zipper_pbm_matrices <- rba_jaspar_matrix_search(tf_class = "Zipper-Type",
                                                collection = "PBM")
```

## List Matrix Profiles Associated to a Base identifier

Since JASPAR release 2010, the matrix profiles are versioned. A matrix profile Identifier has a "base_id.version" naming schema; for example "MA0600.2" corresponds to the second version of a matrix with base ID MA0600. You can Use `rba_jaspar_matrix_versions` to get a list of matrix profiles with a given base ID. Also note that some functions, generally those that are used to list available matrices, have an argument called `only_last_version`.

```{r versions, eval=FALSE}
## Get matrix profiles versions associated to a base id
MA0600_versions <- rba_jaspar_matrix_versions("MA0600")
```

## Get a Matrix Profile

Now that you listed or searched for matrix profiles, you can use `rba_jaspar_matrix` to retrieve matrix profiles. There are two ways in which you can use this function:

### Get Matrix and Annotations as an R Object

To do that, only fill in the `matrix_id` argument in `rba_jaspar_matrix`

```{r matrix_r_object}
pfm_matrix <- rba_jaspar_matrix(matrix_id = "MA0600.2")

## you can find the matrix in the pfm element along with
## other elements which correspond to annotations and details
str(pfm_matrix)
```

### Save a Matrix a File in Specific Format

JASPAR provides position frequency matrices (PFM) formatted as **Raw PFM**, **JASPAR**, **TRANSFAC**, **YAML**, and **MEME**. You can download a matrix profile as a file with any of these formats. To do that, You should use the `file_format` and `save_to` arguments available in `rba_jaspar_matrix`. There are two notes here:

1.  In this case, the function will save your matrix as a file and returns the un-parsed content of the file as a character string.

2.  The `save_to` argument in this function, and in fact through any rbioapi function can be used in many ways:\
    2.1. save_to = NA: rbioapi will automatically generate a file path under your working directory, save the file in that path , and informs you with a message.\
    2.2 save_to = file_name without path: rbioapi will save the file with your supplied name in your working directory.\
    2.3. save_to = a directory path (without file): rbioapi will save the file with a proper name in that directory.\
    2.4. save_to = a file path (i.e. ending with .extension): rbioapi will save the file exactly to this path. Make sure that the file extension of the path matches your requested file format. If this was not the case, rbioapi will save the file with the extension supplied in the path, but issues a warning to inform you about that.

    In any of the aforementioned cases, the file path can be absolute or relative.

```{r matrix_save, eval=FALSE}
## Different wqays in which you can save the matrix file:
meme_matrix1 <- rba_jaspar_matrix(matrix_id = "MA0600.2",
                                  file_format = "meme")

meme_matrix2 <- rba_jaspar_matrix(matrix_id = "MA0600.2",
                                  file_format = "meme",
                                  save_to = "my_matrix.meme")

meme_matrix3 <- rba_jaspar_matrix(matrix_id = "MA0600.2",
                                  file_format = "meme",
                                  save_to = "c:/rbioapi")

meme_matrix4 <- rba_jaspar_matrix(matrix_id = "MA0600.2",
                                  file_format = "meme",
                                  save_to = "c:/rbioapi/my_matrix.meme")
```

## Get Binding Sites of a Matrix Profiles

If available, you can retrieve information on binding sites associated with a matrix profile. The information includes a data frame of genomic coordination of the binding site, URL to FASTA and BED files, along with other annotations.

```{r sites, eval=FALSE}
## Get binding site of a matrix profile:
binding_sites <- rba_jaspar_sites(matrix_id = "MA0600.2")
```

------------------------------------------------------------------------

# TF flexible models (TFFMs)

JASPAR also stores and assigns identifiers to TF flexible models (TFFMs). Just like PFM (position frequency matrices), you can search TFFMs or retrieve information and annotations using a TFFM Identifier. TFFM IDs are versioned, meaning that they are in base_id.version format.

```{r tffm_search, eval=FALSE}
## Search TFFMs. This is a search function. Thus, what has been presented
## in `Search Matrix Profiles` section also applies here:

## Get a list of all the available matrix profile:
all_tffms <- rba_jaspar_tffm_search()

## Search FOX:
FOX_tffms <- rba_jaspar_tffm_search(term = "FOX")

## Transcription factors named FOXP3
FOXP3_tffms <- rba_jaspar_tffm_search(term = "FOXP3")

## Transcription factors of insects taxonomic group
insects_tffms <- rba_jaspar_tffm_search(tax_group = "insects")
```

```{r tffm}
## Now that you have a TFFM ID, you can retrieve it
TFFM0056 <- rba_jaspar_tffm("TFFM0056.3")
str(TFFM0056)
```

------------------------------------------------------------------------

# How to Cite? {#Citations}

To cite JASPAR (Please see <https://jaspar.genereg.net/faq/>):

-   Jaime A Castro-Mondragon, Rafael Riudavets-Puig, Ieva Rauluseviciute, Roza Berhanu Lemma, Laura Turchi, Romain Blanc-Mathieu, Jeremy Lucas, Paul Boddie, Aziz Khan, Nicolás Manosalva Pérez, Oriol Fornes, Tiffany Y Leung, Alejandro Aguirre, Fayrouz Hammal, Daniel Schmelter, Damir Baranasic, Benoit Ballester, Albin Sandelin, Boris Lenhard, Klaas Vandepoele, Wyeth W Wasserman, François Parcy, Anthony Mathelier, JASPAR 2022: the 9th release of the open-access database of transcription factor binding profiles, *Nucleic Acids Research*, Volume 50, Issue D1, 7 January 2022, Pages D165--D173, <https://doi.org/10.1093/nar/gkab1113>

To cite rbioapi:

-   Moosa Rezwani, Ali Akbar Pourfathollah, Farshid Noorbakhsh, rbioapi: User-Friendly R Interface to Biologic Web Services' API, *Bioinformatics*, 2022;, btac172, <https://doi.org/10.1093/bioinformatics/btac172>

------------------------------------------------------------------------

# Links {.heading2}

-   [This article in rbioapi documentation site](https://rbioapi.moosa-r.com/articles/rbioapi_jaspar.html "2.G: JASPAR & rbioapi")

-   [Functions references in rbioapi documentation site](https://rbioapi.moosa-r.com/reference/index.html#section-jaspar-rba-jaspar- "rbioapi reference")

-   [rbioapi vignette index](rbioapi.html "rbioapi: User-Friendly R Interface to Biologic Web Services' API")

------------------------------------------------------------------------

# Session info {#session-info .heading2}

```{r sessionInfo, echo=FALSE}
sessionInfo()
```
