API Documentation

The ‘TModel’ class for model creation and execution

class TCAMpy.TModel(cycles, side, pmax, PA, CCT, Dt, PS, mu, ad, I, M)[source]

Bases: object

Class for a cellular automata, modeling tumor growth.

Parameters:

  • cycles (int) – duration of the model given in hours

  • side (int) – the length of the side of field (10um)

  • pmax (int) – maximum proliferation potential of RTC

  • PA (int) – chance for apoptosis of RTC (in percent)

  • CCT (int) – cell cycle time of cells given in hours

  • Dt (float) – time step of the model given in days

  • PS (int) – STC - STC division chance (in percent)

  • mu (int) – the migration capacity of cancer cells

  • ad (float) – cell-cell adhesion strength (0-1)

  • I (int) – strength of the immune cells (1-5)

  • M (int) – tumor mutation chance (in percent)

animate(mode)[source]

Creates and returns animation of the growth.

Parameters:

mode (int) – create figure, save frame or display animation. (1-3)

Returns:

the animation of the growth (optional)

Return type:

ArtistAnimation

cell_step(x, y, step_type)[source]

The function that makes a single cell do one of the following actions: prolif STC - STC, prolif STC - RTC, prolif RTC - RTC, migration (1-4). New mutations can appear every time a cell proliferates with M chance.

Parameters:

  • x (int) – representing the coordinates of the cell

  • y (int) – representing the coordinates of the cell

  • step_type (int) – type of division or migration (1-4)

count_tumor_cells()[source]

Saves the number of STCs/RTCs to self.stc_number/self.rtc_number.

find_tumor_cells(get_border=True)[source]

Saves the coordinates of tumor cells to self.tumor_cells.

Parameters:

get_border (bool) – enables saving the tumor border separately.

get_neighbours(x, y, neighbour_type)[source]

Returns the neighboring coordinates of a given cell in a 2D NumPy matrix.

Parameters:

  • x (int) – representing the coordinates of the cell

  • y (int) – representing the coordinates of the cell

  • neighbour_type (int) – type of neighboring cells (1-5)

Returns:

a list with the coords of the neighbouring cells

Return type:

list

get_prolif_potentials()[source]

Returns a dictionary of proliferation potential numbers.

Returns:

a dictionary of the proliferation potentials

Return type:

dict

get_statistics()[source]

Returns various statistical properties of the model.

Returns:

a dictionary of the statistical properties

Return type:

dict

immune_response(offset=10, alpha=0.002, it_targ=0.1, infil=0.3)[source]

The function that simulates immune cells. Spawns, moves and activates immune cells.

Parameters:

  • offset (int) – distance of spawnpoints (“frame”) from the tumor

  • alpha (float) – controls strength (slope) of immune exhaustion

  • it_targ (float) – desired mean immune/tumor ratio during simulation

  • infil (float) – “searching/infiltrating” threshold for wbcs (0-1)

init_array()[source]

Initializes/resets the arrays of statistical information.

init_state()[source]

Creates the initial state with one STC in the middle. Creates the field for immune cells and mutations too.

measure_runtime()[source]
mod_cell(x, y, value)[source]

Modifies cell value. (Create initial state before this!)

Parameters:

  • x (int) – representing coordinates of the cell

  • y (int) – representing coordinates of the cell

  • value (int) – the new value at the given position

mutate_probs(chances, x, y)[source]

The function that changes the cell action chances based on the current mutation status of the cell.

Parameters:

  • chances (list of float) – the base action chances

  • x (int) – representing coordinates of the cell

  • y (int) – representing coordinates of the cell

plot_averages(data)[source]

The function that plots the averages of multiple model results. Works with the results of the ‘run_multimodel’ function.

Parameters:

data (pd.DataFrame) – Your data in a pandas dataframe format

Returns:

The plots of the averages with SD values

Return type:

matplotlib.figure.Figure

plot_run(run, boundaries=5)[source]

Creates growth and cell number plots, proliferation potential histograms.

Paramteres:

run (int): which model execution to plot boundaries (int): number of boundaries to plot

Returns:

the generated plots of the specific run

Return type:

matplotlib.figure.Figure

run_model(plot, animate, stats)[source]

The function that runs a single entire simulation. For animation matplotlib backend cannot be inline!

Parameters:

  • plot (bool) – set to true to display the plots of the model

  • animate (bool) – set to true to enable matplotlib animation

  • stats (bool) – set to true to print statistics of the model

run_multimodel(count, init_field, plot, stats)[source]

Runs the model multiple times and returns a DataFrame of statistics.

Parameters:

  • count (int) – number of times to run the simulation

  • init_field (np.array) – custom initial state of field/run

  • plot (bool) – set to true to display the plots of the model

  • stats (bool) – set to true to print statistics of the model

Returns:

collected statistics from each run

Return type:

pd.DataFrame

save_field_to_excel(file_name)[source]

Saves the current state of self.cancer to an excel file.

Parameters:

file_name (str) – name of the excel file

save_statistics(file_name)[source]

Saves various statistical properties of the model to an excel file.

Parameters:

file_name (str) – name of the excel file

separate_columns(data)[source]

Separates the statistics DataFrame columns into logical groups: base stats, STC, RTC, WBC counts, area/radius data and pp values.

Parameters:

data (pd.DataFrame) – Your data in a pandas dataframe format

Returns:

A tuple containing 7 lists of column names:

  • base: Columns with general statistical properties

  • stc: Columns with STC counts at each time point

  • rtc: Columns with RTC counts at each time point

  • wbc: Columns with WBC counts at each time point

  • area: Columns with area data at each time point

  • arad: Columns with radius data at each time point

  • pp: Columns for proliferation potential values

Return type:

tuple of list[str]

store_model()[source]

Stores the results of the previous model executions.

tumor_action()[source]

This is the function that decides what action a cell will do. Either kills the cell or calls the ‘cell_step’ function. This function goes through every single cell in the field.

The ‘TDashboard’ class for dashboard creation

class TCAMpy.TDashboard(model)[source]

Bases: object

Class for a Streamlit dashboard providing a GUI for the model.

Parameters:

model (TModel) – The created model you want a dashboard for

_create_bar_chart(h, pp, std=None)[source]

Creates an Altair bar chart for proliferation potential distribution.

Parameters:

  • h (int) – the height of the plot

  • pp (list of float or int) – Mean or raw counts of cells per proliferation potential class

  • std (list of float, optional) – Standard deviation for each class

Returns:

An Altair chart representing the distribution of proliferation potentials

Return type:

alt.Chart

_create_heatmap(h, title, cmap, ctitle, vmin, vmax, heatmap, scatter=None)[source]

Creates an Altair heatmap with a scatter plot overlaid. Used for tumor field with immune cells, and mutations.

Parameters:

  • h (int) – the height of the plot

  • title (string) – title of the plot

  • cmap (stirng) – colormap for the heatmap

  • vmin (int) – domain for the colormap

  • vmax (int) – domain for the colormap

  • heatmap (2D array-like) – array for the heatmap

  • scatter (2D array-like) – array for scatter plot

Returns:

heatmap with scatter overlay

Return type:

Altair.Chart

_create_line_chart(h, stc, rtc, wbc, stc_l=None, stc_u=None, rtc_l=None, rtc_u=None, wbc_l=None, wbc_u=None)[source]

The function that creates an Altair line chart of the cell numbers.

Parameters:

  • h (int) – the height of the plot

  • stc (list) – a list of the cell and immune numbers (mean or raw)

  • rtc (list) – a list of the cell and immune numbers (mean or raw)

  • wbc (list) – a list of the cell and immune numbers (mean or raw)

  • stc_l (list of float, optional) – Lower bounds (e.g., mean - SD) for cell counts.

  • rtc_l (list of float, optional) – Lower bounds (e.g., mean - SD) for cell counts.

  • wbc_l (list of float, optional) – Lower bounds (e.g., mean - SD) for cell counts.

  • stc_u (list of float, optional) – Upper bounds (e.g., mean + SD) for cell counts.

  • rtc_u (list of float, optional) – Upper bounds (e.g., mean + SD) for cell counts.

  • wbc_u (list of float, optional) – Upper bounds (e.g., mean + SD) for cell counts.

Returns:

represents the line chart of the cell numbers

Return type:

Altair.Chart

_execute_model()[source]

The function for model running logic.

_initialize()[source]

The function that sets the parameters and initializes the model.

_modify_cell()[source]

The function for initial state modification logic.

_reset_save_stats()[source]

The function for the reset/download statistics logic.

_show_statistics()[source]

The function for the statistics printing logic.

_simdata_generator()[source]

The Machine Learning tab for dataset generation and download. Uses the TML class to generate simulation data.

_train_and_predict()[source]

Streamlit UI for model training and prediction using the TML class.

_visualize_run(title, run)[source]

The function for the result visualization logic.

Parameters:

  • title (string) – title of the visualization

  • run (int) – which model execution to plot

get_plot_height(col, scaler)[source]

The function that calculates the height of plots based on screen width, column width and a scaler.

Parameters:

  • col (int) – main column number

  • scalar (float) – scaler for column width

print_title(title)[source]

The function that prints text as a title on the dashboard.

Parameters:

title (string) – The text to print

run_dashboard()[source]

The function that creates the entire streamlit dashboard for the model.

The ‘TML’ class for Machine Learning tasks

class TCAMpy.TML(model)[source]

Bases: object

Class for handling Machine Learning tasks related to the tumor model. Allows dataset generation, parameter exploration, and result export. Allows predicting the size/confluence for a new set of parameters.

Parameters:

model (TModel) – a created instance of the TModel class.

generate_dataset(n=50, random_params=None, output_file='tumor_dataset.csv')[source]

Generate a dataset of tumor simulations by randomizing given parameters.

Parameters:

  • n_sims (int) – Number of simulations to run.

  • randomize_params (dict) –

    Parameters to randomize, e.g. {

    ”PA”: (1, 20), “PS”: (10, 40))

    }

  • output_file (str) – CSV filename to save dataset.

Returns:

Combined DataFrame with all simulation results.

Return type:

pd.DataFrame

predict_new(params)[source]

Predicts an attribute value for a set of parameters using a previously trained model.

Parameters:

params (list) – List of parameters, e.g. [500, 50, 10, 1, 24, 1/24, 15, 4, 4, 10]

Returns:

Predicted tumor size or confluence

Return type:

float

train_predictor(file, target, test_size=0.2, random_state=42, n_estimators=200)[source]

Trains a regression model to predict final tumor size based on simulation parameters.

Parameters:

  • file (str) – CSV file containing the dataset

  • target (str) – Column name of the target attribute

  • test_size (float) – Fraction of dataset to use for testing

  • random_state (int) – Random seed for reproducibility

  • n_estimators (int) – Number of trees in the random forest

Returns:

Trained model metrics (dict): R^2 and MAE metrics on test set

Return type:

model (RandomForestRegressor)