XML based Cell Definitions

Currently stored at the google document here -- please use "suggesting" mode only!

https://docs.google.com/document/d/15dd4wJvBX8s-M4vWAWMK2DY1OPdxjm01SgNIodg5HP4/edit?usp=sharing

Will transfer here soon.

Goals:

1. Simplify model setup
2. Reduce repetition (see 1) -- no longer need to type base parameters over and over again for each cell type
3. Easier to enforce best practices and avoid PhysiCell quirks
   1. Same custom data in all cell definitions, starting in cell defaults (avoid data output quirks)
   2. Cell cycle, phenotype set up first in cell defaults (best practice)
4. After this, users focus on writing custom functions and attaching them to the right cell definitions. No more hand typing / creating these cell definitions.
5. Make it easier to read in initial cell positions (for a future release) -- they can list (x,y,z), ID, and which cell definition. Then perhaps any unique initialization.
6. Easier bridge to linking SBML / molecular models -- specific path to SBML in the cell definition
7. Reduce number of custom parameters needed (part of this is cell def setup)
8. facilitate future where basic models can be created entirely at runtime in some sort of python+jupyter+PhysiCell environment. OR a sort of “PhysiCell studio”

Intended implementation (when parsing in PhysiCell):

1. Read and create a default cell definition
   1. Base / default parameters fully specified here.
   2. Custom data also specified here.
2. All other cell definitions copy the default (at time of creation in PhysiCell instance).
   1. Inheritance: all other cell definitions inherit default parameters from the default definition.
3. All other cell definitions (in XML) are truncated -- only specific parts that deviate from the default are written
4. Create a master list of all cell definitions (unique IDs and character names). This data structure can be queried.
5. Parse this early in the PhysiCell simulation, so it's done before create_cell_types()
6. User edits in create_cell_types() will override / overwrite individual cell definitions.
7. Probably create helper functions create_cell( std::string name ) and create_cell( int typeID) that searches the registry of cell definitions to create the cell type. Helpful for setup_tissue().
8. As before, individual cells can be further specialized at the time of instantiation (e.g., in setup_tissue()).

Anticipated ecosystem impacts:

1. xml2jupyter based tools will need a new tab for cell definitions
   1. Maybe subtabs to facilitate easy browsing of each cell individual definition
   2. Inheritance will need to be accounted for in the tab somehow. Changing a value in defaults needs to “percolate” to all other cell defs, unless overwritten by user.

Specification history:

Feb 24, 2020: Paul Macklin starts this outline of the draft specification. Feb 24, 2020: Edits opened up to MathCancer lab XML core team (Randy Heiland, Nick Mowery, Daniel Mishler) Feb 26, 2020: Edits opened up to close collaborators Mar 4, 2020: Began migration to GitHub dev wiki for community involvement.

Intended timeline

Feb 2020: comments: All MathCancer Lab late Feb 2020: comments by key collaborators at BCS, Institut Curie (especially PhysiBoSS)

Early March 2020: draft implementation in PhysiCell Mid March 2020: rework sample projects using the new spec Mid 2 March 2020: test making new projects from template 2D and template 3D projects

late Mar 2020: virtual town hall Target release: late March 2020 or early April 2020

Late March 2020: plan a training module using the XML ??

• ideally coincides with 1.7.0 launch

---

*** Paul Needs to continue revision here ***

---

Draft XML on next page.

Overall structure (by example)

<cell_definitions> <cell_definition name=”default”> <custom_data> <elastic_coefficient length=”1” units=”1/min”>1.0</elastic_coefficient> <attachment_point length=”3” units=”micron”>-12.8,13.9,0.0</attachment_point> </custom_data> </cell_definition>

<cell_definition name=”cancer”>
	<phenotype>
		<cycle>
			<transition_rates units=”1/min”>
				<rate start_index=”0” end_index=”1”>0.0001</rate>
			</transition_rates>
		</cycle>
		<volume>
			<total units=”micron^3”>2.15e3</total>
		</volume>

</cell_definition> </cell_definitions>

Details on individual blocks on following pages

<transition_rates units=”1/min”> 0.00001 0.00001 0.00001 </transition_rates>

< /death>

0.0 10.2 0.0 1.0 1.0 1.0 10.0 1.0 0.0 0.0 1.0 -3.0

<!-- dimensions: 1/time, density, 1/time -->