iscc.tumor.GlandularTumor

GlandularTumor(n_structures=1, structure_radius=0, grid_size=10, **tumor_kwargs)

Bases: Tumor

Cell-level (one-object-per-cell) glandular tumour engine on a deme grid.

The reference implementation of the iscc growth process: every cell is an explicit Cell object, so it is the most faithful model (and the ground truth the count engine is validated against), but it does not scale to large tumours — prefer GenotypeTumor for anything big. Cells live in demes on a square grid; with structure_radius > 0 the founder is seeded inside a ring-shaped gland and spreads outward, otherwise it starts as a micro-lesion in the centre deme.

Accepts a single config YAML path or the individual parameter blocks (forwarded to the Tumor base). Every knob, with its default and valid range, is covered in the parameter documentation.

Parameters:

Name	Type	Description	Default
n_structures	int	Number of glandular structures to seed (default 1). Read from spatial_params.n_structures when a config is given.	1
structure_radius	int	Radius of the glandular ring in demes (default 0 = no gland; the founder is seeded in the centre deme). Read from spatial_params.structure_radius under a config.	0
grid_size	int	Side length of the square deme grid (default 10). Read from spatial_params.grid_size under a config.	10
**tumor_kwargs		Forwarded to the Tumor base. See Tumor for the shared genome_params / selection_params / deme_params / cell-type blocks (as well as config, seed and layout_seed).	{}

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:
plot_muller	Render a Muller plot of the clonal dynamics (cancer genotype frequencies over steps).
write	Write the tumour to output_path, adding the spatial layout to the base output.
plot_grid	Plot the deme grid, colouring each deme by one or more per-cell attributes.

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

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

write

write(output_path)

Write the tumour to output_path, adding the spatial layout to the base output.

Extends the base Tumor.write with the per-deme spatial files: the most-frequent-genotype grid (grid.csv) and the per-deme genotype counts (genotype_counts_demes.csv).

Parameters:

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

plot_grid

plot_grid(color=None, cmap='viridis', expand_demes=False, ax=None, figsize=(10, 10), dpi=100)

Plot the deme grid, colouring each deme by one or more per-cell attributes.

Rebuilds the per-cell data if stale, then draws one panel per entry in color. "cell_type" shades each deme by its dominant genotype / cell type with a legend; an evolutionary-parameter name, or a snv_ / cnv_ / exp_ + gene key, shades by the per-deme mean value with a colorbar.

Parameters:

Name	Type	Description	Default
color	list of str	Attribute keys to plot (default ["cell_type"]).	None
cmap	str	Matplotlib colormap for the scalar (non cell_type) panels (default "viridis").	'viridis'
expand_demes	bool	Unused placeholder (default False).	False
ax	Axes	Axes to draw into; a new figure is created when None.	None
figsize	tuple	Figure size when a new figure is created (default (10, 10)).	(10, 10)
dpi	int	Figure resolution when a new figure is created (default 100).	100

Returns:

Type	Description
Axes	The axes drawn into.