pybliometrics.scopus.SubjectClassifications

SubjectClassifications() implements the Subject Classifications API. It enables retrieval-like queries for All Science Journal Classification (ASJC) subjects/areas.

Documentation

class pybliometrics.scopus.SubjectClassifications(query, refresh=False, fields=None, **kwds)

Interaction with the Subject Classifications Scopus API.

Parameters:

• query (Dict) – Query parameters and corresponding fields. Allowed keys ‘code’, ‘abbrev’, ‘description’, ‘detail’. For more details on search fields please refer to https://dev.elsevier.com/documentation/SubjectClassificationsAPI.wadl#d1e199.

• 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

• fields (Union[List[str], Tuple[str, ...]], optional) – The fields to return when calling search results. Allowed values: ‘code’, ‘abbrev’, ‘description’, ‘detail’. For details see https://dev.elsevier.com/documentation/SubjectClassificationsAPI.wadl#d1e199.

  Default: None

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

Raises:

• TypeError – If returned fields are not passed in an iterable container.

• ValueError – If any of the parameters fields, refresh or query is not one of the allowed values.

Notes

The directory for cached results is {path}/{fname}, where path is specified in your configuration file, and fname is the md5-hashed version of query dict turned into string in format of ‘key=value’ delimited by ‘&’.

property results: List[NamedTuple] | None

A list of namedtuples representing results of subject classifications search in the form (code, description, detail, abbrev).

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

get_results_size()

Return the number of results (works even if download=False).

Return type:

int

Examples

You initialize the class with a query dict. It contains the “description” (general classification of the subject), “code” (the ASJC code), “detail” (detailed name of the subject), “abbrev” (abbreviation of general classification of subject) or a combination of those:

>>> from pybliometrics.scopus import SubjectClassifications
>>> sub = SubjectClassifications({'description': 'Mathematics'})

You can obtain basic information just by printing the object:

>>> print(sub)
Search '{'description': 'Mathematics', 'field': 'code,description,detail,abbrev'}'
yielded 15 subject areas as of 2021-02-11:
    2600
    2601
    2602
    2603
    2604
    2605
    2606
    2607
    2608
    2609
    2610
    2611
    2612
    2613
    2614

The class has a single method, SubjectClass.results, which returns a list of namedtuples. By default, the API returns the description, code, detail and abbreviation of each found subject, which is also reflected in the fields of namedtuples of SubjectClass().results. You have the option to specify which fields to be included in the search results, such as only the codes of subjects.

>>> sub.results
[Subject(code='2600', description='Mathematics', detail='Mathematics (all)', abbrev='MATH'),
 Subject(code='2601', description='Mathematics', detail='Mathematics (miscellaneous)', abbrev='MATH'),
 Subject(code='2602', description='Mathematics', detail='Algebra and Number Theory', abbrev='MATH'),
 Subject(code='2603', description='Mathematics', detail='Analysis', abbrev='MATH'),
 Subject(code='2604', description='Mathematics', detail='Applied Mathematics', abbrev='MATH'),
 Subject(code='2605', description='Mathematics', detail='Computational Mathematics', abbrev='MATH'),
 Subject(code='2606', description='Mathematics', detail='Control and Optimization', abbrev='MATH'),
 Subject(code='2607', description='Mathematics', detail='Discrete Mathematics and Combinatorics', abbrev='MATH'),
 Subject(code='2608', description='Mathematics', detail='Geometry and Topology', abbrev='MATH'),
 Subject(code='2609', description='Mathematics', detail='Logic', abbrev='MATH'),
 Subject(code='2610', description='Mathematics', detail='Mathematical Physics', abbrev='MATH'),
 Subject(code='2611', description='Mathematics', detail='Modeling and Simulation', abbrev='MATH'),
 Subject(code='2612', description='Mathematics', detail='Numerical Analysis', abbrev='MATH'),
 Subject(code='2613', description='Mathematics', detail='Statistics and Probability', abbrev='MATH'),
 Subject(code='2614', description='Mathematics', detail='Theoretical Computer Science', abbrev='MATH')]

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.