drvizer 0.1.1__tar.gz

drvizer-0.1.1/CHANGELOG.md

@@ -0,0 +1,249 @@
+# Changelog
+
+All notable changes to drVizer are documented here. Versions follow
+[Semantic Versioning](https://semver.org/). The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.1] - 2026-09-02
+
+### Added
+- **CI matrix workflow** (`.github/workflows/ci.yml`): ubuntu-latest
+  on push to `main` and on `pull_request`, with a Python 3.8 - 3.12
+  matrix. Steps include a dedicated Cython build-prerequisites install
+  (mirroring `.github/workflows/benchmarks.yml`) so the editable
+  install compiles its Cython extensions on every runner, then
+  `pytest -q` for the test suite. macOS is intentionally excluded
+  from this matrix because Cython compilation on macOS is unvalidated
+  in the maintainer's Linux/DSR environment and risks a workflow that
+  fails on first push; it can be added in a follow-up phase once the
+  Linux matrix is proven stable across several push cycles.
+- **Release workflow** (`.github/workflows/release.yml`): triggered by
+  push tags matching `v*`. Three sequential jobs: (1) `build` runs
+  `python -m build` and `twine check dist/*`; (2) `test-pypi` always
+  uploads the built artifact to TestPyPI as a dry-run / canary
+  validation step using the `TESTPYPI_API_TOKEN` secret; (3)
+  `publish-pypi` uploads to production PyPI using the
+  `PYPI_API_TOKEN` secret, gated on a `pypi` GitHub environment that
+  requires manual approval via environment protection rules. **No
+  auto-publish on first run.** The upload-artifact / download-artifact
+  pair is wired so the `dist/` directory flows from `build` to both
+  publish jobs.
+- **Editable install gotcha section** in `CLAUDE.md`: documents that
+  switching git branches (especially after manual ref manipulation
+  such as `git update-ref refs/heads/main <sha>` or `git symbolic-ref
+  HEAD refs/heads/main`) leaves the editable install pointing at the
+  old `src/`. Mandated command:
+  `/datf/hanxi/software/miniconda3/envs/DRS/bin/pip install
+  --force-reinstall --no-deps -e .` after every merge.
+
+### Changed
+- **Tuple-return worker contract** (P1-8, Phase 7 PARTIALLY-FIXED ->
+  FIXED; `src/drvizer/_parallel.py`): the
+  `_compute_region_coverage_with_path` worker now returns
+  `Tuple[str, np.ndarray]` -- `(bam_path, coverage_array)` -- so
+  per-bam-path attribution is encoded in the data shape instead of in
+  the closure binding that Phase 7 relied on. The master loop in
+  `aggregate_region_coverages_parallel` unpacks the tuple:
+  `for bam_path, coverage in pool.imap_unordered(...)`. This is a
+  **refactor for clarity and test maintainability**, not a
+  correctness fix: the Phase 7 closure binding was functionally
+  correct (the `bam_path` was bound into the worker closure, the
+  error message included the path, and master aggregation was
+  order-independent). v0.1.0's "Fixed: imap_unordered attribution
+  invariant" entry describes the original closure-binding contract;
+  v0.1.1's "Changed: tuple-return worker contract" describes the same
+  invariant re-expressed as a data shape. The worker still raises
+  `ParallelCoverageError(... from exc)` inside the worker so the
+  `__cause__` chain survives the `imap_unordered` boundary intact.
+- **Test mocks updated** to match the new contract: 4 FakePool mocks
+  across `tests/test_bam_parallel.py` and
+  `tests/test_phase_3_cpu_guard.py` now return `(bam_path,
+  coverage_array)` tuples derived from `args[i][0]`, and the Phase 7
+  `tests/test_phase_7_imap_unordered.py` order-independence test
+  also returns `(bam_path, coverage_array)` tuples in reversed
+  arrival order. Net: the worker contract is exercised end-to-end in
+  every mock that previously returned a raw ndarray.
+
+### Notes
+- v0.1.0 was tagged locally only (commit `dd33199`) and was **never
+  pushed to PyPI**. v0.1.1 is therefore the first PyPI release of
+  drVizer without breaking any existing install.
+- No throughput numbers or speedup claims appear in this release.
+  The GENCODE + ENCODE + pyGenomeTracks comparison is research-grade
+  work that belongs to a separate Stage 3 project, not to v0.1.1.
+
+## [0.1.0] - 2026-09-01
+
+### Added
+- **`pyproject.toml` PEP 621 `[project]` section** (PKG-002): `name=drvizer`,
+  `version=0.1.0`, `requires-python>=3.8`, MIT license text, README,
+  Python 3.8 - 3.12 classifiers (incl. `Development Status :: 4 - Beta`),
+  `dependencies` from `requirements.txt`, optional `[bam]=[pysam]` and
+  `[test]=[pytest]` extras, and `project_urls`. Authoritative single
+  source of install / metadata truth.
+- **`docs/api.md`**: public API contract document describing `DrViz`
+  constructor signature (`adaptive_threshold`, `cache_maxsize`), `plot()`,
+  `get_transcript_data()`, `ReusableParser` context manager,
+  `ParallelCoverageError` inheritance (`RuntimeError` -> subclass),
+  and the `__version__` contract.
+- **Three new test files** (`tests/test_phase_7_*.py`):
+  - `test_phase_7_imap_unordered.py` verifies that the existing
+    `_compute_region_coverage_with_path` worker binds `bam_path` via
+    closure, the `ParallelCoverageError` raised on worker failure
+    carries the failing `bam_path` in its message, and the master
+    consumer's `imap_unordered` loop pairs `bam_path` to its coverage
+    correctly even when results arrive out of order.
+  - `test_phase_7_degradation_guard.py` asserts no `RuntimeWarning` is
+    emitted when zero chunks degraded and exactly one `RuntimeWarning`
+    is emitted with the degradation count in the message when chunks
+    degraded.
+  - `test_phase_7_version_and_metadata.py` asserts `drvizer.__version__`
+    matches `importlib.metadata.version("drvizer")` and both equal
+    `"0.1.0"`, and the `pyproject.toml` classifiers include Python
+    3.8 through 3.12 plus `Development Status :: 4 - Beta`.
+
+### Changed
+- **`setup.py` skeleton** (P1-16): `setup.py` is now a thin C-extension
+  compile-only wrapper. `extra_compile_args=["-std=c99"]` is preserved on
+  every Cython `Extension` block (panel template did not mention this;
+  dropping it would silently violate C99 compliance). All metadata
+  (name, version, classifiers, install_requires, extras_require,
+  project_urls, long_description) was moved to `pyproject.toml [project]`
+  so the two sources no longer drift.
+- **`__version__` bumped `1.0.0` -> `0.1.0`** (PKG-002): first public
+  release tag.
+- **GTF chunk-degradation warning gate** (P1-3): the end-of-parse
+  `RuntimeWarning` in `GTFParser.parse_gtf` is now Python-gated on
+  `if self._chunk_parse_degradation:` so clean parses emit no warning.
+
+### Fixed
+- **`imap_unordered` attribution invariant** (P1-8 verification, P0-8
+  follow-up): the worker `_compute_region_coverage_with_path` already
+  binds `bam_path = args[0]` via closure; the consumer's
+  `imap_unordered` loop relies on the per-`bam_path` `ParallelCoverageError`
+  message (which now embeds the path) instead of result order. The
+  invariant is locked in `tests/test_phase_7_imap_unordered.py`.
+
+### Hygiene
+- **Dead `BEDParser` import removed** from `src/drvizer/api.py:31`
+  (OCR-006): `BEDParser` is not referenced anywhere else in `api.py`;
+  tests import directly from `drvizer.bed_parser`. Net: zero callers
+  depend on the `api.py` re-export.
+- **Dead `defaultdict` import removed** from `src/drvizer/utils.py:10`
+  (OCR-005): `defaultdict` is not referenced anywhere else in
+  `utils.py`.
+- **Stale `docs/superpowers/` `.gitignore` rule removed** (DOC-001):
+  `docs/` does not contain a `superpowers/` directory; the rule was
+  leftover from a prior layout. The corresponding `workspace/`
+  superpowers material now lives under `/datf/hanxi/software/drVizer/workspace/`.
+
+## [Unreleased] — Phase 2.2 (LRU cache + lifecycle)
+
+### Added
+- **LRU cache in `PreparedDataSource`** (Phase 2.2): an
+  `OrderedDict`-backed LRU cache keyed on
+  `(track_id, target_id, chrom, start, end)` so repeat
+  `get_transcript_data` / `plot` calls skip BED parse and BAM
+  coverage work. `cache_maxsize` defaults to 128; configure via
+  `DrViz(cache_maxsize=N)`.
+- **`ReusableParser` lifecycle lock** (Phase 2.2): `__enter__`,
+  `__exit__`, `close()`, and `clear_cache()` methods. `close()` is
+  idempotent and runs the mandated order: `clear_cache` first, then
+  `pool.shutdown(wait=True)`, then flip `_is_closed`. The data
+  source rejects post-close inserts with `RuntimeError`.
+- **`DrViz` context manager**: `with DrViz() as parser:` returns the
+  prepared `ReusableParser` (not the builder) so the cache and pool
+  are scoped to the block.
+- **Adaptive `ProcessPool` threshold** (Phase 2.2): the build-stage
+  process pool is only opened when the genomic-BED record estimate
+  exceeds `adaptive_threshold` (default 20_000). Under the threshold
+  the path is pure sequential and no pool is allocated. Configure via
+  `DrViz(adaptive_threshold=N)`.
+- **BAM dtype compression**: cached coverage payloads are stored as
+  `np.uint32` for `aggregate_method='sum'` and `np.float32` for
+  `aggregate_method='mean'`.
+- `benchmarks/bench_cache_vs_no_cache.py`: stdlib-only benchmark
+  measuring the cache hit/miss speedup across `small/medium/large`
+  BED workloads.
+
+### Changed
+- `DrViz.build()` is now cached: successive calls with the same
+  builder state return the same `ReusableParser` instance so the
+  LRU cache survives. Any mutating method (`load_gtf`,
+  `add_bed_track`, `add_bam_track`) calls `_mark_dirty()` and forces
+  a recompile on the next `build()`.
+- `DrViz.plot()` and `DrViz.get_transcript_data()` route through
+  `self.build()` instead of constructing a fresh `ReusableParser`
+  per call.
+- `drvizer._track_build.prepare_tracks_parallel` accepts
+  `adaptive_threshold` and `data_source` keyword arguments; the
+  ProcessPool executor is owned by the data source so its lifecycle
+  is locked to the `ReusableParser.close()` path.
+- The build-stage outer `ThreadPoolExecutor` wrapper around
+  process + serial paths has been removed; the two paths now run
+  sequentially within `prepare_tracks_parallel` (process first, then
+  serial), and the pool is gated by the threshold.
+
+### Phase 3 — Cython/Python parity & hardening
+
+#### Added
+- **`ParallelCoverageError` re-exported from `drvizer` package**:
+  callers can now `from drvizer import ParallelCoverageError` for
+  typed error handling around parallel coverage failures.
+- **`tests/fixtures/crlf.bed`**: Windows-style CRLF-terminated BED
+  fixture (PARSER-011) exercising comment + blank + multi-chrom
+  records.
+- **`GTFParser._chunk_parse_degradation` counter**: incremented each
+  time the Cython chunk parser falls back to per-row Python parsing
+  (P1-3).
+- **Five new test files** (`tests/test_phase_3_*.py`) covering CRLF
+  BED parity, GTF chunk degradation, BAM projection kernel
+  consistency, `cpu_count()` None guard, and `ParallelCoverageError`
+  exception chain. Two additional tests (`test_close_failure_emits_*`,
+  `test_get_transcript_data_none_coord_safe`) extend the Phase 2.2
+  LRU-cache suite.
+
+#### Changed
+- **P1-8** (`_parallel.py`): the `Pool.imap_unordered` worker now
+  catches any `Exception`, re-raises as `ParallelCoverageError` chained
+  from the worker exception (`raise ... from exc`), and includes the
+  failing BAM path in the message. The original traceback is preserved
+  on `__cause__` so corrupt BAM / missing `.bai` failures stay
+  diagnosable.
+- **P1-3** (`gtf_parser.py`, `_cython_gtf.pyx`): pattern (a) of the
+  Cython chunk try/except decision is implemented. The `_process_chunk`
+  wrapper calls `_parse_gtf_chunk_impl` inside `try/except`; on
+  chunk-level failure it falls back to per-row Python parsing with
+  per-row `try/except (ValueError, TypeError)`, increments
+  `self._chunk_parse_degradation`, and emits a single
+  `RuntimeWarning` at `parse_gtf()` return time. The Cython kernel
+  remains a pure best-effort transform with no C-level try/except.
+- **P1-6** (`bam_parser.py`): extracted the
+  `_project_aligned_blocks_to_transcript(transcript_id, blocks,
+  gtf_parser, target_chrom, region_start, region_len, coverage)`
+  pure-numeric kernel; both the single-transcript and the batch
+  transcript-coverage paths now route through this single helper so
+  spliced-read / int64 / `np.add.at` fixes live in one place.
+- **P1-5** (`_parallel.py`, `_track_build.py`): `cpu_count()` is now
+  guarded with `try/except NotImplementedError` plus a
+  `isinstance(int)` fallback (and `os.cpu_count() or 1` in
+  `_track_build.py`). The original audit's `min(N, None, 32)` →
+  `TypeError` failure mode is impossible.
+- **PARSER-011** (`_cython_bed.pyx`, `bed_parser.py`): BED open mode
+  unified. Cython path uses `raw_line.rstrip(b'\r\n')`; Python
+  fallback opens in `'rb'` and decodes UTF-8 with `errors='replace'`
+  before `rstrip('\r\n')` and tab-splitting. CRLF and LF BEDs now
+  produce byte-identical records across both paths.
+- **Cleanup B** (`api.py`): the three `try/except Exception: pass`
+  blocks in `ReusableParser.close()` and the `__del__` finalizer now
+  surface failures as `warnings.warn(..., ResourceWarning,
+  stacklevel=2)` instead of silently swallowing them.
+- **`PreparedDataSource._fetch_coverage_in_region` /
+  `_fetch_grouped_anno_in_region`** (`api.py`): the cache key now
+  preserves `None` for missing coordinates instead of raising
+  `TypeError` from `int(None)`; repeated calls with `start=None,
+  end=None` are now cache-hits.
+
+## [1.0.0] - prior
+
+Pre-Phase 2.2 release.

drvizer-0.1.1/LICENSE

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

drvizer-0.1.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include src/drvizer/*.pyx
+include LICENSE
+include README.md
+include CHANGELOG.md
+include pyproject.toml

drvizer-0.1.1/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: drvizer
+Version: 0.1.1
+Summary: A Python tool for parsing GTF/BED files and visualizing gene transcript structures
+Author-email: x1han <han_xi@gzlab.ac.cn>
+License: MIT
+Project-URL: Bug Reports, https://github.com/x1han/drVizer/issues
+Project-URL: Source, https://github.com/x1han/drVizer
+Project-URL: Documentation, https://github.com/x1han/drVizer#readme
+Keywords: bioinformatics,genomics,transcriptomics,gtf,bed,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: bam
+Requires-Dist: pysam; extra == "bam"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# drVizer
+
+`drVizer` is a Python library for building transcript-structure figures from GTF models, BED annotations, and BAM coverage tracks.
+
+It is designed for direct RNA sequencing and transcriptomics workflows that need reusable, scriptable, publication-ready matplotlib figures.
+
+## Breaking Fix in v0.1.0
+
+- **`ParallelCoverageError` surfaces the BAM path on worker failure** (P1-8, merged in Phase 3): worker exceptions from `compute_region_coverage` are chained via `raise ... from exc` and include the failing `bam_path` in the message so corrupt BAM / missing `.bai` / `KeyError` / `BrokenPipeError` failures stay diagnosable.
+- **GTF chunk-degradation warning now gated on `N > 0`** (P1-3): the end-of-parse `RuntimeWarning` only fires when `_chunk_parse_degradation > 0`. Clean parses emit no warning.
+- **`pyproject.toml` PEP 621 `[project]` section** (PKG-002): `name=drvizer`, `version=0.1.0`, README, MIT, requires-python `>=3.8`, classifiers (Python 3.8 - 3.12 + Development Status 4 Beta), `dependencies` from `requirements.txt`, optional `[bam]` and `[test]` extras.
+- **`setup.py` skeleton** (P1-16): `setup.py` is now a thin C-extension compile-only wrapper; all metadata truth lives in `pyproject.toml [project]`. `extra_compile_args=["-std=c99"]` is preserved on every Cython `Extension`.
+- **Version bump `1.0.0` -> `0.1.0`** (PKG-002): first public release tag.
+- **Hygiene**: dead `BEDParser` import removed from `src/drvizer/api.py`; dead `defaultdict` import removed from `src/drvizer/utils.py`; stale `docs/superpowers/` rule removed from `.gitignore`.
+
+## Features
+
+- Build transcript structure figures from one or more GTF files.
+- Overlay BED annotation tracks as interval blocks or numeric score bars.
+- Add BAM-derived coverage tracks with `sum` or `mean` aggregation.
+- Reuse parsed state across many plotting calls through a builder-style API.
+- Project transcript-coordinate BED and BAM inputs back into genomic space.
+- Split transcript-coordinate tracks into transcript-specific subtracks.
+- Share automatic y-axis scaling across matched numeric tracks with `y_axis_group`.
+- Export matplotlib figures for publication workflows.
+
+## Installation
+
+Editable install for local development:
+
+```bash
+git clone https://github.com/x1han/drVizer.git
+cd drVizer
+pip install -e .
+```
+
+Regular local install:
+
+```bash
+pip install .
+```
+
+BAM coverage tracks require `pysam`:
+
+```bash
+pip install pysam
+```
+
+## Quick start
+
+The public workflow is centered on `DrViz`:
+
+```python
+from drvizer import DrViz
+
+parser = (
+    DrViz()
+    .load_gtf("genes.gtf")
+    .add_bed_track("repeats.bed", label="TE")
+    .add_bam_track("reads.bam", label="Coverage")
+    .build()
+)
+
+fig = parser.plot("TP53", show=False)
+```
+
+`build()` freezes the configured GTF and tracks into a reusable parser, so plotting many genes does not repeat setup work.
+
+### Reusable parser with auto-cleanup (Phase 2.2)
+
+`DrViz` is also a context manager; using it as such hands back the
+prepared `ReusableParser` and tears down the cache + lazy
+`ProcessPool` on exit:
+
+```python
+from drvizer import DrViz
+
+with DrViz().load_gtf("genes.gtf").add_bed_track("repeats.bed", label="TE") as parser:
+    for gene in ("TP53", "BRCA1", "MYC"):
+        fig = parser.plot(gene, show=False)
+# cache cleared, pool shut down with wait=True
+```
+
+Cache and pool configuration:
+
+- `DrViz(cache_maxsize=N)` — LRU cache capacity (default 128).
+  Caches are per-parser-instance; each new `build()` constructs a
+  fresh cache.
+- `DrViz(adaptive_threshold=N)` — minimum total BED record count
+  that opens a `ProcessPool` during build (default 20_000). Below
+  the threshold, build is purely sequential.
+
+## Core API
+
+### `load_gtf(...)`
+
+Load one or more GTF files. GTF parsing is required before tracks can be built.
+
+```python
+.load_gtf("genes.gtf")
+.load_gtf(["reference.gtf", "novel_transcripts.gtf"])
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `gtf_files` | `str` or `list[str]` | required | Path to one GTF file or ordered list of GTF files. Exon/CDS features are parsed for transcript rendering. Loading a new GTF resets previously added tracks because tracks depend on the active GTF model. |
+
+drVizer uses exon/CDS features and supports gene ID, gene name, or transcript ID lookup during plotting.
+
+### `add_bed_track(...)`
+
+Add BED-backed annotation tracks.
+
+```python
+.add_bed_track("repeats.bed", label="TE", color="tomato")
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bed_files` | `str` or `list[str]` | required | BED file path or multiple BED files grouped into one logical track. BED3 and wider BED records are supported. |
+| `label` | `str` or `None` | auto `Track_N` | Track label shown on the left side of the figure. Duplicate labels are made unique in registration order. |
+| `color` | `str` or `list[str]` | `"orange"` | Matplotlib color for the track. When multiple BED files are passed, a list gives per-file colors. |
+| `alpha` | `float` or `list[float]` | `0.8` | Track transparency from `0` to `1`. When multiple BED files are passed, a list gives per-file alpha values. |
+| `parser_type` | `"distribution"` or `"score"` | `"distribution"` | Rendering mode. `distribution` draws interval blocks; `score` draws numeric BED scores as bars. |
+| `y_axis_range` | `float` or `None` | `None` | Fixed y-axis maximum for `score` tracks. Takes precedence over automatic scaling and `y_axis_group`. |
+| `y_axis_group` | `str` or `None` | `None` | Shared automatic y-axis scaling group for numeric BED `score` tracks. Invalid for `distribution` tracks. |
+| `transcript_coord` | `bool` | `False` | Treat BED `chrom` field as transcript ID and project transcript coordinates back to genomic coordinates through the loaded GTF. |
+| `layer_order` | `None`, `"ascending"`, or `"descending"` | `"ascending"` | Controls drawing order for layered BED elements. |
+| `split_by_transcript` | `None`, `"nc"`, or `"cn"` | `None` | Split transcript-coordinate BED data into transcript-specific subtracks. Requires `transcript_coord=True`. |
+
+Score tracks can share automatic y-axis scaling:
+
+```python
+.add_bed_track("control_m6a.bed", label="Control m6A", parser_type="score", y_axis_group="m6A")
+.add_bed_track("treated_m6a.bed", label="Treated m6A", parser_type="score", y_axis_group="m6A")
+```
+
+### `add_bam_track(...)`
+
+Add BAM-backed coverage tracks.
+
+```python
+.add_bam_track("reads.bam", label="Coverage", color="steelblue")
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bam_files` | `str` or `list[str]` | required | BAM file path or multiple BAM files grouped into one logical coverage track. BAM support requires `pysam`. |
+| `label` | `str` | `"Coverage"` | Track label shown on the left side of the figure. Duplicate labels are made unique in registration order. |
+| `color` | `str` or `list[str]` | `"steelblue"` | Matplotlib color for coverage. When multiple BAM files are rendered as per-file series, a list gives per-file colors. |
+| `alpha` | `float` or `list[float]` | `0.6` | Coverage transparency from `0` to `1`. When multiple BAM files are rendered as per-file series, a list gives per-file alpha values. |
+| `aggregate_method` | `"sum"` or `"mean"` | `"sum"` | Combines multiple BAM files by summed coverage or average coverage. |
+| `y_axis_range` | `float` or `None` | `None` | Fixed coverage y-axis maximum. Takes precedence over automatic scaling and `y_axis_group`. |
+| `y_axis_group` | `str` or `None` | `None` | Shared automatic y-axis scaling group for numeric coverage tracks. |
+| `transcript_coord` | `bool` | `False` | Treat BAM reference names as transcript IDs and project coverage back to genomic coordinates through the loaded GTF. |
+| `layer_order` | `None`, `"ascending"`, or `"descending"` | `"ascending"` | Controls drawing order for per-file coverage series where individual series are rendered. |
+| `split_by_transcript` | `None`, `"nc"`, or `"cn"` | `None` | Split transcript-coordinate BAM coverage into transcript-specific subtracks. Requires `transcript_coord=True`. |
+
+Multiple BAM files can be combined:
+
+```python
+.add_bam_track(
+    ["sample_a.bam", "sample_b.bam"],
+    label="Reads",
+    aggregate_method="mean",
+)
+```
+
+Supported aggregation modes:
+
+- `aggregate_method="sum"`: sum coverage across BAM files.
+- `aggregate_method="mean"`: average coverage across BAM files.
+
+### `build()` and `plot(...)`
+
+Use `build()` when plotting multiple genes from the same inputs:
+
+```python
+parser = (
+    DrViz()
+    .load_gtf("genes.gtf")
+    .add_bed_track("repeats.bed", label="TE")
+    .add_bam_track("reads.bam", label="Coverage")
+    .build()
+)
+
+fig1 = parser.plot("TP53", show=False)
+fig2 = parser.plot("MYC", show=False)
+```
+
+Use one-shot `plot(...)` for quick figures:
+
+```python
+fig = (
+    DrViz()
+    .load_gtf("genes.gtf")
+    .add_bed_track("repeats.bed", label="TE")
+    .plot("TP53", show=False)
+)
+```
+
+`ReusableParser.plot(...)` accepts these parameters:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `gene` | `str` or `list[str]` | required | Gene ID, gene name, transcript ID, or same-chromosome list of identifiers to plot. |
+| `transcript_to_show` | `str`, `list[str]`, or `None` | `None` | Restrict output to one transcript or selected transcripts from the requested gene. |
+| `output` | `str` or `None` | `None` | Optional output path. When set, figure is saved with matplotlib using tight bounding box and 300 DPI. |
+| `figsize` | `tuple` or `None` | `None` | Explicit final figure size in inches. Overrides automatically computed size. |
+| `figfact` | `tuple` or `None` | `None` | Multiplicative width/height factor applied to automatically computed figure size. Ignored when `figsize` is set. |
+| `show` | `bool` | `True` | Display figure through matplotlib. If `False`, figure is closed after creation but still returned. |
+| `close` | `bool` | `False` | Close figure after showing it. Applies when `show=True`. |
+| `**kwargs` | any | | Forwarded to the visualizer, including transcript sorting and layout options. |
+
+## Transcript-coordinate workflows
+
+Set `transcript_coord=True` when BED or BAM records use transcript IDs instead of genomic chromosome names.
+
+```python
+.add_bed_track("mods.transcript.bed", transcript_coord=True)
+.add_bam_track("reads.transcript.bam", transcript_coord=True)
+```
+
+drVizer projects transcript-coordinate intervals and coverage back into genomic plotting space through the loaded GTF model.
+
+## Split transcript tracks
+
+Transcript-coordinate BED and BAM tracks can be split by transcript with `split_by_transcript`:
+
+```python
+split_by_transcript="nc"  # transcript-major order
+split_by_transcript="cn"  # track-major order
+```
+
+Supported modes:
+
+- `None`: keep combined track behavior.
+- `"nc"`: transcript-major ordering; each transcript groups its split tracks together.
+- `"cn"`: track-major ordering; each track groups its transcript-specific subtracks together.
+
+Split transcript tracks require `transcript_coord=True` and do not support multi-gene plotting.
+
+## Numeric y-axis control
+
+Numeric tracks support two y-axis controls:
+
+- `y_axis_range`: manually fix the y-axis maximum.
+- `y_axis_group`: share automatic y-axis scaling across numeric tracks with the same group name.
+
+`y_axis_range` takes precedence over `y_axis_group`.
+
+```python
+parser = (
+    DrViz()
+    .load_gtf("genes.gtf")
+    .add_bam_track("control.bam", label="Control", y_axis_group="reads")
+    .add_bam_track("treated.bam", label="Treated", y_axis_group="reads")
+    .add_bed_track("m6a.bed", label="m6A", parser_type="score", y_axis_group="mod_score")
+    .build()
+)
+```
+
+## Output behavior
+
+drVizer renders matplotlib figures and returns the generated `Figure` object from `plot(...)`.
+
+```python
+fig = parser.plot("TP53", show=False, output="tp53.pdf")
+fig.set_size_inches((10, 6))
+fig.savefig("tp53.png", dpi=300, bbox_inches="tight")
+```
+
+## Documentation
+
+Detailed docs live in `docs/`:
+
+- [Project overview / PDR](docs/project-overview-pdr.md)
+- [Codebase summary](docs/codebase-summary.md)
+- [System architecture](docs/system-architecture.md)
+- [API reference](docs/api-reference.md)
+- [Testing guide](docs/testing-guide.md)
+- [Code standards](docs/code-standards.md)
+- [Changelog](docs/changelog.md)
+
+## Testing
+
+Use the project DRS environment for validation:
+
+```bash
+/datf/hanxi/software/miniconda3/envs/DRS/bin/python -m pytest -q
+```
+
+## Public entry point
+
+```python
+from drvizer import DrViz
+```