Journal Abbreviation Lookup#

Look up journal/magazine name abbreviations using a multi-source cascade: JabRef database (~25K journals) → AbbrevISO API (ISO 4) → NLM Catalog (MEDLINE).

Critical rule: Always use jabbrv.py for lookups. Never guess abbreviations — even common journals have non-obvious abbreviations.

Quick Reference#

User wants...CommandAbbreviate a journal namepython3 jabbrv.py abbrev "Nature Medicine"Expand an abbreviationpython3 jabbrv.py expand "Nat. Med."Auto-detect directionpython3 jabbrv.py lookup "J. Am. Chem. Soc."Fuzzy search (paginated)python3 jabbrv.py search "biolog chem" --limit 10 --offset 0Process a .bib filepython3 jabbrv.py bib refs.bibPreview .bib changes (no write)python3 jabbrv.py bib refs.bib --dry-runExplicit .bib output pathpython3 jabbrv.py bib refs.bib --output out.bibExpand .bib abbreviationspython3 jabbrv.py bib refs.bib --expandBatch text listpython3 jabbrv.py batch journals.txtBatch as NDJSON streampython3 jabbrv.py batch journals.txt --streamInspect cache statepython3 jabbrv.py cache statusDownload missing cache filespython3 jabbrv.py cache updateRebuild cache from scratchpython3 jabbrv.py cache rebuildMachine-readable CLI contractpython3 jabbrv.py schemaSchema for one subcommandpython3 jabbrv.py schema lookup

Output format#

Stdout is a stable JSON envelope when the CLI is not attached to a terminal (piped or captured by an agent), and a human table/indented view when run on a TTY. To force a format: --format json|table|human|auto. --json remains as a back-compat alias for --format json. Flags may appear before or after the subcommand.

Envelope shape (always the same fields for every subcommand):

• Success: { "ok": true, "data": ..., "meta": { "schema_version", "cli_version", "cache", "latency_ms" } }
• Partial success (batch): { "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }
• Error: { "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

Exit codes#

CodeMeaning0success (including partial success)1runtime / upstream error2validation / bad input (missing file, bad flag)3not found (the looked-up journal does not exist)

Error codes (inside error.code)#

not_found, file_not_found, validation_error, runtime_error. Each carries a retryable: bool so agents can branch retry logic.

Workflow#

Step 1: Detect Intent#

IntentActionSingle journal name/abbreviationUse lookup (auto-detect) or abbrev/ expand (explicit direction)"What's the abbreviation for X?"Use abbrev"What journal is X?"Use expandPartial or uncertain nameUse search for fuzzy matchingFix journal names in .bib fileUse bibList of journals to processUse batch

Step 2: Execute#

Run the appropriate jabbrv.py command. The script handles:

1. Local cache lookup (instant, ~25K journals from JabRef)
2. AbbrevISO API fallback (algorithmic ISO 4 abbreviation, forward only)
3. NLM Catalog fallback (biomedical journals, bidirectional)

First run downloads JabRef CSV cache files automatically (~2-5 MB).

Step 3: Present Results#

• Show the full name, abbreviation, and source
• Note the standard (ISO 4 vs MEDLINE) when relevant
• For .bib processing: show the change summary before confirming

ISO 4 vs MEDLINE#

Two common abbreviation standards exist:

StandardPeriodsExampleUsed byISO 4YesNat. Med.Most publishers, BibTeXMEDLINENoNat MedPubMed, NLM databases

JabRef provides ISO 4 style. NLM Catalog provides MEDLINE style. AbbrevISO computes ISO 4 algorithmically from LTWA (List of Title Word Abbreviations).

Common Abbreviation Patterns#

WordAbbreviationWordAbbreviationJournalJ.InternationalInt.AmericanAm.EuropeanEur.Science/SciencesSci.Medicine/MedicalMed.Biology/BiologicalBiol.Chemistry/ChemicalChem.Physics/PhysicalPhys.EngineeringEng.ResearchRes.Review/ReviewsRev.SocietySoc.NationalNatl.ProceedingsProc.TransactionsTrans.LettersLett.CommunicationsCommun.AppliedAppl.ComputationalComput.

Note: Single-word titles (e.g., "Nature", "Science", "Cell") are NOT abbreviated per ISO 4 rules.

Integration Examples#

With Zotero#

bash

# Export BibTeX from Zotero, then standardize journal names
zot export COLLECTION_KEY --format bibtex > refs.bib
python3 jabbrv.py bib refs.bib

With LaTeX#

bash

# Before compiling, ensure all journal names are abbreviated
python3 jabbrv.py bib references.bib
# Use the output file (references_abbrev.bib) in your LaTeX document

Batch Processing#

Create a text file with one journal name per line:

text

Nature Medicine
Journal of Biological Chemistry
Proceedings of the National Academy of Sciences

Then run:

bash

python3 jabbrv.py batch journals.txt

Troubleshooting#

IssueSolution"No result found"Try search with partial name for fuzzy matchingCache download failsCheck network connection, retry with update-cacheWrong abbreviation styleJabRef = ISO 4 (with dots), NLM = MEDLINE (no dots)BibTeX field not detectedEnsure format is journal = {Name} (curly braces)