Skip to content

BIWT

BioInformatics WalkThrough — a guided wizard that turns single-cell data into initial conditions for agent-based models.

You bring an .h5ad, a Seurat .rds, or a plain .csv. BIWT walks you through choosing which metadata column holds your cell-type labels, merging and renaming those types, deciding how many cells to place and where, and attaching phenotype parameters. It hands back a table of positioned cells ready to drop into a simulation.

BIWT is a standalone, pip-installable package. It is host-agnostic: it ships a Qt widget and a small data contract. PhysiCell Studio is the current host.

Start here

  • New to BIWT

    Install it, then run the wizard end to end on a small file.

    Getting started →

  • Working through the wizard

    What each step asks, why, and what happens if you skip it.

    User guide →

  • You have a specific dataset

    Worked examples for Visium, plain scRNA-seq, and deconvolved spots.

    Recipes →

  • Embedding BIWT in your own app

    The BiwtInput / BiwtResult contract and how to wire up the widget.

    Embedding BIWT →

What BIWT produces

The wizard ends by handing the host a BiwtResult. Its coordinates field is a DataFrame with one row per placed cell:

x y z type
-213.4 88.1 0.0 tumor
-198.7 91.6 0.0 tumor
42.0 -310.5 0.0 macrophage

Those column names are the PhysiCell convention — type, not cell_type. The result also reports which cell template you picked for each cell type, if the host offered any; turning those into a config is the host's job.

BIWT never writes to disk. It returns the result in memory and the host decides where it goes.

Scope and limits

BIWT is a setup tool. It does not run simulations, and it does not do bioinformatics analysis — it consumes the output of an analysis you have already done. It expects your cell-type calls to exist already, as a column in obs (or a set of per-spot probability columns, for deconvolved spatial data).

Current limits:

  • 3D placement is partial. Give the domain a z extent greater than 20 µm and the plotters place cells in depth — including the Spatial plotter, which uses your data's z column. But spot-deconvolution placement, and the extra cells from Num cells per spot, are always put at z = 0.
  • Single Visium library. Multi-library arrays use the first library's scale factors.
  • Gene expression is not carried through. Only positions and type labels reach the result; substrate_data and gene_expression are reserved but unpopulated.

Reading these docs

Colored boxes mean specific things:

Note

Context or behavior worth knowing. Nothing goes wrong if you skip it.

Tip

Optional advice that will make your result better.

Warning

You can get a wrong or surprising result here.

Danger

This silently corrupts your output. Read it.

Collapsed Why… boxes hold background you can safely skip on a first pass.