biwt 0.1.0__py3-none-any.whl

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/core/__init__.py

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

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

biwt/core/data_loader.py

@@ -0,0 +1,307 @@
+"""
+Unified single-cell data loader.
+
+Supported formats
+-----------------
+.h5ad          AnnData (requires biwt[anndata])
+.rds           Seurat / SingleCellExperiment via rpy2 + anndata2ri (requires biwt[seurat])
+.rda / .rdata  R workspace files (same rpy2 requirement; loaded with base::load())
+.csv           Flat tabular; spatial coordinates inferred from column names
+
+All paths return a ``BiwtData`` object with a common interface so downstream
+core logic never needs to know the source format.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+import numpy as np
+import pandas as pd
+
+from biwt.core.domain import _detect_spatial_location_from_obsm, _detect_spatial_location_from_obs
+
+
+# ---------------------------------------------------------------------------
+# BiwtData — unified in-memory representation
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BiwtData:
+    """Unified in-memory representation of imported single-cell data.
+
+    Attributes
+    ----------
+    obs:
+        Per-cell metadata DataFrame (cluster labels, cell-type columns, etc.).
+        Analogous to AnnData.obs.
+    obsm:
+        Named coordinate arrays (e.g. ``{"spatial": ndarray, "X_umap": ndarray}``).
+        Analogous to AnnData.obsm.
+    spatial_location:
+        Human-readable description of where spatial coordinates were found,
+        e.g. ``"obsm['spatial']"`` or ``"obs columns 'x', 'y'"`` or ``None``.
+    file_path:
+        Path the data was loaded from.
+    probability_columns:
+        Obs columns that look like per-cell-type deconvolution probabilities.
+    microns_per_pixel:
+        Scale factor derived from platform metadata (e.g. 10x Visium
+        ``scalefactors``).  ``None`` when not available; ``domain.py`` uses
+        this to convert pixel-space coordinates to µm before domain inference.
+    """
+    obs: pd.DataFrame
+    obsm: dict = field(default_factory=dict)
+    spatial_location: Optional[str] = None
+    file_path: str = ""
+    probability_columns: list = field(default_factory=list)
+    microns_per_pixel: Optional[float] = None
+
+    @property
+    def column_names(self) -> list[str]:
+        return list(self.obs.columns)
+
+    @property
+    def has_spatial(self) -> bool:
+        return self.spatial_location is not None
+
+    @property
+    def n_cells(self) -> int:
+        return len(self.obs)
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+class LoadError(Exception):
+    """Raised when a file cannot be loaded."""
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+# R file extensions that share the same load path
+_R_EXTENSIONS = {".rds", ".rda", ".rdata"}
+
+
+def load(file_path: str) -> BiwtData:
+    """Load single-cell data from *file_path* and return a ``BiwtData``.
+
+    Dispatches on file extension:
+        ``.h5ad``              → AnnData
+        ``.rds``               → R object saved with ``saveRDS()``
+        ``.rda`` / ``.rdata``  → R workspace saved with ``save()``
+        ``.csv``               → flat CSV
+
+    Raises
+    ------
+    LoadError
+        On unsupported format or read failure, with an actionable message.
+    """
+    path = Path(file_path)
+    suffix = path.suffix.lower()
+    if suffix == ".h5ad":
+        return _load_h5ad(file_path)
+    if suffix in _R_EXTENSIONS:
+        return _load_r_file(file_path, suffix)
+    if suffix == ".csv":
+        return _load_csv(file_path)
+    raise LoadError(
+        f"Unsupported file extension '{suffix}'. "
+        "BIWT supports: .h5ad, .rds, .rda, .rdata, .csv"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Format-specific loaders
+# ---------------------------------------------------------------------------
+
+def _load_h5ad(file_path: str) -> BiwtData:
+    try:
+        import anndata
+    except ImportError:
+        raise LoadError(
+            "anndata is required for .h5ad files.\n"
+            "Install with:  pip install biwt[anndata]"
+        )
+    try:
+        adata = anndata.read_h5ad(file_path)
+    except Exception as e:
+        raise LoadError(f"Failed to read '{file_path}' as AnnData: {e}") from e
+
+    mpp = _extract_visium_microns_per_pixel(adata)
+    return _from_anndata_object(adata, file_path, microns_per_pixel=mpp)
+
+
+def _load_r_file(file_path: str, suffix: str) -> BiwtData:
+    """Load an R object file (.rds, .rda, or .rdata) via rpy2 + anndata2ri.
+
+    .rds files contain a single serialised R object (``saveRDS`` / ``readRDS``).
+    .rda / .rdata files are R workspace files that can contain multiple named
+    objects (``save`` / ``load``).  We grab the first object in the workspace;
+    if the file was produced by a standard Seurat/SCE export workflow it will
+    contain exactly one object.
+    """
+    try:
+        import anndata2ri
+        from rpy2.robjects.packages import importr
+        from rpy2.robjects import r as reval
+    except ImportError:
+        raise LoadError(
+            "rpy2 and anndata2ri are required for R files.\n"
+            "Install with:  pip install biwt[seurat]"
+        )
+    try:
+        anndata2ri.activate()
+    except Exception as e:
+        raise LoadError(f"anndata2ri activation failed: {e}") from e
+
+    try:
+        base = importr("base")
+
+        if suffix == ".rds":
+            # readRDS returns the object directly
+            robj = base.readRDS(file_path)
+        else:
+            # load() reads into an environment; grab the first named object
+            env = reval("new.env(parent = emptyenv())")
+            base.load(file_path, envir=env)
+            obj_names = list(base.ls(env))
+            if not obj_names:
+                raise LoadError(f"No objects found in R workspace '{file_path}'.")
+            robj = env[obj_names[0]]
+
+        classname = tuple(robj.rclass)[0]
+
+        if classname in ("SingleCellExperiment", "SummarizedExperiment"):
+            adata = anndata2ri.rpy2py(robj)
+        elif classname == "Seurat":
+            reval("library(Seurat)")
+            # Re-read via R string evaluation so Seurat's conversion method is
+            # available; funnel through the same anndata2ri path afterwards.
+            if suffix == ".rds":
+                reval(f'x <- readRDS("{file_path}")')
+            else:
+                reval(f'load("{file_path}"); x <- get(ls()[1])')
+            adata = reval("as.SingleCellExperiment(x)")
+            adata = anndata2ri.rpy2py(adata)
+        else:
+            raise LoadError(
+                f"R object class '{classname}' is not supported. "
+                "Expected: Seurat, SingleCellExperiment, or SummarizedExperiment."
+            )
+    except LoadError:
+        raise
+    except Exception as e:
+        raise LoadError(f"Failed to read '{file_path}' as R object: {e}") from e
+
+    return _from_anndata_object(adata, file_path)
+
+
+def _load_csv(file_path: str) -> BiwtData:
+    try:
+        df = pd.read_csv(file_path)
+    except Exception as e:
+        raise LoadError(f"Failed to read '{file_path}' as CSV: {e}") from e
+
+    spatial_location = _detect_spatial_location_from_obs(df)
+    prob_cols = _find_probability_columns(df)
+
+    # Synthesize obsm["spatial"] from coordinate columns so the dim-red
+    # plotter in EditCellTypesWindow can display the spatial scatter plot.
+    obsm: dict = {}
+    if spatial_location is not None:
+        from biwt.core.domain import _find_coord_col
+        cols = list(df.columns)
+        x_col = _find_coord_col(cols, "x") or _find_coord_col(cols, "imagerow")
+        y_col = _find_coord_col(cols, "y") or _find_coord_col(cols, "imagecol")
+        if x_col and y_col:
+            z_col = _find_coord_col(cols, "z")
+            xy = np.column_stack([df[x_col].to_numpy(float), df[y_col].to_numpy(float)])
+            if z_col:
+                obsm["spatial"] = np.column_stack([xy, df[z_col].to_numpy(float)])
+            else:
+                obsm["spatial"] = xy
+
+    return BiwtData(
+        obs=df,
+        obsm=obsm,
+        spatial_location=spatial_location,
+        file_path=file_path,
+        probability_columns=prob_cols,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _from_anndata_object(
+    adata,
+    file_path: str,
+    microns_per_pixel: Optional[float] = None,
+) -> BiwtData:
+    """Build a BiwtData from an in-memory AnnData object."""
+    try:
+        obs = adata.obs
+        obsm = dict(adata.obsm)
+    except Exception as e:
+        raise LoadError(f"Could not read obs/obsm from AnnData object: {e}") from e
+
+    spatial_loc = (
+        _detect_spatial_location_from_obsm(obsm)
+        or _detect_spatial_location_from_obs(obs)
+    )
+    prob_cols = _find_probability_columns(obs)
+    return BiwtData(
+        obs=obs,
+        obsm=obsm,
+        spatial_location=spatial_loc,
+        file_path=file_path,
+        probability_columns=prob_cols,
+        microns_per_pixel=microns_per_pixel,
+    )
+
+
+def _extract_visium_microns_per_pixel(adata) -> Optional[float]:
+    """Extract the µm/pixel scale factor from 10x Visium AnnData metadata.
+
+    10x Visium spots are 55 µm in diameter in the tissue section.
+    The fullres pixel diameter is stored in
+    ``adata.uns['spatial'][library_id]['scalefactors']['spot_diameter_fullres']``.
+
+    Returns ``None`` for any non-Visium or missing metadata — callers treat
+    ``None`` as "scale unknown; use raw coordinates".
+
+    Platform-specific notes
+    -----------------------
+    This currently handles 10x Visium only.  Other platforms with known
+    physical scales (Xenium, MERFISH, etc.) typically store coordinates
+    already in µm and do not need this conversion.  Add cases here as
+    support for other platforms is added.
+    """
+    try:
+        spatial_meta = adata.uns.get("spatial", {})
+        if not spatial_meta:
+            return None
+        # Take the first library (multi-library arrays are uncommon)
+        library_id = next(iter(spatial_meta))
+        scalefactors = spatial_meta[library_id].get("scalefactors", {})
+        spot_diameter_px = scalefactors.get("spot_diameter_fullres")
+        if spot_diameter_px and spot_diameter_px > 0:
+            visium_spot_diameter_um = 55.0
+            return visium_spot_diameter_um / spot_diameter_px
+    except Exception:
+        pass
+    return None
+
+
+def _find_probability_columns(obs: pd.DataFrame) -> list[str]:
+    """Return obs columns that look like per-cell-type deconvolution probabilities."""
+    return [
+        col for col in obs.columns
+        if col.endswith("_probability") and (obs[col] >= 0).all() and obs[col].sum() > 0
+    ]

biwt/core/domain.py

@@ -0,0 +1,200 @@
+"""
+Domain inference logic.
+
+Priority order for resolving the final DomainSpec:
+  1. preferred        — host-supplied DomainSpec (always wins if provided)
+  2. platform_microns — coordinates already in µm from platform metadata
+                        (currently: 10x Visium via adata.uns['spatial'] scale factors)
+  3. data_range       — min/max of raw coordinate arrays (obsm or obs columns),
+                        scaled by microns_per_pixel when available
+  4. default          — ±500 µm × ±10 µm fallback
+
+Public entry point: ``infer_domain(preferred, obs, obsm, microns_per_pixel)``
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+import numpy as np
+
+from biwt.types import DomainSpec
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def infer_domain(
+    preferred: Optional[DomainSpec] = None,
+    obs=None,                               # pd.DataFrame | None
+    obsm: Optional[dict] = None,
+    spatial_key: Optional[str] = None,
+    microns_per_pixel: Optional[float] = None,
+) -> DomainSpec:
+    """Return the best available DomainSpec given what the data provides.
+
+    Parameters
+    ----------
+    preferred:
+        DomainSpec from the host.  Returned immediately if not ``None``.
+    obs:
+        AnnData / DataFrame of per-cell metadata.  Checked for x/y(/z) columns
+        when obsm yields nothing useful.
+    obsm:
+        Dict of named coordinate arrays (e.g. ``{"spatial": ndarray, ...}``).
+    spatial_key:
+        Explicit key to use in ``obsm``.  If ``None``, heuristic search is used.
+    microns_per_pixel:
+        Scale factor from platform metadata (e.g. 10x Visium).  When provided,
+        raw pixel coordinates are multiplied by this value before computing the
+        domain bounding box so the result is in µm.  ``None`` means coordinates
+        are assumed to already be in µm (or the scale is unknown).
+    """
+    if preferred is not None:
+        return preferred
+
+    # --- try obsm ---------------------------------------------------------
+    if obsm is not None:
+        key = spatial_key or _find_spatial_key(obsm)
+        if key and key in obsm:
+            coords = np.asarray(obsm[key], dtype=float)
+            if coords.ndim == 2 and coords.shape[1] >= 2:
+                if microns_per_pixel is not None:
+                    coords = coords * microns_per_pixel
+                    source = "platform_microns"
+                else:
+                    source = "data_range"
+                return _domain_from_coords(coords, source=source)
+
+    # --- try obs columns --------------------------------------------------
+    if obs is not None:
+        try:
+            cols = list(obs.columns)
+        except AttributeError:
+            cols = []
+        x_col = _find_coord_col(cols, "x")
+        y_col = _find_coord_col(cols, "y")
+        if x_col and y_col:
+            xy = np.column_stack([obs[x_col].values, obs[y_col].values]).astype(float)
+            z_col = _find_coord_col(cols, "z")
+            if z_col:
+                xy = np.column_stack([xy, obs[z_col].values])
+            if microns_per_pixel is not None:
+                xy = xy * microns_per_pixel
+                source = "platform_microns"
+            else:
+                source = "data_range"
+            return _domain_from_coords(xy, source=source)
+
+    return DomainSpec.default()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _domain_from_coords(coords: np.ndarray, source: str = "data_range") -> DomainSpec:
+    """Build a DomainSpec from the bounding box of a coordinate array."""
+    xmin, xmax = float(coords[:, 0].min()), float(coords[:, 0].max())
+    ymin, ymax = float(coords[:, 1].min()), float(coords[:, 1].max())
+    zmin, zmax = -10.0, 10.0
+    if coords.shape[1] >= 3:
+        zmin = float(coords[:, 2].min())
+        zmax = float(coords[:, 2].max())
+    return DomainSpec(xmin=xmin, xmax=xmax, ymin=ymin, ymax=ymax,
+                      zmin=zmin, zmax=zmax, source=source)
+
+
+def _find_spatial_key(obsm: dict) -> Optional[str]:
+    """Return the first obsm key that looks like spatial coordinates."""
+    priority = ["spatial", "X_spatial", "spatial_coords"]
+    for p in priority:
+        if p in obsm:
+            return p
+    for key in obsm:
+        kl = key.lower()
+        if "spatial" in kl or "coord" in kl:
+            return key
+    return None
+
+
+_COORD_CANDIDATES: dict[str, list[str]] = {
+    "x": ["x", "x_coord", "coord_x", "spatial_x", "x_centroid", "cell_x"],
+    "y": ["y", "y_coord", "coord_y", "spatial_y", "y_centroid", "cell_y"],
+    "z": ["z", "z_coord", "coord_z", "spatial_z", "z_centroid", "cell_z"],
+}
+
+
+def _find_coord_col(columns: list[str], axis: str) -> Optional[str]:
+    """Case-insensitive search for a spatial axis column."""
+    cols_lower = {c.lower(): c for c in columns}
+    for candidate in _COORD_CANDIDATES.get(axis, []):
+        if candidate in cols_lower:
+            return cols_lower[candidate]
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Spatial-location description helpers (used by data_loader)
+# ---------------------------------------------------------------------------
+
+def classify_domain_mismatch(
+    data: DomainSpec,
+    preferred: DomainSpec,
+) -> Optional[str]:
+    """Classify the relationship between data coordinates and the preferred domain.
+
+    Returns
+    -------
+    "outside"
+        One or more data boundaries exceed the preferred domain — those cells
+        would be excluded from the simulation.
+    "small"
+        Data fits inside the preferred domain but covers < 50% of at least one
+        axis, or < 50% of the 2-D area — cells would be very sparse.
+    None
+        No significant mismatch.
+    """
+    fits_inside = (
+        data.xmin >= preferred.xmin and data.xmax <= preferred.xmax
+        and data.ymin >= preferred.ymin and data.ymax <= preferred.ymax
+    )
+    if not fits_inside:
+        return "outside"
+    if preferred.width == 0 or preferred.height == 0:
+        return None
+    if (
+        data.width  < 0.5 * preferred.width
+        or data.height < 0.5 * preferred.height
+        or data.width * data.height < 0.5 * preferred.width * preferred.height
+    ):
+        return "small"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Spatial-location description helpers (used by data_loader)
+# ---------------------------------------------------------------------------
+
+def _detect_spatial_location_from_obsm(obsm: dict) -> Optional[str]:
+    """Return a human-readable description of where spatial data lives in obsm."""
+    key = _find_spatial_key(obsm)
+    if key:
+        return f"obsm['{key}']"
+    return None
+
+
+def _detect_spatial_location_from_obs(obs) -> Optional[str]:
+    """Return a human-readable description of spatial columns in an obs DataFrame."""
+    try:
+        cols = list(obs.columns)
+    except AttributeError:
+        return None
+    x_col = _find_coord_col(cols, "x")
+    y_col = _find_coord_col(cols, "y")
+    if x_col and y_col:
+        z_col = _find_coord_col(cols, "z")
+        if z_col:
+            return f"obs columns '{x_col}', '{y_col}', '{z_col}'"
+        return f"obs columns '{x_col}', '{y_col}'"
+    return None

biwt/core/parameters/__init__.py

@@ -0,0 +1,15 @@
+"""
+biwt.core.parameters — cell-type template library.
+
+Current contents
+----------------
+xml_defaults     : Default PhysiCell XML snippets for each config section.
+cell_templates   : Named cell-type phenotype templates (PhysiCell XML strings).
+
+Future direction
+----------------
+This subpackage will grow into a versioned cell-type registry / ontology,
+eventually spun out into its own repo for independent version control.
+Templates will be keyed by canonical cell-type names (with aliases) and
+will carry hierarchical relationships (e.g. "CD8+ T cell" ⊂ "T cell").
+"""