BIWT — BioInformatics WalkThrough

A guided wizard for importing single-cell bioinformatics data and generating initial conditions for agent-based models (ABMs). Designed as a standalone pip-installable package that can be embedded in any host application. Currently integrated with PhysiCell Studio.

Installation

pip install biwt                    # core (CSV support only)
pip install "biwt[anndata]"         # + .h5ad support
pip install "biwt[seurat]"          # + .rds/.rda support (also needs R — see below)
pip install "biwt[gui]"             # + PyQt5 walkthrough UI
pip install "biwt[all]"             # everything

Development install (from a clone):

pip install -e ".[dev]"             # editable + test dependencies

.rds / .rda import needs a working R with Seurat and SingleCellExperiment in addition to the pip extra. See the installation guide for the conda recipe and a troubleshooting guide for the R stack.

Documentation

Full docs: drbergman-lab.github.io/biwt — user guide for every wizard step, worked recipes for Visium / scRNA-seq / spot-deconvolution data, the host-integration contract, and a generated API reference.

Build them locally with:

pip install -e ".[docs]"
mkdocs serve

Quick Start

import sys
from PyQt5.QtWidgets import QApplication

from biwt.gui.theme import apply_light_palette
from biwt.gui.walkthrough import create_biwt_widget
from biwt.types import BiwtInput, DomainSpec

domain = DomainSpec(xmin=-500, xmax=500, ymin=-500, ymax=500, units="micron")
biwt_input = BiwtInput(preferred_domain=domain)

def on_complete(result):
    # result.coordinates is a DataFrame with columns: x, y, z, type
    result.to_csv("config/cells.csv")

app = QApplication(sys.argv)
apply_light_palette(app) 

widget = create_biwt_widget(biwt_input, on_complete=on_complete)
widget.show()

sys.exit(app.exec_())

Running Tests

PYTHONPATH=src python -m pytest tests/ -v

Package Structure

src/biwt/
  types.py              — Public API: DomainSpec, BiwtInput, BiwtResult
  core/
    data_loader.py      — Unified loader (.h5ad, .rds, .csv) → BiwtData
    domain.py           — Domain inference + coordinate column detection
    positioning.py      — Coordinate scaling + build_ic_dataframe
    cell_types.py       — Name matching + keep/merge/delete bookkeeping
    templates.py        — Reading host/user cell template files
  gui/
    walkthrough.py      — Session state machine + Qt widget + step logic
    widgets.py          — Shared Qt widgets
    windows/            — One file per walkthrough step
tests/
  test_session.py       — Session logic end-to-end (Qt-free)
  test_walkthrough_nav.py — Real controller: advance / go back / re-import
  test_name_matching.py — "same cell type?" rules
  test_cell_templates.py — Template files and per-type pre-selection
  test_load_cell_templates.py — The cell-templates window
  test_gui_smoke.py     — Headless Qt import-path and error-dialog tests
  test_positions_plot.py — Spatial placement / plot scaling tests
  test_static_checks.py — pyflakes name resolution over every module
  fixtures/             — CSV and TOML test fixtures
scripts/
  make_screenshot_data.py — Synthetic Visium-like .h5ad for doc screenshots
docs/                   — MkDocs Material site (published to GitHub Pages)
  index.md
  getting-started/      — Install matrix, first walkthrough, R/Seurat troubleshooting
  guide/                — One page per wizard step, plus the domain editor
  recipes/              — Visium, non-spatial scRNA-seq, spot deconvolution
  integration/          — Host embedding: API contract, templates/matching, Studio bridge
  reference/            — mkdocstrings API reference
mkdocs.yml

Key Design Decisions

• No file I/O in BIWT. The package returns BiwtResult in-memory; the host decides how to write.
• Pure-Python session. WalkthroughSession has no Qt dependencies. All Qt logic is in window classes.
• Single source of truth for steps. _step_predicates(session) defines step ordering. Tests import it directly.
• CSV uses type header (not cell_type) to match PhysiCell convention.
• Domain units. DomainSpec.units defaults to "micron" but supports other ABM frameworks.

Implementation Status

Completed

• Data import: .h5ad, .rds/.rda/.rdata, .csv
• Spatial coordinate detection (obsm, obs columns)
• Pixel-coordinate fallback: recognize imagecol→x / imagerow→y (row-flipped) as a last-resort spatial source; domain reported in a generic data unit (no inferred unit name)
• Spatial synthesis from obs columns (x/y/z or imagerow/imagecol → obsm["spatial"]) for CSV and AnnData/R, so the dim-reduction plot offers a Spatial view
• Domain inference with priority chain (host > data > default)
• Domain mismatch: two-tier detection (classify_domain_mismatch: "outside" / "small" / None)
• DomainEditorDialog auto-triggered at positions window open (not import time)
• Context-sensitive mismatch header; no header for manual "Domain Settings…" open
• Dismissing the domain dialog prevents re-trigger on back/forward navigation
• Domain editor OK is gated on a usable domain: all six bounds must parse and min < max on every axis (a zero-width axis divides by zero in placement scaling); offending fields are highlighted and Cancel is never gated
• Domain editor shows the live extents of the domain being edited
• Z-fields default to ±10 for 2D data in domain editor
• Data-unit→host-unit scale factor in the domain editor: auto-detected Visium µm/pixel (_extract_visium_microns_per_pixel), editable, with each value shown in host units beside its parenthesized data-units mirror, synced by the factor, plus a reset-to-file button
• Domain editor is an axis-major ruled grid — one row per axis (X (width), Y (height), Z (depth)) against min / max / size columns — so an axis' extent sits beside the bounds that span it instead of in a separate block six rows below. DomainEditorDialog._AXES is the single source of truth for the layout, the extent derivation, and the validation
• Placement scales cells by the factor and centers them in the domain (compute_spatial_placement; session.effective_scale()) — uniform, aspect-preserving; the domain is an independent host-units container
• "Domain Settings…" button in positions plot window for manual domain editing
• Spot deconvolution query and cell expansion; per-spot apportionment lives in core.positioning.apportion_spot_cells (shifted-divisor equal proportions), with ties broken at random so the surplus cell no longer lands on the first-listed obs column in every spot
• Cluster column selection
• Spatial data query (use spatial coords or random placement)
• Edit cell types (keep / merge / delete) with scatter plot and legend
• Rename cell types with host name suggestions and duplicate blocking
• Cell counts (data counts, confluence, total count modes); a count of zero defines the cell type without placing any of it
• Coordinate placement (spatial scaling, random placement)
• Cell-type rows stay aligned however many types there are: the positions step's checkbox/Undo list and the cell-counts table are grids, so each name shares a row with its own controls
• Cell templates from the landing screen's library (seeded by the host, editable by the user, carried across imports) or loaded at the step; the step is always shown and always skippable
• BiwtResult assembly (coordinates, cell_type_map, domain, cell_templates)
• BIWT generates no framework XML and ships no framework-specific data — the host owns both
• BiwtResult carries no output path — the host owns where results go; to_csv(path) writes and records nothing
• 3-D spatial plot ⇧-drag writes the correct extent slots (the 3-D layout is (x0, y0, z0, width, height, depth), not the 2-D (x0, y0, width, height))
• Studio bridge (BiwtInput/BiwtResult, _biwt_complete callback)
• Host context resolved per run: create_biwt_widget accepts a BiwtInput or a callable returning one, snapshotted for the run
• Host cell types are cell-template candidates; a match returns types.HOST_SOURCE instead of a file path
• Overwrite/Append/Browse/Cancel dialog for CSV output
• Append handles extra columns in existing CSV
• Session reset on reimport
• tomli in core dependencies (fixes import crash on Python 3.9/3.10)
• Step predicate extraction for testability
• [project.urls] metadata so the PyPI page links to the repo, docs, and issues
• Project mark: window icon on the widget and every step window, docs logo and favicon, README header (scripts/make_icons.py derives them)
• MkDocs Material documentation site published to GitHub Pages by .github/workflows/docs.yml
• Docs: user guide (all wizard steps), recipes (Visium / non-spatial / spot deconvolution), host-integration guide, mkdocstrings API reference
• LoadError.docs_url: environment-related import failures link to the setup docs from the "Import failed" dialog; file-related failures stay plain text. Missing dependencies point at the install page, broken R stacks at troubleshooting
• pyproject.toml extras for anndata/seurat/dev dependencies
• CI pipeline (GitHub Actions, Python 3.9–3.12)
• CI: R-dependent .rds tests run in a dedicated seurat job that provisions R, Seurat, and SingleCellExperiment from conda across Python 3.9–3.12; tests/fixtures/make_fixtures.R regenerates the fixture each run so it cannot drift against the resolved R version
• Full suite green (one .rds test skips locally without the R stack; the seurat CI job runs it)

In Progress

• End-to-end manual testing with Studio

Remaining

• User documentation / help text within wizard steps
• Substrate/gene expression pass-through (reserved fields in BiwtResult)
• Multi-library Visium support
• 3D spatial data support beyond z=0 padding

Related Documents

• Documentation site — user guide, recipes, integration guide, API reference (source in docs/)
• PRD.md — Product requirements (behavioral specs, acceptance criteria)
• progress.md — Session decisions and reasoning
• CLAUDE.md — Claude agent guide for this repo