laderast / monarchr Goto Github PK

---
title: "monarchr"
author: "charlie c carey"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

[![Build Status](https://travis-ci.org/charlieccarey/monarchr.svg?branch=master)](https://travis-ci.org/charlieccarey/monarchr) [![codecov](https://codecov.io/github/charlieccarey/monarchr/branch/master/graphs/badge.svg)](https://codecov.io/github/charlieccarey/monarchr) 

## Introduction.

This is the README for the monarchr package.

We use monarchr to retrieve and work with genetic, phenotype, and ontological 
information from the Monarch Inititiative [monarchinitiative.org](https://monarchinitiative.org).

Monarch Initiative's API provides structured data from many biological databases. 
Some of the key advantages of Monarch ensue from their considerable effort to enable 
cross species lookups and unification of many different, often species specific ontologies.

The monarchr package has the following goals:

1. Query Monarch's web API, returning R objects for further analysis in R.
2. Ease access from other popular bioconductor packages to Monarch's data.
3. Facilitate reuse of Monarch's data by other packages.

[view documentation](https://charlieccarey.github.io/monarchr/index.html)

[view code](https://github.com/charlieccarey/monarchr)

[Also see the swagger codegen autogenerated client to the api](https://github.com/charlieccarey/monarchr.biolink)

## Examples.

Here are a few examples of usage.

### Get homologs to a particular gene.

Often, we are interested in a particular gene's homologs or orthologs in another organisms.

We query Monarch by using the bioentity_homologs function.

```{r ex_homologs}
library(monarchr)
gene <- "NCBIGene:8314"
results <- bioentity_homologs(gene)
```

The results are a tibble of homologs (paralogs, orthologs and homologs).

When we ran this query, we retrieved ```r nrow(results$homologs)``` homologs.

```{r ex_homologs_resu, echo = TRUE}
library(DT)
datatable(results$homologs)
```

## Troubleshooting.

If we encounter problems, such as an empty result, we can always ask for Monarch's 
response to our query.

### Response from Monarch Initiative.

We returned the response as a monarch_api (S3) class with its own print method

```{r ex_homologs_resp, echo = TRUE}
class(results$response)
```

The print method only shows the URL and highest 2 levels of the contents.

```{r, echo = TRUE}
results$response
```

To view at an alternative depth, supply the *depth* setting to the print method.

```{r ex_homologs_resp_depth, echo = TRUE, eval = FALSE}
# print(results$response, depth=3) # not run.
```

#### Troubleshooting the server status

```{r inspect_response, echo = TRUE, eval = TRUE}
class(results$response$response) # this is the response we saved from the call to httr GET(url)
results$response$url
results$response$response$status_code
#str(results$response$response)
#results$response$response$headers
#results$response$response$request
```

The server should have responded with an OK (200) status. If not, we can confirm the URL ourselves by pasting into a browser, or look at the response and response headers for more info (courtesy of httr).

### View JSON directly from the server.

We can use the URL at the top of monarchr's summary of the response to see the JSON results directly from the server.

(this is easier to view in Firefox):

[https://api.monarchinitiative.org/api/bioentity/gene/NCBIGene%3A8314/homologs/?rows=100&fetch_objects=true&format=json]

### View HTML on server.

If you prefer to see the expected results as HTML, note how the example of looking up NCBIGene:8314 
on Monarch Initiative website ended up at a table for Monarch's preferred ID (HGNC:950). 

[https://monarchinitiative.org/gene/HGNC:950#homologs]

Replacing HGNC:950 with NCBIGene ID, we are successfully directed to the same view.

[https://monarchinitiative.org/gene/NCBIGene:8314#homologs]

## Verify your search returns something consistent with searching Monarch Initiative's website directly.

1. Go to Monarch's front page: [https://monarchinitiative.org/]
1. In the search box, enter and search for: NCBIGene:8314.
2. Select the exact match (of thousands) from Homo sapiens.
   (This is the first match and shows the gene name is BAP1.)
3. Select homologs from the tabs at the top of the next page.

You should see something similar to the following view.

![Homologs as seen on Monarch Inititiative Website.](images/BAP1_homologs.png)

These results shoud be consistent with what we saw in our tibble above, as displayed by DataTables (R DT package).