alm_ids: Retrieve PLoS article-level metrics (ALM).

In ropensci/alm: R Client for the Lagotto Altmetrics Platform

Retrieve PLoS article-level metrics (ALM).

Description

This is the main function to search the PLoS ALM (article-level metrics) API. See details for more information.

Usage

alm_ids(doi = NULL, pmid = NULL, pmcid = NULL, wos = NULL, scp = NULL,
  url = NULL, info = "totals", source_id = NULL, publisher_id = NULL,
  key = NULL, total_details = FALSE, sum_metrics = NULL, sleep = 0,
  api_url = "http://alm.plos.org/api/v5/articles", ...)

Arguments

doi	(character) Digital object identifier for an article in PLoS Journals
pmid	(numeric) PubMed object identifier
pmcid	(numeric) PubMed Central object identifier
wos	(character) Web of Science identifier
scp	(character) Scopus identifier
url	(character) Canonical URL. This is a URL for an object, not the URL for the Lagotto instance (see api_url)
info	One of totals, summary, or detail (default totals + sum_metrics data in a list). Not specifying anything (the default) returns data.frame of totals across data providers. (character). info='detail' returns all possible data, including slots for info, signposts, totals, and sum_metrics (see the sum_metrics parameter below). IMPORTANT: note, however, that you can only get by day metrics for articles published since May 2014.
source_id	(character) Name of source to get ALM information for. One source only. You can get multiple sources via a for loop or lapply-type call.
publisher_id	(character) Metrics for articles by a given publisher, using the Crossref member_id.
key	(character) Your API key, either enter, or loads from .Rprofile. Only required for PKP source, not the others.
total_details	(logical) If FALSE (the default) the standard totals data.frame is returned; if TRUE, the totals data is in a wide format with more details about the paper, including publication date, title, etc. If you set this to TRUE, the output should no longer with with alm_plot.
sum_metrics	(character) Just like the output you get from setting info='totals', you can get summary metrics by day (sum_metrics='day'), month (sum_metrics='month'), or year (sum_metrics='year'). IMPORTANT: note that you can only get by day metrics for articles published since May 2014.
sleep	Set a sleep time (in seconds). Only used for large calls where you may be in danger of upsetting the server gods, can you say 504 error?
api_url	(character) API endpoint, defaults to http://alm.plos.org/api/v5/articles
...	Curl options (debugging tools mostly) passed on to GET

Details

You can only supply one of the parmeters doi, pmid, pmcid, wos, scp, or url; and you must supply one of them. Query for as many articles at a time as you like. Though queries are broken up in to smaller bits of 50 identifiers at a time. If you supply days, months and/or year parameters, days takes precedence over months and year.

Value

PLoS altmetrics as data.frame's.

References

See a tutorial/vignette for alm at http://ropensci.org/tutorials/alm_tutorial.html

See Also

alm_plot

Examples

## Not run: 
# The default call with either doi, pmid, pmcid, wos, scp, or url without specifying
# an argument for info
alm_ids(doi="10.1371/journal.pone.0029797")

# Details for a single DOI
out <- alm_ids(doi='10.1371/journal.pone.0029797', info='detail')
out
## totals
out$data$info
## history
out$data$sum_metrics

# A single PubMed ID (pmid)
alm_ids(pmid=22590526)

# A single PubMed Central ID (pmcid)
alm_ids(pmcid=212692, info='summary')

# A single Web of Science ID (wos)
alm_ids(wos="000268452400005")

# A single Scopus ID (scp)
alm_ids(scp="68049122102")

# A single Canonical URL (url)
alm_ids(url="http://www.plosmedicine.org/article/info:doi/10.1371/journal.pmed.1000097")

# Provide more than one DOI
dois <- c('10.1371/journal.pone.0001543','10.1371/journal.pone.0040117',
		'10.1371/journal.pone.0029797','10.1371/journal.pone.0039395')
out <- alm_ids(doi=dois)
out$data[[1]] # get data for the first DOI

# Search for DOI's, then feed into alm
library('rplos')
dois <- searchplos(q='evolution', fl='id',
   fq=list('-article_type:correction','doc_type:full'), limit = 250)
out <- alm_ids(doi=dois$data$id)
lapply(out, head)

alm_ids(dois$data$id[1:5], source_id = "facebook")

sources <- c("facebook","twitter","mendeley","reddit","scopus","wikipedia")
lapply(sources, function(x) alm_ids(dois$data$id[1:5], source_id = x))

# Provide more than one pmid
pmids <- c(19300479, 19390606, 19343216)
out <- alm_ids(pmid=pmids)
out$data[[3]] # get data for the third pmid

# Getting data for a specific source_id
alm_ids(doi='10.1371/journal.pone.0035869', source_id='mendeley')
alm_ids(doi='10.1371/journal.pone.0035869', source_id='twitter')
alm_ids(doi='10.1371/journal.pone.0035869', source_id='counter', info='detail')
## fails if more than one source_id given
# alm_ids(doi='10.1371/journal.pone.0035869', source_id=c('twitter','facebook'))

# Get detailed totals output
alm_ids(doi='10.1371/journal.pone.0035869', total_details=TRUE)

# Get summary metrics by day
alm_ids(doi='10.1371/journal.pone.0036240', sum_metrics='day')

# Get summary metrics by month
alm_ids(doi='10.1371/journal.pone.0036240', sum_metrics='month')

# Get summary metrics by year
alm_ids(doi='10.1371/journal.pone.0036240', sum_metrics='year')

# Get data by source_id
alm_ids(source_id='crossref')
alm_ids(source_id='twitter')

# Curl debugging
library('httr')
alm_ids(doi="10.1371/journal.pone.0029797", config=verbose())
dois <- c('10.1371/journal.pone.0001543','10.1371/journal.pone.0040117',
 	'10.1371/journal.pone.0029797','10.1371/journal.pone.0039395')
alm_ids(doi=dois, config=progress())

# Data from other sources
## Crossref article data
### Pass in a different URL - no key needed
api_url <- "http://det.labs.crossref.org/api/v5/articles"
alm_ids(doi='10.1371/journal.pone.0086859', api_url = api_url)
alm_ids(doi='10.11646/zootaxa.3618.1.1', api_url = api_url)
alm_ids(doi='10.1016/j.jep.2013.06.007', api_url = api_url)
alm_ids(doi='10.1111/j.1756-1051.2012.00099.x', api_url = api_url)

## Public Knowledge Project article data
### pass in a different url - an API key needed
api_url <- 'http://pkp-alm.lib.sfu.ca/api/v5/articles'
alm_ids(doi='10.3402/gha.v7.23554', api_url = api_url, key = getOption("pkpalmkey"))

## eLife
### pass in a different url - no key needed
api_url <- 'http://lagotto.svr.elifesciences.org/api/v5/articles'
alm_ids(doi='10.7554/eLife.00471', api_url = api_url)

## End(Not run)

ropensci/alm documentation built on May 18, 2022, 9:47 a.m.