biwt 0.1.0__tar.gz

biwt-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: biwt
+Version: 0.1.0
+Summary: BioInformatics WalkThrough: import single-cell data and generate agent-based model initial conditions
+Author-email: Daniel Bergman <dbergman1@som.umaryland.edu>, Jeanette Johnson <jjohn450@jhmi.edu>, Randy Heiland <heiland@iu.edu>, Paul Macklin <macklinp@iu.edu>, Marwa Naji <mnaji2@jh.edu>
+License: BSD-3-Clause
+Keywords: PhysiCell,bioinformatics,single-cell,initial conditions,agent-based modeling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Provides-Extra: anndata
+Requires-Dist: anndata>=0.9; extra == "anndata"
+Provides-Extra: seurat
+Requires-Dist: anndata>=0.9; extra == "seurat"
+Requires-Dist: anndata2ri>=1.1; extra == "seurat"
+Requires-Dist: rpy2>=3.5; extra == "seurat"
+Provides-Extra: gui
+Requires-Dist: PyQt5>=5.15; extra == "gui"
+Requires-Dist: matplotlib>=3.5; extra == "gui"
+Provides-Extra: all
+Requires-Dist: biwt[anndata,gui,seurat]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-qt; extra == "dev"
+Requires-Dist: biwt[anndata,gui]; extra == "dev"
+
+# 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
+
+```bash
+pip install -e .                    # core (CSV support only)
+pip install -e ".[anndata]"         # + .h5ad support
+pip install -e ".[seurat]"          # + .rds/.rda support (requires R + rpy2)
+pip install -e ".[dev]"             # + test dependencies
+```
+
+## Quick Start
+
+```python
+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")
+
+widget = create_biwt_widget(biwt_input, on_complete=on_complete)
+widget.show()
+```
+
+## Running Tests
+
+```bash
+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 heuristics
+    parameters/
+      cell_templates.py — 29 PhysiCell cell-type XML templates
+      xml_defaults.py   — Default PhysiCell XML scaffold
+  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       — 43 tests covering session logic end-to-end
+  fixtures/             — CSV test fixtures
+```
+
+## 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
+
+- [x] Data import: .h5ad, .rds/.rda/.rdata, .csv
+- [x] Spatial coordinate detection (obsm, obs columns, Visium scale factors)
+- [x] CSV spatial synthesis (x/y/z obs columns → obsm["spatial"])
+- [x] Domain inference with priority chain (preferred > platform > data_range > default)
+- [x] Domain mismatch: two-tier detection (classify_domain_mismatch: "outside" / "small" / None)
+- [x] DomainEditorDialog auto-triggered at positions window open (not import time)
+- [x] Context-sensitive mismatch header; no header for manual "Domain Settings…" open
+- [x] domain_accepted flag prevents re-trigger on back/forward navigation
+- [x] BiwtInput.domain_accepted + "Skip domain validation" checkbox bypass auto-check
+- [x] Z-fields default to ±10 for 2D data in domain editor
+- [x] DomainSpec units field; auto-scale toggle wired into positions step
+- [x] Auto-scale off: raw data bounding box centered at domain center (not identity transform)
+- [x] "Domain Settings…" button in positions plot window for manual domain editing
+- [x] Spot deconvolution query and cell expansion
+- [x] Cluster column selection
+- [x] Spatial data query (use spatial coords or random placement)
+- [x] Edit cell types (keep / merge / delete) with scatter plot and legend
+- [x] Rename cell types with Studio name suggestions and duplicate blocking
+- [x] Cell counts (data counts, confluence, total count modes)
+- [x] Coordinate placement (spatial scaling, random placement)
+- [x] 29 cell parameter templates with XML assembly
+- [x] BiwtResult assembly (coordinates, cell_type_map, domain, XML)
+- [x] Studio bridge (BiwtInput/BiwtResult, _biwt_complete callback)
+- [x] Overwrite/Append/Browse/Cancel dialog for CSV output
+- [x] Append handles extra columns in existing CSV
+- [x] Session reset on reimport
+- [x] Step predicate extraction for testability
+- [x] 57 passing tests
+
+### In Progress
+
+- [ ] End-to-end manual testing with Studio
+
+### Remaining
+
+- [x] pyproject.toml extras for anndata/seurat/dev dependencies
+- [x] CI pipeline (GitHub Actions, Python 3.9–3.12)
+- [ ] CI: R-dependent tests for `.rds` import (requires provisioning R on CI runners; seurat excluded from `dev` extra for now)
+- [ ] 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
+
+- [PRD.md](PRD.md) — Product requirements (behavioral specs, acceptance criteria)
+- [progress.md](progress.md) — Session decisions and reasoning
+- [CLAUDE.md](CLAUDE.md) — Claude agent guide for this repo

biwt-0.1.0/README.md

@@ -0,0 +1,118 @@
+# 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
+
+```bash
+pip install -e .                    # core (CSV support only)
+pip install -e ".[anndata]"         # + .h5ad support
+pip install -e ".[seurat]"          # + .rds/.rda support (requires R + rpy2)
+pip install -e ".[dev]"             # + test dependencies
+```
+
+## Quick Start
+
+```python
+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")
+
+widget = create_biwt_widget(biwt_input, on_complete=on_complete)
+widget.show()
+```
+
+## Running Tests
+
+```bash
+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 heuristics
+    parameters/
+      cell_templates.py — 29 PhysiCell cell-type XML templates
+      xml_defaults.py   — Default PhysiCell XML scaffold
+  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       — 43 tests covering session logic end-to-end
+  fixtures/             — CSV test fixtures
+```
+
+## 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
+
+- [x] Data import: .h5ad, .rds/.rda/.rdata, .csv
+- [x] Spatial coordinate detection (obsm, obs columns, Visium scale factors)
+- [x] CSV spatial synthesis (x/y/z obs columns → obsm["spatial"])
+- [x] Domain inference with priority chain (preferred > platform > data_range > default)
+- [x] Domain mismatch: two-tier detection (classify_domain_mismatch: "outside" / "small" / None)
+- [x] DomainEditorDialog auto-triggered at positions window open (not import time)
+- [x] Context-sensitive mismatch header; no header for manual "Domain Settings…" open
+- [x] domain_accepted flag prevents re-trigger on back/forward navigation
+- [x] BiwtInput.domain_accepted + "Skip domain validation" checkbox bypass auto-check
+- [x] Z-fields default to ±10 for 2D data in domain editor
+- [x] DomainSpec units field; auto-scale toggle wired into positions step
+- [x] Auto-scale off: raw data bounding box centered at domain center (not identity transform)
+- [x] "Domain Settings…" button in positions plot window for manual domain editing
+- [x] Spot deconvolution query and cell expansion
+- [x] Cluster column selection
+- [x] Spatial data query (use spatial coords or random placement)
+- [x] Edit cell types (keep / merge / delete) with scatter plot and legend
+- [x] Rename cell types with Studio name suggestions and duplicate blocking
+- [x] Cell counts (data counts, confluence, total count modes)
+- [x] Coordinate placement (spatial scaling, random placement)
+- [x] 29 cell parameter templates with XML assembly
+- [x] BiwtResult assembly (coordinates, cell_type_map, domain, XML)
+- [x] Studio bridge (BiwtInput/BiwtResult, _biwt_complete callback)
+- [x] Overwrite/Append/Browse/Cancel dialog for CSV output
+- [x] Append handles extra columns in existing CSV
+- [x] Session reset on reimport
+- [x] Step predicate extraction for testability
+- [x] 57 passing tests
+
+### In Progress
+
+- [ ] End-to-end manual testing with Studio
+
+### Remaining
+
+- [x] pyproject.toml extras for anndata/seurat/dev dependencies
+- [x] CI pipeline (GitHub Actions, Python 3.9–3.12)
+- [ ] CI: R-dependent tests for `.rds` import (requires provisioning R on CI runners; seurat excluded from `dev` extra for now)
+- [ ] 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
+
+- [PRD.md](PRD.md) — Product requirements (behavioral specs, acceptance criteria)
+- [progress.md](progress.md) — Session decisions and reasoning
+- [CLAUDE.md](CLAUDE.md) — Claude agent guide for this repo

biwt-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "biwt"
+version = "0.1.0"
+description = "BioInformatics WalkThrough: import single-cell data and generate agent-based model initial conditions"
+authors = [
+    { name = "Daniel Bergman", email = "dbergman1@som.umaryland.edu" },
+    { name = "Jeanette Johnson", email = "jjohn450@jhmi.edu" },
+    { name = "Randy Heiland", email = "heiland@iu.edu" },
+    { name = "Paul Macklin", email = "macklinp@iu.edu" },
+    { name = "Marwa Naji", email = "mnaji2@jh.edu"}
+]
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "BSD-3-Clause" }
+keywords = [
+    "PhysiCell",
+    "bioinformatics",
+    "single-cell",
+    "initial conditions",
+    "agent-based modeling",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+# Minimal hard dependencies — deliberately lean.
+# Optional data formats and GUI are declared below.
+dependencies = [
+    "numpy>=1.22",
+    "pandas>=1.4",
+]
+
+[project.optional-dependencies]
+# pip install biwt[anndata]  — enables .h5ad import
+anndata = ["anndata>=0.9"]
+
+# pip install biwt[seurat]   — enables .rds (Seurat / SingleCellExperiment) import
+seurat = ["anndata>=0.9", "anndata2ri>=1.1", "rpy2>=3.5"]
+
+# pip install biwt[gui]      — enables biwt.gui (PyQt5 walkthrough UI)
+gui = ["PyQt5>=5.15", "matplotlib>=3.5"]
+
+# pip install biwt[all]      — everything
+all = ["biwt[anndata,seurat,gui]"]
+
+# pip install biwt[dev]      — development / testing extras
+dev = ["pytest>=7", "pytest-qt", "biwt[anndata,gui]"]
+# TODO: add a CI job (or optional test marker) that installs biwt[seurat] and
+#       runs R-dependent tests once a strategy for provisioning R on CI is decided.
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# Include any non-Python assets inside the package (e.g. default XML templates)
+"biwt.core.parameters" = ["*.xml", "*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

biwt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

biwt-0.1.0/src/biwt/__init__.py

@@ -0,0 +1,14 @@
+"""
+biwt — BioInformatics WalkThrough
+
+Core public surface:
+    from biwt import BiwtInput, BiwtResult, DomainSpec
+
+GUI (requires biwt[gui]):
+    from biwt.gui import create_biwt_widget
+"""
+
+from biwt.types import DomainSpec, BiwtInput, BiwtResult
+
+__version__ = "0.1.0"
+__all__ = ["DomainSpec", "BiwtInput", "BiwtResult"]

biwt-0.1.0/src/biwt/core/__init__.py

@@ -0,0 +1 @@
+"""biwt.core — data logic with no Qt dependency."""

biwt-0.1.0/src/biwt/core/cell_types.py

@@ -0,0 +1,143 @@
+"""
+Cell-type configuration logic — purely data, no Qt.
+
+The walkthrough gathers user decisions (keep / merge / delete / rename) and
+stores them as ``CellTypeAction`` objects inside a ``CellTypeConfig``.
+``CellTypeConfig.resolve()`` collapses those decisions into a flat
+original_label → final_name mapping that ``positioning.py`` can consume.
+
+``suggest_name_mappings`` provides lightweight heuristic hints to the GUI
+so it can pre-populate rename fields when Studio cell-type names are available.
+Future: replace / augment with a cell-type registry / ontology lookup.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CellTypeAction:
+    """Decision for one cell-type label discovered in the imported data.
+
+    Parameters
+    ----------
+    original_name:
+        The raw label as it appears in the data (e.g. ``"CD8+LAG3= T cell"``).
+    action:
+        One of ``"keep"``, ``"merge"``, ``"delete"``.
+    merge_target:
+        Required when ``action == "merge"``.  The ``original_name`` of the
+        cell type to merge into.  Transitively resolved by ``CellTypeConfig``.
+    final_name:
+        Override the displayed name.  ``None`` means keep ``original_name``.
+    """
+    original_name: str
+    action: str = "keep"                    # "keep" | "merge" | "delete"
+    merge_target: Optional[str] = None      # only when action == "merge"
+    final_name: Optional[str] = None        # None → use original_name
+
+
+@dataclass
+class CellTypeConfig:
+    """Complete cell-type decision set for one BIWT walkthrough session.
+
+    Usage
+    -----
+    config = CellTypeConfig()
+    config.add(CellTypeAction("T cell", action="keep", final_name="tcell"))
+    config.add(CellTypeAction("CD8 T cell", action="merge", merge_target="T cell"))
+    config.add(CellTypeAction("Unknown", action="delete"))
+
+    mapping = config.resolve()
+    # → {"T cell": "tcell", "CD8 T cell": "tcell", "Unknown": None}
+    """
+    actions: dict = field(default_factory=dict)   # original_name → CellTypeAction
+
+    def add(self, action: CellTypeAction) -> None:
+        self.actions[action.original_name] = action
+
+    def resolve_name(self, original: str, _seen: Optional[set] = None) -> Optional[str]:
+        """Return the final cell-type name for *original*, or ``None`` if deleted.
+
+        Handles transitive merges (A→B→C) and detects cycles defensively.
+        """
+        if _seen is None:
+            _seen = set()
+        if original in _seen:
+            # Cycle guard — fall back to original
+            return original
+        _seen.add(original)
+
+        a = self.actions.get(original)
+        if a is None:
+            return original
+        if a.action == "delete":
+            return None
+        if a.action == "merge":
+            if a.merge_target is None:
+                return original
+            return self.resolve_name(a.merge_target, _seen)
+        # action == "keep"
+        return a.final_name if a.final_name else original
+
+    def resolve(self) -> dict[str, Optional[str]]:
+        """Build a flat ``{original_label: final_name | None}`` mapping."""
+        return {name: self.resolve_name(name) for name in self.actions}
+
+    @property
+    def kept_names(self) -> list[str]:
+        """Unique final names that are not deleted."""
+        seen, result = set(), []
+        for final in self.resolve().values():
+            if final is not None and final not in seen:
+                seen.add(final)
+                result.append(final)
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Name-suggestion heuristics
+# ---------------------------------------------------------------------------
+
+def suggest_name_mappings(
+    data_labels: list[str],
+    host_names: list[str],
+) -> dict[str, Optional[str]]:
+    """Suggest a Studio cell-type name for each data label.
+
+    Strategy (in priority order):
+      1. Exact match (case-insensitive).
+      2. Studio name is a substring of the data label (or vice-versa).
+
+    Returns a dict ``{data_label: studio_name | None}``.
+    ``None`` means no suggestion was found.
+
+    This is deliberately simple — good enough for pre-populating the GUI.
+    A future version will query a cell-type ontology / registry.
+    """
+    host_lower = {n.lower(): n for n in host_names}
+    suggestions: dict[str, Optional[str]] = {}
+
+    for label in data_labels:
+        label_lower = label.lower()
+        match: Optional[str] = None
+
+        # 1. Exact
+        if label_lower in host_lower:
+            match = host_lower[label_lower]
+        else:
+            # 2. Substring
+            for sl, sn in host_lower.items():
+                if sl in label_lower or label_lower in sl:
+                    match = sn
+                    break
+
+        suggestions[label] = match
+
+    return suggestions