pybliometrics.scopus.AffiliationRetrieval

AffiliationRetrieval() implements the Affiliation Retrieval API. It provides basic information on registered affiliations, like city, country, its members, and more.

Table of Contents

Documentation

class pybliometrics.scopus.AffiliationRetrieval(aff_id, refresh=False, view='STANDARD', **kwds)[source]

Interaction with the Affiliation Retrieval API.

Parameters
  • aff_id (Union[int, str]) – Scopus ID or EID of the affiliation profile.

  • 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

  • view (str, optional) – The view of the file that should be downloaded. Allowed values: LIGHT, STANDARD, where STANDARD includes all information of the LIGHT view. For details see https://dev.elsevier.com/sc_affil_retrieval_views.html. Note: Neither the BASIC view nor DOCUMENTS or AUTHORS views are active, although documented.

    Default: 'STANDARD'

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

Raises

ValueError – If any of the parameters refresh or view is not one of the allowed values.

Return type

None

Notes

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

property address

The address of the affiliation.

property affiliation_name

The name of the affiliation.

property author_count

Number of authors associated with the affiliation.

property city

The city of the affiliation.

property country

The country of the affiliation.

property date_created

Date the Scopus record was created.

property document_count

Number of documents for the affiliation.

property eid

The EID of the affiliation.

property identifier

The Scopus ID of the affiliation.

property name_variants

A list of namedtuples representing variants of the affiliation name with number of documents referring to this variant.

property org_domain

Internet domain of the affiliation. Requires the STANDARD view.

property org_type

Type of the affiliation. Requires the STANDARD view and only present if profile is org profile.

property org_URL

Website of the affiliation. Requires the STANDARD view.

property postal_code

The postal code of the affiliation. Requires the STANDARD view.

Link to the Scopus web view of the affiliation.

Link to the affiliation’s API page.

URL to the API page listing documents of the affiliation.

property state

The state (country’s administrative sububunit) of the affiliation. Requires the STANDARD view.

property sort_name

The name of the affiliation used for sorting. Requires the STANDARD view.

property url

URL to the affiliation’s API page.

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 Scopus’ Affiliation ID:

>>> from pybliometrics.scopus import AffiliationRetrieval
>>> aff = AffiliationRetrieval(60000356)

You can obtain basic information just by printing the object:

>>> print(aff)
University of Cape Town in Cape Town in South Africa,
has 13,033 associated author(s) and 75,695 associated document(s) as of 2021-07-12

The object has a number of attributes but no methods. For example, information regarding the affiliation itself:

>>> aff.affiliation_name
'University of Cape Town'
>>> aff.sort_name
'Cape Town, University of'
>>> aff.org_type
'univ'
>>> aff.postal_code
'7701'
>>> aff.city
'Cape Town'
>>> aff.state
'Western Cape'
>>> aff.country
'South Africa'
>>> aff.org_domain
'uct.ac.za'
>>> aff.org_URL
'http://www.uct.ac.za'

There are meta information, too:

>>> aff.author_count
13033
>>> aff.document_count
75695

Scopus also collects information on different names affiliated authors use for this affiliation, which pybliometrics returns as list of namedtuples:

>>> aff.name_variants
[Variant(name='University Of Cape Town', doc_count=60095),
 Variant(name='Univ. Cape Town', doc_count=1659),
 Variant(name='Univ Of Cape Town', doc_count=772),
 Variant(name='Univ. Of Cape Town', doc_count=392)]

Using pandas you can easily turn this into a DataFrame:

>>> import pandas as pd
>>> print(pd.DataFrame(aff.name_variants))
                      name doc_count
0  University Of Cape Town     60095
1          Univ. Cape Town      1659
2        Univ Of Cape Town       772
3       Univ. Of Cape Town       392

More on different types of affiliations in section tips.

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 aff.get_cache_file_mdate() to get the date of last modification, and aff.get_cache_file_age() the number of days since the last modification.