rgrid-python 4.5.3__tar.gz

rgrid_python-4.5.3/.gitattributes

@@ -0,0 +1,15 @@
+# GitHub language statistics: only count Python
+*.py linguist-detectable
+*.ipynb linguist-documentation
+*.html linguist-documentation
+*.css linguist-documentation
+*.js linguist-documentation
+*.json linguist-documentation
+*.yml linguist-documentation
+*.yaml linguist-documentation
+*.md linguist-documentation
+*.R linguist-documentation
+*.csv linguist-documentation
+site/** linguist-documentation
+docs/** linguist-documentation
+tutorials/** linguist-documentation

rgrid_python-4.5.3/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+.tox/
+
+# Compiled extensions
+*.so
+*.pyd
+*.dylib
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+.coverage
+
+# Docs build
+site/
+.cache/
+.ipynb_checkpoints/

rgrid_python-4.5.3/LICENSE

@@ -0,0 +1,3 @@
+# Artistic-2.0
+
+See DESCRIPTION from R package.

rgrid_python-4.5.3/PKG-INFO

@@ -0,0 +1,489 @@
+Metadata-Version: 2.4
+Name: rgrid-python
+Version: 4.5.3
+Summary: Python port of the R grid package (tracks R grid 4.5.3)
+Project-URL: Homepage, https://github.com/Bio-Babel/grid_py
+Project-URL: Repository, https://github.com/Bio-Babel/grid_py
+Project-URL: Issues, https://github.com/Bio-Babel/grid_py/issues
+Project-URL: Documentation, https://github.com/Bio-Babel/grid_py#readme
+Author-email: Jeffery Liu <jeffliu.lucky@gmail.com>
+License-Expression: Artistic-2.0
+License-File: LICENSE
+Keywords: R-port,ggplot2,graphics,grid,scientific-visualization,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Artistic License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pycairo>=1.20
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-jupyter; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# grid_py
+
+Python port of the R **grid** package.
+
+## Installation
+
+```bash
+pip install rgrid-python
+```
+
+The importable package name is `grid_py`:
+
+```python
+import grid_py
+```
+
+### System requirements
+
+`grid_py` depends on [`pycairo`](https://pypi.org/project/pycairo/), which
+builds against the system **cairo** library. Install the system package
+*before* `pip install rgrid-python`:
+
+| Platform | Command |
+|---|---|
+| Ubuntu / Debian | `sudo apt install libcairo2-dev pkg-config python3-dev` |
+| Fedora / RHEL | `sudo dnf install cairo-devel pkgconf-pkg-config python3-devel` |
+| macOS (Homebrew) | `brew install cairo pkg-config` |
+| Windows | `conda install -c conda-forge pycairo` *(recommended; the MSVC build is fiddly)* |
+
+`conda install -c conda-forge pycairo` is also the easiest route on Linux /
+macOS if you prefer not to touch system packages.
+
+### Development install
+
+```bash
+git clone https://github.com/Bio-Babel/grid_py
+cd grid_py
+pip install -e ".[dev]"
+pytest                       # 2600+ tests
+```
+
+## Quick Start
+
+```python
+from grid_py import (
+    CairoRenderer, Gpar, Unit, Viewport, GridLayout,
+    get_state, grid_draw, grid_newpage,
+    push_viewport, pop_viewport,
+    rect_grob, text_grob, points_grob, circle_grob,
+    unit_c, string_width,
+)
+```
+
+## The Unit System — Why Layout "Just Works"
+
+The central idea of grid is that **sizes are expressions, not numbers**.
+A `Unit` carries both a value and a *strategy* for resolving that value.
+Resolution is deferred until a viewport is pushed — at that point the parent
+dimensions, font metrics, and device DPI are all known, so every unit can
+evaluate itself in context.
+
+This means the same layout specification produces correct results on a 72 dpi
+screen, a 300 dpi PDF, a 7-inch plot or a 14-inch poster — with no manual
+tweaking.
+
+### Unit types at a glance
+
+| Category | Units | Resolved from |
+|----------|-------|---------------|
+| **Absolute** | `"cm"`, `"inches"`, `"mm"`, `"points"` | Fixed physical conversion |
+| **Relative** | `"npc"` (0-1 fraction of parent) | Parent viewport dimensions |
+| **Font-relative** | `"lines"` (line height), `"char"` (char width) | Current `fontsize` × `lineheight` |
+| **Content-measuring** | `"strwidth"`, `"strheight"` | Cairo text measurement |
+| **Grob-measuring** | `"grobwidth"`, `"grobheight"` | Grob bounding box query |
+| **Flex** | `"null"` | Remaining space (layout only) |
+| **Data** | `"native"` | Viewport `xscale` / `yscale` mapping |
+
+### Mixing units with arithmetic
+
+Units of different types can be freely combined.  The result is a **compound
+unit** that is evaluated recursively at resolve time:
+
+```python
+# "fill the parent, but leave 2 line-heights of margin on each side"
+width = Unit(1, "npc") - Unit(4, "lines")
+
+# "start 1 cm from the right edge"
+x = Unit(1, "npc") - Unit(1, "cm")
+
+# also supports min / max across types
+from grid_py import unit_pmin
+safe_width = unit_pmin(Unit(10, "cm"), Unit(1, "npc"))  # whichever is smaller
+```
+
+Internally `Unit(1,"npc") - Unit(4,"lines")` is stored as a tree:
+
+```
+sum ──┬── 1.0 npc
+      └── -4.0 lines
+```
+
+When the viewport is pushed, each leaf is resolved to inches and summed.
+Changing the font or the device size automatically changes the result.
+
+## Layout Patterns
+
+### Pattern 1 — Adaptive margins with `"lines"`
+
+The most common pattern: margins that scale with the font.
+
+```python
+r = CairoRenderer(width=7, height=5, dpi=150)
+get_state().init_device(r)
+grid_newpage()
+
+# Title: 2 line-heights tall, pinned to the top
+title_vp = Viewport(
+    name="title",
+    x=Unit(0.5, "npc"),
+    y=Unit(1, "npc") - Unit(1, "lines"),
+    width=Unit(1, "npc"),
+    height=Unit(2, "lines"),
+)
+
+# Plot area: fills the rest, with room for axis labels
+plot_vp = Viewport(
+    name="plot",
+    x=Unit(0.5, "npc") + Unit(1, "lines"),
+    y=Unit(0.5, "npc") - Unit(0.5, "lines"),
+    width=Unit(1, "npc") - Unit(4, "lines"),
+    height=Unit(1, "npc") - Unit(5, "lines"),
+)
+```
+
+If you later change `Gpar(fontsize=14)` to `fontsize=20`, the margins grow
+proportionally — no constants to update.
+
+### Pattern 2 — Content-driven margins with `string_width`
+
+Let the label measure itself:
+
+```python
+label = "Sepal Length (cm)"
+margin = string_width(label)          # Unit whose value = rendered width of that string
+
+plot_vp = Viewport(
+    x=margin + Unit(0.5, "cm"),       # left edge = label width + gap
+    width=Unit(1, "npc") - margin - Unit(1, "cm"),
+    y=Unit(0.5, "npc"),
+    height=Unit(1, "npc") - Unit(3, "lines"),
+)
+```
+
+Change the label text → the margin updates automatically.
+
+### Pattern 3 — Flexible grid with `"null"` units
+
+`"null"` units divide **remaining space** proportionally, after all absolute
+and relative units have been allocated.  This is how `GridLayout` works:
+
+```python
+# Column 1: fixed 3 cm (e.g. y-axis labels)
+# Columns 2-3: split remaining space 2:1
+layout = GridLayout(
+    nrow=1, ncol=3,
+    widths=unit_c(Unit(3, "cm"), Unit(2, "null"), Unit(1, "null")),
+    heights=Unit([1], "null"),
+)
+
+main_vp = Viewport(name="main", layout=layout,
+                   x=Unit(0.5, "npc"), y=Unit(0.5, "npc"),
+                   width=Unit(1, "npc"), height=Unit(1, "npc"))
+push_viewport(main_vp)
+
+# Place children into cells
+for col in [1, 2, 3]:
+    cell_vp = Viewport(name=f"cell_{col}",
+                       layout_pos_row=1, layout_pos_col=col)
+    push_viewport(cell_vp)
+    grid_draw(rect_grob(x=0.5, y=0.5, width=1, height=1,
+                        gp=Gpar(fill="grey90", col="grey50")))
+    pop_viewport(1)
+```
+
+Resize the device → column 1 stays 3 cm, the rest reflows.
+
+### Pattern 4 — Nested viewports for complex figures
+
+Viewports nest.  Each child resolves its units against its parent, so you
+can build deeply structured layouts compositionally:
+
+```python
+# Outer: 2-row layout (title + body)
+outer = GridLayout(nrow=2, ncol=1,
+                   heights=unit_c(Unit(2, "lines"), Unit(1, "null")))
+
+# Body: 1×3 panel grid
+inner = GridLayout(nrow=1, ncol=3,
+                   widths=Unit([1, 1, 1], "null"))
+
+push_viewport(Viewport(name="page", layout=outer, ...))
+
+# Row 1 — title
+push_viewport(Viewport(layout_pos_row=1, layout_pos_col=1))
+grid_draw(text_grob("My Title", x=0.5, y=0.5, gp=Gpar(fontsize=16, fontface="bold")))
+pop_viewport(1)
+
+# Row 2 — panels
+push_viewport(Viewport(layout_pos_row=2, layout_pos_col=1, layout=inner))
+for col in [1, 2, 3]:
+    push_viewport(Viewport(layout_pos_row=1, layout_pos_col=col))
+    # ... draw panel content using npc coordinates (0-1 within this cell)
+    pop_viewport(1)
+pop_viewport(1)
+
+pop_viewport(1)
+```
+
+### The three-layer coordinate pipeline
+
+Every coordinate in grid passes through three distinct transformations before
+reaching the device.  Understanding these layers is the key to reasoning about
+why layouts are portable and how viewports compose.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 1:  Unit  →  Viewport-local inches                   │
+│                                                             │
+│  _transform_to_inches()  (_vp_calc.py)                      │
+│                                                             │
+│  Each unit type has its own rule:                           │
+│    "npc"       →  value × parent_width_inches               │
+│    "cm"        →  value / 2.54                              │
+│    "lines"     →  value × fontsize × cex × lineheight / 72 │
+│    "native"    →  map [scalemin, scalemax] → [0, parent]    │
+│    "strwidth"  →  Cairo text_extents(string).width          │
+│    "grobwidth" →  grob.width_details() recursive query      │
+│    "sum"       →  Σ recursive resolve of child units        │
+│    "null"      →  0  (only meaningful inside GridLayout)    │
+│                                                             │
+│  Result: a position or dimension in inches, local to the    │
+│  current viewport's own coordinate system.                  │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 2:  Viewport-local inches  →  Absolute inches        │
+│                                                             │
+│  transform_loc_to_device()  (_renderer_base.py)             │
+│                                                             │
+│  Applies the viewport's accumulated 3×3 affine transform:   │
+│    T = Justification × Rotation × Translation × Parent_T   │
+│                                                             │
+│  Built at push_viewport() time by calc_viewport_transform() │
+│  Each push multiplies into the parent's matrix, so nested   │
+│  viewports compose naturally:                               │
+│                                                             │
+│    abs_loc = [x_inches, y_inches, 1] @ vp_transform_3x3    │
+│                                                             │
+│  Result: inches from device origin (bottom-left).           │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 3:  Absolute inches  →  Device pixels                │
+│                                                             │
+│  inches_to_dev_x/y()  (_renderer_base.py)                   │
+│                                                             │
+│    dev_x = abs_inches_x × DPI                              │
+│    dev_y = device_height - abs_inches_y × DPI   (Y-flip)   │
+│                                                             │
+│  Grid uses bottom-left origin; devices use top-left.        │
+│  This layer bridges the two.                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+A concrete example — drawing a point at `x = Unit(1,"npc") - Unit(2,"lines")`
+inside a child viewport:
+
+```
+User writes:   Unit(1, "npc") - Unit(2, "lines") + Unit(0.5, "cm")
+                         │
+                         ▼  arithmetic builds a compound tree
+Stored as:     sum ──┬── 1.0  npc
+                     ├── -2.0 lines
+                     └── 0.5  cm
+
+  ── Layer 1 ─────────────────────────────────────────
+                         │
+                         ▼  _transform_to_inches(parent_context)
+Resolve:       npc    → 1.0 × parent_width_inches       = 5.000"
+               lines  → -2 × fontsize × lineheight / 72 = -0.333"
+               cm     → 0.5 / 2.54                      = 0.197"
+               sum    → 5.000 - 0.333 + 0.197           = 4.864"  (viewport-local)
+
+  ── Layer 2 ─────────────────────────────────────────
+                         │
+                         ▼  [4.864, y, 1] @ viewport_transform_3x3
+Absolute:      account for viewport position, rotation  = 5.214"  (from device origin)
+
+  ── Layer 3 ─────────────────────────────────────────
+                         │
+                         ▼  × DPI, Y-flip
+Device:        5.214 × 150 = 782 px
+```
+
+**Why this matters for users:**
+
+- **Layer 1** is where your Unit expressions are evaluated.  Because each unit
+  type knows how to measure itself (text metrics, parent size, font size),
+  your layout adapts to context automatically.
+- **Layer 2** is where viewport nesting works.  You never compute global
+  positions — you work in local coordinates and the transform stack composes
+  them.
+- **Layer 3** is invisible to you.  It just makes sure the same inches
+  produce correct pixels on any device.
+
+The net effect: you describe layout in meaningful terms (`"lines"`, `"cm"`,
+`"npc"`, `"strwidth"`), nest viewports freely, and the three-layer pipeline
+ensures the result is correct on every device and at every DPI.
+
+## Backend Architecture
+
+grid\_py ships with a pluggable rendering backend system built on a single
+abstract base class (`GridRenderer`). User code is identical across backends —
+swap the renderer instance to switch output formats.
+
+```
+                      GridRenderer (ABC)
+                 ┌──────────────────────────┐
+                 │  viewport transform stack │
+                 │  unit resolution          │
+                 │  coordinate system mgmt   │
+                 │  29 abstract methods      │
+                 └────────────┬─────────────┘
+                        ┌─────┴──────┐
+                        │            │
+                CairoRenderer   WebRenderer
+                (immediate)     (scene graph)
+                ┌──────────┐   ┌──────────────┐
+                │ PNG/PDF/ │   │ JSON Scene → │
+                │ SVG/PS   │   │ HTML + D3.js │
+                └──────────┘   └──────────────┘
+```
+
+### Renderers
+
+| Backend | Module | Output Formats | Rendering Mode |
+|---------|--------|----------------|----------------|
+| **CairoRenderer** | `renderer.py` | PNG, PDF, SVG, PS | Immediate — draws directly to a pycairo surface |
+| **WebRenderer** | `renderer_web.py` | Standalone HTML (SVG + Canvas + D3.js) | Deferred — builds a JSON scene graph, rendered browser-side |
+
+### Supporting Components
+
+| Component | Module | Role |
+|-----------|--------|------|
+| GridRenderer (ABC) | `_renderer_base.py` | Abstract base class defining the renderer interface (29 abstract methods) |
+| Scene Graph | `_scene_graph.py` | `SceneNode` / `ViewportNode` / `GrobNode` tree used by WebRenderer |
+| Font Metrics | `_font_metrics.py` | Pluggable text measurement (Cairo, fonttools, or heuristic backends) |
+| GridState | `_state.py` | Global singleton that binds the active renderer to the drawing API |
+
+### Backend Selection
+
+There is no registry or factory — instantiate the renderer you need and bind it:
+
+```python
+from grid_py import WebRenderer, get_state, grid_draw
+
+r = WebRenderer(width=7, height=5, dpi=100)
+state = get_state()
+state.init_device(r)
+
+grid_draw(my_grob)          # draws into the scene graph
+html = r.to_html()          # export interactive HTML
+```
+
+`grid_newpage()` creates a `CairoRenderer` by default when no renderer is bound.
+
+## Interactive Web Visualization
+
+`WebRenderer` turns any grid plot into an interactive HTML document.  The same
+layout code that produces a static PNG via `CairoRenderer` can produce a
+zoomable, pannable, tooltip-enabled web page — with zero API changes.
+
+### How it works
+
+```
+Python (grid_py)                          Browser (gridpy.js)
+┌──────────────┐                         ┌──────────────────────┐
+│ grid_draw()  │──→ Scene Graph JSON ──→ │ SVG layer (text,     │
+│ viewports,   │    {root, defs, dpi}    │   shapes, clip/mask) │
+│ grobs, gpar  │                         │ Canvas layer (>2000  │
+│              │                         │   points batch)      │
+│ .metadata    │──→ node.data[] ───────→ │ Quadtree spatial     │
+│ (per-point)  │                         │   index → tooltips   │
+└──────────────┘                         └──────────────────────┘
+```
+
+1. Python builds a JSON scene graph during `grid_draw()` calls
+2. `gridpy.js` renders SVG for shapes/text, Canvas for large point clouds
+3. All data-carrying points register in a spatial index (quadtree)
+4. Hover triggers a proximity query — no DOM hit-testing needed
+
+### Tooltip data
+
+Attach a `metadata` dict to any grob before drawing.  Keys become tooltip
+labels; list values are indexed per point:
+
+```python
+grob = points_grob(x=x_data, y=y_data, pch=19,
+                   gp=Gpar(col=colors, fill=colors))
+grob.metadata = {
+    "species": species_list,          # per-point label
+    "value":   [f"{v:.1f}" for v in values],
+}
+grid_draw(grob)                       # metadata flows into the scene graph
+```
+
+### Output modes
+
+```python
+r = WebRenderer(width=7, height=5, dpi=100)
+get_state().init_device(r)
+# ... draw with grid_draw() ...
+
+# Jupyter notebook — inline display with D3 inlined (no CDN dependency)
+display(r)                            # uses _repr_html_() → <iframe srcdoc>
+
+# Standalone HTML — lightweight, loads D3 from CDN
+r.save("plot.html")                   # open in any browser
+
+# Raw scene graph — for custom frontends (Vue, React, etc.)
+json_str = r.to_scene_json()          # framework calls gridpy.render(el, json)
+```
+
+### Rendering layers
+
+The browser runtime uses a layered architecture for performance:
+
+| Layer | z-index | Content | When used |
+|-------|---------|---------|-----------|
+| Canvas | 1 | Batch-drawn points | Point count > 2000 |
+| SVG | 2 | Text, shapes, small point sets | Default for most grobs |
+| Overlay | 3 | D3 zoom/brush handlers | When `interactive: true` |
+
+Routing is automatic (`render_hint="auto"`), or you can force a layer per grob
+with `render_hint="svg"` or `render_hint="canvas"`.
+
+## Documentation
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```