pybliometrics Documentation

pybliometrics is a Python library designed to pull, cache, and extract data from the Scopus database and its sister databases, ScienceDirect and SciVal. The library is organized into specific modules, providing one class per Elsevier API Access Point.

To use the library, you will interact with one of the following three main modules depending on your data source:

• pybliometrics.scopus: For Scopus API data.
• pybliometrics.sciencedirect: For ScienceDirect API data.
• pybliometrics.scival: For SciVal API data.

Results from AuthorRetrieval are cached locally. To manage or refresh this data:

• Refresh all results: Pass refresh=True to retrieval methods.
• Refresh by age: Pass an integer to retrieval methods to refresh results older than $N$ days (e.g., refresh=100).
• Check cache status:
  • Use au.get_cache_file_mdate() to get the last modification date.
  • Use au.get_cache_file_age() to get the number of days since the last modification.

The Serial Title API provides different levels of data depth via 'views'. When using SerialTitleSearch, you can choose between:

• 'STANDARD': Provides basic information. Use this if you want faster response times or do not need detailed metrics.
• 'ENHANCED': The highest level of detail. It includes all information from the 'STANDARD' view plus comprehensive yearly journal metrics (e.g., publication counts, citation counts, and share of review articles).

Downloaded results are cached to speed up subsequent runs. To manage the cache:

• Refresh all results: Set refresh=True in the AuthorSearch constructor.
• Refresh based on age: Provide an integer to refresh representing the maximum allowed number of days since the last modification. For example, refresh=100 will refresh results older than 100 days.
• Check cache status: Use ab.get_cache_file_mdate() to get the last modification date or ab.get_cache_file_age() to get the age in days.

Results from SubjectClassifications are cached locally to speed up subsequent requests. To manage or refresh this cache, use the following approaches:

• Force refresh: Set refresh=True to bypass the cache and fetch fresh data.
• Time-based refresh: Provide an integer to refresh to specify the maximum allowed age in days. For example, refresh=100 will refresh results if the cached file is older than 100 days.
• Check cache status: Use get_cache_file_mdate() to get the last modification date or get_cache_file_age() to get the number of days since the last modification.

# Refresh if cache is older than 100 days
sub = SubjectClassifications({'description': 'Mathematics'}, refresh=100)

# Force a complete refresh
sub = SubjectClassifications({'description': 'Mathematics'}, refresh=True)

All individual metric properties in AuthorMetrics return a list of MetricData namedtuples. This structure is unified across SciVal metric classes (like InstitutionMetrics) to ensure consistent data analysis.

Each MetricData object contains the following fields:

• entity_id: The ID of the author.
• entity_name: The name of the author.
• metric: The name of the metric (e.g., 'CitationCount' or 'h-index').
• year: The year of the metric (e.g., '2023' or 'all').
• value: The numerical value of the metric.
• percentage: The percentage value (if applicable).
• threshold: The threshold value (if applicable).

# Example MetricData output
# [MetricData(entity_id=57209617104, entity_name='Rose, Michael E.', metric='CitationCount', year='all', value=92, percentage=None, threshold=None)]

Scopus occasionally merges duplicate author profiles, affiliations, or research items. When an author profile is merged, the old profile typically forwards to the new one for approximately 6 months.

If you instantiate a retrieval class (such as AuthorRetrieval) using a merged profile ID and then access its .identifier property, pybliometrics will raise a warning. This warning contains the ID of the new main profile, which you should use for future queries to ensure data accuracy.

Results from PublicationLookup are cached locally to speed up subsequent requests. If you need to update the data because the cache is outdated, you can use the refresh parameter during initialization:

• refresh=True: Forces a refresh of the cached data.
• refresh=N (where N is an integer): Refreshes the cache if the existing data is older than N days.

You can check the cache status using:

• ab.get_cache_file_mdate(): Returns the last modification date of the cache file.
• ab.get_cache_file_age(): Returns the number of days since the cache file was last modified.

# Refresh if cache is older than 100 days
pub = PublicationLookup('85036568406', refresh=100)

# Force refresh regardless of age
pub = PublicationLookup('85036568406', refresh=True)

When working with affiliation data from Scopus, you can distinguish between two types of profiles based on their ID prefix:

• Org profiles (OrgID): These represent formal entities like universities, research institutes, or government organizations. They include precise metadata such as institution type and address. These IDs start with a 6 (e.g., 6XXXXXXX).
• Non-Org profiles: These are automatically clustered profiles that lack specific type or address information. They often represent research networks or virtual institutes, but frequently act as duplicates of existing Org profiles. These IDs start with a 1 (e.g., 1XXXXXXXX).

If you encounter Non-Org profiles that appear to be duplicates of legitimate Org profiles, you should request a merge via the Elsevier Scopus Support Hub.

Article references (useful for citation networks) are accessible via the references attribute.

• view='FULL': Provides the full list of references. Access via ab.references.
• view='REF': Provides more detailed information on the referenced items themselves (e.g., authors_auid, authors_affiliationid, coverDate) but may provide less information on the parent document's other attributes.

To build a citation network, you can convert the references list into a DataFrame and construct EIDs for the cited papers by prefixing the ID with 2-s2.0-.

# Requires view='FULL'
ab = AbstractRetrieval("2-s2.0-85068268027", view='FULL')
refs = ab.references

import pandas as pd
df_refs = pd.DataFrame(refs)
# Construct EIDs for cited papers
df_refs['eid'] = '2-s2.0-' + df_refs['id']

The Scopus Search API provides different levels of data depth via views.

• 'COMPLETE': The default view. It is the highest unrestricted view and contains all information also included in the 'STANDARD' view.
• 'STANDARD': Use this view when speed is a priority and you do not require the full depth of the 'COMPLETE' view.