CaTSiT

Using CaTSiT

• Preparations
• Running a simulation
• Running multiple iterations
• Output file

Preparations

To use CaTSiT, first, you need a main configuration file where your simulation setup is defined. You can download sample configuration files and change them as you like or create a new one according to the XML-Schema.

Next, you need a technical configuration file where you define the time span that the simulation shall cover and the interval at which the current state of the simulated system shall be saved. You can download a sample technical configuration file and change the values duration and timeStepsForSaving as you like. Both values are given in days.

Running a simulation

To start a simulation run open a command line tool of your choice (e.g. cmd in Windows or console in Linux) and change into the CaTSiT folder:

Now you can start the simulation with the following command. Please note that you have to state the absolute file paths to the output file and both configuration files!

Example Windows (all in one line, no new line): Example Linux (all in one line, no new line):

Depending on the configuration (many or few metastases, duration) and the equipment of your pc the simulation can take between some seconds and several minutes. If the simulation takes to long try to decrease the duration in the technical configuration file.

If the simulation aborts with a java.lang.OutOfMemoryError exception, you can evade this error by assigning a higher maximum heap size to the simulation process via the java parameter -Xmx4g. The number represents the number of Gigabyte to assign:

You can save several iterations of a simulation setup in one output file. Just use another sheet name. However, the more simulation runs are already stored in the output file the longer it takes for the software to open the file and save the current simulation results. Therefore, if you want to simulate more than 5 iterations of a simulation setup we recommend to use the provided scripts (runMultipleSims.bat for Windows and runMultipleSims.sh for Linux). The usage of the scripts is described in the next section.

Running multiple iterations

If you want to simulate several iteration of a simulation setup please use the script runMultipleSims.bat for Windows or runMultipleSims.sh for Linux. You will find both scripts in the folder 'scripts' in the main CaTSiT folder.
The script will create a folder and run a certain number of iteration of the given configuration file. All single output files will be merged into one single spreadsheet file. The configuration files will be copied into the same folder so that the configurations files and the simulation results are all stored in one place.
Before you can use the scripts you have to change the variable simPath in line 8 to the path of the CaTSiT folder. In line 66 or 73 you can adjust the number of iterations. The default number of iterations is 100.

Now you can change into the scripts folder and start the script with the following command via the command line. Please note that you have to state the absolute file paths to the output folder and both configuration files!

Windows: Linux:

Possibly you have to change the permissions of the script in Linux before you can execute it. You can do this as followed:

Output file

CaTSiT regularly saves the status of the whole simulated system and writes them into a spreadsheet at the end of the simulation. The spreadsheet is saved in an excel file format (xlsx - Excel 2007 or higher). This file can also be opened with the program LibreOffice Calc.
The interval for saving the current status and the duration that the simulation shall cover can be parametrized in the technical configuration file via the tags timeStepsForSaving and duration. Both values are given in days. Please note, that both values directly influence the size of the output file. For fast growing tumours use small time step values and a short duration to keep track of the progress. For slowly growing tumours user larger time step values (e.g. 10-30) to avoid unnecessary large output files.

If you save more than one simulation run in the output file you can use the formulas of your spreadsheet tool to compute the mean and standard deviation of all simulation runs (e.g. AVERAGE and STDEV in Excel or LibreOffice Calc).

The output file is structured as follows:

Column	Content
A	current time in minutes
B	current time in days
C	number of cells in the primary tumor
D	number of cells in the bloodstream
E	number of metastases
F	number of cells in all metastases
G - IR	Size histogram of all metastases. The size histogram is printed in pairs: The first value represents the upper limit of the current size range and the second value the number of metastases in the current size range (the lower limit is the upper limit of the previous size range or 0 for the very first size range). The size ranges are segmented logarithmically.

If parametrized, separate output files are created for the individual host organs. Whether a separate output file shall be created for a host organ can be parametrized separately for each host organ in the main configuration file (see tag printHostOrgan at the configuration of host organs).
An output file for a host organ is structured as follows:

Column	Content
A	current time in minutes
B	current time in days
C	number of metastases in the corresponding host organ
D	number of cells in all metastases in the corresponding host organ
E - IP	Size histogram of all metastases in the corresponding host organ. The size histogram is printed in pairs: The first value represents the upper limit of the current size range and the second value the number of metastases in the current size range (the lower limit is the upper limit of the previous size range or 0 for the very first size range). The size ranges are segmented logarithmically.