pybliometrics.scopus.PlumXMetrics

PlumXMetrics() implements the PlumX Metrics API. It provides metrics in five categories: captures, citations, usage, mentions, and social media (background information). It works for 33 different types of media.

Table of Contents

Documentation

class pybliometrics.scopus.PlumXMetrics(identifier, id_type, refresh=False)[source]

Interaction with the PlumX Metrics API.

Parameters
  • identifier (str) – The identifier of a document.

  • id_type (str) – The type of used ID. Allowed values are: - ‘airitiDocId’ - ‘arxivId’ - ‘cabiAbstractId’ - ‘citeulikeId’ - ‘digitalMeasuresArtifactId’ - ‘doi’ - ‘elsevierId’ - ‘elsevierPii’ - ‘facebookCountUrlId’ - ‘figshareArticleId’ - ‘githubRepoId’ - ‘isbn’ - ‘lccn’ - ‘medwaveId’ - ‘nctId’ - ‘oclc’ - ‘pittEprintDscholarId’ - ‘pmcid’ - ‘pmid’ - ‘redditId’ - ‘repecHandle’ - ‘repoUrl’ - ‘scieloId’ - ‘sdEid’ - ‘slideshareUrlId’ - ‘smithsonianPddrId’ - ‘soundcloudTrackId’ - ‘ssrnId’ - ‘urlId’ - ‘usPatentApplicationId’ - ‘usPatentPublicationId’ - ‘vimeoVideoId’ - ‘youtubeVideoId’

  • refresh (Union[bool, int], optional) – Whether to refresh the cached file if it exists or not. If int is passed, cached file will be refreshed if the number of days since last modification exceeds that value.

    Default: False

Raises

ValueError – If the parameter refresh is not one of the allowed values.

Return type

None

Notes

The directory for cached results is {path}/ENHANCED/{identifier}, where path is specified in your configuration file.

property category_totals

A list of namedtuples representing total metrics as categorized by PlumX Metrics in the form (capture, citation, mention, socialMedia, usage).

Note: For Citation category a maximum citation count across sources is shown. For details on PlumX Metrics categories see https://plumanalytics.com/learn/about-metrics/.

property capture

A list of namedtuples representing metrics in the Captures category.

Note: For details on Capture metrics see https://plumanalytics.com/learn/about-metrics/capture-metrics/.

property citation

A list of namedtuples representing citation counts from different sources.

Note: For details on Citation metrics see https://plumanalytics.com/learn/about-metrics/citation-metrics/.

property mention

A list of namedtuples representing metrics in Mentions category.

Note: For details on Mention metrics see https://plumanalytics.com/learn/about-metrics/mention-metrics/.

property social_media

A list of namedtuples representing social media metrics.

Note: For details on Social Media metrics see https://plumanalytics.com/learn/about-metrics/social-media-metrics/.

property usage

A list of namedtuples representing Usage category metrics.

Note: For details on Usage metrics see https://plumanalytics.com/learn/about-metrics/usage-metrics/.

get_cache_file_age()

Return the age of the cached file in days.

Return type

int

get_cache_file_mdate()

Return the modification date of the cached file.

Return type

str

get_key_remaining_quota()

Return number of remaining requests for the current key and the current API (relative on last actual request).

Return type

Optional[str]

get_key_reset_time()

Return time when current key is reset (relative on last actual request).

Return type

Optional[str]

Examples

You initialize the class with the identifier of a document and its type:

>>> from pybliometrics.scopus import PlumXMetrics
>>> plum = PlumXMetrics("10.1016/j.softx.2019.100263", id_type='doi')

You can obtain basic information just by printing the object:

>>> print(plum)
Document with doi 10.1016/j.softx.2019.100263 received:
- 104 citation(s) in category 'capture'
- 7 citation(s) in category 'citation'
- 1 citation(s) in category 'mention'
- 42 citation(s) in category 'socialMedia'
- 4 citation(s) in category 'usage'
as of 2021-01-04

To each of the five categories, there is one property storing number and origin of the metrics in namedtuples. If in a category there are no entries the property is simply None:

>>> >>> plum.capture
[Metric(name='READER_COUNT', total=93),
 Metric(name='WATCHER_COUNT', total=7),
 Metric(name='FORK_COUNT', total=4)]
>>> plum.citation
[Metric(name='Scopus', total=7)]
>>> plum.mention
[Metric(name='ALL_BLOG_COUNT', total=1)]
>>> plum.social_media
[Metric(name='TWEET_COUNT', total=42)]
>>> plum.usage
[Metric(name='LINK_OUTS', total=3),
 Metric(name='ABSTRACT_VIEWS', total=1)]

Finally there is a property to total all metrics on an aggregated level:

>>> plum.category_totals
[Category(name='capture', total=104),
 Category(name='citation', total=7),
 Category(name='mention', total=1),
 Category(name='socialMedia', total=42),
 Category(name='usage', total=4)]

There are no bibliometric information such as title or author.

Downloaded results are cached to speed up subsequent analysis. This information may become outdated. To refresh the cached results if they exist, set refresh=True, or provide an integer that will be interpreted as maximum allowed number of days since the last modification date. For example, if you want to refresh all cached results older than 100 days, set refresh=100. Use source.get_cache_file_mdate() to get the date of last modification, and source.get_cache_file_age() the number of days since the last modification.