Skip to main content
Glama

S3 Bibliometric

S3 project: github.com/AI-Growth-Lab/S3: the method, the paper, the S3 web app and proposals for new analyses. Paper: doi.org/10.1016/j.jbusres.2026.116582. This repository holds the code of the s3-bibliometric Python library and MCP server.

Semantic Similarity Score (S3): a bibliometric method for mapping intellectual structures, packaged as a free Python library and an MCP server that LLM assistants (Claude, and any other MCP client) can call.

Give it a Scopus export. It finds the research communities of the field, their central papers, outliers, and the citation flows between communities. Your AI assistant can then label the communities and write up the intellectual structure.

No coding needed: see Use it without coding: Claude, ChatGPT or Colab for step-by-step setup with Claude Desktop, Claude Code, Claude.ai, ChatGPT or a Google Colab notebook, or the visual guides: S3 step by step and Scopus export for S3.

How S3 works

The library follows the published method: Bekamiri, Østergaard & Timmermans (2027), Semantic similarity score: A new method for mapping intellectual structures in business research, Journal of Business Research 219, 116582. https://doi.org/10.1016/j.jbusres.2026.116582

  1. Embed each paper's Title. Abstract with sentence-transformers/all-mpnet-base-v2

  2. S3 matrix = cosine similarity between all papers, time-masked so links run from earlier to later papers (year_i ≤ year_j)

  3. Scan thresholds 0.75–0.85: papers with at least one link S3 ≥ t are retained; Leiden with directed modularity finds the communities

  4. Keep the threshold with the highest SII = mean silhouette of retained papers × number retained

  5. Describe communities with eigenvector and degree centrality and c-TF-IDF terms

  6. With References + EID: in-corpus citations, QI (within-community citations per paper) and MI (the community's within + inward citations as a share of the field's citation links)

Reproducible. One seed (default 42) fixes every random step: Python, NumPy, PyTorch, Leiden/Louvain, sampling and layouts. Two runs on the same file give identical results.

Clean input. Before the analysis S3 drops records with neither title nor abstract and removes duplicates: the same EID, the same title + abstract, the same DOI with the same title (book chapters can share a DOI), and near-identical texts (S3 ≥ 0.98, e.g. reprints). The most-cited copy is kept; res.removed lists every dropped record and why.

Choose the embedding model (default: mpnet, the model of the published paper):

key

model

use it for

mpnet

sentence-transformers/all-mpnet-base-v2

default; the published S3 method

specter

sentence-transformers/allenai-specter

scientific papers (trained on citations)

minilm

sentence-transformers/all-MiniLM-L6-v2

quick looks, about 5× faster

multilingual

paraphrase-multilingual-mpnet-base-v2

corpora mixing languages

qwen3

Qwen/Qwen3-Embedding-0.6B

long abstracts (no truncation); slower

clip

sentence-transformers/clip-ViT-B-32

multimodal (text + images); reads only 77 tokens of text

Any other sentence-transformers model name also works. The threshold range 0.75–0.85 was calibrated for mpnet; other models get a wider scan (0.40–0.95) unless you set one.

Exact, complete references (optional). A Scopus CSV export can miss references: some records have none, and a long reference list can be cut at 32,767 characters, the cell limit of spreadsheet programs (do not open and re-save the export in Excel). By default S3 finds citations by matching titles in the References text and builds bibliographic coupling from the reference strings. With a Scopus API key (SCOPUS_API_KEY, from dev.elsevier.com), enrich_citations fetches every paper's full reference list as Scopus IDs, using the EID column of your original export (no new export needed):

  • in-corpus citations become exact (direct citation, co-citation, QI and MI);

  • bibliographic coupling counts shared cited Scopus IDs instead of matching reference text, for every paper the API returns references for (the others keep their References text);

  • if the map uses citation relations, or was chosen with map_weights="hybrid", the map and communities are rebuilt on the exact data (saved labels are dropped, so label afterwards).

This needs Scopus entitlement: your institution's network or VPN, or an institutional token (SCOPUS_INST_TOKEN). It makes about one request per paper (one per 200 references); Elsevier sets a weekly quota per key, shown on the developer portal. Results are cached in ~/s3bib_runs/_scopus, so an interrupted run continues where it stopped.

export SCOPUS_API_KEY="your-key"      # in your terminal, never in a chat
s3bib report scopus.csv --scopus -o report.html              # text map (default)
s3bib report scopus.csv --scopus --map hybrid -o report.html # or screen the hybrid maps
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(model_name="specter"))
s3bib.enrich_citations(res)                 # exact citations via the Scopus API
s3bib.S3Config(threshold=0.78)              # reproduce a published threshold
s3bib.S3Config(community_method="louvain")  # reproduce the S3 web app instead
s3bib.S3Config(dedupe=False)                # keep duplicates
s3bib.S3Config(mi_denominator="all")        # MI over all in-corpus links
s3bib.S3Config(citation_match="strict")     # short titles need year + first author too
s3bib.S3Config(map_weights="text+coupling") # one of four maps (below)
s3bib.S3Config(map_weights="hybrid")        # screen the hybrid maps, use the best one

Progress. run_s3, compare_maps, extract_triples and enrich_citations show a progress bar while they work (a widget in Jupyter and Colab, a text bar in a terminal): loading, embedding batch by batch, the threshold scan, and so on. Pass progress=False to hide it, or a function progress(stage, fraction) to handle it yourself.

Strict citation matching. Matching titles inside References text can link a short, generic title such as "Introduction" to every reference that contains the word. On the Innovation & Diversity corpus about a quarter of the matched citations came from titles of 25 characters or fewer, and only 11% of those carried the cited paper's year or first author. citation_match="strict" (CLI --strict-citations) keeps a short-title match only when the year (±1) and first author also appear in the reference. The default stays "lenient", as in the S3 web app and the published paper.

Choose the map. By default S3 uses the text map, the published method. Ask for a hybrid map ("hybrid") and S3 first screens the text map against text plus each citation relation at 5–40% weight, and uses the best hybrid only when it raises both the silhouette and the QI (see "Which map?" below); otherwise, or without in-corpus citations, it keeps the text map:

map_weights (CLI --map)

The map is built from

"text" (default)

text similarity (S3) only, the published method

"hybrid"

the screening: the best hybrid map, or text if no hybrid raises both silhouette and QI

"text+coupling"

75% text + 25% bibliographic coupling (shared references)

"text+cocitation"

75% text + 25% co-citation (cited together)

"text+direct"

75% text + 25% direct citation

res = s3bib.run_s3("scopus.csv", s3bib.S3Config(map_weights="text+cocitation"))
s3bib report scopus.csv --map text+cocitation

Every result follows the choice: the threshold scan, communities, network map, knowledge tree, citation flows, bridges, interdisciplinarity and the report header (which names the map). Coupling and co-citation are Salton cosines (0–1). Because the citation part is 0 for most pairs, the threshold scan matches link density: each threshold links as many pairs as one S3 threshold (0.75–0.85) on the same corpus, and SII picks the best, as for S3. Custom mixes also work, e.g. map_weights={"s3": 0.8, "coupling": 0.2}.

Text floor. A citation relation counts only for pairs whose text similarity is already at least 0.05 below the lowest S3 threshold (0.70 for mpnet). Citations then re-rank papers that are close in content and never link two unrelated texts, in line with S3's content-first design. Set it with S3Config(text_floor=0.72), or text_floor=False to let citations count for every pair.

Which map? Compare them before the analysis. compare_maps tries the text map and each citation relation (coupling, co-citation, direct citation) added step by step at 5%, 10%, ... 40% weight, all with the text floor: 25 maps. It builds each candidate map (threshold scan and Leiden only, so it takes minutes, not a full run per map) and scores it on measures that do not favour one kind of map:

Measure

What it checks

Held-out citations

20% of the in-corpus citation links are hidden while the maps are built. Share of hidden links that fall inside one community, minus the share for random communities of the same sizes. A citation map is not judged on its own input.

TCI gain over random

Text coherence of the communities (paper Table 5) beyond random communities of the same sizes

Stability

Adjusted Rand index with the partitions from two other seeds and two 90% samples of the papers

Coverage

Share of papers placed in a community

Agreement with text

Adjusted Rand index with the text map: how different the result is (reported, not used)

A rule fixed in advance recommends a map: keep the text map (the published method) unless a hybrid raises both the silhouette on the text embeddings (paper Table 6) and the QI on the held-out citation links (paper Table 7, counted on links the map did not see), keeps the TCI gain (at most 0.005 lower), loses at most 0.05 stability, and clusters at most 10% fewer papers than the text map (smaller, tighter communities always score higher, so coverage is guarded). Among the hybrids that pass, the highest held-out QI wins. The table also gives a 95% bootstrap interval (over the hidden links) of each map's difference from the text map, so you can see whether a win is larger than sampling noise. Relations that give a tie to fewer than 5% of the papers are left out, with the reason. extended=True also tries the whole grid without the text floor, to show what the floor changes. The report's Q0 draws the held-out gain of each relation against its weight, next to the text map.

from s3bib.mapchoice import compare_maps
ch = compare_maps("scopus.csv", s3bib.S3Config(cache_dir="~/s3bib_cache"))
ch["table"], ch["recommended"], ch["reasons"]
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(map_weights="hybrid")) # screen, then run on the winner
s3bib.enrich_citations(res)        # exact Scopus reference lists, then
res.compare_maps(refresh=True)     # compare the maps again on them
s3bib compare-maps scopus.csv            # the table and the recommendation
s3bib report scopus.csv --map hybrid     # screen, then the full report on the recommended map

The report shows the comparison as Q0 at the top of the methods appendix, and the methods paragraph says which map was used and why. In Claude, the compare_maps tool runs it before run_s3_analysis.

On the command line, s3bib report scopus.csv asks which model to use and whether to use the Scopus API; in Claude, the assistant asks the same two questions before the first run.

Reproducing the paper. On the paper's ‘Innovation and Diversity’ corpus, with S3Config(threshold=0.78, dedupe=False) the run retains exactly the paper's 1,826 papers, and the ten largest Leiden communities and their QI, local and global citations closely match Table 1.

Visuals. The report includes the paper's figures (S3 network map as in Panel 1, SII curve as in Fig. 3, elbow plot as in Fig. 4, citation-flow heatmap as in Table 2), an interactive paper-level network map drawn with force-graph, the library behind the S3 web app's map (hover for the paper, click for its abstract, drag, zoom, play the network year by year, dark/light, click a community to highlight it; a built-in map is used offline), a knowledge tree (communities per 5-year window, linked by citations and S3 similarity from earlier to later periods; switch between citation, similarity or both links, filter weak links, click a community to follow its lineage), a citation-flow diagram, a stacked growth chart, and author × community and country × community maps. Community colours are the same in every chart.

kt = res.knowledge_tree(window_years=5)   # {"windows", "nodes", "links"} as DataFrames

Related MCP server: Paper Chaser MCP

The networks behind S3: one-mode, two-mode, knowledge graph

S3 answers its questions from three levels of network. You can export each of them:

Level

Nodes

Ties

Questions

One-mode

papers

SIMILAR_TO (S3 ≥ threshold)

Q1–Q3, Q5–Q7, Q9, Q12–Q13, Q21–Q23

One-mode, multiplex

papers

SIMILAR_TO + CITES (+ coupling, co-citation, co-authorship in Q35–Q37)

Q4, Q8, Q10, Q11, Q24, Q35–Q37

Two-mode

papers + authors, keywords, journals, institutions, countries, funders or references

AUTHORED_BY, HAS_KEYWORD, …

Q14–Q16, Q19, Q20; co-citation and bibliographic coupling (Q4) are projections of the paper–reference network

Knowledge graph

all of the above + communities

all tie types + IN_COMMUNITY, LOCATED_IN

Q17, Q18

Communities are not in the data: S3 derives them from the one-mode similarity network. The knowledge graph adds them as nodes so that questions across communities become graph queries.

res.networks()                        # node and tie types and counts per level
G = res.network("kg")                 # networkx MultiDiGraph; also "similarity", "citation",
                                      # "one-mode", "paper-author", "paper-keyword", ...
res.export_networks("networks/")      # node/edge CSVs (Neo4j, igraph) + GraphML (Gephi)
                                      # add two_mode_kinds=[..., "reference"] for the large
                                      # paper-reference network

Knowledge-graph triples: methods, data, theories and findings

Add what the papers use and find to the knowledge graph as triples, then read them per theme:

Relation

From → to

Example

USES_METHOD

paper → Method

fsQCA, panel regression

USES_DATA

paper → Dataset

Community Innovation Survey, patent data

USES_THEORY

paper → Theory

resource-based view

STUDIES

paper → Construct

absorptive capacity

STUDIED_IN, IN_INDUSTRY, AT_LEVEL

paper → Country, Industry, Level

Germany, manufacturing, firm

INCREASES, DECREASES, NO_EFFECT_ON, MODERATES, MEDIATES, ASSOCIATED_WITH

Construct → Construct

absorptive capacity INCREASES innovation performance

Upload your own (CSV, Excel, JSON): columns paper_id (EID, DOI or title), subject, relation, object, optionally evidence. Spelling variants of an entity are merged.

Or let Claude or ChatGPT extract them from the titles and abstracts, batch by batch, with a progress bar and a cache (an interrupted run resumes; a repeated run costs nothing):

Route

Uses

Command

claude-code

your Claude plan, through the Claude Code command line

s3bib extract-triples scopus.csv --backend claude-code

codex

your ChatGPT plan, through the Codex command line

--backend codex

anthropic

the Claude API (ANTHROPIC_API_KEY)

--backend anthropic

openai

the OpenAI API (OPENAI_API_KEY)

--backend openai --model <model>

in a Claude chat

Claude itself, in Claude Desktop or Claude Code

ask: "extract the knowledge-graph triples" (prompt s3_triples)

The API routes need pip install "s3-bibliometric[llm]". Every extracted triple keeps a quote from the abstract as evidence, and S3 marks whether that quote is really in the title or abstract (evidence_found), so you can check the rest before citing them.

res = s3bib.run_s3("scopus.csv")
res.extract_triples("claude-code", max_papers=30)   # try on 30 papers first
res.add_triples("my_triples.csv")                   # or add your own
res.answer("Q39")    # methods, data, theories and settings per theme, gaps, rising methods
res.answer("Q40")    # findings between constructs: established, contested, single-study
s3bib extract-triples scopus.csv --backend claude-code -o triples.csv
s3bib report scopus.csv --triples triples.csv

The triples join the knowledge graph (res.network("kg"), export_networks, Neo4j/Gephi files) next to themes, authors, journals and funders; the theme cards in the report list each theme's methods, theories and data.

Three levels of analysis

Level

What it adds

Questions

1. S3 — the published method

The text-similarity map and what the S3 paper reports from it. Questions marked S3 paper are in the paper; extension questions use the same map.

S3 paper: Q1 threshold (SII) · Q2 structure quality · Q3 outliers · Q38 evaluation against coupling, BERTopic and random clusters (paper Tables 5–7) · Q5 communities · Q6 topics · Q7 core papers · Q8 local vs global foundations · Q10 citation flows, QI, MI (Tables 1–2). Extensions: Q0 which map to use (text alone or text plus citations) · Q9 closeness · Q11 knowledge gaps · Q12 bridges · Q13 growth · Q14 concepts · Q21–Q23 interdisciplinarity

2. Two-mode networks and knowledge graph (default)

Authors, institutions, countries, journals, funders and references; the map options that mix in citation relations

Q4 agreement with coupling and co-citation · Q15–Q20 actors · Q35 layer overlap and projection check · Q36 homophily · Q37 citation direction

3. Prediction (off unless asked)

Link prediction and graph neural networks

Q24–Q34

Each level includes the ones below it. Choose it for a run or per call:

res = s3bib.run_s3("scopus.csv", s3bib.S3Config(level=1))   # only the published method
res.questions(level=2)                                     # the ranked list, and which ones your data supports
res.answer("Q8")                                           # findings + tables for one question
res.report("report.html", level=1)                         # the report at one level
s3bib report scopus.csv -o report.html --level 1
s3bib questions --level 1

Q38 compares the methods as in the paper: the Topic Coherence Index (TCI = 1 − Jensen–Shannon divergence between each paper's TF-IDF words and its community's), the silhouette on the SBERT embeddings for every method, and QI. BERTopic is included when installed (pip install "s3-bibliometric[bertopic]"). Absolute values depend on text cleaning, so compare the methods within one run rather than with the numbers printed in the paper.

The report: organised for a literature review

res.report("report.html") writes one self-contained HTML page in the order a review is written:

  1. The field at a glance — the numbers, the themes, one paper per theme to read first, the foundations the field builds on, where it is going, the gaps to discuss (and leading authors at level 2).

  2. Scope — records in and out (PRISMA-style counts) and papers that do not belong.

  3. Themes — one card per theme: terms and keywords, papers to read first, foundations, growth, which themes it builds on and is used by, the closest themes in content, and at level 2 its authors, countries, journals and funders. Each card is one subsection of your review.

  4. How themes connect, Evolution, Who does the work (level 2).

  5. Research agenda — knowledge gaps, emerging themes, collaboration gaps (level 2) and forecasts (level 3), for your discussion and future-research sections.

  6. Methods appendix — a methods paragraph to adapt (with the references), a glossary, and the analyses that show the map can be trusted.

Every result carries a For your review note and a tag: L1 · S3 paper, L1 · extension, L2 or L3. When the map mixes in citation relations, the report says that even the level-1 results are no longer the published method. Downloads for writing:

res.export_review("review/")   # reading_list.ris (Zotero, EndNote, Mendeley), reading_list.bib,
                               # themes.csv, prisma.csv, methods.txt
res.report("report.html", layout="questions")   # the previous layout: every question in order

Prediction (level 3, stages 7–8) is off by default (S3Config(prediction=False), level=2). Until you switch it on, Q24–Q34 do not appear in the question list, the report, the CLI or Claude, and asking for one returns a note that prediction is off. Switch it on for a whole run, or for one call:

res = s3bib.run_s3("scopus.csv", s3bib.S3Config(prediction=True))   # everything on for this run
res.report("report.html")                    # then includes Q24–Q34
res.answer("Q30")
res.find_experts("board diversity and green innovation", kind="author")   # R-GCN (Q32)

res.report("report.html", prediction=True)   # or per call, on a run without it
res.answer("Q30", prediction=True)
s3bib report scopus.csv --prediction
s3bib questions --prediction

Every prediction is tested honestly before it is used: the corpus is split in time (the last 5 years are the test window), models see only information from before the split, and each result is compared with simple baselines (popularity, community size, Adamic-Adar, nearest paper) with 95% intervals, so the report says when a model does not beat chance. The GNNs (GraphSAGE, R-GCN, a temporal GCN + GRU, TransE and RotatE) are small and written in plain PyTorch, which sentence-transformers already installs; nothing else is needed.

Multiplex, homophily and direction (Q35–Q37). The same papers are tied in five ways: text (the map's S3 links), bibliographic coupling, co-citation, direct citation and co-authorship.

Question

Measures

What it tells you

Q35

Jaccard overlap between layers; lift = how many times more often a tie of one layer is also a tie of another than a random pair

Which relations the text map misses, so which map option (map_weights) adds the most

Q36

Attribute assortativity r (−1 to +1) per attribute and layer, with the within-group share expected by chance

Whether ties stay inside the same community, journal, country or funder, and in which layer

Q37

PageRank on in-corpus citations; per community a source score (+1 only cited, −1 only citing); reciprocity of flows between communities against random direction

Which papers and communities are knowledge sources, and whether knowledge moves one way

A paper can only cite older papers, so reciprocity is measured between communities, not papers.

Projection check (Q35). Coupling, co-citation and co-authorship are one-mode projections of two-mode networks (papers–references, cited–citing papers, papers–authors). Projections inflate ties and clustering: one popular reference links every paper that cites it, and a ten-author paper makes a clique of ten (Jankowski et al. 2026, Commun. Phys. 9:35). Q35 therefore reports, for each projected layer:

  • Significant ties: two papers share more items than chance predicts from how many items each has and how popular the items are (stochastic degree sequence model with Chung–Lu probabilities, Poisson test, Benjamini–Hochberg FDR 0.05 over all paper pairs). With the ties shuffled and all degrees kept, no tie is significant.

  • Four-cycle clustering of the two-mode network itself (Robins & Alexander), next to the clustering of the projection, so you can see how much clustering the projection creates.

To build the map and Q35–Q37 from significant ties only:

res = s3bib.run_s3("scopus.csv", s3bib.S3Config(map_weights="text+coupling", backbone=True))
s3bib report scopus.csv --map text+coupling --backbone
from s3bib.layers import layers, overlap, homophily, pagerank, flow_direction
J, lift, summary = overlap(res)      # Q35 tables
homophily(res)                       # Q36: attribute, layer, r
pagerank(res)                        # Q37: PageRank per paper

Charts or tables. Result sections are closed until you click them open. Tables open as bar charts; switch any of them to the table (and pick the column to plot), or switch all of them at once at the top of the report. Q6 shows one word cloud per main community (the top 10, five per row): 30 words each by default, 10 to 50 with one menu.

In Claude, use the s3_guided prompt, or ask: "Walk me through the S3 questions for my Scopus file."

Use it without coding: Claude, ChatGPT or Colab

S3 runs on your own computer, so your data stays with you, or in a Google Colab notebook in your browser. How you use it depends on your app:

Your app

How

Setup

Claude Desktop (Mac, Windows)

Chat with S3 directly: Claude runs the analysis and explains it

Once: install uv, paste 6 lines into Claude's settings

Claude Code

Same, from the terminal

Once: install uv, one command

Claude.ai (browser, phone) or ChatGPT

Make the report with one command, then upload it to the chat

Once: install uv

Google Colab (browser) or Jupyter

Paste three cells into a notebook; it runs S3 and downloads the report

Nothing to install in Colab

Claude.ai in the browser and ChatGPT cannot start programs on your computer, so they cannot run S3 themselves; they can read and explain the report and files S3 makes.

Step 0: export your papers from Scopus

In Scopus, select all results → Export → CSV. Tick every information group (citation, bibliographical, abstract and keywords, funding, and references). Title and abstract are required; the rest (year, citations, authors, affiliations, keywords, references, funding) unlock more of the analysis. Web of Science and OpenAlex exports work if they have Title and Abstract columns.

Step 1: install uv (once)

uv starts S3 for you and installs everything it needs.

  • Mac: open Terminal and paste:

    curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows: open PowerShell and paste:

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen the Terminal (or PowerShell) window afterwards.

Step 2a: Claude Desktop

  1. In Claude Desktop open Settings → Developer → Edit Config. This opens claude_desktop_config.json.

  2. Paste this and save (if the file already has "mcpServers", add only the "s3-bibliometric" part inside it):

    {
      "mcpServers": {
        "s3-bibliometric": {
          "command": "uvx",
          "args": ["s3-bibliometric"]
        }
      }
    }
  3. Quit Claude Desktop completely and open it again. S3's tools now appear in Claude's tools menu in the chat box.

  4. Ask, for example:

    Run S3 on ~/Downloads/scopus.csv. Label the communities, walk me through the level-1 questions, and build the literature-review report.

    Claude asks which language model to use (mpnet, the model of the S3 paper, is the default) and whether you have a Scopus API key for exact citations (optional; never paste a key into the chat). To use one, add it to the config above, next to "args": "env": {"SCOPUS_API_KEY": "your-key"}, and restart Claude Desktop. The first run downloads the model (about 420 MB) and takes a few minutes; later runs are fast.

If the tools do not appear: Claude Desktop may not find uvx. In Terminal run which uvx (Mac) or where uvx (Windows) and put that full path in "command", e.g. "command": "/Users/you/.local/bin/uvx".

Step 2b: Claude Code

claude mcp add s3-bibliometric -- uvx s3-bibliometric

Then ask the same as above.

Step 2c: Claude.ai in the browser, or ChatGPT

  1. Make the report with one command in Terminal (Mac) or PowerShell (Windows). Replace the file path with yours:

    uvx --from s3-bibliometric s3bib report ~/Downloads/scopus.csv -o ~/Desktop/s3_report.html

    It asks which language model to use (press Enter for the default) and whether you have a Scopus API key (answer n if not). Add --level 1 for only the published S3 method.

  2. Open s3_report.html in your browser. At the top, click the downloads: Themes table (CSV), Methods paragraph, and the reading list (RIS) for Zotero, EndNote or Mendeley.

  3. Upload the report and the downloaded files to Claude.ai or ChatGPT, and ask, for example:

    This is an S3 analysis of my literature. Name each theme in 3-5 words, summarise the field's structure, and draft the structure of my literature review with the gaps to discuss.

Step 2d: a Google Colab notebook (or Jupyter)

Nothing to install: Colab runs Python in your browser, on Google's servers. Skip step 1.

  1. Open colab.research.google.com → New notebook. Optional: Runtime → Change runtime type → T4 GPU makes the embedding faster.

  2. In the first cell, install S3 and press ▶ (or Shift+Enter):

    !pip install -q s3-bibliometric
  3. In a new cell, upload your Scopus CSV (pick the file when asked):

    from google.colab import files
    csv = list(files.upload())[0]
  4. In a new cell, run S3 and download the report (the text map, the published method):

    import s3bib
    res = s3bib.run_s3(csv)
    res.report("s3_report.html")       # add level=1 for only the published S3 method
    files.download("s3_report.html")

    For a hybrid map (text plus citations, screened), use s3bib.run_s3(csv, s3bib.S3Config(map_weights="hybrid")) and print(res.answer("Q0")) to see the screening. The first run downloads the language model (about 420 MB). Then open the report and use it as in step 2c, or keep asking in the notebook, e.g. print(res.answer("Q8")) or res.questions() for the list of questions.

Notes:

  • Colab runs on Google's servers, so your file is uploaded there. A free Colab session ends after a while; download the report before you close it.

  • Scopus API key in Colab: click the key icon (Secrets), add SCOPUS_API_KEY, allow the notebook to use it, and run this before the report:

    import os
    from google.colab import userdata
    os.environ["SCOPUS_API_KEY"] = userdata.get("SCOPUS_API_KEY")
    s3bib.enrich_citations(res)

    Reference lists need your institution's Scopus access, and Google's servers are not on your campus network, so this usually also needs an institutional token (SCOPUS_INST_TOKEN, from your library), stored the same way.

  • Jupyter on your own computer: install with pip install s3-bibliometric in your environment, skip the upload cell, and use the file path, e.g. csv = "/Users/you/Downloads/scopus.csv"; open s3_report.html instead of downloading it.

What you can ask

  • "Which questions can S3 answer for my data?" — the ranked research questions, in three levels: 1 the published S3 method, 2 authors, countries, journals, funders and citation networks, 3 predictions (only when you ask).

  • "What are the main themes, and which papers should I read first?"

  • "Where are the knowledge gaps?" · "Which themes are emerging?"

  • "Write the methods paragraph for my paper."

  • "Build the literature-review report at level 1."

The tools Claude uses

Tool

What it does

compare_maps

Before the analysis: compare the text map with text+coupling, text+cocitation and text+direct on your corpus and recommend one

run_s3_analysis

Run S3 on a CSV/XLSX (year range, map option, strict citation matching); returns a run_id and a summary

list_embedding_models

The language models you can choose (default: mpnet, as in the S3 paper)

enrich_citations

Exact, complete reference lists from the Scopus API: exact citations, and coupling from cited Scopus IDs (needs SCOPUS_API_KEY in the server's environment)

list_runs

Saved runs

list_questions

The ranked research questions for a level (1, 2 or 3) and whether your data supports each

answer_question

Findings and tables for one question, e.g. Q8

build_report

The literature-review report (or every question in order), at a level

get_threshold_scan

Silhouette / SII / communities for each threshold

list_communities

Community table incl. QI/MI and saved labels

get_community

Central papers with abstracts, keywords, TF-IDF terms

save_community_labels

Store the labels the assistant proposes

get_outliers

Unconnected papers + nearest community

get_citation_structure

Community × community citation matrix + QI/MI

get_knowledge_tree

How communities grow and split over time

search_papers

Semantic search inside the corpus

export_results

Write CSV outputs

export_networks

One-mode, two-mode and knowledge-graph networks as CSV + GraphML

add_triples

Add a triples file (methods, data, theories, findings) to the knowledge graph

triple_extraction_options

Which extraction routes work here: Claude plan, ChatGPT plan, API keys, or the chat

extract_triples

Extract triples from the abstracts with Claude Code, Codex or an API, with progress

next_triple_batch, save_triples

Claude extracts the triples itself in the chat, batch by batch, with progress

Prompts: s3_guided walks through the questions stage by stage; s3_report writes the intellectual-structure report. Runs are saved in ~/s3bib_runs (change it with the S3BIB_HOME environment variable).

Use it from Python

pip install s3-bibliometric
import s3bib

res = s3bib.run_s3("scopus.csv")       # or run_s3(df, s3bib.S3Config(start_year=2010))
res.scan                               # threshold scan
res.communities()                      # size, citations, years, QI/MI
res.community_papers(0, n=10)          # most central papers
res.top_keywords(0); res.top_terms(0)
res.outliers()
res.citation_matrix()
res.search("absorptive capacity")
res.labels = {0: "Open innovation", 1: "M&A"}
res.export("results/")                 # CSVs
res.save("runs/innovation")            # reload with s3bib.S3Result.load(...)

Use it from R

The R package s3bibliometric runs this library of the same version, so R and Python give the same results. Details: r/README.md.

remotes::install_github("AI-Growth-Lab/s3-bibliometric", subdir = "r")
library(s3bibliometric)
res <- s3_run("scopus.csv")                  # text map; map = "hybrid" screens the hybrids
s3_communities(res)
s3_report(res, "s3_report.html")

Python is set up automatically on first use (via reticulate). The R and Python version numbers are always the same: a test fails if they differ, and every release updates both.

Input

Export from Scopus as CSV with at least Title and Abstract. Also used if present: Year, Cited by, Authors, Author Keywords, Source title, DOI, and References + EID (needed for the citation analysis).

Notes

  • On a CPU, embedding 5,000 abstracts takes a few minutes. The silhouette step uses an N×N matrix (~100 MB at N = 5,000).

  • A paper counts as citing another if the first 60 characters of the other paper's normalised title appear in its References. This step is O(N²).

Tests

The tests run on real data: 109 OpenAlex records (CC0) on absorptive capacity and work group diversity, with their real all-mpnet-base-v2 embeddings, in tests/data/. python tests/data/build_openalex_sample.py rebuilds them.

Authors

Hamid Bekamiri (maintainer), with S3 co-authors Christian Richter Østergaard and Bram Timmermans.

Citation

S3 project: github.com/AI-Growth-Lab/S3. To propose a new analysis, open an issue there; report problems with this library here.

If you use this package, please cite the S3 paper:

Bekamiri, H., Østergaard, C. R., & Timmermans, B. (2027). Semantic similarity score: A new method for mapping intellectual structures in business research. Journal of Business Research, 219, 116582. https://doi.org/10.1016/j.jbusres.2026.116582

License

MIT

Available Tools

23 tools
add_triplesA

Add knowledge-graph triples from a file (CSV, Excel, JSON or JSON lines) to a run. Columns: paper_id (EID, DOI or title), subject, relation, object (optional: subject_type, object_type, evidence). Paper relations: USES_METHOD, USES_DATA, USES_THEORY, STUDIES, STUDIED_IN, IN_INDUSTRY, AT_LEVEL (subject "PAPER"); findings between constructs: INCREASES, DECREASES, NO_EFFECT_ON, MODERATES, MEDIATES, ASSOCIATED_WITH. The triples join the knowledge graph and answer Q39 (methods, data, theories per theme) and Q40 (findings, contested relations).

Inputs: path (required), run_id (required). Returns: result

answer_questionB

Answer one ranked question, e.g. "Q8" (foundational papers) or "Q21" (interdisciplinarity). Returns findings (plain sentences) and result tables. The prediction questions Q24-Q34 are off unless prediction=True (only when the user asks for prediction).

Inputs: run_id (required), question_id (required), max_rows, prediction. Returns: result

build_reportA

Write one self-contained HTML report. layout="review" (default) is organised for a literature review: a one-page brief, scope (records in and out), one card per theme (what it is about, papers to read first, growth, links to other themes), how themes connect, evolution, research agenda (gaps) and a methods appendix, with RIS/BibTeX reading lists and a methods paragraph to download. layout="questions" lists every question. level: 1 = the published S3 method, 2 = + two-mode and knowledge graph (default), 3 = + prediction (prediction=True is the same; a few minutes more). Default path: the run folder.

Inputs: run_id (required), level, title, layout, +2 more. Returns: result

compare_mapsA

Before the full analysis: which map should S3 use for this corpus? Compares the text map (the published method) with text plus bibliographic coupling, co-citation or direct citation at 5%, 10%, ... 40% weight; citations count only for pairs already close in content (the text floor). extended=True adds the same grid without the floor. 20% of the in-corpus citation links are hidden while the maps are built; each map is scored on the hidden links inside its communities (gain over random communities of the same sizes), on text coherence (TCI gain over random), stability (ARI across seeds and 90% samples) and coverage. A rule fixed in advance recommends a map. Show the user the table and the recommendation, then pass the chosen map to run_s3_analysis as map_relations. Takes a few minutes; embeddings are cached for the run. With run_id instead of csv_path, compares on that run's papers and citation links: use this after enrich_citations, so the comparison uses the exact Scopus reference lists.

Inputs: seed, run_id, csv_path, end_year, +4 more. Returns: result

enrich_citationsA

Exact, complete reference lists from the Scopus Abstract Retrieval API, for every paper of the run (by EID). The in-corpus citation links become exact, and bibliographic coupling uses the cited Scopus IDs instead of the exported References text (which can be truncated or missing). If the run's map uses citation relations (or was chosen with map_relations="hybrid"), the map and communities are rebuilt and saved labels are dropped: label the communities after this step. Reads SCOPUS_API_KEY (and optional SCOPUS_INST_TOKEN) from this server's environment; needs Scopus entitlement (institution network or token). About 0.2 s per paper; cached.

Inputs: run_id (required). Returns: result

export_networksA

Export the networks behind S3 at three levels: one-mode (papers tied by S3 similarity and/or citations), two-mode (papers + authors, keywords, journals, institutions, countries, funders or references) and a knowledge graph (all node and tie types together, with communities as nodes). Writes node/edge CSVs (Neo4j, igraph) and GraphML (Gephi) to output_dir (default: the run folder) and returns the files and a summary of what each network contains.

Inputs: run_id (required), output_dir. Returns: result

export_resultsA

Write CSV outputs (papers with community + label, community table, threshold scan, citation matrix) to output_dir (default: the run folder).

Inputs: run_id (required), output_dir. Returns: result

extract_triplesA

Extract triples (methods, data, theories, constructs, settings, findings) from the titles and abstracts of a run with "claude-code", "codex", "anthropic" or "openai" (see triple_extraction_options), batch by batch, and add them to the run. Reports progress after every batch; answers are cached, so a repeated or interrupted run resumes. Large corpora take a while: tell the user the number of papers first, or test with max_papers=30.

Inputs: run_id (required), model, backend, batch_size, +1 more. Returns: result

get_citation_structureB

In-corpus citation flows between the largest communities (rows cite columns), plus QI (within-community citations / size) and MI (share of field citations). Needs References and EID columns in the export.

Inputs: run_id (required). Returns: result

get_communityA

Details for one community, to interpret or label it: the most central papers (eigenvector centrality, then citations) with abstracts, top author keywords and top TF-IDF terms. Set abstract_chars=0 to return titles only.

Inputs: run_id (required), community_id (required), max_papers, abstract_chars. Returns: result

get_knowledge_treeB

Knowledge tree: papers per community in each time window, and links from earlier to later windows weighted by citations and by S3 similarity links. Use it to describe how communities emerged, which earlier work each one builds on, and where knowledge flowed.

Inputs: run_id (required), min_links, window_years, n_communities. Returns: result

get_outliersB

Papers with no S3 link above the chosen threshold (the "irrelevant" set), most cited first, with their nearest similarity and suggested community.

Inputs: run_id (required), limit. Returns: result

get_threshold_scanC

Threshold scan table: threshold, silhouette, clustered papers, SII, number of communities and edges. The best threshold maximises SII.

Inputs: run_id (required). Returns: result

list_communitiesB

All communities (largest first) with size, citations, year span, saved label, and QI/MI citation metrics when References were available.

Inputs: run_id (required), min_size. Returns: result

list_embedding_modelsA

Embedding models the user can choose for run_s3_analysis (key, model, kind, max tokens, description). Default: mpnet, the model used in the published S3 paper.

Inputs: no named parameters. Returns: result

list_questionsA

The ranked research questions of the S3 method, in three levels: level 1 = the published S3 method (text similarity map; each question says whether it is in the S3 paper or an extension), level 2 (default) = + two-mode networks and knowledge graph (authors, institutions, journals, funders, layer overlap, homophily, citation direction), level 3 = + prediction (link prediction Q24-Q29, GNNs Q30-Q34; only when the user asks; include_prediction=True is the same as level 3). Shows priority and whether this dataset has the columns each question needs.

Inputs: run_id (required), level, include_prediction. Returns: result

list_runsA

List saved S3 runs (run_id, number of papers, best threshold, labels saved?).

Inputs: no named parameters. Returns: result

next_triple_batchA

In-chat extraction, step 1: the next papers without triples (id, title, abstract), the extraction instructions, and the progress so far. Extract the triples yourself, following the instructions, then call save_triples with this batch's paper ids. Repeat until done is true, telling the user the progress after each batch.

Inputs: run_id (required), batch_size. Returns: result

run_s3_analysisA

Run the S3 pipeline on a Scopus CSV/Excel export (needs Title and Abstract; Year, Cited by, Authors, Author Keywords, References and EID are used if present).

Follows the published S3 method: embeds Title+Abstract (all-mpnet-base-v2), builds the time-ordered S3 graph, scans thresholds 0.75-0.85 and keeps the Leiden (directed modularity) partition with the highest SII (silhouette x retained papers). Set threshold (e.g. 0.78) to reproduce a published run, or community_method="louvain" to reproduce the S3 web app. embedding_model is a key from list_embedding_models or any sentence-transformers model name (ask the user first; default mpnet). Records without title and abstract are dropped and duplicates (same DOI/EID/text, or S3 >= 0.98) are removed unless remove_duplicates=False. map_relations chooses the map, and every answer and report follows it: "text" (default; S3 text similarity, the published method), "hybrid" when the user asks for a hybrid map (screens text plus each citation relation at 5-40% weight, as compare_maps does, and uses the best hybrid if it raises both silhouette and QI, else text), or a specific hybrid the user names: "text+coupling", "text+cocitation", "text+direct" (75%/25%) or weights such as "s3=0.8,coupling=0.2". strict_citations=True stops short titles such as "Introduction" from matching unrelated references. significant_ties_only=True keeps only coupling, co-citation and co-authorship ties that are significant under a degree-preserving null model (in the map and Q35-Q37). Can take several minutes for thousands of papers the first time; embeddings are cached afterwards.

Returns a run_id plus a summary: best threshold, communities, outlier count.

Inputs: csv_path (required), seed, rerun, end_year, +8 more. Returns: result

save_community_labelsB

Store short topic labels for communities, e.g. {"0": "Open innovation", "1": "..."}. Labels are saved with the run and included in exports.

Inputs: labels (required), run_id (required). Returns: result

save_triplesA

In-chat extraction, step 2: save the triples you extracted for one batch (each with paper_id, subject, subject_type, relation, object, object_type, evidence) and mark the batch's papers done, including papers with nothing to extract. Returns the progress message to show the user, e.g. "Saved 42 triples. 60 of 800 papers done (8%)".

Inputs: run_id (required), triples (required), paper_ids (required). Returns: result

search_papersC

Semantic search over the run's papers (same embedding model as S3).

Inputs: query (required), run_id (required), top_k. Returns: result

triple_extraction_optionsA

Which ways of extracting triples work on this computer: "claude-code" (the user's Claude plan via the Claude Code command line), "codex" (the user's ChatGPT plan via the Codex command line), "anthropic" / "openai" (API keys in this server's environment), and always "chat" (you extract them yourself with next_triple_batch and save_triples). Ask the user which to use.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target clearly distinct stages of the S3 workflow: run setup, map comparison, analysis, inspection, labeling, export, and reporting. The only real overlap is among the triple-extraction tools (extract_triples, next_triple_batch, save_triples, add_triples), but their descriptions clarify the automated versus in-chat versus file-import paths.

    Naming Consistency4/5

    The set overwhelmingly uses predictable snake_case verb_noun naming, such as list_runs, run_s3_analysis, get_community, save_triples, and export_results. Minor deviations like triple_extraction_options and next_triple_batch are noun-oriented or workflow-step names, but they remain readable and mostly consistent.

    Tool Count3/5

    With 23 tools, the surface is on the heavy side for a single server and includes many inspection/reporting endpoints. Most tools do earn their place in a complex bibliometric pipeline, but the count sits at the borderline where consolidation could improve usability.

    Completeness5/5

    The surface covers the full S3 lifecycle: listing models and runs, running analyses, comparing maps, enriching citations, extracting/importing triples, inspecting thresholds, communities, outliers, citation structure and knowledge trees, searching papers, saving labels, exporting results and networks, answering ranked questions, and building reports. No obvious workflow dead end is apparent.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Scopus to AI assistants for literature discovery. Provides tools for finding papers, experts, citation networks, and analyzing research trends.
      2
      GPL 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to conduct academic research workflows such as paper discovery, literature mapping, citation chasing, author pivots, citation repair, and regulatory or species document retrieval.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables manuscript researchers to conduct retrieval and scoring searches, inspect human-readable results, record inline reviews, rescore cached corpora, and export reports or ChatGPT-ready research packets.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants such as Claude to search academic literature, retrieve abstracts and full text, trace citations and multi-generation citation networks, and analyze author profiles, journal quality and bibliometrics from a conversation. It works with Scopus by default and can run the same analyses against OpenAlex without a subscription.
      35
      46 PyPI
      1
      MIT