4DFUCCI

4D FUCCI README File

This README file supplements the code made publicly available on GitHub. It contains a brief guide on how the available code is designed to be run for the reader’s testing, as well as recommendations for some parameter choices depending on available computational power.

System Requirements

• MATLAB R2018a or later
• MEX and C compiler
• Additional note: High performance computing is recommended, with 4 CPUs and 32 GB RAM if setting I = 201. Otherwise, a personal computer is sufficient.

Installation

MATLAB can interpret C code with the mex function. Before running the IBM, ensure that the cells.c file is compiled with MATLAB, using the command

mex cells.c -R2018a

in the command window in MATLAB. A Windows compatible compilation file is provided, (cells.mexw64), but it is recommended that the cells.c file is manually compiled, and required if running on Linux or MacOS, as the interpreting file is not compatible across operating systems

Visualisation of the 3D nutrient profiles require Python, and the packages Plotly, Numpy, Scipy, and Matplotlib. Python can be installed from here, and the packages can be installed with the command,

pip install [package]

in the Command Prompt or Unix terminal.

Running the IBM

Two approaches to running the model are provided in the repository. We make the full IBM simulation code available, as well as an example production of figures with a quick iteration of the simulation.

IBM Code

The IBM itself is contained in the ibm3d.m and cells.c functions. These are called with parameters supplied by hpc_script.m and quick_demo.m.

Full IBM Modelling

The full IBM is recommended for use in high performance computing. To run the full suite of simulations, call the command

for i = 1:10
   hpc_script(i)
end

The input to hpc_script.m, sim_id, is a parameter that identifies the simulation, and sets the initial radius and population. The variability case is provided, and can be uncommented (variables exp_N0 and exp_rad) to select the variable conditions. Also, sim_id acts as a seed for the random number generation, and names the workspaces when saving. The function hpc_script.m saves these workspaces into the Workspaces folder, ready for analysis and figure generation.

Quick example

A quick example of the IBM with a reduced number of nodes (I = 51) and experimental period (T = 144 h) is also provided. This generates all figures created with the full IBM (with the exception of days 7-10 and the Python figures) and is a good, quick example realisation of the IBM. The runtime is approximately 5-6 minutes, including data analysis and figure generation.

Reproducing Figures

With 10 workspaces, the data for figures can be prepared, and the figures can be generated. All code required to reproduce the figures is readily available, however the data plotted in the figures must first be taken from the IBM and prepared for visualisation. To achieve this preparation, run the workspace_analysis.m file. This can be a computationally expensive process and take a large amount of time to complete. To get a quicker example of data visualisation for all 10 days of the simulation, set runcount = 1 on line 52. The file cMap.mat is the workspace variable that defines the colourmap for nutrient profiles. This is loaded in automatically in the code.

When workspace_analysis.m is complete, each figure can be generated by running the corresponding .m file in their corresponding folders. All figures will be saved with the day they correspond to (if appropriate) in their appropriate folders, generated by the figure creation file. For generating 3D nutrient profile plots, one 3D nutrient profile is generated by running nutrient3Dplot.py. To change which time point is plotted, change the variable c_X on line 46 of nutrient3Dplot.py, so that X is between 0 and 10, inclusive. This X corresponds to which day of the simulation is plotted. One nutrient profile per run of nutrient3Dplot.py is plotted so that the Plotly API is not overcrowded, and won't crash the tab in the browser.

Experimental Data

The experimental radius data are collected in the RadiusData folder. IncucyteData.csv contains the data for external radii for a number of experiments, including the radius data for WM793b, with an initial seeding density of 10,000 cells. Files with the name format dayX.csv are the outer, arrested, and necrotic radius estimates from the image processing for experimental images. The data in this folder are used for the generation of Figure 8.

The spheroid experiments, and images that are collected and processed, were performed with the human metastatic melanoma cell line WM793B. For all experimental images, the scale bar corresponds to 200 micrometres. Spheroids were harvested on experiment days 4, 5, 6, 7, 8, 9, 10, 12, and 14, corresponding to 0, 1, 2, 3, 4, 5, 6, 8, and 10 days after spheroid formation.

2D Spheroid Slices

The 2D spheroid slice images are labelled according to the template DX_Y_(type)_(ut/lt). Each segment of this template is explained below:

• DX corresponds to the day of the experiment for which the spheroid was harvested. The value of X specifically corresponds to the number of days after seeding.
• Y corresponds to the spheroid replicate harvested on Day X and mounted for imaging
• The (type) label of an image may be one of:
  • dapi -- indicating that the image is of the DAPI nucleus staining in the spheroid.
  • draqonly -- indicating that the image is exclusively of the DRAQ7 necrotic cell staining in the spheroid, with the background DRAQ7 removed.
  • nodraq -- indicates experimental images that have both red and green FUCCI channels, without DRAQ7 staining.
  • draq -- for experimental images with red and green FUCCI channels and DRAQ7 staining.
  • processed -- denotes experimental images processed and analysed with the image processing algorithm to estimate the outer, arrested, and necrotic radii (marked with white dashed lines).
  • hyp -- for experimenal images stained for hypoxia with pimonidazole.
• (ut/lt) is optional, and indicates all previous information (where relevant) for an experimental image taken at the upper tropic or lower tropic, respectively. For spheroids without a substantial necrotic core, this corresponds to half of the distance between the equator and top or bottom of the spheroid. With a significant necrotic core, the spheroid tropics are defined as the heights corresponding to the top or bottom of the necrotic cores.

3D Spheroid Images

The 3D spheroid images are similarly labelled, with the template DX_Y_3D_(half), where each template segment is:

• DX represents the day of the experiment corresponding to the spheroid harvesting, after seeding the spheroid.
• Y is the spheroid replicate from Day X and mounted for imaging.
• 3D indicates that the image is a 3D spheroid picture
• (half) is optional, and indicates that the spheroid is a hemisphere picture.

Experimental images

The spheroid replicates that have a full set of intact equator, upper tropic, and lower tropic images are:

• D4 -- 1, 2, 3, 4
• D5 -- 1, 2, 3, 4
• D6 -- 1, 2, 3, 4, 5
• D7 -- 2, 3, 4, 6, 7, 8
• D8 -- 1, 2, 3, 4, 5, 6
• D9 -- 1, 2, 3, 4, 5, 6, 7, 8
• D10 -- 1, 2, 4, 5, 6, 7, 8
• D12 -- 1, 2, 4, 5, 6, 7, 8
• D14 -- 1, 2, 3, 4, 5, 6, 7, 8