README.Rmd

rplos
=====

```{r echo=FALSE}
knitr::opts_chunk$set(
  fig.path = "man/figures/",
  warning = FALSE,
  message = FALSE,
  collapse = TRUE,
  comment = "#>",
  fig.cap = ""
)
```

[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![cran checks](https://cranchecks.info/badges/worst/rplos)](https://cranchecks.info/pkgs/rplos)
[![R-check](https://github.com/ropensci/rplos/workflows/R-check/badge.svg)](https://github.com/ropensci/rplos/actions?query=workflow%3AR-check)
[![codecov.io](https://codecov.io/github/ropensci/rplos/coverage.svg?branch=master)](https://codecov.io/github/ropensci/rplos?branch=master)
[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/rplos)](https://github.com/r-hub/cranlogs.app)
[![cran version](https://www.r-pkg.org/badges/version/rplos)](https://cran.r-project.org/package=rplos)

## Install

You can get this package at CRAN [here](https://cran.r-project.org/package=rplos), or install it within R by doing

```{r eval=FALSE}
install.packages("rplos")
```

Or install the development version from GitHub

```{r eval=FALSE}
remotes::install_github("ropensci/rplos")
```

```{r}
library("rplos")
```

## What is this?

`rplos` is a package for accessing full text articles from the Public Library of Science journals using their API.

## Information

You used to need a key to use `rplos` - you no longer do as of 2015-01-13 (or `v0.4.5.999`).

rplos vignetttes: <https://docs.ropensci.org/rplos/>

PLOS API documentation: <http://api.plos.org/>

PLOS Solr schema is at <https://gist.github.com/openAccess/9e76aa7fa6135be419968b1372c86957> but is 1.5 years old so may not be up to date.

Crossref API documentation can be found at <https://github.com/CrossRef/rest-api-doc>. See also [rcrossref](https://github.com/ropensci/rcrossref) ([on CRAN](https://cran.r-project.org/package=rcrossref)) with a much fuller implementation of R functions for all Crossref endpoints.

## Throttling

Beware, PLOS recently has started throttling requests. That is,
they will give error messages like "(503) Service Unavailable -
The server cannot process the request due to a high load", which
means you've done too many requests in a certain time period. Here's
[what they say](http://api.plos.org/solr/faq/#solr_api_recommended_usage) on the matter:

> Please limit your API requests to 7200 requests a day, 300 per hour, 10 per minute and allow 5 seconds for your search to return results. If you exceed this threshold, we will lock out your IP address. If you're a high-volume user of the PLOS Search API and need more API requests a day, please contact us at api@plos.org to discuss your options. We currently limit API users to no more than five concurrent connections from a single IP address.

## Quick start

### Search

Search for the term ecology, and return id (DOI) and publication date, limiting to 5 items

```{r}
searchplos('ecology', 'id,publication_date', limit = 5)
```

Get DOIs for full article in PLoS One

```{r}
searchplos(q="*:*", fl='id', fq=list('journal_key:PLoSONE',
   'doc_type:full'), limit=5)
```

Query to get some PLOS article-level metrics, notice difference between two outputs

```{r}
out <- searchplos(q="*:*", fl=c('id','counter_total_all','alm_twitterCount'), fq='doc_type:full')
out_sorted <- searchplos(q="*:*", fl=c('id','counter_total_all','alm_twitterCount'),
   fq='doc_type:full', sort='counter_total_all desc')
head(out$data)
head(out_sorted$data)
```

A list of articles about social networks that are popular on a social network

```{r}
searchplos(q="*:*",fl=c('id','alm_twitterCount'),
   fq=list('doc_type:full','subject:"Social networks"','alm_twitterCount:[100 TO 10000]'),
   sort='counter_total_month desc')
```

Show all articles that have these two words less then about 15 words apart

```{r}
searchplos(q='everything:"sports alcohol"~15', fl='title', fq='doc_type:full', limit=3)
```

Narrow results to 7 words apart, changing the ~15 to ~7

```{r}
searchplos(q='everything:"sports alcohol"~7', fl='title', fq='doc_type:full', limit=3)
```

Remove DOIs for annotations (i.e., corrections) and Viewpoints articles

```{r}
searchplos(q='*:*', fl=c('id','article_type'),
   fq=list('-article_type:correction','-article_type:viewpoints'), limit=5)
```

### Faceted search

Facet on multiple fields

```{r}
facetplos(q='alcohol', facet.field=c('journal','subject'), facet.limit=5)
```

Range faceting

```{r}
facetplos(q='*:*', url=url, facet.range='counter_total_all',
 facet.range.start=5, facet.range.end=100, facet.range.gap=10)
```

### Highlight searches

Search for and highlight the term _alcohol_ in the abstract field only

```{r}
(out <- highplos(q='alcohol', hl.fl = 'abstract', rows=3))
```

And you can browse the results in your default browser

```{r eval=FALSE}
highbrow(out)
```

![highbrow](man/figures/highbrow.png)

### Full text urls

Simple function to get full text urls for a DOI

```{r}
full_text_urls(doi='10.1371/journal.pone.0086169')
```

### Full text xml given a DOI

```{r}
(out <- plos_fulltext(doi='10.1371/journal.pone.0086169'))
```

Then parse the XML any way you like, here getting the abstract

```{r}
library("XML")
xpathSApply(xmlParse(out$`10.1371/journal.pone.0086169`), "//abstract", xmlValue)
```

### Search within a field

There are a series of convience functions for searching within sections of articles.

* `plosauthor()`
* `plosabstract()`
* `plosfigtabcaps()`
* `plostitle()`
* `plossubject()`

For example:

```{r}
plossubject(q='marine ecology',  fl = c('id','journal'), limit = 10)
```

However, you can always just do this in `searchplos()` like `searchplos(q = "subject:science")`. See also the `fq` parameter. The above convenience functions are simply wrappers around `searchplos`, so take all the same parameters.

### Search by article views

Search with term _marine ecology_, by field _subject_, and limit to 5 results

```{r}
plosviews(search='marine ecology', byfield='subject', limit=5)
```

### Visualize

Visualize word use across articles

```{r fig.cap="wordusage"}
plosword(list('monkey','Helianthus','sunflower','protein','whale'), vis = 'TRUE')
```

### progress bars

```{r eval = FALSE}
res <- searchplos(q='*:*', limit = 2000, progress = httr::progress())
#>  |=====================================| 100%
#>  |=====================================| 100%
#>  |=====================================| 100%
#>  |=====================================| 100%
```

## Meta

* Please [report any issues or bugs](https://github.com/ropensci/rplos/issues).
* License: MIT
* Get citation information for `rplos` in R doing `citation(package = 'rplos')`
* Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project, you agree to abide by its terms.

---

This package is part of a richer suite called [fulltext](https://github.com/ropensci/fulltext), along with several other packages, that provides the ability to search for and retrieve full text of open access scholarly articles. We recommend using `fulltext` as the primary R interface to `rplos` unless your needs are limited to this single source.

---