-
Notifications
You must be signed in to change notification settings - Fork 0
Handbook
A terminal-first bibliometric analysis CLI tool — from raw export files to insights.
- Overview
- Installation
- Quick Start
- Data Management
- Descriptive Statistics
- Text Mining & NLP
- Network Analysis
- LLM-Powered AI Analysis
- Configuration
- Trend Analysis
- Report Generation
- Export & Interoperability
- Supported Formats
- Help System
Citationer is a terminal-first bibliometric analysis tool for researchers, students, and librarians. It automates the entire pipeline:
Raw export files → Parse & Unify → Clean & Dedup → Analyze → Export
┌─────────────────────────────────────────┐
│ CLI Layer (Typer + Rich) │
├─────────────────────────────────────────┤
│ Stats Engine │ Text Engine │ Network Engine
├─────────────────────────────────────────┤
│ Parsers (CNKI, WoS) │ Dedup Engine │
├─────────────────────────────────────────┤
│ SQLite Cache │ Config (YAML) │ LLM Client
└─────────────────────────────────────────┘
- Zero-config: Auto-detects file formats; defaults cover 80% of use cases
- Local-first: All data processed locally; LLM calls are opt-in with privacy safeguards
- Pipe-friendly: JSON, CSV, GEXF, GraphML export — works with standard Unix tools
- Progressive complexity: Simple commands for common tasks; sub-commands for deep analysis
- Python 3.11 or later
- pip or pipx
pipx install citationer # Recommended (isolated)
pip install citationer # Standard pip installpip install "citationer[all]"This installs:
-
jieba— Chinese text segmentation -
scikit-learn,gensim— Topic modeling & clustering -
networkx,python-louvain,plotly— Network analysis & visualization -
openai— LLM API client -
wordcloud— Word cloud generation
citationer --helpA minimal workflow takes 4 commands:
cd /path/to/your/literature # 1. Go to your data directory
citationer scan # 2. Detect bibliographic files
citationer import # 3. Parse & store records
citationer stats overview # 4. View the dashboard📁 扫描结果: /path/to/literature
┌──────────────────────┬────────┬────────┬──────────────┐
│ 文件名 │ 来源 │ 条目数 │ 年份范围 │
├──────────────────────┼────────┼────────┼──────────────┤
│ wos_core.txt │ WoS │ 156 │ 2015 - 2024 │
│ cnki_export.xlsx │ CNKI │ 234 │ 2018 - 2025 │
└──────────────────────┴────────┴────────┴──────────────┘
📊 文献全景概览
┏━━━━━━━━━━━━━━┳━━━━━━┓
┃ 指标 ┃ 数值 ┃
┡━━━━━━━━━━━━━━╇━━━━━━┩
│ 总文献数 │ 390 │
│ 覆盖年份 │ 2015 ~ 2025 │
│ 作者总数 │ 1234 │
│ h-index │ 42 │
...
Scans a directory recursively for supported file types, auto-identifies the source database and format.
citationer scan # Current directory
citationer scan /path/to/data # Specific directory
citationer scan --no-recursive # Top-level onlyOutput: A table showing filename, detected source, record count, and year range per file.
A faster, non-recursive version of scan.
citationer statusParses detected files and stores unified records in a local SQLite database (.citationer/cache.db).
citationer import # Import — clears old data by default
citationer import file1.txt file2.xlsx # Import specific files
citationer import --keep # Append to existing dataRuns data quality checks and a 4-layer deduplication engine.
citationer clean # Full clean: validate + dedup
citationer clean --no-check-duplicates # Validate only
citationer clean --no-check-missing # Dedup only
citationer clean --dry-run # Preview without mergingDeduplication Layers:
| Layer | Method | Action |
|---|---|---|
| 1 | DOI exact match | Auto-merge |
| 2 | Title similarity ≥ 85% + same year | Auto-merge |
| 3 | Title similarity ≥ 70% + same first author + same year | Auto-merge (log for review) |
| 4 | Cross-language: author surname + year + journal + pages | Auto-merge |
Validation Checks:
- Missing title / year / authors
- Year anomalies (outside 1900–2030 range)
All stats commands read from the local database. Run citationer import first.
citationer stats overviewOutput: Total records, year range, journal count, unique authors, solo/coop rates, institution/country counts, language distribution, document type distribution, average citations, h-index.
citationer stats yearly # Annual counts
citationer stats yearly --cumulative # With cumulative lineIncludes a linear trend slope (publications/year).
citationer stats journals --top 20 # Top-20 journals by countcitationer stats authors --top 20 # Top-20 authorsAdditional metrics:
-
Price's Law core authors:
count ≥ 0.749 × √(max_publications) - Author h-index: Based on citations within the dataset
- Solo/coop rates: Percentages of single-author vs. multi-author works
- First-author distribution: Who publishes most as first author
citationer stats institutions --top 20 # Top-20 institutionsAuto-detects language (Chinese vs. English), tokenizes, removes stop words.
citationer text preprocess # All fields (title + abstract)
citationer text preprocess --field title # Title only
citationer text preprocess --lang zh # Force Chinese tokenization
citationer text preprocess --lang en # Force English tokenization
citationer text preprocess --top 10 # Show top 10 samplesChinese: jieba segmentation with bundled academic stop words (~250 terms).
English: Built-in regex tokenizer with lemmatization; spaCy used if available (en_core_web_sm).
citationer text keywords --top 50 # Top-50 keywords
citationer text keywords --min-count 3 # Filter rare keywords
citationer text keywords --per-year # With year × keyword heatmap
citationer text keywords --format json --output keywords.jsoncitationer text topics --method lda # LDA (gensim)
citationer text topics --method nmf # NMF (scikit-learn)
citationer text topics --num-topics 8 # Specify topic count
citationer text topics --max-terms 15 # Terms per topicAuto-detection: When --num-topics is not specified, the engine automatically determines an optimal count based on vocabulary size (capped at 15).
Coherence score: LDA reports c_v coherence for quality assessment.
TF-IDF based key sentence extraction — no LLM required, works offline.
citationer text summarize --max-sentences 10
citataioner text summarize --output summary.txtClusters papers by title + abstract similarity.
citationer text cluster --method kmeans # K-Means (default)
citationer text cluster --method hierarchical # Agglomerative
citationer text cluster --n-clusters 5 # Specify cluster count
citationer text cluster --vectorizer tfidf # TF-IDF (default)
citationer text cluster --output clusters.csvReports silhouette score, cluster sizes, and representative terms per cluster.
All network commands support CSV, GEXF, and GraphML export, plus interactive HTML visualization via Plotly.
citationer network keywords --top 50 --threshold 3
citationer network keywords --output-format gexf --output keywords.gexf
citationer network keywords --viz --output network.htmlParameters:
-
--top N: Only include top-N most frequent keywords -
--threshold N: Minimum co-occurrence count for an edge
# Author collaboration
citationer network coauthors --min-papers 2
citationer network coauthors --min-papers 5 --output-format csv
# Institution collaboration
citationer network coauthors --type institutions --min-papers 3
citationer network coauthors --type institutions --viz --output inst_net.htmlIncludes Louvain community detection — nodes are color-coded by community in HTML exports.
Two references cited together in the same paper form a co-citation link. Requires the references field to be populated (included in WoS full-record exports; not available in CNKI exports).
citationer network cocitation --top 30Two papers that share references are coupled. Falls back to keyword-based coupling if reference data is unavailable.
citationer network coupling --top 30
citationer network coupling --output-format gexf --viz| Format | Use Case |
|---|---|
csv |
Edge list for spreadsheet analysis |
gexf |
Import into Gephi |
graphml |
Import into Cytoscape |
html (via --viz) |
Interactive Plotly force-directed graph, self-contained single file |
Requires an LLM API key. See Configuration for setup.
Only titles and abstracts are sent to the LLM. Author names, emails, affiliations, DOIs, and source filenames are stripped before transmission. All responses are cached locally by input hash to avoid redundant API calls.
Runs LDA topic modeling locally, then sends the topic keywords to the LLM for human-readable labels.
citationer ai topics --auto-label --num-topics 5
citationer ai topics --auto-label --dry-run # Preview without API callImportant: Only topic keywords are sent to the LLM — not the full paper records. This keeps token consumption minimal (~500-1000 tokens per call).
Generates a 200–500 word literature review summary from titles and abstracts.
citationer ai summarize # Default: first 100 records
citationer ai summarize --max-records 50 # Limit input size
citationer ai summarize --language zh # Output in Chinese
citationer ai summarize --dry-run # Preview the promptCompares early vs. recent periods to identify shifting research focuses, emerging topics, and declining areas.
citationer ai trends
citationer ai trends --window 5 # 5-year comparison window
citationer ai trends --dry-runClassifies papers across configurable dimensions (research methods, theoretical frameworks, application domains, etc.).
citationer ai classify
citationer ai classify --dimensions "methods,theories,applications"
citationer ai classify --dry-runcitationer ai infoShows: API key status (masked), model, endpoint, temperature, max tokens, cache statistics.
The LLM client enforces a default 200,000 character input limit (~50K tokens). If your data exceeds this, records are automatically truncated with a note. Use --max-records to explicitly control input size. The ai topics command sends only topic keywords (0 records), so it never hits the limit.
Citationer stores configuration in .citationer/config.yaml (auto-created in the current directory).
citationer config show # View all settings
citationer config set llm.api_key sk-xxx # Set API key
citationer config set llm.model deepseek-chat # Set model
citationer config set llm.base_url https://api.openai.com/v1 # Set endpoint
citationer config set llm.temperature 0.5 # Set temperature
citationer config set llm.max_tokens 8192 # Set max output tokens
citationer config init # Create config with defaults
citationer config init --force # Overwrite existing config| Key | Description | Default |
|---|---|---|
llm.api_key |
API key (required) | "" |
llm.model |
Model name | deepseek-chat |
llm.base_url |
API endpoint URL | https://api.deepseek.com |
llm.temperature |
Generation temperature (0.0–2.0) | 0.3 |
llm.max_tokens |
Max output tokens | 4096 |
| Variable | Overrides |
|---|---|
CITATIONER_LLM_API_KEY |
llm.api_key |
CITATIONER_LLM_MODEL |
llm.model |
CITATIONER_LLM_BASE_URL |
llm.base_url |
CITATIONER_LLM_TEMPERATURE |
llm.temperature |
CITATIONER_LLM_MAX_TOKENS |
llm.max_tokens |
DEEPSEEK_API_KEY |
llm.api_key (legacy, lower priority) |
Environment variable > Config file (.citationer/config.yaml) > Default
# DeepSeek (default)
citationer config set llm.base_url https://api.deepseek.com
citationer config set llm.model deepseek-chat
# OpenAI
citationer config set llm.base_url https://api.openai.com/v1
citationer config set llm.model gpt-4o
# Ollama (local)
citationer config set llm.base_url http://localhost:11434/v1
citationer config set llm.model llama3
citationer config set llm.api_key ollama # Ollama doesn't require a real keyIdentifies keywords that suddenly spike in frequency, revealing emerging research topics.
citationer trend hotspots --top 30 # Top-30 keywords
citationer trend hotspots --gamma 0.5 # More sensitive (detects weaker bursts)
citationer trend hotspots --min-years 3 # Min 3 consecutive yearsParameters:
-
--top N: Number of top keywords to analyze (default 30) -
--gamma: Sensitivity (0.5 = sensitive, 2.0 = only strong bursts) -
--min-years: Minimum consecutive years to qualify as a burst
Output: Table of detected bursts with keyword, time period, strength, and trend direction (📈 rising / 📉 declining).
Builds a keyword co-occurrence network, detects theme clusters, and plots them on a centrality × density quadrant diagram.
citationer trend strategy --top 50 # Top-50 keywordsQuadrants:
| Quadrant | Name | Meaning |
|---|---|---|
| Q1 (high C, high D) | 🚀 Motor | Well-developed, central themes |
| Q2 (low C, high D) | 🔬 Niche | Well-developed, peripheral themes |
| Q3 (low C, low D) | 🌱 Emerging | Under-developed, weak connections |
| Q4 (high C, low D) | 📚 Basic | Important but under-developed |
Output: Table of themes with centrality/density scores + terminal scatter plot.
Generates a comprehensive Markdown or HTML report including all analysis results.
citationer report quick -o report.md # Markdown report
citationer report quick -o report.html # HTML report
citationer report quick --enhance -o r.md # LLM-enhanced with AI findingsReport contents: Overview, yearly trend, top journals/authors, keywords, topic modeling, co-occurrence network.
Generate a report using a YAML configuration file.
citationer report custom config.yaml -o report.mdExample config.yaml:
title: "My Literature Analysis"
sections:
- overview
- yearly
- journals
- authors
- keywords
- topics| Command | Flag | Output |
|---|---|---|
network keywords |
--output-format csv |
Edge list CSV |
network keywords |
--output-format gexf |
Gephi-compatible GEXF |
network keywords |
--output-format graphml |
Cytoscape-compatible GraphML |
network keywords |
--viz |
Interactive Plotly HTML |
network coauthors |
--viz |
Community-colored HTML graph |
citationer text keywords --format json --output keywords.json
citationer text topics --output topics.json
citationer text cluster --output clusters.csvAll table-formatted output can be combined with standard Unix tools:
citationer stats journals --top 30 | grep "Nature"
citationer text keywords --format json | jq '.keywords[:5]'| Source | Format | Extension | Parser | Status |
|---|---|---|---|---|
| Web of Science | Plain text (tagged) |
.txt, .ciw
|
WosTextParser |
✅ |
| Web of Science | Tab-delimited |
.txt, .tsv, .csv
|
WosTabDelimitedParser |
✅ |
| Web of Science | Excel export |
.xlsx, .xls
|
WosExcelParser |
✅ |
| CNKI (知网) | Excel export | .xlsx |
CnkiExcelParser |
✅ |
| Scopus | CSV/Excel |
.csv, .xlsx
|
ScopusParser |
✅ |
| PubMed | XML/MEDLINE |
.xml, .nbib
|
PubMedParser |
✅ |
| CSSCI | Excel/Text |
.xlsx, .txt, .csv
|
CssciParser |
✅ |
| BibTeX | Generic | .bib |
BibTeXParser |
✅ |
| RIS | Generic |
.ris, .txt
|
RISParser |
✅ |
CNKI Excel exports are identified by characteristic Chinese column headers (题名, 作者, 来源, 关键词, 摘要, etc.). At least 3 matching headers are required for positive detection.
-
Tagged text: First line starts with
FNor a valid WoS field tag (PT,AU, etc.) -
Tab-delimited: First line contains tab-separated field tags (
PT\tAU\tTI\t...) - Excel: Header row contains English markers like "Publication Type", "Authors", "Article Title"
Citationer has a three-tier help system:
Shows all top-level commands grouped by category, plus quick-start examples and global options.
citationer --help
citationer # Same effect (no-args = help)Shows all sub-commands within a group with descriptions.
citationer stats --help
citationer network --help
citationer ai --helpShows full parameter list with types, defaults, and usage examples.
citationer stats yearly --help
citationer text topics --help
citationer network keywords --helpyour-project/
├── data/ # Your bibliographic files
│ ├── wos_export.txt
│ └── cnki_2024.xlsx
├── .citationer/ # Auto-generated (gitignore this)
│ ├── cache.db # SQLite database
│ ├── cache.db-shm # SQLite WAL
│ ├── cache.db-wal # SQLite WAL
│ └── config.yaml # Your configuration
└── citationer_output/ # Default report output directory
Citationer v4 — July 2026