pybliometrics.scopus.SerialTitle¶
SerialTitle() implements the Serial Title API. It offers basic information on registered serials (also known as sources), including publisher details, identifiers, and various metrics.
Documentation¶
- class pybliometrics.scopus.SerialTitle(issn, refresh=False, view='ENHANCED', years=None, **kwds)[source]¶
Interaction with the Serial Title API.
- Parameters:
issn (
Union[int,str]) – The ISSN or the E-ISSN of the source.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:Falseview (
str, optional) – The view of the file that should be downloaded. Allowed values: STANDARD, ENHANCED, CITESCORE. For details see https://dev.elsevier.com/sc_serial_title_views.html.Default:'ENHANCED'years (
str, optional) – A string specifying a year or range of years (combining two years with a hyphen) for which yearly metric data (SJR, SNIP, yearly-data) should be looked up for. If None, only the most recent metric data values are provided. Note: If not None, refresh will always be True.Default:Nonekwds (
str) – Keywords passed on as query parameters. Must contain fields and values mentioned in the API specification at https://dev.elsevier.com/documentation/SerialTitleAPI.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}/{source_id}, where path is specified in your configuration file.
- property aggregation_type: str¶
The type of the source.
- property citescoreyearinfolist: List[NamedTuple] | None¶
(year citescoare) or (when view=”CITESCORE”) (year citescore status documentcount citationcount percentcited rank). rank is None or a named tuple of the form (subjectcode rank percentile).
For more information see the [CiteScore documentation](https://service.elsevier.com/app/answers/detail/a_id/14880/supporthub/scopus/).
- Type:
A list of named tuples of the form
- property eissn: str | None¶
The electronic ISSN of the source.
- property issn: str | None¶
The ISSN of the source.
- property oaallowsauthorpaid: str | None¶
Whether under the Open-Access policy authors are allowed to pay.
- property openaccess: int | None¶
Open Access status (0 or 1).
- property openaccessstartdate¶
Starting availability date.
- property openaccesstype: str | None¶
Open Archive status (full or partial).
- property openaccessarticle: bool | None¶
Open Access status.
- property openarchivearticle: bool | None¶
Open Archive status.
- property openaccesssponsorname: str | None¶
The name of the Open Access sponsor.
- property openaccesssponsortype: str | None¶
The type of the Open Access sponsor.
- property openaccessuserlicense: str | None¶
The User license.
- property publisher: str¶
The publisher of the source.
- property scopus_source_link: str¶
URL to info site on scopus.com.
- property self_link: str¶
URL to the source’s API page.
- property sjrlist: List[Tuple[int, float]] | None¶
The SCImago Journal Rank (SJR) indicator as list of tuples in the form (year, indicator). See https://www.scimagojr.com/journalrank.php.
- property sniplist: List[Tuple[int, float]] | None¶
The Source-Normalized Impact per Paper (SNIP) as list of tuples in the form (year, indicator). See https://blog.scopus.com/posts/journal-metrics-in-scopus-source-normalized-impact-per-paper-snip.
- property source_id: int¶
The Scopus ID of the source.
- property subject_area: List[NamedTuple] | None¶
List of named tuples of subject areas in the form (area, abbreviation, code) of the source.
- property title: str¶
The title of the source.
- property yearly_data: List[NamedTuple] | None¶
Yearly citation information as a list of namedtuples in the form (year, publicationcount, revpercent, zerocitessce, zerocitespercentsce, citecountsce). That’s the number of documents published in this year, the share of review articles thereof, the number and share of not-cited documents, and the number of distinct documents that were cited in this year.
- 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 an ISSN or an E-ISSN (works with and without hyphen, but leading zeros are mandatory):
>>> from pybliometrics.scopus import SerialTitle >>> source = SerialTitle("00368075")
You can obtain basic information just by printing the object:
>>> print(source) 'Science', journal published by 'American Association for the Advancement of Science', is active in Multidisciplinary Metrics as of 2023-11-15: SJR: year value 2022 13.328 SNIP: year value 2022 7.729 ISSN: 0036-8075, E-ISSN: 1095-9203, Scopus ID: 23571
The object has a number of attributes but no methods. For example, information regarding the source itself:
>>> source.title 'Science' >>> source.publisher 'American Association for the Advancement of Science' >>> source.issn '0036-8075' >>> source.eissn '1095-9203' >>> source.source_id 23571
Crucially, it provides three metrics: CiteScore (see here for further information), SCImago Journal Rank indicator (see here), and Source Normalized Impact Factor (SNIP; see here). This information is presented in lists of two-element tuples, with the first element indicating the year of metric evaluation.
>>> source.citescoreyearinfolist [Citescoreinfolist(year=2022, citescore=59.0), Citescoreinfolist(year=2023, citescore=58.8)] >>> source.sjrlist [(2022, 13.328)] >>> source.sniplist [(2022, 7.729)]
The citescoreyearinfolist property provides detailed information for all available years when view=”CITESCORE” is used. It includes the status of the metric, the document count and citation count (of the previous 4 years), the share of documents actually cited, and the rank and percentile for each related ASJC subject:
>>> source_full = SerialTitle("00368075", view="CITESCORE") >>> info = pd.DataFrame(source_full.citescoreyearinfolist) >>> print(info) year citescore status documentcount citationcount percentcited rank 0 2023 58.8 In-Progress 4730 278199 79 [(1000, 2, 99)] 1 2022 59.0 Complete 4895 288748 82 [(1000, 2, 98)] 2 2021 57.8 Complete 4823 278545 84 [(1000, 2, 98)] 3 2020 46.8 Complete 4833 226134 82 [(1000, 2, 98)] 4 2019 45.3 Complete 4799 217261 81 [(1000, 2, 98)] 5 2018 47.1 Complete 4681 220642 82 [(1000, 2, 98)] 6 2017 49.4 Complete 4215 208286 90 [(1000, 2, 98)] 7 2016 49.5 Complete 4176 206665 89 [(1000, 1, 99)] 8 2015 46.6 Complete 4016 187040 89 [(2700, 18, 99), (1000, 2, 98)] 9 2014 46.0 Complete 3923 180376 90 [(2700, 18, 99), (1000, 2, 98)] 10 2013 46.9 Complete 3839 179860 92 [(2700, 16, 99), (1000, 2, 98)] 11 2012 46.3 Complete 3861 178780 92 [(2700, 11, 99), (1000, 2, 98)] 12 2011 44.7 Complete 3843 171898 91 [(2700, 12, 99), (1000, 2, 98)]
The yearly_data time series includes the number of documents published in a given year. It contains the number of documents published in this year, the share of review articles thereof, the number and share of not-cited documents, and the number of distinct documents that were cited in this year.
>>> source.yearly_data[-1] Yearlydata(year=2023, publicationcount=1800, revpercent=2.94, zerocitessce=1201, zerocitespercentsce=66.72222222222223, citecountsce=726948) >>> yearly_data = pd.DataFrame(source.yearly_data) >>> yearly_data.head() year publicationcount revpercent zerocitessce zerocitespercentsce citecountsce 0 1996 2395 4.97 655 27.348643 236545 1 1997 2833 6.28 904 31.909636 244078 2 1998 2816 4.69 854 30.326705 254500 3 1999 2373 6.28 532 22.418879 276054 4 2000 2402 6.99 459 19.109076 293867
By default, SerialTitle() retrieves only the most recent metrics, although yearly data is availble from 1996 onwards. If you provide a year or a range of years via the optional parameter years, SerialTitle() will retrieve information for these years (except for the CiteScore):
>>> source_y = SerialTitle("00368075", years="2017-2019") >>> source_y.citescoreyearinfolist [Citescoreinfolist(year=2022, citescore=59.0), Citescoreinfolist(year=2023, citescore=58.8)] >>> source_y.sjrlist [(2017, 14.142), (2018, 13.251), (2019, 13.11)] >>> source_y.sniplist [(2017, 7.409), (2018, 7.584), (2019, 7.535)]
Fields associated with the source are stored as a list of namedtuples:
>>> source.subject_area [Subjectarea(area='Multidisciplinary', abbreviation='MULT', code=1000)]
Additionally, there is information on Open Access status, which, however, is often empty.
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.
