Updated ECM density and anisotropy to be more readily available to rest of code for use in rules. Extensive update of readme. Added in shell scripts.

Author: johnmetzcar

README.md

@@ -7,7 +7,29 @@
 
 In this framework [[1](#references)] for modeling the ECM and cell-ECM interactions, we divide the ECM into volumetric elements that track local ECM density, alignment, and overall anisotropy (local microstructure). Individual cell agents can locally remodel each of these properties, while these properties can in turn influence cell behavior including changes in migration speed, chemotactic response, ECM contact guidance, proliferation, death, secretion, and differentiation. It is implemented as an extension of the open source package PhysiCell [[2]](#references) and can readily be used to incorporate local ECM effects into agent-based models, in particular through PhysiCell rules [[3]](#references). 
 
-For additional details and background on the components of this framework, see [1](#references)
+For additional details and background on the components of this framework, see [[1](#references)]
+
+## Overview of repository structure and key files
+
+### ECM and cell-ECM core files
+
+All the examples use the same core source code files. These are the core of the framework and its extension to PhysiCell. They are:
+
+- `extracellular_matrix.h/extracellular_matrix.cpp`
+    - Contains the ECM element and ECM mesh class definitions and other initilization routine
+- `cell_ECM_interactions.h/cell_ECM_matrix.cpp`
+    - Contains functions for the bidirectional cell-ECM interactions, generating a default ECM compatible agent, and custom output routines
+
+These files are currently located in `custom_modules`. 
+
+### Model files
+
+There are three example models, several variants of the leader-follower model, and simple test models. See the below `Compling and running sample models` below for details on those models. 
+
+There is one makefile for all compilation. It is located in the `root`. 
+
+Each base model has a main_XXX.cpp (in `root`), custom source code (in `custom_code`), and one to several additional model specficifcation files in `config` - always including an XML-based model config file and sometimes including PhysiCell rules and initial cell position files (both .csv's). The config directory also contains special XML-bassed model files for testing and making stochastic replicates. 
+
 
 ## Using the framework
 
@@ -21,6 +43,8 @@ There are 3 main sample models as well as a series of simple tests. Listed below
 
 `make` - compiles the AMIGOS-invasion executable
 
+The following output directories will need made to run the simulations below: `simple_test0`, `simple_test1`, `simple_test3`, and `simple_test4`. `simple_test2` is already in the repository.
+
 Simple tests - demonstrating the main cell-ECM interactions as one way (either ECM remodeling or ECM following) experiments:
 
 - `./AMIGOS-invasion config/simple_test0_straight_ECM.xml` - ECM following: random 1-D motion along vertically oriented ECM
@@ -35,16 +59,22 @@ Simple tests - demonstrating the main cell-ECM interactions as one way (either E
 
 - `./fibrosis config/fibrosis.xml` - simulated tissue insult is cleared by macrophages, which recruit fibroblasts that increase ECM density in the presence of macrophages, leading to hyperdense ECM that is relatively impenetrable cells surrounding a region of relatively less dense ECM where the tissue insult occurred (Figure 3 from [[1](#references)]).
 
+Output will go to `fibrosis_test`
+
 #### _Basement membrane degradation and stromal invasion_:
 
 `make invasive_carcinoma` - compiles invasive carcinoma executable
 
 - `./invasive_carcinoma config/invasive_carcinoma.xml` - simulation of basement membrane degradation by tumor recruited fibroblasts, leading to invasion of stroma by previously _in situ_ tumor (Figure 4 from [[1](#references)]).
 
+Output will go to `invasive_carcinoma_output`
+
 #### _Leader-follower and collective migration model_:
 
 `make` - compiles the AMIGOS-invasion executable
 
+The following output directories will need made to run the simulations below: `adh_0_repulsion_0_speed_10_no_reading`, `adh_0_repulsion_0_speed_10_no_writing`, `adh_0_repulsion_0_speed_10`, `adh_10_replusion_25_speed_080`, `adh_10_replusion_25_speed_050`, `adh_10_replusion_25_speed_010`, and `leader_follower_decreased_remodeling`. `leader_follower` is already in the repository. 
+
 - `./AMIGOS-invasion writing_only.xml`- No contact guidance in the follower cell population - notably lacks outward migration of fiber following cells ("followers") (Figure 5a from [[1](#references)])
 - `./AMIGOS-invasion reading_only.xml` - No production of directional cues in ECM for followers to follow - notably lacks outward migration of fiber following cells (Figure 5b from [[1](#references)])
 - `./AMIGOS-invasion writing_and_reading.xml` - Enables the two cell populations (leader and follower), with leaders producing paths in the ECM that followers follow (stigmergy) (Figure 5c from [[1](#references)])
@@ -56,15 +86,15 @@ Simple tests - demonstrating the main cell-ECM interactions as one way (either E
 
 ### Running through the Studio
 
-All the above models (and in general any PhysiCell model) can be run via the PhysiCell Studio ([User Guide](https://github.com/PhysiCell-Tools/Studio-Guide/blob/main/README.md) and reference [[x]](#references)). 
+All the above models (and in general any PhysiCell model) can be run via the PhysiCell Studio ([User Guide](https://github.com/PhysiCell-Tools/Studio-Guide/blob/main/README.md) and reference [[4]](#references)). 
 
 Briefly, to run an ECM-based model AND enable visualization of the ECM variables (anisotropy, density, and orientation), use the following pattern to start the Studio:
 
 `python path_to_studio_directory/studio_ecm.py -e [executable_name] -c [config/config_file_name]`
 
-This assumes you are invoking python in the same directory as the executable and that your config file is in `config`. Note that in the command above, we use `studio_ecm.py` NOT `studio.py`. Using `studio_ecm.py` will add built in ECM field visualization to the Studio. However, this is not an officially supported feature of the Studio, so it may at some point be deprecated without notice. We will attempt to maintain compatiability. 
+This assumes you are invoking python in the same directory as the executable and that your config file is in `config`. Note that in the command above, we use `studio_ecm.py` NOT `studio.py`. Using `studio_ecm.py` will add built-in ECM field visualization to the Studio. However, this is not an officially supported feature of the Studio, so it may at some point be deprecated without notice. We will attempt to maintain compatiability. 
 
-Note that the ECM-based models are modifiable in the regular version of the studio, but the ECM visualization is not. Please see the PhysiCell Studio Guide and preprint for general information and details on the Studio.
+Note that the ECM-based models are modifiable in the regular version of the studio, but the  ECM visualization is not. Please see the PhysiCell Studio Guide and preprint for general information and details on the Studio.
 
 ### nanoHUB
 
@@ -75,21 +105,17 @@ A cloud-based, executable version of the leader-follower model is available at [
 
 In addition to the standard PhysiCell outputs, our model outputs an ECM specific MATLAB file at each save time.  The file is saved to the `output` folder with the form `outputxxxxxxxx_ECM.mat` where `xxxxxxxx` is the _i_ th simulation output.  The MATLAB file contains one array named `ECM_Data` with each column representing a voxel (indexed using voxel id) and rows representing the x, y, and z voxel coordinates, ECM anisotropy, ECM density, and fiber orientation x, y, and z components.  
 
+ECM anisotropy and density can also be output to non-diffusing fields through the function `copy_ECM_data_to_BioFVM` in `cell_ECM_interactions.cpp`. Currently, this is enabled by uncommenting the line `// copy_ECM_data_to_BioFVM();` in each models main file. Note that to use this feature, the model needs to have the fields `ECM_anisotropy` and `ECM_density` in the model config file (xml file) and the ECM element size has to match the diffusion voxel size. These fields can be added to any model config file through the Studio - make a new field, change the field name to match the above exactly and accept the defaults (0 for everything). Do this twice. 
+
 ## ECM visualization
 
 This data can be visualized using the README and scripts in [python_imaging](python_imaging/). We provide general image production through a general template script [image_processing_script.py](python_imaging/image_processing_script.py) which accesses the *PhysiCellPlotter* class in the module *Image processing for PhysiCell* in [image_processing_for_physicell.py](python_imaging/image_processing_for_physicell.py). For image production settings optimzied for the default parameter settings, see [partial_history_multilevel_contour_still.py](python_imaging/partial_history_multilevel_contour_still.py) and [partial_history_multilevel_contour_movie.py](python_imaging/partial_history_multilevel_contour_movie.py). This script will make an overlaying composite plot of cells (leaders are blue and followers are yellow), a contour plot showing oxygen (in red) and a quiver plots showing cell movement history. Note that we do our best to ensure that all code and scripts in `python_imaging` work without alteration and as expected - and please consider it to be a preliminary release that is not guanteed to work and that may change in the future. 
 
-## Future work
-
-- Remove deprecated user_parameters from all model files and code base. 
-- Add "Exploration of leader-follower collective migration model" into README (using previous, but currently out of date material). 
-    - Could include several model walk throughs by video
-    - Could include more in depth context for the leader-follower collective migration
-    - Could include more on the ECM model details (again out of date material is available for updating)
+For rapid visualization, the Studio can be used - in either regular or ECM mode. Note that if ECM anisotropy and density are output to the standard microenvironment outputs, they can visualized with regular version of the Studio. 
 
 ## Running PhysiCell simulations across a team
 
-PhysiCell can be run in a distributed fashion across a team using DAPT: Distributed Automated Parameter Testing [5]. See the coder [here](https://github.com/BenSDuggan/DAPT) including a [detailed PhysiCell example](https://github.com/PhysiCell-Tools/DAPT-example).
+PhysiCell can be run in a distributed fashion across a team using DAPT: Distributed Automated Parameter Testing [5]. See the code [here](https://github.com/BenSDuggan/DAPT) including a [detailed PhysiCell example](https://github.com/PhysiCell-Tools/DAPT-example).
 
 ## Some key makefile rules
 
@@ -107,23 +133,35 @@ make zip-source         : compresses all files required to reproduce simulation
 
 See makefile for additional rules. 
 
+## Future work
+
+- Remove deprecated user_parameters from all model files and code base. 
+- Add "Exploration of leader-follower collective migration model" into README (using previous, but currently out of date material). 
+    - Could include several model walk throughs by video
+    - Could include more in depth context for the leader-follower collective migration
+    - Could include more on the ECM model details (again out of date material is available for updating)
+- Review optimal way to include `copy_ECM_data_to_BioFVM`
+    - Will possibly add an XML parameter for this
+    - Will review possibly calling at mechanics or phenotype time step (currently being called at diffusion time step)
+- Additonal future work is included in [[1](#references)]
 
 ## Acknowledgements
 
 This work was funded in part by a joint (AMIGOS) JKTGF and BCRF grant. We thank Margherita Botticelli for many productive conversations on the cell-ECM interaction code.
 
 ## References
 
-[1] Metzcar, J, Duggan, BS, Fischer, B, Murphy, M, Heiland, R., Macklin, P. A simple framework for agent-based
-modeling with extracellular matrix. bioRxiv 2022.11.21.514608; doi: [https://doi.org/10.1101/2022.11.21.514608](https://doi.org/10.1101/2022.11.21.514608)
+[1] Metzcar, J., Duggan, B.S., Fischer, B., Murphy, M., Heiland, R., Macklin, P, 2024. A simple framework for agent-based modeling with extracellular matrix. bioRxiv 2022.11.21.514608; https://doi.org/10.1101/2022.11.21.514608
+
+[2] Ghaffarizadeh, A., Heiland, R., Friedman, S.H., Mumenthaler, S.M., and Macklin, P. PhysiCell: an Open Source Physics-Based Cell Simulator for Multicellular Systems, PLoS Comput. Biol. 14(2): e1005991, 2018. https://dx.doi.org/10.1371/journal.pcbi.1005991
+
+[3] Johnson, J.A.I., Stein-O’Brien, G.L., Booth, M., Heiland, R., Kurtoglu, F., Bergman, D.R., Bucher, E., Deshpande, A., Forjaz, A., Getz, M., Godet, I., Lyman, M., Metzcar, J., Mitchell, J., Raddatz, A., Rocha, H., Solorzano, J., Sundus, A., Wang, Y., Gilkes, D., Kagohara, L.T., Kiemen, A.L., Thompson, E.D., Wirtz, D., Wu, P.-H., Zaidi, N., Zheng, L., Zimmerman, J.W., Jaffee, E.M., Chang, Y.H., Coussens, L.M., Gray, J.W., Heiser, L.M., Fertig, E.J., Macklin, P.. Digitize your Biology! Modeling multicellular systems through interpretable cell behavior. bioRxiv, 2023. https://doi.org/10.1101/2023.09.17.557982
 
-[2] Ghaffarizadeh, A, Heiland, R, Friedman, SH, Mumenthaler, SM, and Macklin, P. PhysiCell: an Open Source Physics-Based Cell Simulator for Multicellular Systems, PLoS Comput. Biol. 14(2): e1005991, 2018. DOI: [10.1371/journal.pcbi.1005991](https://dx.doi.org/10.1371/journal.pcbi.1005991)
 
-[3] Cheung KJ, Gabrielson E, Werb Z, Ewald AJ. Collective invasion in breast cancer requires a conserved basal epithelial program. Cell 2013; 155(7):1639-51. [10.1016/j.cell.2013.11.029](10.1016/j.cell.2013.11.029)
+[4] Heiland, R., Bergman, D., Lyons, B., Cass, J., Rocha, H.L., Ruscone, M., Noël, V., Macklin, P.. PhysiCell Studio: a graphical tool to make agent-based modeling more accessible. bioRxiv, 2023 https://doi.org/10.1101/2023.10.24.563727
 
-[4] Nguyen-Ngoc KV\*, Cheung KJ*, Brenot A, Shamir ER, Gray RS, Hines WC, Yaswen P, Werb Z, Ewald AJ. The ECM microenvironment regulates collective migration and local dissemination in normal and malignant mammary epithelium. Proceedings of the National Academy of Science 2012; [10.1073/pnas.1212834109](10.1073/pnas.1212834109) *Co-First Authors. PMCID: PMC3465416
+[5] Duggan, B.S., Metzcar, J., and Macklin, P. DAPT: A package enabling distributed automated parameter testing. Gigabyte 2021, 1–10, 2021. https://doi.org/10.46471/gigabyte.22
 
-[5] Duggan, BS, Metzcar, J, and Macklin, P (2021). DAPT: A package enabling distributed automated parameter testing. Gigabyte 2021, 1–10. [10.46471/gigabyte.22](10.46471/gigabyte.22).
 
 
 **Latest PhysiCell info:**  follow [@PhysiCell](https://twitter.com/PhysiCell) on Twitter (http://twitter.com/PhysiCell)

custom_modules/cell_ECM_interactions.cpp

@@ -8,7 +8,7 @@ extern ECM ecm;
 
 
 
-void copy_ECM_data_to_BioFVM( Cell* pCell, Phenotype& phenotype, double dt )
+void copy_ECM_data_to_BioFVM( void )
 {
 
 
@@ -25,12 +25,20 @@ void copy_ECM_data_to_BioFVM( Cell* pCell, Phenotype& phenotype, double dt )
 	if (ECM_anisotropy_index < 0) 
     {
         std::cout << "        static int ECM_anisotropy_index = " <<ECM_anisotropy_index << std::endl;
+		std::cout << "        ADD ECM_anisotropy field to your simulation!!!" << std::endl;
+		std::cout << "        This feature only works with ECM_anisotropy field added to your simulation. Set decay and diffusion constant to 0" << std::endl;
+		std::cout << "        AND match ECM element size to the diffusion voxel size!!!" << std::endl;
+		std::cout << "        Halting!!!!!!" << std::endl;
         std::exit(-1);   
     }
 	static int ECM_density_index = BioFVM::microenvironment.find_density_index( "ECM_density" ); 
 	if (ECM_density_index < 0) 
     {
         std::cout << "        static int ECM_density_index = " <<ECM_density_index << std::endl;
+		std::cout << "        ADD ECM_density field to your simulation!!!" << std::endl;
+		std::cout << "        This feature only works with ECM_density field added to your simulation. Set decay and diffusion constant to 0!!!" << std::endl;
+		std::cout << "        AND match ECM element size to the diffusion voxel size!!!" << std::endl;
+		std::cout << "        Halting!!!!!!" << std::endl;
         std::exit(-1);   
     }
     for( int n=0; n < number_of_voxels ; n++ )

custom_modules/cell_ECM_interactions.h

@@ -4,7 +4,7 @@
 using namespace BioFVM; 
 using namespace PhysiCell;
 
-void copy_ECM_data_to_BioFVM( Cell* pCell, Phenotype& phenotype, double dt );
+void copy_ECM_data_to_BioFVM( void);
 
 double dot_product_ext( const std::vector<double>& v , const std::vector<double>& w );
 

custom_modules/extracellular_matrix.h

@@ -68,7 +68,7 @@ class ECM_options
 };
 
 
-void copy_ECM_data_to_BioFVM( void );
+// void copy_ECM_data_to_BioFVM( void );
 
 // extern ECM_options default_ecm_options; 
 // extern ECM ecm;

main-ecm.cpp

@@ -305,6 +305,8 @@ int main( int argc, char* argv[] )
 			{
 				microenvironment.simulate_diffusion_decay( diffusion_dt );
 			}
+
+			// copy_ECM_data_to_BioFVM();
 
 			// run PhysiCell 
 			((Cell_Container *)microenvironment.agent_container)->update_all_cells( PhysiCell_globals.current_time );

main_fibrosis.cpp

@@ -262,6 +262,8 @@ int main( int argc, char* argv[] )
 			// if(parameters.bools("freeze_uE_profile")==true)
 
 			microenvironment.simulate_diffusion_decay( diffusion_dt );
+
+			// copy_ECM_data_to_BioFVM();
 
 			// run PhysiCell 
 			((Cell_Container *)microenvironment.agent_container)->update_all_cells( PhysiCell_globals.current_time );

main_invasive_carcinoma.cpp

@@ -258,6 +258,8 @@ int main( int argc, char* argv[] )
 			{
 				microenvironment.simulate_diffusion_decay( diffusion_dt );
 			}
+
+			// copy_ECM_data_to_BioFVM();
 
 			// run PhysiCell 
 			((Cell_Container *)microenvironment.agent_container)->update_all_cells( PhysiCell_globals.current_time );

shell_scripts/make_all_executables.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+make -j4
+make fibrosis -j4
+make invasive_spheroid -j4

shell_scripts/make_continous_remodeling_leader_follower_movies_and_stills.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Script for making leader-follower movies and stills. Assumes data is already run!!!
+
+# leader follower
+cp python_imaging/partial_history_multilevel_contour_movie.py leader_follower/
+cp python_imaging/partial_history_multilevel_contour_still.py leader_follower/
+cd leader_follower
+python partial_history_multilevel_contour_movie.py
+cp multi_color_movie.mp4 ../1_images_for_paper/leader_follower.mp4
+python partial_history_multilevel_contour_still.py 480 1920
+cp multi_contour_still_480.png ../1_images_for_paper/continous_remodeling_speed_050_2880_minutes.png
+cp multi_contour_still_1920.png ../1_images_for_paper/continous_remodeling_speed_050_11520_minutes.png
+
+cd ..
+cp python_imaging/partial_history_multilevel_contour_movie.py leader_follower_decreased_remodeling/
+cp python_imaging/partial_history_multilevel_contour_still.py leader_follower_decreased_remodeling/
+cd leader_follower_decreased_remodeling
+python partial_history_multilevel_contour_movie.py
+cp multi_color_movie.mp4 ../1_images_for_paper/leader_follower_decreased_remodeling.mp4
+python partial_history_multilevel_contour_still.py 480 1920
+cp multi_contour_still_480.png ../1_images_for_paper/continous_remodeling_decreased_remodeling_2880_minutes.png
+cp multi_contour_still_1920.png ../1_images_for_paper/continous_remodeling_decreased_remodeling_11520_minutes.png
+
+
+
+
+
+
+
+