Setting initial behaviors from config-defined distributions

[drbergman]

A common feature implemented in PhysiCell models is initializing cells within a given cell type with heterogeneity across one or more variables. Currently, users can either set this up in custom.cpp--not preferable as it requires C++ knowledge--or by adding columns to cells.csv and labeled according to the behavior name (or volume). This latter option, to my knowledge, is not well-known or documented¹. It also requires users to use another language to generate the values and to tie the values only to cells read in from a CSV and not any cells placed by other means.

I propose we allow for a new element as a child of cell_definition called initial_parameter_distributions. Here is a template of what I am currently experimenting with:

	</custom_data>

	<initial_parameter_distributions enabled="false">
		<distribution enabled="false" type="Log10Normal" check_base="true">
			<behavior>Volume</behavior> 
			<mu>4</mu>
			<sigma>2</sigma>
			<upper_bound>100000</upper_bound>
		</distribution>
		<distribution enabled="false" type="LogUniform" check_base="true">
			<behavior>apoptosis</behavior>
			<min>1e-6</min>
			<max>1e-2</max>
		</distribution>
	</initial_parameter_distributions>

</cell_definition>

At the end of setup_tissue, these parameter distributions will be used to initialize cell behavior, limited in the exact same way as load_cells_csv_v2, i.e., volume and any behavior. Choosing this spot in the code could cause values specified in cells.csv to be overwritten if the behavior is present in both.

I currently have the following distributions implemented: Uniform, LogUniform², Normal, LogNormal, and Log10Normal. Log10Normal is defined by $X\sim 10^{\mu+\sigma Z},\ Z\sim\mathcal{N}(0,1)$³. Adding a new distribution requires adding it to a long if-else if-... block and appending the name to a list of supported_distributions.

Other details

See the template project after custom_data for how this can be implemented. Note: those are disabled to not change the base behavior of the template project.

See the end of setup_tissue() in the template project for where to insert into your own project.

Checks are performed to ensure coherence (lower bounds <= upper bounds) and to make sure that truncated normals warn the user about how long they will take for draws.

Footnotes

1. I don't recall learning it at workshops. I learned about it when looking into adding this functionality myself. ↩

2. https://en.wikipedia.org/wiki/Reciprocal_distribution ↩

3. Users will likely find powers of 10 easier to interpret than powers of e. ↩

[rheiland]

This raises an interesting issue. When a PR affects the XML model definition, we need to be mindful of what it will mean for the Studio and for users' expectations. If our goal is to have the XML and the Studio "in sync", then we basically need to do sync'd PRs and releases. But maybe we'll adopt a more relaxed approach of allowing XML changes and then later incorporate them into the Studio (in spite of what we stated in the Studio preprint).

[drbergman]

I think so long as we are working with PhysiCell v1.x.x and nothing is being broken, we should incorporate the change to studio after PhysiCell agrees to include the change but before PhysiCell releases the change. All changes of this nature should be backwards compatible by setting defaults in missing XML elements and/or having the default values in new elements produce the previous behavior. FWIW, this PR does both. Well, with the template project, at least. When I get around to writing the studio addition, I'll make sure the defaults for those enabled attributes are "false".