add visualization functions and dependencies

Author: jsdearbo

CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased]
+
+### Added
+- `seq_tools/visualization.py` — matplotlib-based plotting utilities requiring no grelu or genome files:
+  - `plot_ism_heatmap` — ISM log2FC result as a diverging-colormap heatmap (ACGT rows)
+  - `plot_prediction_track` — 1D bin-level model prediction as a filled area chart
+  - `plot_gene_model` — exon/intron track from a soft-label DataFrame, colored by p_exon
+  - `plot_attribution` — per-position saliency bar chart or tangermeme logo (falls back gracefully)
+  - `multi_track_figure` — stacked, shared-x-axis multi-panel figure layout
+- All five visualization functions exposed in `seq_tools.__init__.__all__`
+- `examples/04_interpretation_workflow.ipynb` — end-to-end interpretation notebook:
+  - ISM with `seq_tools.variant` (no grelu required)
+  - API tour of `interpret.ism`, `interpret.attribution`, `interpret.modisco`
+  - Synthetic attribution and gene model visualization
+  - Composite multi-track figure combining all tracks
+- `tests/test_labels.py` — comprehensive tests for the splicing label generation pipeline:
+  - `_disjoint_labels_with_priority`: priority ordering, exon/intron segmentation, PSI override, multi-chrom
+  - `collapse_exon_coords_weighted`: read-weighted PSI aggregation vs. naive average
+  - `generate_soft_labels`: schema, exon/intron assignment, rMATS PSI integration (pyranges-gated)
+- `tests/test_dataset.py` — tests for `GenomicWindowDataset` and `rasterize_window`:
+  - Shard loading, caching behavior, transform support, DataLoader compatibility
+  - Bin boundary alignment, partial overlap weighting, NaN handling
+
+### Changed
+- `training/multitask_head.py` — module docstring now includes a design note explaining the output-collapse problem and how per-task `BatchNorm1d` in `SplitHead` prevents it
+- `pyproject.toml` — added `matplotlib >= 3.5` as a core dependency
+
 ## [0.1.0] — 2025-01-01
 
 ### Added

README.md

@@ -12,6 +12,7 @@ Built around [gReLU](https://github.com/Genentech/gReLU) and designed for Borzoi
 - **Genomic intervals** — chromosome tiling, window centering, output bin mapping
 - **Splicing label generation** — hard/soft PSI labels from rMATS + StringTie, with priority-based disjoint segmentation
 - **Variant construction** — SNV generation and scoring for in silico mutagenesis
+- **Visualization** — ISM heatmaps, prediction tracks, gene model and attribution plots (matplotlib, no grelu required)
 - **Custom losses** — PSI-aware, Bhattacharyya, masked MSE/Poisson for multitask training
 - **Multitask heads** — nonlinear, split-head, and cell-type conditional architectures
 - **LoRA fine-tuning** — lightweight low-rank adaptation for Conv1d and Linear layers with weight merging
@@ -37,7 +38,8 @@ seq_tools/              Core sequence utilities
 ├── intervals.py        Genomic interval generation, centering, bin conversion
 ├── fasta.py            FASTA reading, windowed iteration
 ├── labels.py           Splicing label generation (rMATS + StringTie)
-└── variant.py          SNV generation and variant scoring
+├── variant.py          SNV generation and variant scoring
+└── visualization.py    ISM heatmaps, prediction tracks, gene model and attribution plots
 
 training/               Model training infrastructure
 ├── losses.py           PSI, Bhattacharyya, masked MSE/Poisson losses
@@ -100,6 +102,28 @@ cond_head = ConditionalHead(in_channels=1920, n_celltypes=5, out_channels=1)
 pred = cond_head(trunk_features, cell_type_id=torch.tensor([2]))
 ```
 
+### Visualize ISM results and model predictions
+
+```python
+from seq_tools.visualization import (
+    plot_ism_heatmap,
+    plot_prediction_track,
+    plot_gene_model,
+    multi_track_figure,
+)
+import matplotlib.pyplot as plt
+
+# ISM heatmap from score_variants output — shape (4, L), ACGT rows
+fig, ax = plt.subplots(figsize=(15, 2))
+plot_ism_heatmap(ism_matrix, genome_start=10_500_000, ax=ax, title="log2FC")
+
+# Stacked multi-track figure with shared x-axis
+fig, axes = multi_track_figure(3, height_ratios=[2, 1.5, 1])
+plot_prediction_track(predictions, ax=axes[0], ylabel="PSI")
+plot_ism_heatmap(ism_matrix, ax=axes[1])
+plot_gene_model(soft_label_df, ax=axes[2])
+```
+
 ### Generate splicing labels
 
 ```python
@@ -124,7 +148,7 @@ This toolkit extends [gReLU](https://github.com/Genentech/gReLU) rather than rep
 
 - Python ≥ 3.10
 - PyTorch ≥ 2.0
-- NumPy, Pandas
+- NumPy, Pandas, Matplotlib
 
 Optional:
 - [gReLU](https://github.com/Genentech/gReLU) — model loading, attribution, ISM

pyproject.toml

@@ -22,17 +22,17 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
 ]
-
-[project.urls]
-Repository = "https://github.com/jsdearbo/sequence_to_function_model_tools"
-"Bug Tracker" = "https://github.com/jsdearbo/sequence_to_function_model_tools/issues"
-
 dependencies = [
     "numpy>=1.24",
     "pandas>=2.0",
     "torch>=2.0",
+    "matplotlib>=3.5",
 ]
 
+[project.urls]
+Repository = "https://github.com/jsdearbo/sequence_to_function_model_tools"
+"Bug Tracker" = "https://github.com/jsdearbo/sequence_to_function_model_tools/issues"
+
 [project.optional-dependencies]
 full = [
     "grelu",

seq_tools/__init__.py

@@ -6,6 +6,13 @@
 from seq_tools.encoding import one_hot_encode, decode_one_hot, reverse_complement, normalize_chrom
 from seq_tools.intervals import generate_intervals, make_input_interval, genome_to_output_bins
 from seq_tools.variant import generate_snvs, generate_window_variants, score_variants
+from seq_tools.visualization import (
+    plot_ism_heatmap,
+    plot_prediction_track,
+    plot_gene_model,
+    plot_attribution,
+    multi_track_figure,
+)
 
 __all__ = [
     "one_hot_encode",
@@ -18,4 +25,9 @@
     "generate_snvs",
     "generate_window_variants",
     "score_variants",
+    "plot_ism_heatmap",
+    "plot_prediction_track",
+    "plot_gene_model",
+    "plot_attribution",
+    "multi_track_figure",
 ]