S3 step by step

Analyse your literature with S3, step by step

S3 maps the themes of a research field from the titles and abstracts of its papers, checks which map fits your data best, and writes a report organised for a literature review. Use it from Claude, ChatGPT or a Google Colab notebook without writing code yourself, or from R.

Free and open source Runs on your computer, or in Google Colab First run downloads a 420 MB language model (a few minutes) Latest version on PyPI
Code, user guide and proposals: github.com/AI-Growth-Lab/s3-bibliometric · Package: pypi.org/project/s3-bibliometric Method: 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

The whole guide in 3 minutes. Watch on YouTube.

1

Export your papers from Scopus

Select all results → Export → CSV, and tick every information group. Step by step, with what each field unlocks: Scopus export for S3.

Title (required)Abstract (required) YearCited byAuthorsAffiliations KeywordsReferencesEIDFunding

Each extra field unlocks more of the analysis: references give citation flows and the map comparison, authors and affiliations give the who's who. Web of Science and OpenAlex exports also work.

Give S3 the file exactly as Scopus exported it. Opening and re-saving it in Excel cuts long reference lists at 32,767 characters.

2

Install uv, once (not needed in Colab or R)

uv starts S3 and installs everything it needs. Paste one line, then close and reopen the window.

Mac: Terminal
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows: PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
3

Optional: complete references with a Scopus API key

With a key from dev.elsevier.com, S3 fetches every paper's full reference list from Scopus using the EID column of your export: exact citations, and bibliographic coupling from Scopus IDs instead of reference text. Without a key, S3 matches titles in the References column.

Command line (Mac)
export SCOPUS_API_KEY="your-key"
Then add --scopus to the report command.
Claude Desktop: in the config, next to "args"
"env": {"SCOPUS_API_KEY": "your-key"}

Reference lists need your institution's Scopus access: run it on campus or the VPN, or ask your library for an institutional token. Never paste a key into a chat.

4

Optional: a hybrid map (text plus citations)

S3 uses the text map by default, as in the published method. If you ask for a hybrid map, S3 first screens text plus bibliographic coupling, co-citation or direct citation at 5%, 10%, … 40% weight. It uses the best hybrid only when it raises both the silhouette and the QI of the communities above the text map's, while clustering at least 90% as many papers; otherwise it keeps the text map. Citations only count for papers that are already close in content.

Claude Desktop or Claude Code: ask
Run S3 on ~/Downloads/scopus.csv with a hybrid map.
Command line (Claude.ai or ChatGPT route)
uvx --from s3-bibliometric s3bib report ~/Downloads/scopus.csv --map hybrid -o ~/Desktop/s3_report.html
Google Colab or Python
res = s3bib.run_s3(csv, s3bib.S3Config(map_weights="hybrid"))
R
res <- s3_run("~/Downloads/scopus.csv", map = "hybrid")

The report's Q0 shows the screening: silhouette, QI and topic coherence at every weight, and which map was used.

5

Optional: a knowledge graph of methods, data, theories and findings

S3 can add what each paper uses and finds to its knowledge graph as triples: methods, data sources, theories, constructs, countries, industries and level of analysis, and findings between constructs such as absorptive capacity → increases → innovation performance. The report then shows each theme's methods and theories, gaps, and which findings papers agree or disagree on (Q39 and Q40).

Upload your own triples (CSV or Excel with paper_id, subject, relation, object), or let Claude or ChatGPT extract them from the abstracts. A progress bar shows each batch, and every triple keeps a quote from the abstract that S3 checks.

Claude Desktop or Claude Code: ask
Extract the knowledge-graph triples for my S3 run and show me Q39 and Q40.
Claude asks whether to use your Claude plan, your ChatGPT plan, an API key, or do it in the chat.
Command line, with your Claude plan (Claude Code installed)
uvx --from s3-bibliometric s3bib extract-triples ~/Downloads/scopus.csv --backend claude-code -o ~/Desktop/triples.csv
Then add --triples ~/Desktop/triples.csv to the report command. --backend codex uses your ChatGPT plan.
Google Colab or Python, with an API key or your own file
res.extract_triples("anthropic", max_papers=30) # or res.add_triples("triples.csv")
API keys need pip install "s3-bibliometric[llm]" and ANTHROPIC_API_KEY or OPENAI_API_KEY (Colab: Secrets).
R
s3_extract_triples(res, "claude-code") # or s3_add_triples(res, "triples.csv")

Try 30 papers first: extraction takes a few seconds per paper, and the answers are saved, so a stopped run carries on where it left off.

Chat runs S3

Claude Desktop

Mac or Windows app
  1. Open Settings → Developer → Edit Config.
  2. Paste this and save:
    { "mcpServers": { "s3-bibliometric": { "command": "uvx", "args": ["s3-bibliometric"] } } }
  3. Quit Claude completely and open it again. S3's tools appear in the tools menu of the chat box.
  4. Ask:
    Run S3 on ~/Downloads/scopus.csv, label the themes and build the literature-review report.

Tools missing? Run which uvx (Mac) or where uvx (Windows) and put that full path in "command". Updating: restart Claude; if the new tools don't show, run uv cache clean s3-bibliometric first.

Chat runs S3

Claude Code

Terminal or the Claude desktop app's Code tab
  1. Add S3 with one command:
    claude mcp add s3-bibliometric -- uvx s3-bibliometric
  2. Ask:
    Run S3 on my Scopus file, show me the themes and the papers to read first, and write the methods paragraph.

Claude asks which language model to use (mpnet, from the S3 paper, is the default) and whether you have a Scopus API key. Never paste a key into the chat.

Notebook runs S3

Google Colab (or Jupyter)

Browser, nothing to install
  1. Open colab.research.google.com → New notebook. Optional: Runtime → Change runtime type → T4 GPU makes the embedding faster.
  2. Install S3 (first cell):
    !pip install -q s3-bibliometric
  3. Upload your Scopus CSV (pick the file when asked):
    from google.colab import files csv = list(files.upload())[0]
  4. Run S3 and download the report:
    import s3bib res = s3bib.run_s3(csv) res.report("s3_report.html") files.download("s3_report.html")
    For a hybrid map, see step 4.

Colab runs on Google's servers, so your file is uploaded there. Scopus API key: store it under Secrets (key icon) as SCOPUS_API_KEY, then run import os; from google.colab import userdata, os.environ["SCOPUS_API_KEY"] = userdata.get("SCOPUS_API_KEY") and s3bib.enrich_citations(res) before the report; Google's servers are off campus, so this usually also needs an institutional token. In Jupyter on your computer, skip the upload cell and use the file path.

You run S3, chat explains

Claude.ai or ChatGPT

Browser or phone
  1. Make the report with one command (change the file path):
    uvx --from s3-bibliometric s3bib report ~/Downloads/scopus.csv -o ~/Desktop/s3_report.html
    Press Enter for the default model; answer n if you have no Scopus API key. Add --map hybrid for a hybrid map (step 4).
  2. Open s3_report.html and click the downloads at the top: themes table, methods paragraph, reading list.
  3. Upload the report and files to the chat, and ask:
    Name each theme in 3–5 words and draft the structure of my literature review, with the gaps to discuss.

Browser chats can't start programs on your computer, so they read the report S3 made instead of running S3 themselves.

R runs S3

R or RStudio

R 4.1 or newer; results come back as data frames
  1. Install the R package once:
    install.packages("remotes") remotes::install_github("AI-Growth-Lab/s3-bibliometric", subdir = "r")
  2. Run S3, see the themes and write the report:
    library(s3bibliometric) res <- s3_run("~/Downloads/scopus.csv") s3_communities(res) s3_report(res, "s3_report.html")
  3. Work with any answer in R, for example the foundations of each theme:
    s3_answer(res, "Q8")$tables[[1]]
    Try it first on the included example: s3_run(s3_example()).

The first time, R sets up the matching Python library by itself (through reticulate), and the first run downloads the language model (420 MB). The R package and the Python library always have the same version, so they give the same results. Scopus API key: put SCOPUS_API_KEY=your-key in ~/.Renviron, restart R, then s3_enrich_citations(res).

What you get: a report organised for your literature review

The field at a glanceNumbers, themes, one paper per theme to read first, trends and gaps.
Theme cardsWhat each theme is about, word clouds, foundations, growth, links between themes, and with triples its methods, theories and data.
Research agendaKnowledge gaps and emerging themes for your discussion section.
Methods appendixWhich map was used and why (text alone or text plus citations), a methods paragraph to adapt, a glossary and the validation against other methods.
DownloadsReading lists for Zotero, EndNote or Mendeley (RIS, BibTeX), themes table, PRISMA counts.

Levels of analysis

Level 1The published S3 methodThemes, central and foundational papers, citation flows, gaps, growth.
Level 2 · default+ Who and whereAuthors, countries, journals, funders and citation networks.
Level 3 · when you ask+ PredictionsWhich gaps will close, which themes will grow, who will collaborate.