pybliometrics.scival.AuthorMetrics

AuthorMetrics() implements the SciVal Author Metrics API.

It accepts one or more Scopus Author IDs as the main argument and retrieves various performance metrics for the specified authors.

Documentation

class pybliometrics.scival.AuthorMetrics(author_ids, metric_types=None, by_year=False, refresh=False, **kwds)

Interaction with the SciVal Author Metrics API.

Parameters:

• author_ids (str | list) – Scopus Author ID(s). Can be a single ID or comma-separated string of IDs, or a list of IDs (e.g. [55586732900, 57215631099]).

• metric_types (str | list | None, optional) – Metric type(s) to retrieve. Can be a single metric or comma-separated string, or a list. Available metrics are: AcademicCorporateCollaboration, AcademicCorporateCollaborationImpact, CitationCount, CitedPublications, Collaboration, CollaborationImpact, FieldWeightedCitationImpact, ScholarlyOutput, PublicationsInTopJournalPercentiles, OutputsInTopCitationPercentiles, HIndices. If not provided, all metrics are retrieved.

  Default: None

• by_year (bool, optional) – Whether to retrieve metrics broken down by year.

  Default: False

• refresh (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

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

Note

All metric properties return lists of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold) which enable concatenation of results from different metrics.

property AcademicCorporateCollaboration: list[MetricData] | None

Academic corporate collaboration metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property AcademicCorporateCollaborationImpact: list[MetricData] | None

Academic corporate collaboration impact metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property authors: list[MetricData] | None

A list of namedtuples representing authors and their basic info in the form (id, name, uri).

property CitationCount: list[MetricData] | None

Citation count metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property CitationsPerPublication: list[MetricData] | None

Citations per publication metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property CitedPublications: list[MetricData] | None

Cited publications metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property Collaboration: list[MetricData] | None

Collaboration metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property CollaborationImpact: list[MetricData] | None

Collaboration impact metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property FieldWeightedCitationImpact: list[MetricData] | None

Field weighted citation impact metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property HIndices: list[MetricData] | None

H-indices metrics for each author (only available when by_year=False). Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property OutputsInTopCitationPercentiles: list[MetricData] | None

Outputs in top citation percentiles metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property PublicationsInTopJournalPercentiles: list[MetricData] | None

Publications in top journal percentiles metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property ScholarlyOutput: list[MetricData] | None

Scholarly output metrics for each author. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

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 one or more Scopus Author IDs. The argument can be a single ID, a list of IDs, or a comma-separated string of IDs.

>>> from pybliometrics.scival import AuthorMetrics, init
>>> init()
>>> author_metrics = AuthorMetrics("57209617104")

You can obtain basic information just by printing the object:

>>> print(author_metrics)
AuthorMetrics for 1 author(s):
- Rose, Michael E. (ID: 57209617104)

There are many properties available that provide different types of metrics. You can explore the available authors:

>>> author_metrics.authors
[Author(id=57209617104, name='Rose, Michael E.', uri='Author/57209617104')]

Individual Metric Properties

Each metric property returns a list of MetricData namedtuples with the structure: (entity_id, entity_name, metric, year, value, percentage, threshold) where entity_id and entity_name refer to the author.

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

>>> author_metrics.HIndices
[MetricData(entity_id=57209617104, entity_name='Rose, Michael E.', metric='h-index', year='all', value=5.0, percentage=None, threshold=None)]

Available Metric Properties:

• AcademicCorporateCollaboration

• AcademicCorporateCollaborationImpact

• CitationCount

• CitationsPerPublication

• CitedPublications

• Collaboration

• CollaborationImpact

• FieldWeightedCitationImpact

• HIndices (only available when by_year=False)

• OutputsInTopCitationPercentiles

• PublicationsInTopJournalPercentiles

• ScholarlyOutput

Note

Unified Data Structure: AuthorMetrics uses a unified MetricData structure with entity_id and entity_name fields. For authors, these fields contain the author ID and author name respectively. This structure is compatible with InstitutionMetrics and other SciVal metric classes, enabling consistent data analysis across different entity types.

Concatenating Metrics

Metrics can be concatenated and converted into a pandas DataFrame for easier analysis.

>>> import pandas as pd
>>> collab_data = []
>>> collab_data.extend(author_metrics.Collaboration)
>>> collab_data.extend(author_metrics.CollaborationImpact)
>>> df = pd.DataFrame(collab_data)
>>> df.head()

	entity_id	entity_name	metric	year	value	percentage	threshold
0	57209617104	Rose, Michael E.	Institutional collaboration	all	1.000000	11.11	None
1	57209617104	Rose, Michael E.	International collaboration	all	7.000000	77.78	None
2	57209617104	Rose, Michael E.	National collaboration	all	0.000000	0.00	None
3	57209617104	Rose, Michael E.	Single authorship	all	1.000000	11.11	None
4	57209617104	Rose, Michael E.	Institutional collaboration	all	0.000000	NaN	None
5	57209617104	Rose, Michael E.	International collaboration	all	12.571428	NaN	None
6	57209617104	Rose, Michael E.	National collaboration	all	0.000000	NaN	None
7	57209617104	Rose, Michael E.	Single authorship	all	4.000000	NaN	None

Multiple Authors

You can analyze multiple authors simultaneously. Furthermore, you can specify whether you want metrics broken down by year or not. If by_year=True, each metric will be returned for each year separately.

>>> multi_authors = AuthorMetrics([57209617104, 7004212771], by_year=True)
>>> print(multi_authors)
AuthorMetrics for 2 author(s):
- Kitchin, John R. (ID: 7004212771)
- Rose, Michael E. (ID: 57209617104)
>>> # Create a DataFrame from the Collaboration metrics
>>> df_multi = pd.DataFrame(multi_authors.Collaboration)
>>> df_multi.head()

	entity_id	entity_name	metric	year	value	percentage	threshold
0	7004212771	Kitchin, John R.	Institutional collaboration	2024	6	37.500000	None
1	7004212771	Kitchin, John R.	Institutional collaboration	2020	1	50.000000	None
2	7004212771	Kitchin, John R.	Institutional collaboration	2021	1	33.333336	None
3	7004212771	Kitchin, John R.	Institutional collaboration	2022	6	66.666670	None
4	7004212771	Kitchin, John R.	Institutional collaboration	2023	5	55.555557	None

Filtering Specific Metrics

You can request only specific metrics to reduce API response size:

>>> h_index_only = AuthorMetrics("57209617104", metric_types=["HIndices"])
>>> h_index_only.HIndices
[MetricData(entity_id=57209617104, entity_name='Rose, Michael E.', metric='h-index', year='all', value=5.0, percentage=None, threshold=None)]

>>> # Multiple specific metrics
>>> selected_metrics = AuthorMetrics("57209617104", metric_types=["CitationCount", "ScholarlyOutput"])
>>> selected_metrics.CitationCount
[MetricData(entity_id=57209617104, entity_name='Rose, Michael E.', metric='CitationCount', year='all', value=92, percentage=None, threshold=None)]

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