Skip to content

Analysing a literature

Once records are in hand, scopusflow turns them into the figures a bibliometric study usually needs, all from the one stable schema. The examples here run on the harvest bundled with the package, which holds 138 real articles on graphene supercapacitors published between 2015 and 2024. It stands in for a Scopus retrieval because retrieved records cannot be redistributed, and it lets every figure on this page be drawn without a key. A live harvest of the same phrase is shown alongside, though Scopus would return a different set of records, and Get started gives the fuller account of where the bundled set comes from.

Where the records come from

A live harvest is two calls, a query and a plan run through fetch_plan, and both need a configured key.

import pybliometrics

import scopusflow as sf

pybliometrics.init()   # once per session, before the first search

q = sf.scopus_query('"graphene supercapacitor"', field="TITLE-ABS-KEY")
plan = sf.SearchPlan(q, years=range(2015, 2025), partition="year")
records = sf.fetch_plan(plan, cache_dir="graphene-harvest")

example_records returns the bundled stand-in, already normalised into the same schema, which is what the rest of this page works on. Its records came from OpenAlex's exact-phrase search for the same phrase in titles and abstracts, limited to journal articles, so the harvest above would return a different set. Without the quotation marks it would be far larger, since Scopus joins the words of an unquoted phrase with AND, and in OpenAlex the unquoted words match about a hundred times as many records.

records = sf.example_records()
out(records[["title", "year", "publication", "citations"]].head(3))
title year publication citations
Enhanced Capacitive Properties of All-solid-state Symmetric Graphene Supercapacitors by Incorporating Nitrogen-doping and SnO2 Nanoparticles 2015 Journal of Inorganic Materials 1
Fabrication and Characterization of a Vertically-Oriented Graphene Supercapacitor 2015 DigitalCommons - CalPoly (California State Polytechnic University) 0
Flexible and Stackable Laser-Induced Graphene Supercapacitors 2015 ACS Applied Materials & Interfaces 469

What is in a record set

top tallies the most frequent sources or authors. Author strings that hold several names are split, so each contributor is counted once per record.

out(sf.top(records, by="source", n=5))
out(sf.top(records, by="author", n=6))
value n
ACS Applied Materials & Interfaces 8
Journal of Power Sources 5
Synthetic Metals 5
Electrochimica Acta 4
Journal of Materials Chemistry A 4
value n
Hao Yang 3
L. Ojeda 3
R. Mendoza 3
A.I. Mtz-Enríquez 2
Bin Wang 2
Congming Li 2

The tally has a long tail, as a topic literature usually does. ACS Applied Materials & Interfaces heads it with eight records, while 77 of the 90 journals represented appear only once or twice. The two records whose source title is missing are dropped from the tally, since an empty name is not a journal.

How a literature grows

year_counts is the offline tally of records per year from a set you already hold. Because the bundled harvest is a complete pull of its OpenAlex search, these counts are the publications that search matched in each year. A year without records is counted as zero, so a trend never runs straight across an empty year. For a harvest of your own, the plan it carries decides which years count, and a year no cell searched is left out.

trend = sf.year_counts(records)
out(trend)
year n
2015 15
2016 9
2017 10
2018 15
2019 19
2020 13
2021 13
2022 15
2023 15
2024 14

scopus_trend instead asks the API for the count in each year without downloading the records, which is far cheaper when all you want is the shape of the growth. It needs a key, so it is shown but not run.

trend = sf.scopus_trend(q, years=range(2015, 2025))

Turn it into figures

With the optional plot extra installed, the summaries become matplotlib figures. When the years of a trend reach the year its counts were retrieved in, plot_trend adds a note below the axis saying that year was incomplete at retrieval. Scopus goes on indexing a year's publications after the year has begun. The bundled corpus records no retrieval time, so its figure carries none.

sf.plot_trend(sf.year_counts(records))
show()
2026-11-15T17:25:44.611122 image/svg+xml Matplotlib v3.11.2, https://matplotlib.org/
sf.plot_top(sf.top(records, by="source"))
show()
2026-11-15T17:25:44.784219 image/svg+xml Matplotlib v3.11.2, https://matplotlib.org/

Size a niche

Where the figures above summarise records already in hand, scopus_intersections sizes a set of concepts and their overlap straight from the count endpoint, one cheap request per row, so a whole landscape costs no harvest. A concept value can be a bare term, wrapped in field for you, or a complete field-tagged expression such as a synonym set, used as given.

sets = sf.scopus_intersections(
    concepts={
        "semantic priming": "semantic priming",
        "mental simulation":
            "TITLE-ABS-KEY(mental simulation) OR TITLE-ABS-KEY(embodied simulation)",
    },
    intersections=[["semantic priming", "mental simulation"]],
    field="TITLE-ABS-KEY",
)

The result has a fixed shape, one row per concept and per intersection, which we reproduce here so the chart renders without a key. plot_scopus_intersections draws it as a lollipop chart on a log axis, with the intersection accented.

sets = pd.DataFrame({
    "label": ["semantic priming", "mental simulation",
              "semantic priming × mental simulation"],
    "query": ["TITLE-ABS-KEY(semantic priming)",
              "TITLE-ABS-KEY(mental simulation) OR "
              "TITLE-ABS-KEY(embodied simulation)",
              "(TITLE-ABS-KEY(semantic priming)) AND "
              "(TITLE-ABS-KEY(mental simulation) OR "
              "TITLE-ABS-KEY(embodied simulation))"],
    "n": pd.array([6600, 2600, 18], dtype="Int64"),
    "type": ["concept", "concept", "intersection"],
    "size": [1, 1, 2],
    "members": ["semantic priming", "mental simulation",
                "semantic priming; mental simulation"],
})
focal = sets.loc[sets["type"] == "intersection", "label"].tolist()
sf.plot_scopus_intersections(sets, highlight=focal)
show()
2026-11-15T17:25:45.025840 image/svg+xml Matplotlib v3.11.2, https://matplotlib.org/

Read the fuller record

scopus_abstract pulls the abstract and fuller metadata for a known identifier, and is resilient to the odd id that fails. It calls the Abstract Retrieval API, so it needs a key.

dois = sf.extract_dois(records)
abstracts = sf.scopus_abstract(dois[:10], by="doi")
abstracts[["doi", "title", "year"]]

The result is one row per identifier, over the stable ABSTRACT_COLUMNS schema. The bundled harvest carries the bibliographic fields but no abstract text, so the frame below takes its two most-cited records and leaves the one column the corpus cannot supply as a placeholder. Everything else in those rows is the real record.

most_cited = records.nlargest(2, "citations")
abstracts = pd.DataFrame({
    "scopus_id": pd.NA,
    "doi": most_cited["doi"],
    "title": most_cited["title"],
    "abstract": "(the bundled harvest carries no abstract text)",
    "publication": most_cited["publication"],
    "date": most_cited["date"],
    "year": most_cited["year"],
    "citations": most_cited["citations"],
}, columns=sf.abstract.ABSTRACT_COLUMNS)
out(abstracts[["title", "publication", "year", "citations"]])
title publication year citations
Graphene for batteries, supercapacitors and beyond Nature Reviews Materials 2016 1247
Flexible and Stackable Laser-Induced Graphene Supercapacitors ACS Applied Materials & Interfaces 2015 469

A failed identifier does not stop the batch, but yields an all-NA row that still records the id, together with a warning. Two failures concern the key rather than one identifier: a refused entitlement (HTTP 403) raises ScopusFlowForbiddenError and stops the batch, and a spent weekly quota stops the requests, keeps the rows already retrieved and warns once with ScopusFlowQuotaWarning, as Author keywords and references describes.