pybliometrics.scopus.AffiliationRetrieval

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

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.

Notes

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

property address: str | None

The address of the affiliation.

property affiliation_name: str

The name of the affiliation.

property author_count: int

Number of authors associated with the affiliation.

property city: str | None

The city of the affiliation.

property country: str | None

The country of the affiliation.

property date_created: Tuple[int, int, int] | None

Date the Scopus record was created.

property document_count: int

Number of documents for the affiliation.

property eid: str

The EID of the affiliation.

property identifier: int

The Scopus ID of the affiliation.

property name_variants: List[NamedTuple]

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

property org_domain: str | None

Internet domain of the affiliation. Requires the STANDARD view.

property org_type: str | None

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

property org_URL: str | None

Website of the affiliation. Requires the STANDARD view.

property postal_code: str | None

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: str | None

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

property sort_name: str | None

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

property url: str

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:

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 using 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 several 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 convert 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 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.