ads-bib 0.1.0

Pipeline for querying and turning NASA's ADS publications metadata into curated, analysis-ready datasets, topic maps, and citation networks.

ads-bib

ads-bib takes a NASA ADS search query and produces a normalized, curated dataset, with disambiguated author names (AND via ads-and), topic models (via BERTopic or Toponymy), and citation networks ready for e.g. Gephi, CiteSpace, or VOSviewer, locally or via API.

Installation

Use uv and Python 3.12.

uv pip install ads-bib
# or: pip install ads-bib

Quick Start

Create a .env file in your project root with the relevant API keys.

ADS_TOKEN=your-ads-token           # required
OPENROUTER_API_KEY=your-key        # only for the openrouter road
HF_TOKEN=your-key                  # only for the huggingface road
MODAL_TOKEN_ID=your-modal-id       # only for AND with backend=modal
MODAL_TOKEN_SECRET=your-modal-secret

ADS user token settings | OpenRouter Keys | Hugging Face Access Tokens | Modal.

Then run in your terminal:

ads-bib run --preset openrouter --set search.query='author:"Hawking, S*"'

Author name disambiguation is off by default. Enable the local CPU/GPU path with --set author_disambiguation.enabled=true; use --set author_disambiguation.backend=modal only when your Modal credentials are configured.

Full setup details: Get Started | Runtime Roads

Python API

import ads_bib

ads_bib.run(
    preset="openrouter",
    query='author:"Hawking, S*"',
)

More examples and the NotebookSession interface: Python API docs

Pick a Runtime Road

Road	Hardware	Network	Cost
openrouter	any	API calls	pay-per-token
hf_api	any	API calls	HF-plan-dependent
local_cpu	CPU only	model downloads only	free after setup
local_gpu	NVIDIA + CUDA	model downloads only	free after setup

Full provider matrix and first-run behavior: Runtime Roads

Output

Each run produces a self-contained output directory:

• publications.parquet — cleaned, translated, topic-labeled publications, with disambiguated authors when AND is enabled
• references.parquet — normalized cited-reference metadata, with disambiguated authors when AND is enabled
• topic_info.parquet — one row per topic with labels, counts, and representation fields
• topic_map.html — interactive topic visualization (open in any browser), using datamapplot
• .gexf citation networks — direct citation, co-citation, bibliographic coupling, author co-citation
• download_wos_export.txt — Web of Science format for e.g. CiteSpace / VOSviewer
• run_summary.yaml — full run metadata and stage timings

Topic map output from author:"Hawking, S*" in datamapplot.

Author co-citation output from author:"Hawking, S*" in Gephi Lite.