Sci-Scripts — Daily research scripts

中文

Small CLI tools that grew out of a real research-note workflow: citation export, journal ranking lookup, scientific plotting, GitHub fetching, OCR fallback.

Design principles: pure Python stdlib (matplotlib is the only third-party dependency), single-file, no framework, copy-and-run. No API keys, no personal data.

---

Overview

Script	Purpose	Deps
bib_export.py	Literature notes (YAML frontmatter) → BibTeX / GB/T 7714 citations	none
journal_rank.py	Journal ranking lookup via easyScholar free API (IF / JCR / CAS tier / TOP / ESI)	none (bring your own key)
gh_fetch.py	GitHub repo metadata + README + file tree in one fetch (urllib direct, no gh CLI)	none
draw_data.py	Scientific line charts with matplotlib (CJK font fallback)	matplotlib
draw_excalidraw.py	Text list → Excalidraw flowchart JSON (auto layout, CJK-aware)	none
img_ocr.py	Image OCR fallback via tesseract (Chinese + English)	tesseract (optional)

All six scripts are self-contained and work from any directory — no hard-coded paths. (bib_export.py defaults to ./10-Literature; point --notes at your notes folder when running elsewhere.)

---

Quick Start

# Env: Python 3.8+, Windows / Linux / macOS
git clone https://github.com/Guaiss1105/sci-scripts.git
cd sci-scripts

python gh_fetch.py owner/repo                       # repo info in one shot
python journal_rank.py "Nano Letters" "ACS Nano"    # journal ranking

pip install -r requirements.txt                     # all third-party deps (matplotlib)
python draw_data.py data.csv --x 0 --y 1 --xlabel Wavelength --ylabel Intensity --out fig.png

⚠️ Windows users: passing Chinese characters via CLI arguments garbles under GBK (tested). Keep CJK content in script-internal strings, files, or JSON configs; pass only ASCII paths via argv.

---

Tools

bib_export.py — Citation export

Parses YAML frontmatter from literature notes and outputs BibTeX or GB/T 7714 citations, filterable by category / topic / reading status. Missing volume/page fields are omitted honestly — never fabricated.

python bib_export.py --notes /path/to/notes --format bibtex --topic strong-coupling --out refs.bib
python bib_export.py --format gbt7714 --status done

journal_rank.py — Journal ranking

Queries the free easyScholar API for impact factor, JCR quartile, CAS tier, TOP flag, and ESI discipline.

python journal_rank.py "Nano Letters" "ACS Nano"   # single or multiple
python journal_rank.py --file list.txt            # batch, one journal per line

Config: put your free key from easyScholar into a easyscholar_key file (no extension) next to the script, or set the EASYSCHOLAR_KEY environment variable. The 0.6s/call rate limit is built in.

gh_fetch.py — GitHub repo info fetch

A fallback for restricted networks (WebFetch blocked, no gh CLI installed): direct urllib access to api.github.com / raw.githubusercontent.com. Public repos need no token; 60 requests/hour limit.

python gh_fetch.py owner/repo                 # metadata + README + tree
python gh_fetch.py owner/repo --file src/x.py # fetch a single file

draw_data.py — Scientific plotting

matplotlib line charts in a research style: multi-column csv/txt, legend, grid, dpi 200, automatic CJK font fallback.

python draw_data.py data.csv --x 0 --y 1 --xlabel Wavelength --ylabel Intensity --out fig.png

draw_excalidraw.py — Flowchart generation

Turns a text list like "step1;step2" into an Excalidraw flowchart JSON (rectangles, arrows, centered text, horizontal/vertical layouts) that opens directly in Obsidian or excalidraw.com.

python draw_excalidraw.py "step1;step2" --direction v --out fig.excalidraw.md

img_ocr.py — OCR fallback

A wrapper around tesseract (Chinese + English). If tesseract is missing, the script self-checks and prints install instructions.

python img_ocr.py image.png

---

Testing

python smoke_test.py    # compile + --help for all scripts; CI runs this on every push

---

Field Notes

These tools live on real-world gotchas. The scripts work because of them:

Where	Gotcha
gh_fetch.py	When WebFetch is blocked and no gh CLI exists, urllib-direct to api.github.com is the only reliable channel. Public repos: no token needed, 60 req/h.
draw_excalidraw.py	CJK full-width characters need a width coefficient of ~1.0 (half-width 0.5) or text boxes misalign. Rotated text must be positioned by center ± height/2.
draw_data.py	Windows systems often lack CJK fonts — the script auto-falls back, or labels render as tofu boxes.
journal_rank.py	The free easyScholar API rate-limits at 0.6s/call; batch queries are slow by design, not broken.
img_ocr.py	Tesseract is frequently absent; the script detects and guides installation instead of crashing.
bib_export.py	YAML frontmatter with unquoted @ breaks the whole block — the parser is defensive about quotes.

---

What's not included

• Tools that depend on proprietary API keys (e.g. multimodal image-reading/generation) are excluded — key-based auth cannot be open-sourced, and keys must never be committed.
• This repo contains no key files; .gitignore excludes *_key patterns. Keep it that way if you fork.

---

Known limitations (tested, not guessed)

• Chinese CLI args on Windows garble under GBK — use file/JSON configs for CJK content.
• easyScholar free API rate-limits at 0.6s/call; batch queries are slow by design.
• draw_excalidraw.py JSON re-saved once by the Excalidraw plugin gets minified — normal, editing still works.

---

License

MIT — free to use, modify, commercialize, or close-source. Just keep the copyright notice.