Notebook app

Jupyter and Google Colab widget application for biblioflow workflows.

Purpose

biblioflow-nb provides a notebook-native widget interface that mirrors the core workflow of biblioflow-web without requiring a FastAPI server, React app, or local browser server. It is intended for Jupyter notebooks, JupyterLab, and Google Colab.

Installation

pip install biblioflow-nb

For plotting extras when they are implemented:

pip install "biblioflow-nb[plot]"

Quickstart

import biblioflow_nb as bfn

app = bfn.launch()

Launch with an existing dataset:

import biblioflow as bf
import biblioflow_nb as bfn

dataset = bf.load("records.ris")
app = bfn.launch(records=dataset)

Import PubMed or PubMed Central records directly from a notebook, or stage them first for screening:

import os
import biblioflow_nb as bfn

os.environ["BIBLIOFLOW_NCBI_EMAIL"] = "researcher@example.org"

app = bfn.app(display=False)
app.from_pubmed(query="bibliometrics AND reproducibility", limit=20)
app.from_pmc(query="open science", limit=20)

run = app.stage_pubmed(query="bibliometrics AND reproducibility", limit=20)
app.update_candidates([run["candidates"][0]["candidate_id"]], status="selected")
app.promote_candidates()
app.display()

from_pubmed_central(...) is also available as a long-form alias for from_pmc(...). API keys may be passed as api_key=... or configured through BIBLIOFLOW_NCBI_API_KEY; they are not stored in session manifests.

Google Colab

Call colab_setup() before launching. It is safe to call outside Colab.

import biblioflow_nb as bfn

bfn.colab_setup()
app = bfn.launch()

Colab helper functions are provided for upload/download behavior where the Colab runtime exposes compatible APIs.

Widget workflow

The notebook application provides panels for:

  • Loading local paths or uploaded files.
  • Searching remote sources through the Remote screening panel.
  • Staging records, files, PubMed, and PubMed Central results as generic screening runs before promotion.
  • Previewing validation warnings and normalized records.
  • Applying common filters.
  • Running overview analysis.
  • Inspecting source, author, affiliation, country, document, keyword, and map placeholders as the core implementation evolves.
  • Building matrices and networks.
  • Exporting datasets and downloading artifacts in notebook environments.

Programmatic screening helpers mirror the web app’s source-agnostic workflow:

app.stage_records([{"title": "Manual candidate"}], source="generic")
app.stage_file("records.ris", source="auto", format="auto")
app.stage_pubmed(query="bibliometrics", limit=50)
app.stage_pmc(query="open science", limit=50)
app.update_candidates(["candidate-id"], status="maybe")
app.promote_candidates(include_statuses=("selected", "maybe"))

Direct from_pubmed(...) and from_pmc(...) imports remain available as compatibility shortcuts when an intermediate screening step is not needed.

Development

makim nb.tests
makim nb.package.build
makim nb.examples.check

Direct package commands:

cd packages/biblioflow-nb
PYTHONPATH=src:../biblioflow/src pytest
PYTHONPATH=src:../biblioflow/src python -m ruff check src tests
PYTHONPATH=src:../biblioflow/src python -m mypy src
poetry build

Design rule

Notebook widgets should call the same biblioflow functions as the Python API and web backend. New bibliometric methods, matrix types, network types, normalizers, or exporters belong in the core library first.