pybliometrics.scival.InstitutionLookupMetrics

InstitutionLookupMetrics() implements the metrics endpoint of the SciVal InstitutionLookup API.

It accepts one or more SciVal Institution IDs as the main argument and retrieves various performance metrics for the specified institutions.

Documentation

class pybliometrics.scival.InstitutionLookupMetrics(institution_ids, metric_types=None, by_year=False, refresh=False, **kwds)[source]

Interaction with the SciVal’s metrics endpoint of the InstitutionLookup API.

Parameters:

  • institution_ids (str | list) – SciVal Institution ID(s). Can be a single ID or comma-separated string of IDs, or a list of IDs (e.g. [309054, 309086]).

  • 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. 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/SciValInstitutionAPI.wadl.

Note

All metric properties return lists of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property AcademicCorporateCollaboration: list[MetricData] | None

Academic corporate collaboration metrics for each institution. 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 institution. Returns list of MetricData namedtuples with structure: (entity_id, entity_name, metric, year, value, percentage, threshold).

property institutions: list[Institution] | None

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

property CitationCount: list[MetricData] | None

Citation count metrics for each institution. 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 institution. 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 institution. 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 institution. 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 institution. 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 institution. 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 institution. 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 institution. 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 institution. 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 SciVal Institution IDs. The argument can be a single ID, a list of IDs, or a comma-separated string of IDs.

>>> from pybliometrics.scival import InstitutionLookupMetrics, init
>>> init()
>>> institution_metrics = InstitutionLookupMetrics("309021")

You can obtain basic information just by printing the object:

>>> print(institution_metrics)
InstitutionLookupMetrics for 1 institution(s):
- Humboldt University of Berlin (ID: 309021)

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

>>> institution_metrics.institutions
[Institution(id=309021, name='Humboldt University of Berlin', uri='Institution/309021')]

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 institution.

>>> institution_metrics.CitationCount
[MetricData(entity_id=309021, entity_name='Humboldt University of Berlin', metric='CitationCount',
            year='all', value=368527, percentage=None, threshold=None)]

For nested metrics (like CollaborationImpact), metric contains the specific sub-type:

>>> institution_metrics.CollaborationImpact
[MetricData(entity_id=309021, entity_name='Humboldt University of Berlin', metric='Institutional collaboration',
            year='all', value=8.610204, percentage=None, threshold=None),
 MetricData(entity_id=309021, entity_name='Humboldt University of Berlin', metric='International collaboration',
            year='all', value=22.430689, percentage=None, threshold=None),
 MetricData(entity_id=309021, entity_name='Humboldt University of Berlin', metric='National collaboration',
            year='all', value=9.935493, percentage=None, threshold=None),
 MetricData(entity_id=309021, entity_name='Humboldt University of Berlin', metric='Single authorship',
            year='all', value=3.187361, percentage=None, threshold=None)]

Available Metric Properties:

  • AcademicCorporateCollaboration

  • AcademicCorporateCollaborationImpact

  • CitationCount

  • CitationsPerPublication

  • CitedPublications

  • Collaboration

  • CollaborationImpact

  • FieldWeightedCitationImpact

  • OutputsInTopCitationPercentiles

  • PublicationsInTopJournalPercentiles

  • ScholarlyOutput

Note

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

Concatenating Metrics

>>> import pandas as pd
>>>
>>> collab_data = []
>>> collab_data.extend(institution_metrics.Collaboration)
>>> collab_data.extend(institution_metrics.CollaborationImpact)
>>> df = pd.DataFrame(collab_data)
>>> df.head()
entity_id entity_name metric year value percentage threshold
0 309021 Humboldt University of Berlin Institutional collaboration all 980.000000 4.32 None
1 309021 Humboldt University of Berlin International collaboration all 12754.000000 56.16 None
2 309021 Humboldt University of Berlin National collaboration all 6728.000000 29.63 None
3 309021 Humboldt University of Berlin Single authorship all 2247.000000 9.89 None
4 309021 Humboldt University of Berlin Institutional collaboration all 8.610204 NaN None

Multiple Institutions

You can analyze multiple institutions simultaneously and retrieve metrics by_year:

>>> multi_institutions = InstitutionLookupMetrics([309050, 309076], by_year=True)
>>> print(multi_institutions)
InstitutionLookupMetrics for 2 institution(s):
- Technical University of Berlin (ID: 309050)
- Heidelberg University  (ID: 309076)
>>> # Get CitedPublications metrics
>>> df = pd.DataFrame(multi_institutions.CitedPublications)
>>> df.head()
entity_id entity_name metric year value percentage threshold
0 309050 Technical University of Berlin CitedPublications 2024 2400 66.133920 None
1 309050 Technical University of Berlin CitedPublications 2020 3294 89.462250 None
2 309050 Technical University of Berlin CitedPublications 2021 3385 88.404290 None
3 309050 Technical University of Berlin CitedPublications 2022 3209 86.472650 None
4 309050 Technical University of Berlin CitedPublications 2023 3044 80.529100 None
5 309076 Heidelberg University CitedPublications 2024 5937 72.517410 None
6 309076 Heidelberg University CitedPublications 2020 7423 92.005455 None
7 309076 Heidelberg University CitedPublications 2021 7828 90.864770 None
8 309076 Heidelberg University CitedPublications 2022 7354 88.166885 None
9 309076 Heidelberg University CitedPublications 2023 6921 85.150100 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 institution_metrics.get_cache_file_mdate() to obtain the date of last modification, and institution_metrics.get_cache_file_age() to determine the number of days since the last modification.