ropensci / raltmetric

Query and visualize metrics from altmetric.com

---

---

rAltmetric

This package provides a way to programmatically retrieve altmetrics from various publication types (books, newsletters, articles, peer-reviewed papers and more) from altmetric.com. The package is really simple to use and only has two major functions:

• altmetrics - Pass it a doi, isbn, uri, arxiv id or other to get metrics
• altmetric_data Pass it the results from the previous call to get a tidy data.frame

Questions, features requests and issues should go here.

Installing the package 🛠

A stable version is available from CRAN. To install

install.packages('rAltmetric')
# or the 👷 dev version
devtools::install_github("ropensci/rAltmetric")

Quick Tutorial

Obtaining metrics

There was a 2010 paper by Acuna et al that received a lot of attention on Twitter. What was the impact of that paper?

library(rAltmetric)
acuna <- altmetrics(doi = "10.1038/465860a")
acuna
#> Altmetrics on: "Metrics: Do metrics matter?" with altmetric_id: 385053 published in Nature.
#>                         stats
#> cited_by_fbwalls_count      3
#> cited_by_feeds_count        3
#> cited_by_gplus_count        2
#> cited_by_msm_count          1
#> cited_by_policies_count     1
#> cited_by_posts_count       31
#> cited_by_tweeters_count    20
#> cited_by_accounts_count    30

Data

To obtain the metrics in tabular form for further processing, run any object of class altmetric through altmetric_data() to get a data.frame that can easily be written to disk.

altmetric_data(acuna)
#>                         title             doi     pmid
#> 1 Metrics: Do metrics matter? 10.1038/465860a 20559361
#>                                                                         tq1
#> 1 Survey of how metrics are used in hiring, promotion and tenure decisions.
#>                                                                                                   tq2
#> 1 Should some professions be excluded from performance metrics? #metrics #kpi #performancemeasurement
#>                                                tq3
#> 1 “@Nanomedicina: Publications: Do metrics matter?
#>                                               tq4            altmetric_jid
#> 1 Do metrics matter? #oaweek13 (in talk @pgroth ) 4f6fa50a3cf058f610003160
#>      issns1    issns2 journal cohorts.pub cohorts.sci cohorts.com
#> 1 0028-0836 1476-4687  Nature          13           5           2
#>   context.all.count context.all.mean context.all.rank context.all.pct
#> 1           7133716  6.3030007714043           130911              98
#>   context.all.higher_than context.journal.count context.journal.mean
#> 1                 7003174                 44393       68.76030910975
#>   context.journal.rank context.journal.pct context.journal.higher_than
#> 1                10546                  76                       33847
#>   context.similar_age_3m.count context.similar_age_3m.mean
#> 1                        76598              5.330816089403
#>   context.similar_age_3m.rank context.similar_age_3m.pct
#> 1                        1082                         98
#>   context.similar_age_3m.higher_than context.similar_age_journal_3m.count
#> 1                              75516                                  894
#>   context.similar_age_journal_3m.mean context.similar_age_journal_3m.rank
#> 1                     54.580732362822                                 262
#>   context.similar_age_journal_3m.pct
#> 1                                 70
#>   context.similar_age_journal_3m.higher_than type altmetric_id schema
#> 1                                        632 news       385053  1.5.4
#>   is_oa cited_by_fbwalls_count cited_by_feeds_count cited_by_gplus_count
#> 1 FALSE                      3                    3                    2
#>   cited_by_msm_count cited_by_policies_count cited_by_posts_count
#> 1                  1                       1                   31
#>   cited_by_tweeters_count cited_by_accounts_count last_updated  score
#> 1                      20                      30   1454625692 53.388
#>   history.1y history.6m history.3m history.1m history.1w history.6d
#> 1          0          0          0          0          0          0
#>   history.5d history.4d history.3d history.2d history.1d history.at
#> 1          0          0          0          0          0     53.388
#>                                 url   added_on published_on subjects
#> 1 http://dx.doi.org/10.1038/465860a 1317207766   1276646400  science
#>   scopus_subjects readers.citeulike readers.mendeley readers.connotea
#> 1         General                 3              303                2
#>   readers_count
#> 1           308
#>                                                                 images.small
#> 1 https://altmetric-badges.a.ssl.fastly.net/?size=64&score=54&types=mbtttfdg
#>                                                                 images.medium
#> 1 https://altmetric-badges.a.ssl.fastly.net/?size=100&score=54&types=mbtttfdg
#>                                                                  images.large
#> 1 https://altmetric-badges.a.ssl.fastly.net/?size=180&score=54&types=mbtttfdg
#>                                               details_url
#> 1 http://www.altmetric.com/details.php?citation_id=385053

You can save these data into a clean spreadsheet format:

acuna_data <- altmetric_data(acuna)
readr::write_csv(acuna_data, path = 'acuna_altmetrics.csv')

Gathering metrics for many DOIs

For a real world use-case, one might want to get metrics on multiple publications. If so, just read them from a spreadsheet and llply through them like the example below.

library(rAltmetric)
library(magrittr)
#> 
#> Attaching package: 'magrittr'
#> The following object is masked from 'package:purrr':
#> 
#>     set_names
#> The following object is masked from 'package:tidyr':
#> 
#>     extract
library(purrr)


ids <- list(c(
  "10.1038/nature09210",
  "10.1126/science.1187820",
  "10.1016/j.tree.2011.01.009",
  "10.1086/664183"
))

alm <- function(x)  altmetrics(doi = x) %>% altmetric_data()

results <- pmap_df(ids, alm)
# This results in a data.frame with one row per identifier.

Further reading

• Metrics: Do metrics matter?
• The altmetrics manifesto

📚 To cite package rAltmetric in publications use:

  Karthik Ram (2017). rAltmetric: Retrieves altmerics data for any
  published paper from altmetrics.com. R package version 0.7.
  http://CRAN.R-project.org/package=rAltmetric

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {rAltmetric: Retrieves altmerics data for any published paper from
altmetrics.com},
    author = {Karthik Ram},
    year = {2017},
    note = {R package version 0.7},
    url = {http://CRAN.R-project.org/package=rAltmetric},
  }

raltmetric's Issues

link in gh-pages page

from an email

Since late November, the target of the link titled ‘Digging into altmetrics’ at http://ropensci.github.io/rAltmetric/#use-cases has had a limited scope: within the intranet of our University only. This is due to a lengthy update process of the local WordPress platform. This situation is said to last until the end of January 2015, perhaps even longer. Lack of resources etc. Just in case you’d like to edit the link: I put a backup copy to my private domain http://tuijasonkkila.fi/blog/digging-into-altmetrics/

New identifiers (URN, ISBN)?

Dear Developers,

with the new identifiers that Altmetric.com now supports (ISBN, URN) are there any plans to add those to the Arguments so that Altmetrics for Publications are searchable via URN or ISBN?
That would be great.
With best regards
Elisabeth

counts x timeframe

Would it be possible to retrieve, for each DOI, counts x timeframe for different sources? and an extract of the news or tweets for example?

A DOI like 'this/is/notadoi' returns a score of 12.35

Example:

library("rAltmetric")
result <- altmetrics(doi = "this/is/notadoi")
(result$title)
#> [1] "Using Qualitative Methods to Create a Home Health Web Application User Interface for Patients with Low Computer Proficiency"
(result$score)
#> [1] 12.35

Add generic method for show

This should print to screen the contents of a altmetric object.

Missing provider information

I just used this for the first time (and I realize #14 is out there, so this may be kind of moot) but the package doesn't seem to be returning provider information correctly. As an example:

> altmetrics(doi = "10.1158/0008-5472.CAN-13-0991")
Altmetrics on: "A Novel Model of Dormancy for Bone Metastatic Breast Cancer Cells" with altmetric_id: 1860158 published in Cancer Research.
    provider count
1          7     1
2          8    12
3          2    21
4 integer(0)     1
5         11     3
6          1    17

I assume, from documentation, those should be provider names not numbers. I'm not really sure how to interpret this as it is currently printing.

List of PMID's creates parse_url error

I created a list of PMID's I have- roughly 27,00 - and when I pass it through altmetrics(pmid = my_list), i consistently get an error. Is there a way I can pass all 27000 pmids through the commands so to create a new dataframe with all of the metrics?

More details from API

filing this issue from an email thread from Jason so I don't forget later

I do appreciate your response. Yes, this a more detailed response, however,
no it does not contain the fields I was looking for.
I was not sure if the package produced responses similar to those from the
api's documentation. I am looking for twitter timestamps for multiple
articles, like the response here, for example: https://api.
altmetric.com/docs/call_fetch.html.

Thank you.

What is the correct way to query for an arXiv ID?

I'd like to obtain results for an arXiv ID, such as arXiv:1312.5566. I haven't been able to get it to work though. So far, I have tried a number of combinations, but none of them worked:

• altmetrics(arXiv='arXiv:1312.5566')
• altmetrics(arXiv='1312.5566')
• altmetrics('arXiv/arXiv:1312.5566')

What would be the correct call?

NULL list element in raw_metrics

When dealing with many DOIs and when no metrics has been found for some of them (ie the list element is NULL), the altmetric_data function throws an error about the raw_metrics list:

metric_data <- ldply(raw_metrics, altmetric_data)

Error in class(output[[var]]) <- class(value) :
attempt to set an attribute on NULL

data.frame output from calling altmetric_data doesn't seem quite right

For example, see this screenshot:

It looks like a bunch of fields that should be character or factor were somehow converted to numeric (e.g., title, doi, etc.).

Here's the link to the code if you want to reproduce what I did

altmetric(handle)

I wonder if the library could allow the use of Handles to select documents (apart from DOI).

Thanks

testing

Retrieving tweets

Dear rAltmetric developer(s)
Thank you very much for developing this very useful package. As altmetric research grows, people are looking into content analysis of tweets, Facebook comments, etc. For my case, it's tweets. So, it would be great if we could also retrieve tweets of articles based on DOI with rAltmetric.
Thanks and regards
Tint

Fix issue with arxiv

Arrrr> altmetrics(arXiv = "arXiv:1611.01704")
Error in altmetrics(arXiv = "arXiv:1611.01704") : 
  No metrics found for object
Arrrr> altmetrics("arXiv:1611.01704")
Altmetrics on: "End-to-end Optimized Image Compression" with altmetric_id: 13423869 published in arXiv.
                        stats
cited_by_posts_count      107
cited_by_tweeters_count    92
cited_by_accounts_count    92

Package needs a major rewrite

Everything here is quite dated (pre httr), and could use a solid refresh.
There also seem to have been some silent API changes that I need to account for after emailing with Altmetric.

I'll strive to get the new package ready by the end of the week.

Add Generic methods for plot

This will provide a way to generate ggplots of metrics data as a generic method.

CRAN check notes

checking package dependencies ... NOTE
Depends: includes the non-default packages:
  ‘plyr’ ‘RCurl’ ‘reshape2’ ‘png’ ‘ggplot2’ ‘RJSONIO’
Adding so many packages to the search path is excessive and importing
selectively is preferable.

checking top-level files ... NOTE
Non-standard files/directories found at top level:
  ‘acuna.png’ ‘altmetric_logo_title.png’

checking dependencies in R code ... NOTE
Packages in Depends field not imported from:
  ‘RCurl’ ‘RJSONIO’ ‘ggplot2’ ‘plyr’ ‘png’ ‘reshape2’
  These packages need to be imported from (in the NAMESPACE file)
  for when this namespace is loaded but not attached.
See the information on DESCRIPTION files in the chapter ‘Creating R
packages’ of the ‘Writing R Extensions’ manual.

checking R code for possible problems ... NOTE
altmetric_data: no visible global function definition for ‘rbind.fill’
altmetric_data: no visible global function definition for ‘unrowname’
altmetric_data: no visible global function definition for ‘melt’
altmetric_data: no visible global function definition for ‘dcast’
altmetrics: no visible global function definition for ‘getCurlHandle’
altmetrics: no visible global function definition for ‘compact’
altmetrics: no visible global function definition for ‘getURL’
altmetrics: no visible global function definition for ‘fromJSON’
plot.altmetric: no visible global function definition for ‘melt’
plot.altmetric: no visible global function definition for ‘readPNG’
plot.altmetric: no visible global function definition for
  ‘getURLContent’
plot.altmetric: no visible global function definition for ‘ggplot’
plot.altmetric: no visible global function definition for ‘aes’
plot.altmetric: no visible global function definition for ‘geom_point’
plot.altmetric: no visible global function definition for ‘ggtitle’
plot.altmetric: no visible global function definition for ‘xlab’
plot.altmetric: no visible global function definition for ‘ylab’
plot.altmetric: no visible global function definition for ‘theme’
plot.altmetric: no visible global function definition for
  ‘element_blank’
plot.altmetric: no visible global function definition for
  ‘element_line’
plot.altmetric: no visible global function definition for
  ‘annotation_raster’
plot.altmetric: no visible global function definition for
  ‘element_text’
print.altmetric: no visible global function definition for ‘melt’

Error in altmetrics: No metrics found for object

Right now, if you search for a DOI that does not have altmetric data, you get an error "No metrics found for object". Would it be possible for the function to just send a warning when the DOI is not found?

For example, if you do:

altmetrics(doi = "10.22199/s07187475.2015.0001.00004")

You will get:

Error in altmetrics(doi = "10.22199/s07187475.2015.0001.00004") : No metrics found for object

The main issue is that if I want to get the altmetric data for a group of papers, I have to include ways to keep on going when there is an error, so, something like this fails miserably:

DOIS = c("10.22199/s07187475.2015.0001.00004", "10.1093/brain/aww231", "10.1038/s41562-017-0118")
altmetrics_lists = DOIS %>% map( ~ altmetrics(doi = .x))
altmetrics_df = altmetrics_lists %>% map_df(~rAltmetric::altmetric_data(.x))

If I remove the offending DOI, I can get all the altmetric info easily:

DOIS = c("10.1093/brain/aww231", "10.1038/s41562-017-0118")
altmetrics_lists = DOIS %>% map( ~ altmetrics(doi = .x))
altmetrics_df = altmetrics_lists %>% map_df(~rAltmetric::altmetric_data(.x))

As far as I can see, changing: error("No metrics found for object") for warning("No metrics found for object") would suffice?

Remove depends list

Looking at my old code, yuck. Need to move everything away from the depends list to Imports. Also consider switching away from RCurl to httr if that is possible without too much headache.

Update Readme file with API language

The free Altmetric API (and thus rAltmetric) can be used without a key, but our API is only meant to be used that way for small-scale, noncommercial analyses.

To help rAltmetric users understand how to request an API key for larger scale analyses and commercial uses (eg reporting) and to point people towards the Altmetric help documentation when they have data-related questions, it would be wonderful to have the README.md file updated with the following language:

This package provides a way to programmatically retrieve metrics from various publication types (books, journal articles, data sets, and more) from Altmetric. The package is really simple to use and only has two major functions:

• altmetrics - Pass it a doi, isbn, uri, arxiv id or other to get metrics
• altmetric_data - Pass it the results from the previous call to get a tidy data.frame

rAltmetric uses the free Altmetric API to retrieve metrics. You can use this package without an API key for small-scale or exploratory noncommercial analyses.

You’ll need to provide rAltmetric with an Altmetric API key to avoid rate limits if:

• You intend to retrieve data for more than 250 publications, or
• You intend to use this package for any kind of commercial analyses (including organizational reporting, consulting work, etc)

To request an Altmetric API key, email [email protected] with a description of your project.

Package-related questions, feature requests and issues should go here.

Altmetric data-related questions can usually be answered by checking out their API documentation or Altmetric support portal or, if all else fails, emailing [email protected].