# 2.F: UniProt & rbioapi

#### Moosa Rezwani

#### 2021-04-29

# 1 Introduction

Directly quoting from UniProt:

> The Universal Protein Resource (UniProt) is a comprehensive resource for protein sequence and annotation data. The UniProt databases are the UniProt Knowledgebase (UniProtKB), the UniProt Reference Clusters (UniRef), and the UniProt Archive (UniParc). The UniProt consortium and host institutions EMBL-EBI, SIB and PIR are committed to the long-term preservation of the UniProt databases.

> (source: https://www.uniprot.org/help/about)

# 2 Search vs Retrieve

Most of rbioapi UniProt functions have two variants. one to retrieve data using a proper accession, and the second one (which have a `_search` suffix) is to search using any combination of arguments. We first demonstrate this using an example, then provide a list of such functions in rbioapi.

Suppose we are interested in Human CD40 ligand protein, and we know that it’s UniProt accession is “P29965”. We can simply do as the following:

    ## 1 We can retrieve CD40 protein's information by qurying it's UniProt accession:
    cd40 <- rba_uniprot_proteins(accession = "P29965")

    ## 2 We use str() to inspect our object's structure
    str(cd40, 1)
    #> List of 13
    #>  $ accession       : chr "P29965"
    #>  $ id              : chr "CD40L_HUMAN"
    #>  $ proteinExistence: chr "Evidence at protein level"
    #>  $ info            :List of 4
    #>  $ organism        :List of 3
    #>  $ protein         :List of 4
    #>  $ gene            :'data.frame':    1 obs. of  2 variables:
    #>  $ comments        :'data.frame':    12 obs. of  10 variables:
    #>  $ features        :'data.frame':    63 obs. of  9 variables:
    #>  $ dbReferences    :'data.frame':    128 obs. of  4 variables:
    #>  $ keywords        :'data.frame':    13 obs. of  1 variable:
    #>  $ references      :'data.frame':    25 obs. of  3 variables:
    #>  $ sequence        :List of 5

This is the equivalent of the page that UniProt have on this accession (UniProtKB - P29965). But what if we didn’t know the UniProt accession? Or simply want to perform a search using certain parameters? We can use the function with `_search` suffix:

    ## 1 From the available arguments, we fill only those which we think is pertinent
    cd40_search <- rba_uniprot_proteins_search(protein = "CD40 ligand",
                                              organism = "human",
                                              reviewed = TRUE)
    ## 2 As always, we use str() to inspect our object's structure
    str(cd40_search, 2)
    #> List of 1
    #>  $ P29965:List of 13
    #>   ..$ accession       : chr "P29965"
    #>   ..$ id              : chr "CD40L_HUMAN"
    #>   ..$ proteinExistence: chr "Evidence at protein level"
    #>   ..$ info            :List of 4
    #>   ..$ organism        :List of 3
    #>   ..$ protein         :List of 4
    #>   ..$ gene            :List of 1
    #>   ..$ comments        :List of 12
    #>   ..$ features        :List of 63
    #>   ..$ dbReferences    :List of 128
    #>   ..$ keywords        :List of 13
    #>   ..$ references      :List of 25
    #>   ..$ sequence        :List of 5

This is the equivalent of ‘advanced search’ in UniProt web portal. Refer to function `rba_uniprot_proteins_search`’s manual for more information. Remember that in `*_search` functions, you are not required to fill every argument, you can use any combination of arguments you see fit to build your search query.

The applications of `*_search` variants are not limited to what the title ‘search’ implies. These functions will also retrieve the search hits in their response; Thus you can use them for mass-retrieving. If you refer to the “argument” section in the functions’ manuals, you would see that many arguments accept a vector of values. consider the following examples:

    ## 1 As the simplest scenario, we can retrieve multiple proteins in one call
    multi_prs1 <- rba_uniprot_proteins_search(accession = c("P04637",
                                                           "P38398",
                                                           "P24941",
                                                           "P60953",
                                                           "P06493",
                                                           "Q02241"))
    ## As always, we use str() to inspect our object's structure
    str(multi_prs1, 1)
    #> List of 6
    #>  $ P24941:List of 14
    #>  $ P04637:List of 14
    #>  $ Q02241:List of 14
    #>  $ P38398:List of 14
    #>  $ P06493:List of 14
    #>  $ P60953:List of 14

    ## 2 Or alternatively, search using Gene names, also we want to exclude isoforms and only retrieve swiss-prot entries
    multi_prs2 <- rba_uniprot_proteins_search(gene = c("KIF23",
                                                      "BRCA1",
                                                      "TP53",
                                                      "CDC42"),
                                             reviewed = TRUE,
                                             taxid = 9606,
                                             isoform = 0)

    str(multi_prs2, 1)
    #> List of 29
    #>  $ Q9ULZ0:List of 14
    #>  $ Q02241:List of 14
    #>  $ P38398:List of 14
    #>  $ Q9Y2B4:List of 13
    #>  $ Q8IXH6:List of 14
    #>  $ Q53FA7:List of 14
    #>  $ Q12888:List of 14
    #>  $ Q96A56:List of 14
    #>  $ O14683:List of 14
    #>  $ A1A5B4:List of 14
    #>  $ Q9NS56:List of 14
    #>  $ P04637:List of 14
    #>  $ Q9HCN2:List of 14
    #>  $ Q96S44:List of 14
    #>  $ Q8NBR0:List of 14
    #>  $ Q13625:List of 14
    #>  $ Q9UKI2:List of 14
    #>  $ Q6NZY7:List of 14
    #>  $ Q6DT37:List of 14
    #>  $ Q00587:List of 14
    #>  $ O14613:List of 14
    #>  $ Q5VT25:List of 14
    #>  $ P60953:List of 14
    #>  $ Q9H3Q1:List of 14
    #>  $ Q7L0Q8:List of 14
    #>  $ Q07960:List of 14
    #>  $ Q9Y5S2:List of 14
    #>  $ Q9NRR8:List of 14
    #>  $ Q9NRR3:List of 14

    ## 3 Search for every proteins with chemokines keyword
    multi_prs3 <- rba_uniprot_proteins_search(keyword = "chemokines")

    str(multi_prs3, 1)
    #> List of 14
    #>  $ P69332:List of 15
    #>  $ P24766:List of 15
    #>  $ P19063:List of 14
    #>  $ P16849:List of 15
    #>  $ P09703:List of 15
    #>  $ Q6SW98:List of 15
    #>  $ P33854:List of 14
    #>  $ P0DSV7:List of 15
    #>  $ Q98314:List of 15
    #>  $ P34016:List of 14
    #>  $ P21064:List of 14
    #>  $ P0DSV8:List of 15
    #>  $ P07562:List of 14
    #>  $ F5HBX1:List of 14

    ## 4 Search for every protein of "SARS-CoV-2" virus in Swiss-Prot
    multi_prs4 <- rba_uniprot_proteins_search(organism = "SARS-CoV-2",
                                             reviewed = TRUE)

    str(multi_prs4, 1)
    #> List of 16
    #>  $ P0DTD8:List of 14
    #>  $ P0DTD1:List of 14
    #>  $ P0DTC1:List of 13
    #>  $ P0DTD2:List of 14
    #>  $ P0DTC8:List of 14
    #>  $ P0DTC4:List of 14
    #>  $ P0DTD3:List of 14
    #>  $ P0DTC9:List of 14
    #>  $ P0DTC6:List of 14
    #>  $ P0DTC5:List of 14
    #>  $ P0DTC3:List of 14
    #>  $ P0DTG0:List of 13
    #>  $ P0DTC7:List of 14
    #>  $ P0DTC2:List of 14
    #>  $ P0DTG1:List of 13
    #>  $ P0DTF1:List of 13

## 2.1 Functions with `*_search` variant

The search variants are not limited to what we showed above. Here is a list of the function that have both a retrieve and search variants. Refer to their manuals for detailed guides and examples.

1. `rba_uniprot_proteins()` & `rba_uniprot_proteins_search()`

2. `rba_uniprot_features()` & `rba_uniprot_features_search()`

3. `rba_uniprot_variation()` & `rba_uniprot_variation_search()`

4. `rba_uniprot_proteomics()` & `rba_uniprot_proteomics_search()`

5. `rba_uniprot_antigens()` & `rba_uniprot_antigens_search()`

6. `rba_uniprot_proteomes()` & `rba_uniprot_proteomes_search`

7. `rba_uniprot_genecentric()` & `rba_uniprot_genecentric_search()`

8. `rba_uniprot_uniparc()` & `rba_uniprot_uniparc_search()`

# 3 UniProt functions categories

In UniProt RESTful API documentation, the endpoints are organized into 5 group. Here are those categories and rbioapi functions that correspond to each one. Refer to the functions’ manuals for more details.

## 3.1 Proteins

### 3.1.1 Proteins:

- `rba_uniprot_proteins()`

- `rba_uniprot_proteins_search()`

- `rba_uniprot_proteins_crossref()`

### 3.1.2 Features

- `rba_uniprot_features()`

- `rba_uniprot_features_search()`

### 3.1.3 Variation

`rba_uniprot_variation()`

`rba_uniprot_variation_search()`

### 3.1.4 Proteomics

- `rba_uniprot_proteomics()`

- `rba_uniprot_proteomics_search()`

### 3.1.5 Antigens

- `rba_uniprot_antigens()`

- `rba_uniprot_antigens_search()`

## 3.2 Proteomes

- `rba_uniprot_proteomes()`

- `rba_uniprot_proteomes_search()`

- `rba_uniprot_genecentric()`

- `rba_uniprot_genecentric_search()`

## 3.3 Taxonomy

- `rba_uniprot_taxonomy()`

- `rba_uniprot_taxonomy_lca()`

- `rba_uniprot_taxonomy_lineage()`

- `rba_uniprot_taxonomy_name()`

- `rba_uniprot_taxonomy_path()`

- `rba_uniprot_taxonomy_relationship()`

## 3.4 Coordinates

- `rba_uniprot_coordinates()`

- `rba_uniprot_coordinates_search()`

- `rba_uniprot_coordinates_location()`

- `rba_uniprot_coordinates_sequence()`

## 3.5 UniParc

- `rba_uniprot_uniparc()`

- `rba_uniprot_uniparc_search()`

- `rba_uniprot_uniparc_bestguess()`

- `rba_uniprot_uniparc_sequence()`

# 4 Session info

    #> R version 4.0.5 (2021-03-31)
    #> Platform: x86_64-w64-mingw32/x64 (64-bit)
    #> Running under: Windows 10 x64 (build 19043)
    #>
    #> Matrix products: default
    #>
    #> locale:
    #> [1] LC_COLLATE=C
    #> [2] LC_CTYPE=English_United States.1252
    #> [3] LC_MONETARY=English_United States.1252
    #> [4] LC_NUMERIC=C
    #> [5] LC_TIME=English_United States.1252
    #> system code page: 1256
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] rbioapi_0.7.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] Rcpp_1.0.6        knitr_1.33        magrittr_2.0.1    xtable_1.8-4
    #>  [5] R6_2.5.0          rlang_0.4.10      fastmap_1.1.0     highr_0.9
    #>  [9] stringr_1.4.0     httr_1.4.2        tools_4.0.5       grid_4.0.5
    #> [13] DT_0.18           xfun_0.22         png_0.1-7         jquerylib_0.1.4
    #> [17] ellipsis_0.3.2    htmltools_0.5.1.1 crosstalk_1.1.1   yaml_2.2.1
    #> [21] digest_0.6.27     lifecycle_1.0.0   shiny_1.6.0       later_1.2.0
    #> [25] promises_1.2.0.1  sass_0.3.1        htmlwidgets_1.5.3 curl_4.3
    #> [29] mime_0.10         evaluate_0.14     rmarkdown_2.7     stringi_1.5.3
    #> [33] compiler_4.0.5    bslib_0.2.4       jsonlite_1.7.2    httpuv_1.6.0