iscc.tumor.GenotypeTumor

GenotypeTumor(config=None, seed=42, genome_params=None, selection_params=None, cancer_cell_params=None, deme_params=None, spatial_params=None, epithelial_cell_params=None, stromal_cell_params=None, immune_cell_params=None, host_cell_params=None, genome_mode='abstract', genome_spec=None, update_mode='exact', tau=1.0, snapshot_every=1, microenv_params=None, layout_seed=None, expression_params=None)

Genotype-level (count-based) tumour engine — the default, scalable iscc growth model.

The tumour grows on a grid of demes (lattice patches); each deme is represented as genotype counts over a shared registry rather than one Python object per cell, so it is spatially explicit at the deme level while every birth / death / mutation / dispersal event is O(1) integer arithmetic on counts. It realises the same evolutionary process as the cell-level GlandularTumor (statistically equivalent, roughly two orders of magnitude faster) and is the class most users should reach for. Typical flow: construct, call grow to run the dynamics, then read the per-cell ground truth off make_cell_data and quality-check it with diagnose.

The constructor takes either a single config YAML path (the usual entry point; see notebooks/example_config.yaml) or the individual nested-dict parameter blocks below. Only the top-level blocks are summarised here — every knob, with its default, valid range and effect, is covered in the parameter documentation.

Parameters:

Name	Type	Description	Default
config	str or Path	Path to a YAML config that defines all of the parameter blocks below (keys genome_params, selection_params, deme_params, spatial_params, cell_params and any optional layers). When given it overrides the individual arguments. This is the recommended entry point.	None
seed	int	EVOLUTION seed (default 42): drives the per-run stochastic dynamics and the spatial seeding. Two runs differing only in seed are two patients with the same genome landscape but different evolution.	42
genome_params	dict	Genome geometry — n_segments × segment_size set the gene count (default 5 × 200 = 1000 genes).	None
selection_params	dict	The CINner fitness model — driver / dispersal / resistance proportions and effect sizes, viability limits, and the optional epistasis_params / dependency_params network layers.	None
cancer_cell_params	dict	Cancer-cell dynamics — division_rate, death_rate, mutation_rate, n_snvs_per_allele, snv_prob / cnv_prob, amp_prob, wgd_rate.	None
deme_params	dict	Per-deme demography — initial_cancer_cells, carrying_capacity, maximum_death_rate and the density-dependent crowding law.	None
spatial_params	dict	Grid and tissue geometry, given as keys of this dict (not as individual constructor arguments): grid_size, dispersal_rate, structure_radius / n_structures (glandular substrate), and the optional compartment-selection hazards (epithelial_barrier, stromal_hazard).	None
epithelial_cell_params	dict	Seeding parameters for each non-cancer (static) cell type — the tissue structure, cell-type labels and local immune density that the cancer death rate reads.	None
stromal_cell_params	dict	Seeding parameters for each non-cancer (static) cell type — the tissue structure, cell-type labels and local immune density that the cancer death rate reads.	None
immune_cell_params	dict	Seeding parameters for each non-cancer (static) cell type — the tissue structure, cell-type labels and local immune density that the cancer death rate reads.	None
host_cell_params	dict	Seeding parameters for each non-cancer (static) cell type — the tissue structure, cell-type labels and local immune density that the cancer death rate reads.	None
genome_mode	(abstract, real)	"abstract" (default) uses a random gene-driver layout; "real" wires the genome from human chromosome-arm data and requires genome_spec.	"abstract"
genome_spec	GenomeSpec	Real-genome specification (required when genome_mode="real").	None
update_mode	(exact, tau)	"exact" (default) is the reference one-event-per-update Gillespie engine; "tau" is tau-leaping (tau sets the generation length), whose cost scales with number-of-clones × number-of-generations instead of number-of-cells.	"exact"
tau	float	Tau-leaping generation length, used only when update_mode="tau" (default 1.0).	1.0
snapshot_every	int	Under tau-leaping, record a full per-clone snapshot every k generations (default 1) so the Muller / grid plots keep working.	1
microenv_params	dict	Microenvironment layer (hypoxia field + cell-cell communication). Off by default; a pure readout that never changes growth.	None
expression_params	dict	Gene-program expression layer (program_params, activity_params, coupling_params, dosage_params, snv_effect_params). Off by default; a readout only.	None
layout_seed	int	GENOME-LAYOUT seed (config-determined, shared across runs of the same config): fixes driver identities and baseline expression so a cohort is comparable by construction. Defaults to the fixed DEFAULT_LAYOUT_SEED.	None

Methods:

Name	Description
is_extinct	Whether the tumour has died out — True when the total deme event rate is zero.
get_tumor_size	Total number of live cells across all genotypes (cancer and normal).
grow	Advance the tumour by n_steps update steps and materialise the result.
make_cell_data	Expand the per-deme genotype counts into per-cell ground-truth tables.
plot_muller	Render a Muller plot of the clonal dynamics (clone frequencies over steps, nested by ancestry).
plot_grid	Plot the spatial deme grid, colouring each deme by a per-cell attribute.
plot_grid_compartments	Two spatial grids (primary + met) side by side, shared clone colormap. by_drivers
plot_muller_compartments	Two-band Muller (primary over met) sharing one colormap with the grids. by_drivers
plot_muller_founders	A SINGLE primary Muller highlighting the clone(s) that seeded the metastasis, so you can
plot_clone_tree	Ground-truth clone tree: the TRUE genotypes_parents genealogy collapsed to the
get_genotype_frequencies	Cancer-genotype ids and their frequencies (normal cell types excluded).
epistasis_ground_truth	The planted network — the answer key for MHN/TreeMHN/CBN/REVOLVER edge + order recovery.
event_table	Per-clone event sets and the ORDER this lineage acquired them (empty when epistasis is off).
diagnose	Flag degenerate ("crappy") tumour regimes after growth, with actionable hints.
write	Write the canonical iscc layout (so isccsample/isccdata can consume it).

is_extinct

is_extinct()

Whether the tumour has died out — True when the total deme event rate is zero.

get_tumor_size

get_tumor_size()

Total number of live cells across all genotypes (cancer and normal).

grow

grow(n_steps=1000, seed=None, treatment=None, **kwargs)

Advance the tumour by n_steps update steps and materialise the result.

Runs the birth / death / mutation / dispersal process (exact Gillespie or tau-leaping, per update_mode), appending a population snapshot to self.traces each step, and finally calls make_cell_data to build the per-cell ground truth.

Parameters:

Name	Type	Description	Default
n_steps	int	Number of update steps to run (default 1000).	1000
seed	int	Evolution seed for this call; defaults to the tumour's construction seed.	None
treatment	Treatment	A therapy (e.g. Chemotherapy, TargetedTherapy, Immunotherapy, Surgery) whose dosing schedule and rate modifiers are applied each step; None (default) grows the tumour untreated.	None

Returns:

Type	Description
list	self.traces — the list of per-step population snapshots.

make_cell_data

make_cell_data(cell_prefix='C', **kwargs)

Expand the per-deme genotype counts into per-cell ground-truth tables.

Materialises one row per cell (each genotype's count becomes that many identical cells) into self.cell_data — a dict of dataframes keyed by cell name: evolutionary parameters, expression, SNV and CNV matrices, grid coordinates, cell-type and deme labels, plus any optional layers that are enabled (compartment, allele-resolved expression / RNA BAF, program activity). Called automatically at the end of grow.

Parameters:

Name	Type	Description	Default
cell_prefix	str	Prefix for the generated cell names (default "C").	'C'

Returns:

Type	Description
dict	self.cell_data — the per-cell dataframes.

plot_muller

plot_muller(ax=None, by_drivers=False, **kwargs)

Render a Muller plot of the clonal dynamics (clone frequencies over steps, nested by ancestry).

by_drivers=True colours by distinct DRIVER-mutation combinations (Noble's demon convention) instead of by genotype, collapsing passenger-only diversity; combine with min_freq for a size threshold. Additional keywords (ax, colormap, normalize) select the target axes and control the styling.

plot_grid

plot_grid(color=None, ax=None, **kwargs)

Plot the spatial deme grid, colouring each deme by a per-cell attribute.

Rebuilds the per-cell data if stale, then draws the grid coloured by color (default the dominant clone / cell type). When the metastatic compartment is enabled and no explicit ax is passed, both the primary and met grids are drawn side by side with a shared clone colormap.

Parameters:

Name	Type	Description	Default
color	str or list of str	Attribute key(s) to colour by; defaults to the dominant clone / cell type.	None
ax	Axes	Axes to draw into; forces the single-panel primary view. A new figure is created when None.	None

Returns:

Type	Description
Axes	The axes drawn into.

plot_grid_compartments

plot_grid_compartments(color=None, axes=None, by_drivers=False, by_stage=False, **kwargs)

Two spatial grids (primary + met) side by side, shared clone colormap. by_drivers colours by functional clone (matching the driver-collapsed 2-band Muller); by_stage colours by the stage-dominant driver; pass min_freq to also merge below-threshold clones.

plot_muller_compartments

plot_muller_compartments(axes=None, by_drivers=False, by_stage=False, star_seeder=True, **kwargs)

Two-band Muller (primary over met) sharing one colormap with the grids. by_drivers collapses genotypes to FUNCTIONAL clones and min_freq (a fraction) merges below-threshold clones, so selective sweeps (DCIS→IDC breach, the met founder, post-chemo resistant escape) show as bands instead of a passenger rainbow. by_stage instead colours by the STAGE-DOMINANT driver. star_seeder stars the first met-seeding clone's band in BOTH panels at the seeding moment (so a minor founder is findable).

plot_muller_founders

plot_muller_founders(ax=None, **kwargs)

A SINGLE primary Muller highlighting the clone(s) that seeded the metastasis, so you can see which — usually minor — primary population founds the met. Founders are read from the seeding events; a primary clone is highlighted iff it shares a functional signature with one.

plot_clone_tree

plot_clone_tree(ax=None, by_stage=False, by_drivers=False, **kwargs)

Ground-truth clone tree: the TRUE genotypes_parents genealogy collapsed to the display clones, each node at its true mutational depth, sized by peak population and coloured by by_stage (stage-dominant driver) or by_drivers (functional clone). Pass min_freq to set the collapse threshold (default 0.02).

get_genotype_frequencies

get_genotype_frequencies(normalize=True)

Cancer-genotype ids and their frequencies (normal cell types excluded).

Parameters:

Name	Type	Description	Default
normalize	bool	If True (default) the counts are divided by their sum to give proportions; otherwise raw cell counts are returned.	True

Returns:

Type	Description
tuple of (list, numpy.ndarray)	The cancer-genotype ids and their matching counts / frequencies.

epistasis_ground_truth

epistasis_ground_truth()

The planted network — the answer key for MHN/TreeMHN/CBN/REVOLVER edge + order recovery.

Returns the true E matrix, the marginal effects beta, the interaction edges, the conjunctive dependency DAG, the mutually-exclusive pairs and the event->gene modules; or None when epistasis is off. Shared by every patient of a cohort (drawn from the layout stream), which is what makes pooling patients to recover ONE network well-posed.

event_table

event_table()

Per-clone event sets and the ORDER this lineage acquired them (empty when epistasis is off).

One row per cancer genotype: its cell count, the events it carries, and the realised order along its lineage — the per-patient ordering ground truth. event_groups is the truthful form (one tuple per mutating division; events inside a group are TIED, having been acquired together, so no order between them exists); event_order is that flattened for exports needing a linear path. Score ordering against event_groups — event_order breaks ties arbitrarily.

diagnose

diagnose(thresholds=None, verbose=False)

Flag degenerate ("crappy") tumour regimes after growth, with actionable hints.

Computes phenotype metrics (size, clonal diversity, TMB, clone spatial confinement, fraction-genome-altered, hypoxia core–rim contrast, 1/f fit) and checks each against an overridable threshold: extinct / monoclonal / hypermutated / well-mixed / no-microenvironment-gradient / CNA-runaway / trivial-genome. Returns a TumorDiagnosis. Read-only — it never draws from self.rng or changes the counts, so it cannot alter simulation output (like the microenvironment ground truth).

write

write(output_path)

Write the canonical iscc layout (so isccsample/isccdata can consume it).