pybliometrics.scopus.PlumXMetrics

PlumXMetrics() implements the PlumX Metrics API. It offers metrics across five categories: captures, citations, usage, mentions, and social media – see here for background information. It works for many different types of media.

Documentation

class pybliometrics.scopus.PlumXMetrics(identifier, id_type, refresh=False, **kwds)[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’; ‘cabiAbstractId’; ‘citeulikeId’; ‘digitalMeasuresArtifactId’; ‘doi’; ‘elsevierId’; ‘elsevierPii’; ‘facebookCountUrlId’; ‘figshareArticleId’; ‘isbn’; ‘lccn’; ‘medwaveId’; ‘nctId’; ‘oclc’; ‘pittEprintDscholarId’; ‘pmcid’; ‘pmid’; ‘redditId’; ‘repecHandle’; ‘repoUrl’; ‘scieloId’; ‘sdEid’; ‘slideshareUrlId’; ‘smithsonianPddrId’; ‘ssrnId’; ‘urlId’

  • 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

  • kwds (str) – Keywords passed on as query parameters. Must contain fields and values mentioned in the API specification at https://dev.elsevier.com/documentation/PlumXMetricsAPI.wadl.

Raises:

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

Notes

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

property category_totals: List[NamedTuple] | None

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: List[NamedTuple] | None

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: List[NamedTuple] | None

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: List[NamedTuple] | None

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: List[NamedTuple] | None

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: List[NamedTuple] | None

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:

str | None

get_key_reset_time()

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

Return type:

str | None

Examples

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

>>> from pybliometrics.scopus import PlumXMetrics
>>> plum = PlumXMetrics("2-s2.0-85054706190", id_type='elsevierId')

You can obtain basic information just by printing the object:

>>> print(plum)
Document with elsevierId 2-s2.0-85054706190 received:
- 460 citation(s) in category 'capture'
- 232 citation(s) in category 'citation'
- 2 citation(s) in category 'mention'
- 42 citation(s) in category 'socialMedia'
- 216 citation(s) in category 'usage'
as of 2023-10-20

For each of the five categories, there is a corresponding property that stores the number and origin of the metrics in namedtuples. If a category has no entries, the corresponding property will be None:

>>> >>> plum.capture
[Metric(name='READER_COUNT', total=459),
 Metric(name='EXPORTS_SAVES', total=1)]
>>> plum.citation
[Metric(name='Scopus', total=231),
 Metric(name='CrossRef', total=80),
 Metric(name='Policy Citation', total=1)]
>>> plum.mention
[Metric(name='NEWS_COUNT', total=2)]
>>> plum.social_media
[Metric(name='FACEBOOK_COUNT', total=42)]
>>> plum.usage
[Metric(name='ABSTRACT_VIEWS', total=205),
 Metric(name='LINK_OUTS', total=11)]

Finally, there is a property that totals all metrics at an aggregated level:

>>> plum.category_totals
[Category(name='capture', total=460),
 Category(name='citation', total=232),
 Category(name='mention', total=2),
 Category(name='socialMedia', total=42),
 Category(name='usage', total=216)]

There are no bibliometric information such as title or author.

Downloaded results are cached to expedite subsequent analyses. 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 ab.get_cache_file_mdate() to obtain the date of last modification, and ab.get_cache_file_age() to determine the number of days since the last modification.