genoplot 0.1.0a1__tar.gz

genoplot-0.1.0a1/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

genoplot-0.1.0a1/.gitignore

@@ -0,0 +1,11 @@
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+
+# demo outputs
+demo_output/
+examples_output/
+
+# build artifacts
+dist/
+*.egg-info/

genoplot-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luan Leal
+
+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.

genoplot-0.1.0a1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: genoplot
+Version: 0.1.0a1
+Summary: Modular genome neighborhood plots with colormaps
+Author-email: Luan Leal <luanleal@usp.br>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.0
+Description-Content-Type: text/markdown
+
+# genoplot
+
+Modular genome neighborhood plots with colormaps.
+
+`genoplot` plots the genes around an anchor gene on each plasmid: a backbone
+line with direction-aware gene arrows, colored by a numeric association value
+(e.g. NPMI). It replaces the original monolithic `plot_npmi_neighborhood`
+function with pure coordinate math separated from matplotlib rendering.
+
+- **Polars in, figure out** — pass a `pl.DataFrame` of coordinates, get a
+  `matplotlib` figure.
+- **Circular genomes handled for free** — windows may cross the plasmid
+  boundary; genes spanning the replication origin stay contiguous.
+
+## Quick start
+
+```python
+import genoplot
+
+coords = genoplot.make_mock_coords()
+fig, axes = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1", "plasmid_4"],
+    neighbor_range=10_000,
+)
+fig.savefig("neighborhoods.png", dpi=200)
+```
+
+## Installation
+
+The project uses [pixi](https://pixi.sh):
+
+```bash
+pixi install
+pixi run test   # run tests
+pixi run lint   # ruff check src tests scripts
+pixi run demo   # regenerate demo_output/*.png
+```
+
+For a plain pip install: `pip install -e .` (requires python >=3.11, needs
+`polars`, `matplotlib`, `numpy`).
+
+## Coordinate table schema
+
+One row per gene. Required columns: `plasmid`, `gene_id`, `start`, `end`,
+`strand` (the entry `start`/`end` may be any integer range; `strand` is
+`1` or `-1`). Optional but useful: label columns (`accession`,
+`short_name`) and a numeric value column such as `NPMI_h1`.
+
+```python
+import polars as pl
+import genoplot
+
+df = pl.DataFrame({
+    "plasmid": ["p1"] * 3,
+    "gene_id": ["g1", "g2", "g3"],
+    "accession": ["WP_00000001.1", "WP_00000002.1", None],
+    "short_name": ["RepB", None, "parA"],
+    "start": [0, 3400, 5100],
+    "end": [1200, 3900, 5800],
+    "strand": [1, -1, 1],
+    "NPMI_h1": [0.91, None, -0.2],
+})
+genoplot.plot_neighborhoods(df, ["p1"])
+```
+
+## API
+
+### High level
+
+- `genoplot.plot_neighborhoods(coords, plasmids, *, neighbor_range=10_000,
+  value_col="NPMI_h1", color="managua", vmin=-1.0, vmax=1.0, ...)` —
+  one track per plasmid. Returns `(fig, axes)`; a shared colorbar is
+  attached on the right. Plasmids without an anchor gene get a placeholder
+  row. `value_col` selects the numeric column used for anchor ranking,
+  gene coloring, the colorbar, and the title. `predicate=...` (a
+  DataFrame->DataFrame filter) narrows the anchor candidates before
+  ranking and takes precedence over `label_contains` — e.g. pass
+  `predicate=lambda df: df.filter(pl.col("NPMI_h1") > 0.7)` for a minimum
+  anchor threshold.
+
+### Lower level
+
+- `genoplot.schema.validate_coords(df)` — check required columns, cast
+  `start`/`end` to `Int64`; `check_value_column(df, col)`.
+- `genoplot.window.Window`, `make_window`, `resolve_window` — pure
+  coordinate math mapping genes into a linear frame where the visible
+  window is `[0, width]`. Genes are sorted by `_plot_start`; origin-spanning
+  genes stay contiguous.
+- `genoplot.anchors.select_anchor(genes, value_col,
+  label_contains="Rep")` — pick the highest-value candidate (default: a
+  `short_name` containing `"Rep"`). Pass `predicate=...` for a custom
+  filter, or `label_contains=None` to disable the label rule.
+- `genoplot.colors.build_cmap / build_norm / value_to_color / add_colorbar`
+  — colormap machinery; missing values render as `lightgray`.
+- `genoplot.render.draw_backbone / draw_gene_arrow / draw_gene_label /
+  draw_track` — drawing primitives onto a caller-provided `Axes`.
+
+### Mock data
+
+- `genoplot.make_mock_coords(n_plasmids=4, seed=2026, value_col="NPMI_h1")`
+  — deterministic synthetic table for demos/tests. The first plasmid's
+  anchor sits near the origin and the last near the genome end to exercise
+  boundary-crossing windows.
+
+## Render a demo
+
+```bash
+pixi run demo
+```
+
+writes PNGs into `demo_output/` (gitignored).
+
+## Layout
+
+```
+src/genoplot/
+  schema.py    column conventions + validation
+  window.py    circular-window coordinate math
+  anchors.py   anchor gene selection
+  colors.py    colormap / norm helpers
+  render.py    drawing primitives (backbone, arrows, labels)
+  figure.py    high-level plot_neighborhoods API
+  mock.py      seeded synthetic data generator
+tests/         pytest suite (window, anchors, colors, figure)
+scripts/
+  demo.py      demo PNG renderer
+```

genoplot-0.1.0a1/PROGRESS.md

@@ -0,0 +1,90 @@
+# genoplot — progress notes
+
+State as of 2026-08-27: **complete**. All tasks green.
+
+## What this is
+
+Library `genoplot` (src layout, pixi + hatchling) replacing the original
+monolithic `plot_npmi_neighborhood` function. Modular: pure coordinate
+math separated from matplotlib rendering; Polars in, figure out.
+
+## Done
+
+- [x] `pyproject.toml` — genoplot 0.1.0, deps (polars, matplotlib, numpy),
+      pixi workspace (conda-forge/linux-64), pypi deps (pytest, ruff),
+      tasks: `demo`, `lint`, `test`. Editable install of the package.
+- [x] `src/genoplot/schema.py` — column constants, `validate_coords`,
+      `check_value_column`, `SchemaError`.
+- [x] `src/genoplot/window.py` — `Window` dataclass (xmin/xmax/width,
+      anchor ± flank), `make_window`, `resolve_window`.
+- [x] `src/genoplot/anchors.py` — `select_anchor` (max value among
+      candidates; `label_contains="Rep"` default, or custom predicate;
+      returns None if no candidates).
+- [x] `src/genoplot/colors.py` — `build_cmap/build_norm/value_to_color/
+      add_colorbar`, MISSING_COLOR="lightgray".
+- [x] `src/genoplot/render.py` — primitives: `draw_backbone`,
+      `draw_gene_arrow` (FancyArrow, head_ratio=0.2, head_max=300),
+      `draw_gene_label`, `set_track_limits`, `draw_track` (anchor gets
+      black outline). YLIM computed from arrow geometry: matplotlib 3.11
+      FancyArrow builds a plain polygon with width/head_width in DATA
+      units, so arrows span ±max(width, head_width)/2 ≈ ±1 around
+      Y_CENTER; YLIM = (-1.3, 2.3) (previously -0.7..2.3 clipped the
+      arrow bottoms).
+- [x] `src/genoplot/figure.py` — `plot_neighborhoods`: GridSpec rows +
+      shared colorbar axis, per-plasmid filtering, placeholder row when
+      no anchor ("No annotated genes with NPMI"), title template
+      `{plasmid} | {value_col}={value:.3g}`, defaults color="managua",
+      vmin/vmax=-1/1, neighbor_range=10_000, value_col="NPMI_h1".
+- [x] `src/genoplot/mock.py` — `make_mock_coords(n_plasmids, seed,
+      value_col)`: seeded numpy RNG; genes 300-1500 bp with gaps;
+      ~18% named genes; each plasmid has an intended Rep anchor with
+      NPMI 0.75-0.95 plus 1-2 decoy Reps (-0.5..0.5); plasmid_1's anchor
+      near origin, last plasmid's anchor near genome end (exercises
+      wrap-around windows).
+- [x] `src/genoplot/__init__.py` — public API re-exports + `__all__`.
+- [x] Env built: `pixi install` (Python 3.14.7 via conda-forge).
+- [x] Tests (25 passing): `tests/conftest.py` (MPLBACKEND=Agg before
+      pyplot import, autoclose figures), `tests/test_window.py` (interior
+      identity, xmin<0 / xmax>L wrap cases sorted by `_plot_start`,
+      origin-spanning gene contiguous, edge-partial overlap included,
+      outside excluded), `tests/test_anchors.py` (max-value Rep, None when
+      no candidates/values, predicate precedence, label filter off),
+      `tests/test_colors.py`, `tests/test_figure.py` (axes/cbar counts,
+      PNG save, placeholder rows, SchemaError paths).
+- [x] `scripts/demo.py` — mock data -> PNGs into `demo_output/` (default
+      flank, big-flank boundary crossing, all four plasmids).
+- [x] Verification: `pixi run test` (25 passed), `pixi run lint`
+      (all checks passed), `pixi run demo` (3 PNGs regenerated).
+      NOTE: model could not render PNGs (no image input), so the final
+      visual eyeball step was skipped — outputs should be checked by eye.
+- [x] `README.md` — quick start, schema, API summary, pixi usage, layout.
+- [x] `examples.md` + `scripts/examples.py` — six simple runnable
+      examples rendered into `examples_output/` (all gitignored); pixi
+      task `examples` added. Covers hand-built tables, mock defaults,
+      styling, boundary-crossing flanks, anchor customization with a
+      predicate, and CSV input.
+- [x] `plot_neighborhoods(..., predicate=...)` — anchor-candidate filter
+      threaded into `select_anchor` (takes precedence over
+      `label_contains`); used for minimum anchor thresholds. Two new
+      tests (27 passing); README + examples.md updated.
+
+## Design decision to remember
+
+Window math is fully modulo-based (`rel = (coord - xmin) mod L`, window =
+[0, width] in shifted frame). Consequence: a gene spanning the replication
+origin stays **contiguous** (single arrow) because the backbone linearizes
+at the *window edges*, not at the origin — so no gene-splitting branch is
+needed anywhere.
+
+## Optional polish (not done, not needed)
+
+- Ruff config tweaks, docstring pass, `pixi run fmt`/`ruff format` if
+  desired.
+- `mock._next_accession` uses a module-level counter — not seed-safe for
+  exact reproducibility of accession strings across calls (positions/NPMIs
+  are seeded). Fine for tests.
+
+## Gotchas
+
+- Python here is system 3.14 without pip; conda-forge solve should pick
+  a compatible python (>=3.11 pinned).

genoplot-0.1.0a1/README.md

@@ -0,0 +1,128 @@
+# genoplot
+
+Modular genome neighborhood plots with colormaps.
+
+`genoplot` plots the genes around an anchor gene on each plasmid: a backbone
+line with direction-aware gene arrows, colored by a numeric association value
+(e.g. NPMI). It replaces the original monolithic `plot_npmi_neighborhood`
+function with pure coordinate math separated from matplotlib rendering.
+
+- **Polars in, figure out** — pass a `pl.DataFrame` of coordinates, get a
+  `matplotlib` figure.
+- **Circular genomes handled for free** — windows may cross the plasmid
+  boundary; genes spanning the replication origin stay contiguous.
+
+## Quick start
+
+```python
+import genoplot
+
+coords = genoplot.make_mock_coords()
+fig, axes = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1", "plasmid_4"],
+    neighbor_range=10_000,
+)
+fig.savefig("neighborhoods.png", dpi=200)
+```
+
+## Installation
+
+The project uses [pixi](https://pixi.sh):
+
+```bash
+pixi install
+pixi run test   # run tests
+pixi run lint   # ruff check src tests scripts
+pixi run demo   # regenerate demo_output/*.png
+```
+
+For a plain pip install: `pip install -e .` (requires python >=3.11, needs
+`polars`, `matplotlib`, `numpy`).
+
+## Coordinate table schema
+
+One row per gene. Required columns: `plasmid`, `gene_id`, `start`, `end`,
+`strand` (the entry `start`/`end` may be any integer range; `strand` is
+`1` or `-1`). Optional but useful: label columns (`accession`,
+`short_name`) and a numeric value column such as `NPMI_h1`.
+
+```python
+import polars as pl
+import genoplot
+
+df = pl.DataFrame({
+    "plasmid": ["p1"] * 3,
+    "gene_id": ["g1", "g2", "g3"],
+    "accession": ["WP_00000001.1", "WP_00000002.1", None],
+    "short_name": ["RepB", None, "parA"],
+    "start": [0, 3400, 5100],
+    "end": [1200, 3900, 5800],
+    "strand": [1, -1, 1],
+    "NPMI_h1": [0.91, None, -0.2],
+})
+genoplot.plot_neighborhoods(df, ["p1"])
+```
+
+## API
+
+### High level
+
+- `genoplot.plot_neighborhoods(coords, plasmids, *, neighbor_range=10_000,
+  value_col="NPMI_h1", color="managua", vmin=-1.0, vmax=1.0, ...)` —
+  one track per plasmid. Returns `(fig, axes)`; a shared colorbar is
+  attached on the right. Plasmids without an anchor gene get a placeholder
+  row. `value_col` selects the numeric column used for anchor ranking,
+  gene coloring, the colorbar, and the title. `predicate=...` (a
+  DataFrame->DataFrame filter) narrows the anchor candidates before
+  ranking and takes precedence over `label_contains` — e.g. pass
+  `predicate=lambda df: df.filter(pl.col("NPMI_h1") > 0.7)` for a minimum
+  anchor threshold.
+
+### Lower level
+
+- `genoplot.schema.validate_coords(df)` — check required columns, cast
+  `start`/`end` to `Int64`; `check_value_column(df, col)`.
+- `genoplot.window.Window`, `make_window`, `resolve_window` — pure
+  coordinate math mapping genes into a linear frame where the visible
+  window is `[0, width]`. Genes are sorted by `_plot_start`; origin-spanning
+  genes stay contiguous.
+- `genoplot.anchors.select_anchor(genes, value_col,
+  label_contains="Rep")` — pick the highest-value candidate (default: a
+  `short_name` containing `"Rep"`). Pass `predicate=...` for a custom
+  filter, or `label_contains=None` to disable the label rule.
+- `genoplot.colors.build_cmap / build_norm / value_to_color / add_colorbar`
+  — colormap machinery; missing values render as `lightgray`.
+- `genoplot.render.draw_backbone / draw_gene_arrow / draw_gene_label /
+  draw_track` — drawing primitives onto a caller-provided `Axes`.
+
+### Mock data
+
+- `genoplot.make_mock_coords(n_plasmids=4, seed=2026, value_col="NPMI_h1")`
+  — deterministic synthetic table for demos/tests. The first plasmid's
+  anchor sits near the origin and the last near the genome end to exercise
+  boundary-crossing windows.
+
+## Render a demo
+
+```bash
+pixi run demo
+```
+
+writes PNGs into `demo_output/` (gitignored).
+
+## Layout
+
+```
+src/genoplot/
+  schema.py    column conventions + validation
+  window.py    circular-window coordinate math
+  anchors.py   anchor gene selection
+  colors.py    colormap / norm helpers
+  render.py    drawing primitives (backbone, arrows, labels)
+  figure.py    high-level plot_neighborhoods API
+  mock.py      seeded synthetic data generator
+tests/         pytest suite (window, anchors, colors, figure)
+scripts/
+  demo.py      demo PNG renderer
+```

genoplot-0.1.0a1/examples.md

@@ -0,0 +1,214 @@
+# genoplot examples
+
+Six small, self-contained examples. They build on each other, so read them
+in order. Run everything with:
+
+```bash
+pixi run examples
+```
+
+which regenerates the images below into `examples_output/`.
+
+The examples use mock coordinates (`genoplot.make_mock_coords`) so they are
+deterministic and need no data files. For your own data, replace the mock
+frame with any `pl.DataFrame` following the
+[schema](README.md#coordinate-table-schema).
+
+---
+
+## 1. Plot a table you build by hand
+
+The smallest possible call: define a few genes, pass them to
+`plot_neighborhoods`, get a figure back.
+
+```python
+import polars as pl
+import genoplot
+
+genes = pl.DataFrame({
+    "plasmid":     ["p1"] * 3,
+    "gene_id":     ["g1", "g2", "g3"],
+    "accession":   ["WP_00000001.1", "WP_00000002.1", None],
+    "short_name":  ["RepB", None, "parA"],
+    "start":       [0, 3400, 5100],
+    "end":         [1200, 3900, 5800],
+    "strand":      [1, -1, 1],
+    "NPMI_h1":     [0.91, None, -0.2],
+})
+
+fig, _ = genoplot.plot_neighborhoods(genes, ["p1"])
+fig.savefig("my_plot.png", dpi=200)
+```
+
+![Example 1](examples_output/ex1.png)
+
+`RepB` (value 0.91) is picked as the anchor because it is the `Rep`-labeled
+gene with the highest `NPMI_h1`. It gets a black outline; the gene without a
+value renders gray.
+
+---
+
+## 2. The defaults, on realistic mock data
+
+Generated data mimics real plasmid tables: ~25-45 genes per plasmid,
+sparse labels, sparse values, and one `Rep` anchor per plasmid.
+
+```python
+import genoplot
+
+coords = genoplot.make_mock_coords(n_plasmids=4)
+fig, _ = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1", "plasmid_4"],
+    neighbor_range=10_000,   # show anchor ± 10 kb
+)
+fig.savefig("example2.png", dpi=200)
+```
+
+![Example 2](examples_output/ex2.png)
+
+Every gene is drawn as a direction-aware arrow (strand `+1` points right,
+`-1` points left), colored by its `NPMI_h1` value through the shared
+colorbar.
+
+---
+
+## 3. Tune colors, bounds, and titles
+
+All the knobs are keyword arguments on `plot_neighborhoods`:
+
+```python
+import genoplot
+
+coords = genoplot.make_mock_coords(n_plasmids=2)
+fig, _ = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1", "plasmid_2"],
+    color="viridis",          # any matplotlib colormap name
+    vmin=-0.5,                # colorbar normalization (default -1..1)
+    vmax=1.0,
+    colorbar_label="NPMI (normalized)",      # shared colorbar text
+    title_template="{plasmid} — best {value_col}={value:.2f}",
+)
+fig.savefig("example3.png", dpi=200)
+```
+
+![Example 3](examples_output/ex3.png)
+
+The title template receives `plasmid`, `value_col`, and `value` (the
+anchor's score).
+
+---
+
+## 4. Wide windows that cross the plasmid boundary
+
+Genomes here are circular. When the flank is large, the window can extend
+past both ends of the sequence; genes on the far side are then pulled in
+from the "other direction". The first plasmid's anchor sits near the start
+and the last near the end, which is exactly where this happens.
+
+```python
+import genoplot
+
+coords = genoplot.make_mock_coords(n_plasmids=4)
+fig, _ = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1", "plasmid_4"],
+    neighbor_range=25_000,
+    figsize=(16, 5),
+)
+fig.savefig("example4.png", dpi=200)
+```
+
+![Example 4](examples_output/ex4.png)
+
+A gene spanning the replication origin is drawn as a single contiguous
+arrow, never split in two.
+
+---
+
+## 5. Pick the anchor yourself
+
+By default a candidate is a gene whose label contains `"Rep"`, and the
+highest-scoring candidate wins. Set `label_contains=None` to rank every
+labeled gene by score instead:
+
+```python
+import genoplot
+
+coords = genoplot.make_mock_coords(n_plasmids=2)
+fig, _ = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1", "plasmid_2"],
+    label_contains=None,
+)
+fig.savefig("example5.png", dpi=200)
+```
+
+![Example 5](examples_output/ex5.png)
+
+For a fully custom rule, pass a `predicate` (a `DataFrame -> DataFrame`
+filter) to `plot_neighborhoods`. It is applied to the anchor candidates
+before ranking and replaces the `"Rep"` rule. A minimum anchor threshold is
+just a value filter — here we only accept anchors scoring above 0.7:
+
+```python
+import polars as pl
+import genoplot
+
+coords = genoplot.make_mock_coords(n_plasmids=2)
+
+def above_07(df):
+    return df.filter(pl.col("NPMI_h1") > 0.7)
+
+fig, _ = genoplot.plot_neighborhoods(
+    coords,
+    ["plasmid_1"],
+    predicate=above_07,          # overrides label_contains
+)
+fig.savefig("threshold.png", dpi=200)
+```
+
+If no candidate survives the predicate, the row shows the "No annotated
+genes with NPMI" placeholder instead of a plot. The same filter is exposed
+on the lower-level `genoplot.select_anchor`, which returns the anchor row
+as a dict if you need it directly:
+
+```python
+anchor = genoplot.select_anchor(
+    coords.filter(pl.col("plasmid") == "plasmid_1"),
+    "NPMI_h1",
+    predicate=above_07,
+)
+print(anchor["gene_id"], anchor["short_name"])   # best-scoring gene > 0.7
+```
+```
+
+---
+
+## 6. Read your table from a file
+
+A file on disk works exactly like the frames above — just load it and
+plot. (The mock generator can emit one for you.)
+
+```python
+import polars as pl
+import genoplot
+
+genoplot.make_mock_coords(n_plasmids=3).write_csv("genes.csv")
+df = pl.read_csv("genes.csv")
+
+fig, _ = genoplot.plot_neighborhoods(df, ["plasmid_2"])
+fig.savefig("example6.png", dpi=200)
+```
+
+![Example 6](examples_output/ex6.png)
+
+Columns stay the same: `plasmid`, `gene_id`, `start`, `end`, `strand`,
+optional labels (`accession`, `short_name`), and your value column.
+
+---
+
+That's the whole API for everyday use. For the lower-level drawing
+primitives (backbone, arrows, labels) see
+[README.md](README.md#api).