iscc.tumor.Tumor

Tumor(config=None, genome_params=dict(), cancer_cell_params=dict(), epithelial_cell_params=dict(), stromal_cell_params=dict(), immune_cell_params=dict(), deme_params=dict(), selection_params=dict(), seed=42, layout_seed=None)

Bases: object

Shared base for the cell-level and count-based tumour engines; holds the common construction parameters.

Both GlandularTumor (cell-level) and GenotypeTumor (count-based) share the construction parameters below — a single config YAML path, or the individual nested-dict parameter blocks — and forward them here.

Parameters:

Name	Type	Description	Default
config	str or Path	Path to a YAML config that defines the parameter blocks below (keys genome_params, selection_params, deme_params, cell_params and, for spatial engines, spatial_params). When given it overrides the individual arguments; this is the recommended entry point.	None
genome_params	dict	Genome geometry — n_segments × segment_size set the gene count (default 5 × 200 = 1000 genes).	dict()
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.	dict()
deme_params	dict	Per-deme demography — initial_cancer_cells, carrying_capacity, maximum_death_rate and the density-dependent crowding law.	dict()
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.	dict()
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.	dict()
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.	dict()
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.	dict()
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
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
get_genotype_frequencies	Frequencies of the cancer genotypes (normal cell types excluded).
is_extinct	Whether the tumour has died out — True when the total deme event rate is zero.
grow	Advance the tumour by n_steps update steps and materialise the result.
get_tumor_size	Total number of live cells across all genotypes (cancer and normal).
make_cell_data	Make a dataframe containing, for each cell:
write	Write the tumour to output_path in the canonical iscc layout.
plot_muller	Render a Muller plot of the clonal dynamics (cancer genotype frequencies over steps).

get_genotype_frequencies

get_genotype_frequencies(normalize=True)

Frequencies of the cancer genotypes (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)	An (unused) snvs list and the array of per-genotype frequencies.

is_extinct

is_extinct()

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

grow

grow(n_steps=10, seed=42, treatment=None, batch_size=1, **kwargs)

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

Each step samples demes proportionally to their event rates and applies the birth / death / mutation / dispersal process, appending a population snapshot to self.traces; treatment dosing is applied per step when a treatment is given. 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 10).	10
seed	int	Evolution seed for this call (default 42); each step draws a fresh generator from seed plus the elapsed step count.	42
treatment	Treatment	A therapy whose dosing schedule and rate modifiers are applied each step; None (default) grows the tumour untreated.	None
batch_size	int	Number of demes updated per step (default 1).	1

Returns:

Type	Description
list	The per-step population snapshots recorded during this call.

get_tumor_size

get_tumor_size()

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

make_cell_data

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

Make a dataframe containing, for each cell: type, evolutionary_parameters, deme_id, gene_exp, gene_mut, gene_cnv

write

write(output_path)

Write the tumour to output_path in the canonical iscc layout.

Creates the directory and writes the population traces (trace_counts.csv, parents.csv, genotypes.csv), the per-gene gene_data matrices and the per-cell cell_data matrices, so the sampling and data-generation stages can consume it.

Parameters:

Name	Type	Description	Default
output_path	str or Path	Directory to create and write into.	required

plot_muller

plot_muller(ax=None, colormap='gnuplot', normalize=True, smoothing_std=0.1, show_axes=True)

Render a Muller plot of the clonal dynamics (cancer genotype frequencies over steps).

Stacks each cancer genotype's abundance through the recorded traces, nested by ancestry; normal cell types are excluded.

Parameters:

Name	Type	Description	Default
ax	Axes	Axes to draw into; a new figure is created when None.	None
colormap	str	Matplotlib colormap name for the clones (default 'gnuplot').	'gnuplot'
normalize	bool	Plot frequencies (True, default) or absolute cell counts (False).	True
smoothing_std	float	Standard deviation of the band smoothing (default 0.1).	0.1
show_axes	bool	Draw axis labels (True, default) or hide the axes (False).	True