ChasteGuides/RunningCellBasedVisualization

Running the cell-based visualizer

Note: this page describes how to use the java visualizers supplied with the source release. The new, recommended approach is to use Paraview (see tutorials)

To visualize the results of a 2D cell-centre of vertex simulation using Chaste's bespoke visualizers you must

compile the relevant .java file;
run the visualizer from the anim folder.

1. Compile the relevant `.java` file

From the Chaste main directory

[chaste@userpc60 Chaste]$ cd anim
[chaste@userpc60 anim]$ javac Visualize2dCentreCells.java
[chaste@userpc60 anim]$ javac Visualize2dVertexCells.java

There is a clash between these classes, so you may need to recompile the one you want.

2. Run the visualizer from the anim folder

To simply visualize cells, use:

[chaste@userpc60 anim]$ java Visualize2dCentreCells <data_path_and_prefix> <options>
[chaste@userpc60 anim]$ java Visualize2dVertexCells <data_path_and_prefix> <options>

The pathname of the input must come first but the additional arguments output, springs, nocells, ghosts and notcylindrical may appear in any order. The visualizer will warn you if any options are not recognised but will continue running.

The pathname probably looks something like

<data_path_and_prefix> = /tmp/YOUR_USERNAME/testoutput/CHASTE_TEST_NAME/results_from_time_0 
or
<data_path_and_prefix> = /tmp/YOUR_USERNAME/testoutput/CHASTE_TEST_NAME/results_from_time_1.8333

Note that you don't have to specify separate nodes and elements files, just the folder they live in.

The following are command-line options:

Command	Default	Description
`output`	Off	Writes an output to PNG files, which can be converted into an animated GIF (see below)
`springs`	Off	Visualize the springs between the cells
`nocells`	Off	Do not visualize cells
`ghosts`	Off	Visualize ghost nodes and springs (cell-centre only)
`circles`	Off	Visualize cells as overlapping circles of predefined radius
`PDE`	Off	Visualize the solution to a reaction-diffusion PDE associated with the `CellBasedSimulation` (cell-centre only)
`betacatenin`	Off	Displays a 'GFP style' simulation with shading dependent on protein concentrations; this is automatically set to 'On' if `results.vizsetup` has a line which reads `BetaCatenin` (cell-centre only, for use in crypt visualizations)
`notcylindrical`	Off	Supress the cylindrical routine (print to screen exactly what is in the input files). This is automatically set to 'On' if a `results.vizsetup` file with the parameter `MeshWidth` is not supplied. (cell-centre only)
`axes`	On	Visualize x and y axes for the simulation
`axesequal`	On	Visualize x and y axes for the simulation using equal scales
`ancestors`	On*	Visualize the ancestor index of each cell
`orientation`	Off	Visualize cell orientations (cell-centre only)
`potts`	Off	Visualize results as a cellular Potts model (vertex only)

* When the appropriate results files are present.

For example, to switch off cell visualization but draw ghost nodes and springs, use:

[chaste@userpc60 anim]$ java Visualize2dCentreCells <data_path_and_prefix> ghosts springs nocells

Memory

If you get an out of memory error, use

java -Xmn100M -Xms512M -Xmx512M Visualize2dCentreCells <path>

for big simulations (24 hours of big crypts), or even

java -Xmn200M -Xms700M -Xmx700M Visualize2dCentreCells <path>

for really big simulations (50 hours of full sized crypts). See comment 1 in ticket:293

Making an MPEG movie

When you have created image0*.png files in the anim folder (by running the visualizer with the output argument), go to the anim folder (cdchaste then cd anim)and simply type

[chaste@userpc60 anim]$ ./make_a_movie

This creates an MPEG format movie using MPlayer, and seems to compress it, whatever the length, into a file of about 15MB.

Making an animated gif

[chaste@userpc60 anim]$ convert image*.png my_cool_animation.gif

Renaming files

You may want to do this so you can show the results from one simulation following on from another, before making your movie. The following changes the filenames from image0*.png to image2*.png.

[chaste@userpc60 anim]$ for f in image*; do mv $f ${f/image0/image2}; done

Data formats

The cell-centre simulation visualizer Visualize2dCentreCells requires two results files. The first required file is the nodes file (results.viznodes), where each line should be of the form

    time x_1 y_1 x_2 y_2 ... x_n y_n

where (x_1,y_1),...,(x_n,y_n) are points. The second required file is the cell types file (results.vizcelltypes), where each line should be of the form

    time c_1 c_2 ... c_n

where c_1,...,c_n are numbers corresponding to cell types:

0 = stem cell (cyan)
1 = transit cell (yellow)
2 = differentiated cell (pink)
3 = early cancer cell (light grey)
4 = late cancer cell (grey)
5 = labelled cell (purple)
6 = apoptosing cell (dark grey)
7 = sloughed cell or ghost node (invisible (silver), with all connecting edges invisible)

For cell-centre simulations incorporating a Delaunay mesh, an elements results file (results.vizelements) is also required, where each line should be of the form

    time element1_node1 element1_node2 element1_node3 ... elementn_node1 elementn_node2 elementn_node3

The vertex simulation visualizer Visualize2dVertexCells requires all three of the above results files.

An optional fourth results file is the setup file (results.vizsetup), which includes parameters such as

    MeshWidth value
    Cutoff value
    PDE
    BetaCatenin
    Complete

Complete tells the visualizer that this set of results files are finished and it can read the last line safely. N.B. A setup file is required for a cylindrical visualization, to tell the visualizer what the crypt width is.

Other visualizer results files take the form results.viz<whatever>, where <whatever> can currently be any of the following:

betacatenin - for visualizing beta-catenin protein concentrations (cell-centre only, for use in crypt visualizations)
pdesolution - for visualizing the solution to a reaction-diffusion PDE associated with the cell-based simulation (vertex only)
ancestors - for visualizing clonal populations, i.e. populations of cells with common ancestors
orientation - for visualize cell orientations in simulations where cells have preferred orientations (cell-centre only)
stress - for visualizing the stress experienced by each cell (cell-centre only; see the DiscreteSystemForceCalculator class)
vizboundarynodes - for visualizing which nodes lie on the boundary of the cell population (vertex only)

These files should all take the same form as results.viznodes: a row for every time step (with time as first item in the row) followed by a number of variables relating to each cell.

All the files should all be in a folder called vis_results/. The location of this folder is then specified when calling Visualize2dCentreCells.