-
Notifications
You must be signed in to change notification settings - Fork 111
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.
- Simplify model setup
- Reduce repetition (see 1) -- no longer need to type base parameters over and over again for each cell type
- Easier to enforce best practices and avoid PhysiCell quirks
- Same custom data in all cell definitions, starting in cell defaults (avoid data output quirks)
- Cell cycle, phenotype set up first in cell defaults (best practice)
- After this, users focus on writing custom functions and attaching them to the right cell definitions. No more hand typing / creating these cell definitions.
- 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.
- Easier bridge to linking SBML / molecular models -- specific path to SBML in the cell definition
- Reduce number of custom parameters needed (part of this is cell def setup)
- 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”
- Read and create a default cell definition
- Base / default parameters fully specified here.
- Custom data also specified here.
- All other cell definitions copy the default (at time of creation in PhysiCell instance).
- Inheritance: all other cell definitions inherit default parameters from the default definition.
- All other cell definitions (in XML) are truncated -- only specific parts that deviate from the default are written
- Create a master list of all cell definitions (unique IDs and character names). This data structure can be queried.
- Parse this early in the PhysiCell simulation, so it's done before create_cell_types()
- User edits in create_cell_types() will override / overwrite individual cell definitions.
- 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().
- As before, individual cells can be further specialized at the time of instantiation (e.g., in setup_tissue()).
- xml2jupyter based tools will need a new tab for cell definitions
- Maybe subtabs to facilitate easy browsing of each cell individual definition
- 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.
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.
Mar 5, 2020: Wiki conversion complete. Soliciting community feedback next.
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
Individual blocks will be defined in subsections below.
<cell_definitions>
<cell_definition name=”default”>
<phenotype>
<cycle />
<death />
<volume />
<!-- geometry omitted from now, as auto-calculated from volume -->
<mechanics />
<motility />
<secretion />
<molecular />
</phenotype>
<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>
</phenotype>
</cell_definition>
</cell_definitions>
Paul Macklin (Mar 5): Put comments in like this.
<cycle code=”0”> <!-- advanced_Ki67_cycle_model : codes are defined in PhysiCell_constants.* -->
<transition_rates units=”1/min”> <!-- units here since all transition rates have same units -->
<rate start_index=”0” end_index=”1”>0.00001</rate>
<rate start_index=”1” end_index=”2” fixed_duration="true">0.00001</rate>
<rate start_index=”2” end_index=”0”>0.00001</rate>
</transition_rates>
</cycle>
Paul Macklin (Mar 5): Edited model_ID to code to better match the Cycle data structure.
Paul Macklin (Mar 5): Edited to note that transition rates can be set for fixed duration.
<death>
<model code="100" name="apoptosis">
<rate units="1/min">5.316666666666667e-5</rate>
<!-- use this if the death model has more than one phase -->
<transition_rates units=”1/min”> <!-- units here since all transition rates have same units -->
<rate start_index=”0” end_index=”1” fixed_duration="true">0.001937984496124</rate>
</transition_rates>
<parameters>
<unlysed_fluid_change_rate units="1/min" />
<lysed_fluid_change_rate units="1/min" />
<cytoplasmic_biomass_change_rate units="1/min" />
<nuclear_biomass_change_rate units="1/min" />
<calcification_rate units="1/min" />
<relative_rupture_volume units="dimensionless" />
</parameters>
</model>
<model code="101" name="necrosis">
<rate units="1/min">0.0</rate>
<!-- use this if the death model has more than one phase -->
<transition_rates units=”1/min”> <!-- units here since all transition rates have same units -->
<rate start_index=”0” end_index=”1” fixed_duration="false">9e9</rate>
<rate start_index=”1” end_index=”2” fixed_duration="true">1.157407407407407e-5</rate>
</transition_rates>
<parameters>
<unlysed_fluid_change_rate units="1/min" />
<lysed_fluid_change_rate units="1/min" />
<cytoplasmic_biomass_change_rate units="1/min" />
<nuclear_biomass_change_rate units="1/min" />
<calcification_rate units="1/min" />
<relative_rupture_volume units="dimensionless" />
</parameters>
</model>
</death>
Paul Macklin (Mar 5): Updated to reflect the death data structure and need for parameters. I started filling in default parameter values.
Paul Macklin (Mar 5): Some outstanding questions:
- Is this would be where we should specify if necrosis is stochastic or deterministic?? Or is that more of a custom parameter or option that belongs elsewhere?
- Probably need to set properties of tracked internalized substrates at lysis time. Release everythign? Which substrates?
<!-- give the “mature” or “target” cell volume here, and fluid / solid change rates -->
<volume>
<total units=”micron^3” />
<fluid_fraction units=”dimensionless” />
<nuclear units=”micron^3” />
<cytoplasmic units=”micron^3” />
<fluid_change_rate units=”1/min” />
<cytoplasmic_solid_change_rate units=”1/min” />
<nuclear_solid_change_rate units=”1/min” />
<!-- anything else? maybe nuclear : cytoplasmic is an internallyinternaly calculated thing, instead of specified -->
</volume>
Paul Macklin (Mar 5): Put comments in like this.
<!-- minimal parameters here for now -->
<mechanics>
<cell_cell_adhesion_strength units=”micron/min” />
<cell_cell_repulsion_strength units=”micron/min” />
<relative_maximum_adhesion_distance units=”dimensionless” />
</mechanics>
Paul Macklin (Mar 5): Put comments in like this.
Idea here is to optionally allow a specification of basic chemotaxis. Users are always free to replace the defaults with their own.
<motility>
<options enabled=”true” 2D=”true” />
<speed units=”micron/min” />
<persistence_time units=”min” />
<migration_bias units=”dimensionless” />
<chemotaxis enabled=”true” substrate_index=”0” direction=”1” />
<!-- index matches one of the microenvironment indices above -->
<!-- 1 if up gradient, -1 if against gradient -->
</motility>
Paul Macklin (Mar 5): Put comments in like this.
This is going to be the most laborious part for people.
We could include 3 in template by default, and just don’t parse the later entries if there are fewer substrates.
We could also use a shorter, vector form like <secretion_rates units=”1/min”>0,10.2,0.0</secretion_rates>
We could also use the convention that unspecified rates are set to zero. In this case, only set the nonzero rates. (This is Paul's favorite option.) Moreover, users could leave this section blank, and only set nonzero rates for specific cell types.
<secretion>
<!-- generally use this OR net export rates -->
<secretion_rates units=”1/min”>
<secretion_rate index=”1”>10.2</secretion_rate>
</secretion_rates>
<secretion_targets units=”substrate density”>
<secretion_target index=”0”>1.0</secretion_target>
<secretion_target index=”1”>1.0</secretion_target>
<secretion_target index=”2”>1.0</secretion_target>
</secretion_rates>
<uptake_rates units=”1/min”>
<uptake_rate index=”0”>10.0</uptake_rate>
<uptake_rate index=”1”>1.0</uptake_rate>
</uptake_rates>
<!-- generally use this OR secretion_rates -->
<net_export_rates units=”total substrate/min”>
<net_export_rate index=”1”>1.0</net_export_rate>
<net_export_rate index=”2”>-3.0</net_export_rate>
</net_export_rates>
</secretion>
Paul Macklin (Mar 5): Secretion and uptake rates have dimensions of 1/time. Target has dimensions of density=substance/volume. Export rate has units of substance/time.
<molecular />
<!-- mostly a placeholder, but name of SBML model -->
<!-- eventually some index mapping here -->
Paul Macklin (Mar 5): Put comments in like this.