This repository includes the necessary data, scripts and python code to reproduce the results of:

F Font-Clos, S Zapperi, CAM La Porta. Humanoid global vascular model for circulating tumor cells, The Journal, 1234-56, 2020.
link to publication

In addition, we provide code to solve hemodynamic equations in a directed network, simulate Circulating Tumor Cells (CTC) trajectories on it, and render a 3D-like movie of CTC trajectories in pancreatic cancer. You can see the final video here.

You can simulate your own CTC trajectories using the code/launch_tracers_fullsystem.py file:

python code/launch_tracers_fullsystem.py --help
usage: Launch many tracers from an organ into the blood stream
       --organ ORGAN --network NETWORK -n NUM_TRACERS --output_dir OUTPUT_DIR
       [--verbose] [--drop_trajectories] [--keep_times] [--suffix SUFFIX] [-h]

required arguments:
  --organ ORGAN         Name of recognized organ. See Makefile for list of
                        available organs
  --network NETWORK     Full body network with attachment probabilities
  -n NUM_TRACERS, --num_tracers NUM_TRACERS
                        Number of tracers (to be splitted among available
                        starting points
  --output_dir OUTPUT_DIR
                        Path to output dir

optional arguments:
  --verbose             This is a binary switch flag.
  --drop_trajectories   do not store full trajectories, just final position
  --keep_times          additionaly store simulation time
  --suffix SUFFIX       Suffix to add to output files
  -h, --help            Show this help message and exit.

For instance, to simulate 100 CTC trajectories starting from the pancreas, and store the output in certain path/to/output/dir, labeling your simulations as _my_trajectories, and keeping all information (will produce larger output), you would run:

python code/launch_tracers_fullsystem.py \
				--keep_times \
				--organ pancreas \
				--map_endpoints \
				--suffix _my_trajectories \
				--network output/data/solved_flow_networks/solved_total_closed.p \
				--num_tracers 100 \
				--output_dir path/to/output/dir

This will produce the file path/to/output/dir/pancreas_tracers_100_my_trajectories.p with a size of around 300Mb. The output is stored as a pickled pandas DataFrame, and includes all positions, times and labels of the associated network nodes, for all steps of 100 CTC simulated trajectories. Notice that if you want to compute organ-to-organ probabilities, you can pass the --drop_trajectories flag and omit the --keep_times one to produce much smaller output files.

You can exactly reproduce the manuscript figures by executing the notebooks in the notebooks/ directory:

1. Solve hemodynamic flow eqs on network
2. Compute fraction of cells from simulations
3. Autopsy metastasis freqs
4. Model fraction cells heatmap
5. Whole-body flow plots
6. Model vs data plots
7. Trajectories 2D pancreas

Alternatively, you can run all notebooks in one go with

./run_all_notebooks.sh

which will re-generate all figures of the manuscript.

To render the CTC movie from scratch, you need to install blender 2.8 on a high-performance computer. Notice the video is rendered at very high resolution. The scripts provided in video/ can be used generate 1250 PNG images of size 3840 x 2160 pixels, each of which has a size of 5-15Mb. We include a few sample frames in the video/frames directory.

To install blender on Ubuntu machines, you can use the video/install_blender.sh script. Notice you will need administrator privileges for that. Simply run

cd video
./install_blender.sh

Our blender raw file video/ctc_movie.blend is too large to be hosted on github, but you can get it via this google drive link: ctc_movie.blend. Before trying to render frames, download the blender file and place it in the video/ folder.

Note: we recommend rendering on a large cluster, AWS instance, renderfarm service or similar. Rendering on a standard desktop computer is possible but might weeks.

To render all frames, run the video/install_blender.sh script.

cd video
./render_frames.sh

We use ffmpeg to encode the video from individual PNG frames. Once you have rendered all frames, to obtain large, medium and small size videos in one go run

cd video
./make_ctc_movie.sh

The original mesh files from which the flow network is obtained have been downloaded from the BodyParts3D project:

• BodyParts3D/Anatomography: link to main site | link to download site

The autopsy data comes from several publications, see the manuscript for details. We include hand-curated excel files from which it is easy to retrieve the data used in the manuscript:

• Abrams, 1950: publication | excel file
• Bubendorf, 2000: publication | excel file
• Budczies, 2015: publication | excel file
• diSibio, 2008: publication | excel file
• Schlageter, 2016: publication | excel file

Beyond well-known python packages (numpy, matplotlib, seaborn, pandas, etc), this repository depends on the following:

• pyembree
• trimesh (forked version here)
• K3D-jupyter
• blender (2.8)(installation recommended via this install script for ubuntu)

We recommend installing dependencies in a clean, isolated environment via pipenv, virtualenv or similar. For instance, if you are a conda user, you could do:

conda create --yes --name ctcmodel pip
conda activate ctcmodel
pip install -r requirements.txt