-
Notifications
You must be signed in to change notification settings - Fork 92
XML based Cell Definitions
Old version was a google document here -- please use "suggesting" mode only!
https://docs.google.com/document/d/15dd4wJvBX8s-M4vWAWMK2DY1OPdxjm01SgNIodg5HP4/edit?usp=sharing
- 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.
Mar 6, 2020: All-lab feedback and input on the specification and intended behavior and inheritance.
Mar 8, 2020: Public announcement of dev wiki draft of specification and call for public input (via @PhysiCell on twitter).
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” ID="0">
<phenotype>
<cycle />
<death />
<volume />
<!-- geometry omitted from now, as auto-calculated from volume -->
<mechanics />
<motility />
<secretion />
<molecular />
</phenotype>
<custom_data>
<elastic_coefficient units=”1/min”>1.0</elastic_coefficient>
<attachment_point units=”micron”>-12.8,13.9,0.0</attachment_point>
</custom_data>
</cell_definition>
<cell_definition name=”cancer” ID="1" parent_type="default">
<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.
Gaelle Letort (Mar 12): About the name and index of cell types and substrates, I would suggest not to use the index to refer to one of them afterwards but to refer to the name instead. It would be more easy for the user to remember the name than to have to remember which types was associated with which index (for example when specifying secretion_rates, it would be more easy to write/read secretion rate for tnf-alpha than secretion rate for substrate index 0). Maybe it's already possible, but then it could be used like this in the examples. Also like this, the index could be non visible to the user and be only in-code. Also in the same idea, if a user defines two cell types with the same index or the same name (by uncarefull coping pasting by example), is it handled by the program ?
<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.
Gaelle Letort (Mar 12): Same here, it's difficult to knwo which rate corresponds to which transition. Might be more complex in this case to name it, so maybe here indexes are more convenient, I don't know.
<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.
Gaelle Letort (Mar 12): Those parameters were unclear to me and gave me troubles when I begun on PhysiBoSS. I think it would be better to have the default volume mode as simple as possible, with only the cell size, not considering nucleus and cytoplasmic fractions at all. A lot of project that could use PhysiCell may not need intracellular mechanics level. For project that need it, it would be good to give detailed examples or explanation of it, and how those different parameters are related to each other.
<!-- 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.
Gaelle Letort (Mar 12): It could also be important to allow for different cell-cell adhesion/repulsion parameter according to cell types interactions (homotypic or heterotypic). It is not the same if fibroblast-fibrobalst interacts than fibroblast-hela cell. I would add the possibility to choose a parameter for homotypic interactions or heterotypic.
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.
Gaelle Letort (Mar 12): Here again, if we could refer to the substrate by name instead of index, it seems more intuitive to me.
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_targets>
<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.
Gaelle Letort (Mar 12): Is this where we specify the MaBoSS files to use for each cell type ?