Citationer

A terminal-first bibliometric analysis CLI tool — scan, import, analyze, and visualize your literature collection.

Citationer is a lightweight, local-first, zero-config CLI tool for researchers. Drop into a directory with bibliographic export files, run a single command, and get a complete literature analysis — from descriptive statistics with terminal charts to knowledge graphs and AI-powered topic labeling.

Features

Installation

# Recommended: isolated install via pipx
pipx install citationer

# Or via pip
pip install citationer

# With all optional dependencies (NLP, network, AI, viz)
pip install "citationer[all]"

# From source
git clone https://github.com/JasonCENG/citationer.git
cd citationer
pip install --no-build-isolation -e ".[all,dev]"

Quick Start

# 1. Check version
citationer --version

# 2. Navigate to your literature directory
cd /path/to/literature

# 2. Scan for bibliographic files
citationer scan

# 3. Import into the local database (auto-clears old data)
citationer import

# 4. Clean & deduplicate
citationer clean

# 5. View the overview dashboard
citationer stats overview

Command Reference

Data Management

citationer scan                  # Scan directory for bibliographic files
citationer status                # Quick status check
citationer import                # Import files (clears old data by default)
citationer import --keep         # Append to existing data
citationer clean                 # Validate & deduplicate records

Descriptive Statistics (stats)

citationer stats overview             # Dashboard: totals, years, h-index, languages
citationer stats yearly               # Braille line chart
citationer stats yearly --cumulative  # Dual bar+line chart
citationer stats yearly --table       # Data table
citationer stats journals --top 20    # Horizontal bar chart
citationer stats authors --top 20     # Bar chart + Price's Law core authors
citationer stats institutions --top 20 # Bar chart

Text Mining (text)

citationer text preprocess       # Tokenize + language detection
citationer text keywords --top 30     # Keyword frequency
citationer text keywords --per-year   # Keyword × year heatmap
citationer text topics --method lda   # LDA topic modeling
citationer text topics --method nmf   # NMF topic modeling
citationer text summarize              # TF-IDF extractive summary
citationer text cluster --method kmeans  # Document clustering

Trend Analysis (trend)

citationer trend hotspots --top 30        # Keyword burst detection
citationer trend hotspots --gamma 0.5     # More sensitive (detects weaker bursts)
citationer trend strategy --top 50        # Strategic diagram (centrality × density)

Multi-Dataset Comparison (compare)

# Compare all imported datasets by source_database
citationer compare overview
citationer compare trends
citationer compare topics --top-n 30
citationer compare network --type authors --min-papers 2

# Compare by original file
citationer compare overview --by file

# Export results as JSON or CSV
citationer compare overview --format json -o compare.json
citationer compare trends --format csv -o trends.csv

Export (export)

citationer export csv -o data.csv         # Export to CSV
citationer export json -o data.json       # Export to JSON
citationer export bibtex -o refs.bib     # Export to BibTeX

Reports (report)

citationer report quick -o report.md       # Generate Markdown report
citationer report quick -o report.html     # HTML report
citationer report quick --enhance -o r.md  # LLM-enhanced report
citationer report custom cfg.yaml -o r.md  # Custom YAML-configured report

Network Analysis (network)

citationer network keywords --top 50 --threshold 3   # Co-occurrence network
citationer network coauthors --min-papers 2           # Author collaboration
citationer network coauthors --type institutions       # Institution collaboration
citationer network cocitation --top 30                 # Co-citation analysis
citationer network coupling --top 30                   # Bibliographic coupling

# Export formats: csv, gexf, graphml, html (interactive)
citationer network keywords --output-format gexf --output graph.gexf
citationer network coauthors --viz --output network.html

LLM-Powered Analysis (ai)

# Configure your LLM first
citationer config set llm.api_key sk-your-key
citationer config set llm.model deepseek-chat

citationer ai topics --auto-label     # Auto-label LDA topics
citationer ai summarize               # Generate literature review (200-500 words)
citationer ai trends                  # Identify research trends & gaps
citationer ai classify                # Multi-dimensional classification
citationer ai info                    # View LLM config & cache stats

# Preview without API call
citationer ai summarize --dry-run

Interactive Mode (interactive)

citationer interactive              # Step-by-step guided analysis wizard

Pipeline Runner (run)

citationer run pipeline.yaml         # Execute declarative YAML pipeline

Configuration (config)

citationer config show                # View all settings
citationer config set llm.api_key sk-xxx  # Set API key
citationer config set llm.model gpt-4o    # Change model
citationer config set llm.base_url https://api.openai.com/v1  # Change provider
citationer config init                # Initialize config file with defaults

LLM Provider Configuration

Citationer supports any OpenAI-compatible API. Edit .citationer/config.yaml or use env vars:

# .citationer/config.yaml
llm:
  api_key: "sk-xxx"
  model: "deepseek-chat"
  base_url: "https://api.deepseek.com"
  temperature: 0.3
  max_tokens: 4096

Environment variables override the config file: CITATIONER_LLM_API_KEY, CITATIONER_LLM_MODEL, etc.

Supported Bibliographic Formats

Development

# Install with all dependencies
pip install --no-build-isolation -e ".[all,dev]"

# Run tests
pytest tests/ -v

# Lint & type check
ruff check src/ tests/
mypy src/ --ignore-missing-imports

# Coverage report
pytest tests/ --cov=src/citationer --cov-report=term-missing

Documentation

• Wiki Home — Links to all docs
• Handbook — Full user manual (English)
• 用户手册 — 中文用户手册
• PRD v4.0 — Latest product roadmap (Phase 5/6)
• PRD v3.0 — Previous roadmap (historical)
• PRD v2.1 — Terminal charts
• PRD v2.0 — Full requirements doc (Phase 1–5) (historical)
• PRD v1.0 — Original PRD (historical)

License

MIT © Jason Yu