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[^1]. 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="true">
    <distribution>
        <behavior>Volume</behavior>
	<type>Log10Normal</type>
	<mu>4</mu>
	<sigma>2</sigma>
	<upper_bound>100000</upper_bound>
    </distribution>
    <distribution>
        <behavior>apoptosis</behavior>
	<type>LogUniform</type>
	<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[^2], Normal, LogNormal, and Log10Normal. Log10Normal is defined by $X\sim 10^{\mu+\sigma Z},\ Z\sim\mathcal{N}(0,1)$[^3]. Adding a new distribution requires adding it to a long if-else if-... block and appending the name to a list of supported_distributions.

[^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.