sciglyph 0.1.0__tar.gz

sciglyph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guo Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sciglyph-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: sciglyph
+Version: 0.1.0
+Summary: Publication-quality scientific illustration in pure matplotlib - no BioRender, no Illustrator
+Author: Guo Cheng
+License: MIT
+Project-URL: Homepage, https://github.com/GuoCheng24/sciglyph
+Project-URL: Issues, https://github.com/GuoCheng24/sciglyph/issues
+Keywords: matplotlib,scientific-figures,publication,illustration,graphical-abstract,bioinformatics,deep-learning,diagram
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# sciglyph
+
+[![test](https://github.com/GuoCheng24/sciglyph/actions/workflows/test.yml/badge.svg)](https://github.com/GuoCheng24/sciglyph/actions/workflows/test.yml) [![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Publication-quality scientific illustration in pure matplotlib — no BioRender, no Illustrator.**
+
+Overview figures and architecture diagrams are usually drawn by hand in a
+subscription tool. That makes them pretty, but also unreproducible: you cannot
+diff them, you cannot regenerate them when the numbers change, and you cannot
+put them under version control.
+
+`sciglyph` gives you the primitives to draw the same figures as **code**.
+
+<p align="center">
+  <img src="gallery/overview_figure.png" width="88%">
+</p>
+
+<p align="center">
+  <img src="gallery/architecture.png" width="100%">
+</p>
+
+<sub>Both figures above are generated by the scripts in
+<a href="examples/">examples/</a> — nothing was touched by hand. The content is
+synthetic; swap in your own numbers and the layout carries over.</sub>
+
+---
+
+## Why
+
+| | subscription tools | `sciglyph` |
+|---|---|---|
+| Reproducible | ✗ manual pixel-pushing | ✓ a script |
+| Version control | ✗ binary blobs | ✓ diffable source |
+| Data-driven | ✗ retype every number | ✓ read straight from your results |
+| Vector output | ~ depends on export | ✓ PDF/SVG with editable text |
+| Cost | subscription | free, MIT |
+
+## Install
+
+```bash
+pip install git+https://github.com/GuoCheng24/sciglyph
+```
+
+Only `matplotlib` and `numpy`. Nothing else.
+
+<sub>Not on PyPI yet, so the git URL above is the install line that works today.
+When it lands, `pip install sciglyph` will too.</sub>
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+from sciglyph import bio, set_canvas, report, RC
+
+plt.rcParams.update(RC)
+fig = plt.figure(figsize=(7.2, 3.0), dpi=300)
+ax = fig.add_axes([0, 0, 1, 1]); ax.set_xlim(0, 1); ax.set_ylim(0, 1); ax.axis("off")
+set_canvas(fig)                      # required on non-square canvases
+
+bio.person(ax, .08, .55, s=.30)
+bio.dna(ax, .25, .55, w=.05, h=.45, n=2)
+bio.cell(ax, .42, .55, r=.06, seed=1)
+bio.seq_logo(ax, .60, .40, [("A", .6), ("C", .9), ("G", .4), ("T", .7)], w=.03)
+
+report(fig, ax)                      # catch text collisions before saving
+fig.savefig("figure.pdf", bbox_inches="tight")
+```
+
+Run the full examples:
+
+```bash
+python examples/overview_figure.py    # -> gallery/overview_figure.png
+python examples/architecture.py       # -> gallery/architecture.png
+```
+
+## What's included
+
+**`sciglyph.bio`** — glyphs for Nature/Science-style overview figures:
+`person` (cohorts) · `dna` · `cell` · `lipid` · `metabolite` ·
+`nucleosome_chain` · `umap_layer` (the stacked atlas look) ·
+`seq_logo` (information-scaled letters, no logomaker needed) ·
+`stacked_planes` · `rbox` · `arr`
+
+**`sciglyph.arch`** — glyphs for architecture diagrams:
+`cuboid` / `feature_stack` (3-D feature blocks) · `trapezoid` (encoders) ·
+`module_stack` (`Conv|BN|ReLU` bars) · `dashed_group` (the `(a)/(b)/(c)`
+language) · `flow` · `op_circle` · `snowflake` (frozen backbone) ·
+`image_thumb` · `embedding_space` (contrastive panels) · `loss_tag` · `bracket`
+
+**`sciglyph.layout`** — pre-flight collision detection.
+
+## Catching layout bugs before you save
+
+When a figure breaks, it is almost never the artwork — it is the layout.
+`report()` uses the real rendered bounding boxes to find overlapping text, so
+you do not have to hunt for it by eye:
+
+```python
+report(fig, ax)
+# [sciglyph.layout] 36 text objects
+#   ! 'CD4 Treg/-FOXP3' x 'SMR' overlap 92%
+```
+
+It also works from the command line on any script that exposes `fig` and `ax`:
+
+```bash
+python -m sciglyph.layout my_figure.py
+```
+
+It checks three things, each of which shipped a broken figure before it existed:
+
+| check | what it catches |
+|---|---|
+| text overlap | two labels drawn over each other |
+| **artwork overlap** | a row of boxes laid out slightly too wide, so each one covers its neighbour — the strings may not overlap at all, so text-level checks miss it entirely |
+| **missing glyphs** | a character the font cannot draw, rendered as an empty box. Symbols typed as literals (`✓`, `❄`) are the usual casualty |
+
+Two kinds of overlap are deliberately *not* reported, because they are the
+layout working: a panel containing its contents, and an unfilled dashed shape —
+a ring drawn around the thing it annotates.
+
+**These are geometric checks.** Whether the figure actually *reads* well still
+needs your eyes.
+
+## Notes from actually shipping these figures
+
+- **Call `set_canvas(fig)`.** In `[0,1]` coordinates a "circle" is `r·W` wide
+  and `r·H` tall. On a 12×3 canvas, every circle becomes a rugby ball.
+- **Anchor arrows to what `feature_stack` returns**, not to hard-coded
+  coordinates — otherwise changing the number of blocks silently breaks them.
+- **Never put symbol codepoints in figure text.** `❄` (U+2744) is missing from
+  most sans fonts and renders as a tofu box. Draw it (`arch.snowflake`).
+- **Overlapping translucent fills blend into one muddy colour.** Keep the fill
+  under `alpha=0.15`, stroke each curve, *and* offset the peaks. Tuning alpha
+  alone will not save you.
+- **Fonts:** Arial/Helvetica are often absent on Linux. `RC` falls back to
+  Liberation Sans (metric-compatible with Arial) and sets `pdf.fonttype=42`
+  so text stays editable in the PDF — a hard requirement at most journals.
+- **Don't move elements toward whitespace.** Whitespace relocates, it does not
+  disappear. Decide which row an element belongs to, move it as a group, then
+  verify with the quadrant ink distribution.
+
+## Honest scope
+
+This gets you clean flat schematics combined with data panels — the register
+of a Nature/Science overview figure or a TPAMI architecture diagram. It will
+**not** reproduce hand-drawn illustration (shaded organs, textured cells,
+gradients). For that, embed a CC-BY asset and cite it rather than fake it.
+
+## License
+
+MIT © Guo Cheng
+
+## 关于那行 star 提示
+
+调用 `report()` 时，`sciglyph` 会在**第 5 次和第 25 次**往 stderr 写一行，提一句这个仓库在哪。**一辈子只有这两次**，此外再不出声。
+
+它不会出现在：管道或重定向里（stderr 不是终端就直接返回，连计数文件都不建）、CI 环境里（`CI` / `GITHUB_ACTIONS`）。它写的是 stderr 而非 stdout，所以不会污染你的数据输出；它包在 `try/finally` 里且吞掉自身所有异常，**不会改变退出码，也不会影响结果**。
+
+永久关掉：
+
+```bash
+export SCIGLYPH_NO_NUDGE=1
+```
+
+计数存在 `$XDG_STATE_HOME/sciglyph/usage.json`（默认 `~/.local/state/sciglyph/usage.json`），删掉即重置。

sciglyph-0.1.0/README.md

@@ -0,0 +1,166 @@
+# sciglyph
+
+[![test](https://github.com/GuoCheng24/sciglyph/actions/workflows/test.yml/badge.svg)](https://github.com/GuoCheng24/sciglyph/actions/workflows/test.yml) [![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**Publication-quality scientific illustration in pure matplotlib — no BioRender, no Illustrator.**
+
+Overview figures and architecture diagrams are usually drawn by hand in a
+subscription tool. That makes them pretty, but also unreproducible: you cannot
+diff them, you cannot regenerate them when the numbers change, and you cannot
+put them under version control.
+
+`sciglyph` gives you the primitives to draw the same figures as **code**.
+
+<p align="center">
+  <img src="gallery/overview_figure.png" width="88%">
+</p>
+
+<p align="center">
+  <img src="gallery/architecture.png" width="100%">
+</p>
+
+<sub>Both figures above are generated by the scripts in
+<a href="examples/">examples/</a> — nothing was touched by hand. The content is
+synthetic; swap in your own numbers and the layout carries over.</sub>
+
+---
+
+## Why
+
+| | subscription tools | `sciglyph` |
+|---|---|---|
+| Reproducible | ✗ manual pixel-pushing | ✓ a script |
+| Version control | ✗ binary blobs | ✓ diffable source |
+| Data-driven | ✗ retype every number | ✓ read straight from your results |
+| Vector output | ~ depends on export | ✓ PDF/SVG with editable text |
+| Cost | subscription | free, MIT |
+
+## Install
+
+```bash
+pip install git+https://github.com/GuoCheng24/sciglyph
+```
+
+Only `matplotlib` and `numpy`. Nothing else.
+
+<sub>Not on PyPI yet, so the git URL above is the install line that works today.
+When it lands, `pip install sciglyph` will too.</sub>
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+from sciglyph import bio, set_canvas, report, RC
+
+plt.rcParams.update(RC)
+fig = plt.figure(figsize=(7.2, 3.0), dpi=300)
+ax = fig.add_axes([0, 0, 1, 1]); ax.set_xlim(0, 1); ax.set_ylim(0, 1); ax.axis("off")
+set_canvas(fig)                      # required on non-square canvases
+
+bio.person(ax, .08, .55, s=.30)
+bio.dna(ax, .25, .55, w=.05, h=.45, n=2)
+bio.cell(ax, .42, .55, r=.06, seed=1)
+bio.seq_logo(ax, .60, .40, [("A", .6), ("C", .9), ("G", .4), ("T", .7)], w=.03)
+
+report(fig, ax)                      # catch text collisions before saving
+fig.savefig("figure.pdf", bbox_inches="tight")
+```
+
+Run the full examples:
+
+```bash
+python examples/overview_figure.py    # -> gallery/overview_figure.png
+python examples/architecture.py       # -> gallery/architecture.png
+```
+
+## What's included
+
+**`sciglyph.bio`** — glyphs for Nature/Science-style overview figures:
+`person` (cohorts) · `dna` · `cell` · `lipid` · `metabolite` ·
+`nucleosome_chain` · `umap_layer` (the stacked atlas look) ·
+`seq_logo` (information-scaled letters, no logomaker needed) ·
+`stacked_planes` · `rbox` · `arr`
+
+**`sciglyph.arch`** — glyphs for architecture diagrams:
+`cuboid` / `feature_stack` (3-D feature blocks) · `trapezoid` (encoders) ·
+`module_stack` (`Conv|BN|ReLU` bars) · `dashed_group` (the `(a)/(b)/(c)`
+language) · `flow` · `op_circle` · `snowflake` (frozen backbone) ·
+`image_thumb` · `embedding_space` (contrastive panels) · `loss_tag` · `bracket`
+
+**`sciglyph.layout`** — pre-flight collision detection.
+
+## Catching layout bugs before you save
+
+When a figure breaks, it is almost never the artwork — it is the layout.
+`report()` uses the real rendered bounding boxes to find overlapping text, so
+you do not have to hunt for it by eye:
+
+```python
+report(fig, ax)
+# [sciglyph.layout] 36 text objects
+#   ! 'CD4 Treg/-FOXP3' x 'SMR' overlap 92%
+```
+
+It also works from the command line on any script that exposes `fig` and `ax`:
+
+```bash
+python -m sciglyph.layout my_figure.py
+```
+
+It checks three things, each of which shipped a broken figure before it existed:
+
+| check | what it catches |
+|---|---|
+| text overlap | two labels drawn over each other |
+| **artwork overlap** | a row of boxes laid out slightly too wide, so each one covers its neighbour — the strings may not overlap at all, so text-level checks miss it entirely |
+| **missing glyphs** | a character the font cannot draw, rendered as an empty box. Symbols typed as literals (`✓`, `❄`) are the usual casualty |
+
+Two kinds of overlap are deliberately *not* reported, because they are the
+layout working: a panel containing its contents, and an unfilled dashed shape —
+a ring drawn around the thing it annotates.
+
+**These are geometric checks.** Whether the figure actually *reads* well still
+needs your eyes.
+
+## Notes from actually shipping these figures
+
+- **Call `set_canvas(fig)`.** In `[0,1]` coordinates a "circle" is `r·W` wide
+  and `r·H` tall. On a 12×3 canvas, every circle becomes a rugby ball.
+- **Anchor arrows to what `feature_stack` returns**, not to hard-coded
+  coordinates — otherwise changing the number of blocks silently breaks them.
+- **Never put symbol codepoints in figure text.** `❄` (U+2744) is missing from
+  most sans fonts and renders as a tofu box. Draw it (`arch.snowflake`).
+- **Overlapping translucent fills blend into one muddy colour.** Keep the fill
+  under `alpha=0.15`, stroke each curve, *and* offset the peaks. Tuning alpha
+  alone will not save you.
+- **Fonts:** Arial/Helvetica are often absent on Linux. `RC` falls back to
+  Liberation Sans (metric-compatible with Arial) and sets `pdf.fonttype=42`
+  so text stays editable in the PDF — a hard requirement at most journals.
+- **Don't move elements toward whitespace.** Whitespace relocates, it does not
+  disappear. Decide which row an element belongs to, move it as a group, then
+  verify with the quadrant ink distribution.
+
+## Honest scope
+
+This gets you clean flat schematics combined with data panels — the register
+of a Nature/Science overview figure or a TPAMI architecture diagram. It will
+**not** reproduce hand-drawn illustration (shaded organs, textured cells,
+gradients). For that, embed a CC-BY asset and cite it rather than fake it.
+
+## License
+
+MIT © Guo Cheng
+
+## 关于那行 star 提示
+
+调用 `report()` 时，`sciglyph` 会在**第 5 次和第 25 次**往 stderr 写一行，提一句这个仓库在哪。**一辈子只有这两次**，此外再不出声。
+
+它不会出现在：管道或重定向里（stderr 不是终端就直接返回，连计数文件都不建）、CI 环境里（`CI` / `GITHUB_ACTIONS`）。它写的是 stderr 而非 stdout，所以不会污染你的数据输出；它包在 `try/finally` 里且吞掉自身所有异常，**不会改变退出码，也不会影响结果**。
+
+永久关掉：
+
+```bash
+export SCIGLYPH_NO_NUDGE=1
+```
+
+计数存在 `$XDG_STATE_HOME/sciglyph/usage.json`（默认 `~/.local/state/sciglyph/usage.json`），删掉即重置。

sciglyph-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sciglyph"
+version = "0.1.0"
+description = "Publication-quality scientific illustration in pure matplotlib - no BioRender, no Illustrator"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Guo Cheng" }]
+keywords = ["matplotlib", "scientific-figures", "publication", "illustration",
+            "graphical-abstract", "bioinformatics", "deep-learning", "diagram"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = ["matplotlib>=3.5", "numpy>=1.20"]
+
+[project.urls]
+Homepage = "https://github.com/GuoCheng24/sciglyph"
+Issues = "https://github.com/GuoCheng24/sciglyph/issues"
+
+[tool.setuptools.packages.find]
+include = ["sciglyph*"]

sciglyph-0.1.0/sciglyph/__init__.py

@@ -0,0 +1,35 @@
+"""sciglyph - publication-quality scientific illustration in pure matplotlib.
+
+Two glyph families plus a layout checker:
+
+* :mod:`sciglyph.bio`    biological / omics glyphs for Nature-style overview figures
+* :mod:`sciglyph.arch`   neural-network architecture glyphs (TPAMI / CVPR style)
+* :mod:`sciglyph.layout` pre-flight text-collision detection
+
+Quick start::
+
+    import matplotlib.pyplot as plt
+    from sciglyph import bio, set_canvas, RC, report
+
+    plt.rcParams.update(RC)
+    fig = plt.figure(figsize=(7.2, 4.0), dpi=300)
+    ax = fig.add_axes([0, 0, 1, 1]); ax.set_xlim(0, 1); ax.set_ylim(0, 1); ax.axis("off")
+    set_canvas(fig)                      # required on non-square canvases
+
+    bio.dna(ax, .2, .5, w=.05, h=.4, n=2)
+    bio.cell(ax, .4, .5, r=.05, seed=1)
+
+    report(fig, ax)                      # check for text collisions
+    fig.savefig("figure.pdf", bbox_inches="tight")
+"""
+
+from ._canvas import set_canvas, aspect
+from .layout import text_collisions, report
+from . import bio
+from . import arch
+
+RC = bio.RC
+
+__version__ = "0.1.0"
+__all__ = ["bio", "arch", "layout", "set_canvas", "aspect",
+           "text_collisions", "report", "RC", "__version__"]

sciglyph-0.1.0/sciglyph/_canvas.py

@@ -0,0 +1,37 @@
+"""Shared canvas state: aspect-ratio compensation for round primitives.
+
+In a [0,1] x [0,1] coordinate system a "circle" of radius r is physically
+r*W wide and r*H tall, where W and H are the figure size in inches. On any
+non-square canvas circles therefore render as ellipses -- measured on a 6x2
+canvas, human heads and cells came out badly flattened.
+
+Every round primitive in sciglyph divides its horizontal extent by this ratio,
+so you get visually round shapes on any canvas. Call `set_canvas(fig)` once,
+right after creating the figure.
+"""
+
+from matplotlib.patches import Ellipse
+
+__all__ = ["set_canvas", "aspect", "circle"]
+
+_STATE = {"ar": 1.0}
+
+
+def set_canvas(fig):
+    """Register the figure aspect ratio. **Required on any non-square canvas.**
+
+    Returns the ratio (width / height), mostly so you can assert on it.
+    """
+    w, h = fig.get_size_inches()
+    _STATE["ar"] = float(w) / float(h)
+    return _STATE["ar"]
+
+
+def aspect():
+    """Current width/height ratio (1.0 until `set_canvas` is called)."""
+    return _STATE["ar"]
+
+
+def circle(ax, xy, r, **kw):
+    """A visually round circle, corrected for the canvas aspect ratio."""
+    return ax.add_patch(Ellipse(xy, width=2 * r / _STATE["ar"], height=2 * r, **kw))

sciglyph-0.1.0/sciglyph/_nudge.py

@@ -0,0 +1,58 @@
+"""Mention the repo once or twice, to people who are actually using this.
+
+Deliberately quiet: never on the first run, never when stderr is not a
+terminal (so piped and redirected output stays clean), never in CI, and
+never more than twice in the lifetime of an install. `SCIGLYPH_NO_NUDGE=1`
+turns it off for good.
+"""
+import os
+import sys
+import json
+from pathlib import Path
+
+REPO = "GuoCheng24/sciglyph"
+_SHOW_AT = (5, 25)          # run counts at which we say something
+_ENV_OFF = "SCIGLYPH_NO_NUDGE"
+
+
+def _state_path():
+    base = os.environ.get("XDG_STATE_HOME") or (Path.home() / ".local" / "state")
+    return Path(base) / "sciglyph" / "usage.json"
+
+
+def _quiet():
+    if os.environ.get(_ENV_OFF):
+        return True
+    if os.environ.get("CI") or os.environ.get("GITHUB_ACTIONS"):
+        return True
+    # Not a terminal means someone is piping or redirecting us; stay out of it.
+    return not (hasattr(sys.stderr, "isatty") and sys.stderr.isatty())
+
+
+def record_run():
+    """Count this run and, at two points, print a single line to stderr.
+
+    Any failure here is swallowed: a nudge must never break the tool or
+    change its exit status.
+    """
+    if _quiet():
+        return
+    try:
+        p = _state_path()
+        try:
+            data = json.loads(p.read_text())
+        except Exception:
+            data = {}
+        n = int(data.get("runs", 0)) + 1
+        data["runs"] = n
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(data))
+        if n in _SHOW_AT:
+            print(
+                "\n── sciglyph has been useful " + str(n) + " times. If it saved you time,\n"
+                "   a star helps other people find it: https://github.com/" + REPO + "\n"
+                "   (silence this with SCIGLYPH_NO_NUDGE=1)",
+                file=sys.stderr,
+            )
+    except Exception:
+        pass