Dynamic Properties: Whether or Where?

[jonathanhhb]

Placeholder for discussion about exactly what we mean by Dynamic Properties. I think we all agree that we want to minimize "hard-coding of properties" but it's not a question of whether we have specific code for certain properties but where we put that.

[krosenfeld-IDM]

I think one example is how @clorton has been initializing the model:

laser/src/idmlaser/models/numpynumba.py

Lines 113 to 119 in d20bf93

	population = Population(capacity)
	population.add_property("states", dtype=_STATES_TYPE_NP, default=0)
	population.add_property("dob", dtype=_DOB_TYPE_NP, default=0)
	population.add_property("susceptibility", dtype=_SUSCEPTIBILITY_TYPE_NP, default=1)
	population.add_property("etimer", dtype=_ITIMER_TYPE_NP, default=0)
	population.add_property("itimer", dtype=_ITIMER_TYPE_NP, default=0)
	population.add_property("nodeid", dtype=_NODEID_TYPE_NP, default=0)

Based off of this pattern, I could envisage easily adding a property via a similar:

population.add_property("risk_group", dtype=_RISK_GROUP_DTYPE, default=0)

You are right that a lot of the code (e.g., transmission) depends by name on the properties defined here but one thing I like is that it seems pretty straight-forward to add a property. Maybe it is not as easy to remove or change in this exampe.

[krosenfeld-IDM]

Here is the excerpt from the wiki on Open Design Questions regarding hard coded properties. (@jonathanhhb original author?):

Christopher has been using an approach in which all properties (e.g., age) are adding dynamically and programmatically, potentially based on step function code. Jonathan has been treating the modeled population file headers as the definition of properties but there is also code in the step functions that references specific properties. Which of these do we want to go with? Or do we want a variation on this? Are there any built-in properties? Like age or node? But even with those, one modeler might want an age property which gets updated every timestep and another might want date-of-birth which gets compared to "now" each timestep. And with node, a single node sim might not have a node property. Do we want the core code to be completely agnostic of properties? (Probably) As for adding properties to the model, at some point once the model is loaded/generated, the columns are defined. Some combination of model definition and step function coding freezes the property set.

[krosenfeld-IDM]

and @KevinMcCarthyAtIDM 's response:

Argue strongly for dynamic properties. Light agents implies, to me, that the user can make agents that are 'as simple as they need to be, but not simpler'. On the other side, having the flexibility to serve a variety of spatial disease modeling problems implies that the framework will need to accommodate a large set of possible properties, relevant to specific use cases. With hard-coded properties, it seems we must sacrifice one or the other.

[jonathanhhb]

When I took a crack at moving my code to "dynamic properties", I started to split the code between code that simply had to be aware that there were properties like "age", or "infected" and generic or code code that didn't. It quickly became apparent that most of the code was initialization of the population dataframe (which required knowing about properties) or "step functions" which did math on those properties. The "core code" is relatively small and frankly trivial.

Even at the level of demographics, in order to create a minimal population dataframe (set of datatype vectors with values for each agent), we have to make some choices about how that population will be represented: age or date of birth? expected_life_span or date_of_death? home_node? Not to mention how we represent the epi state. infected flag or disease state? And so on. So there will pretty early on be "hard-coding" where we make these choices, and then the "step function" code will only work with the properties we selected. So we will need to keep those together in some way. I like @clorton's idea of inspecting the library of "step functions" to infer the properties and then create a population with those, but that seems to me to be mostly applicable to synthetic populations. And it's usually not just enough to say "oh, there needs to be an immunity flag, I'll add a vector N immunity flags. Those all need a data type (which could be inferrable) but also initial values. How does that work in a way that has no baked in knowledge of properties?

I agree that it would be nice if adding properties to synthetic populations could be easy and programmatic.

I do feel like simulations of real world populations -- E&W or North Nigeria -- are best done as what essentially amounts to a serialized (saved) population file. Do we really want to set initial ages, immunities, lifespans, etc. from parameterized distributions? Perhaps -- it's not up to me -- but that seems surprising. Any serialized/saved population file will have properties "hard-coded".

I'm not arguing for "hard-coding" any particular set of properties into LASER. To me, LASER is a Reference Design. I'm just saying that any particular implementation will including making decisions pretty early about how to encode demographics and disease (epi) and so it feels odd to abstract that. We could let the model builder write the step functions and have code that infers the properties from that, but it seems the "columns" of the population dataframe ought to be pretty transparent and explicit. I would put these in some kind of schema and load that and add "dynamic properties" from that schema.

[KevinMcCarthyAtIDM]

@jonathanhhb - Thanks for all of this feedback, it's great. I already like this discussion forum more than the wiki or Teams for this sort of issue - though unclear whether I should add a comment or reply to yours; since I'll be responding directly to a couple of your points, I think I'll opt for "reply".

First, I 100% agree with a point you made in your last paragraph - I'm just saying that any particular implementation will including making decisions pretty early about how to encode demographics and disease (epi). Totally! Any specific implementation will absolutely face these decisions almost immediately (as well as uncovering some new decisions over the process, I'm sure). First, I think that can be a good thing - in EMOD, we had robust discussion about having default values and opted against it because "the user should have to think about each piece of the model they're putting together". I still like that philosophy, though I think it hurt us because of the sheer number of parameters, and because every time anybody added a new feature that made it back to the shared branches, everybody had to think about that feature's impact on their work and set things appropriately. In the large population use case, I think the justification is more "think about what you really need, because each property costs you when you get to large populations".

I think the reason I'm in favor of agent properties being dynamically set in a specific model implementation rather than expected by the overall reference design - for any specific property we might argue has to be there, I can readily give a counterpoint where I don't need that (and don't want to carry around the memory hit), or I need something different, and I'd love to be able to support that flexibility to the user. For example - thinking of the primary use case as being "spatial-first" models, if I'm interested in modeling whether total air traffic flow predicts the early spread of COVID around the world, or cell phone movement predicting Ebola's spread around West Africa, I wouldn't need ages at all for that, or probably any demographic processes at all except for population numbers. Or I could want to use agents to represent something other than a single person. Similarly for disease properties - for a disease with multiple infections, waning dynamics, rather than "S, E, I, R" states I'd probably want an "infected flag" and "correlate of immunity". So agreed - the choices have to be made very early on, but I think that's appropriate, and making any choice "core" to the model constrains its applicability.

I think there are some decisions we have made that can consider to be "hard-coded", or built into the expectations about model design. Though would love people's thoughts about these:

• The model is called "light agent spatial", so there will always be "agents", even if they don't necessarily represent individuals. There will also always be spatial "nodes", even if there's only 1, and even if we don't attach any explicitly spatial information onto that node. The "core" of the model is defining the properties and dynamics of the agents, the interactions between the agents in the same node, and the interactions between agents in different nodes (or interactions between nodes?)
• The "node to agent" mapping is one-to-one or one-to-many, but never many-to-one or many-to-many. Or simply - nodes can hold lots of agents, but agents can only be in one node on a given timestep.
• The agents are rows of an array & their properties/state are the columns of that array
• The model is discrete-time: we're not supporting continuous-time things like tau-leaping (though we might use them to decide which timestep in the future something happens), taking unequal time steps, etc. Fundamentally, a "step" takes the model from time T to time T+dT, comprised of a series of user defined state update operations. Not all operations must occur on each timestep.
• It's also discrete-space: Nodes may have metadata associated with them, like shapes, areas, pop density, ..., but as far as the model is concerned they are fundamentally "points", edges on a network, without any spatial substructure that the agents move about within.
• At least for now, the reference model has one agent "type". That is, agents have properties, but we don't have multiple agent arrays representing fundamentally different kinds of agents undergoing fundamentally different dynamics (e.g., human agents and mosquito agents). (This last one may be something we come back to?) Though I suppose this sort of setup could be used for EULAs and EILAs, in the event where we need to keep track of more EULA properties than just numbers?

[jonathanhhb]

I love this effort to capture those things that we think are the actual LASER constraints or design! (And I didn't see anything there I disagreed with.) And noting that there are no properties that are baked in -- not even age/dob. (Except maybe node id?).

[KevinMcCarthyAtIDM]

I think "node id" is probably the one that we can assume is there. This model is intended for spatial use cases (somebody could, I suppose, co-opt the node to represent something other than space, but if really all you had was a bunch of agents with. no marker that denotes some kind of heterogeneity in their interactions, I think you'd just rather use a different model)

[krosenfeld-IDM]

If a model is fast 🚀 and easy 🧠 to setup and analyze (assuming I'd already have familiarity) that can be pretty persuasive...

[krosenfeld-IDM]

What is cool about the way the @clorton has implemented the properties is that it would be really easy to create a version of a DiseaseModel (e.g. NumbaSpatialSIR vs the existing NumbaSpatialSEIR) where you don't have ages at all. You'd just have to drop the add_property step:

laser/src/idmlaser/models/numpynumba.py

Line 115 in d20bf93

population.add_property("dob", dtype=_DOB_TYPE_NP, default=0)

and of course wouldn't be using the property anywhere any of the _phases.

I don't think the choice is hard-coded at all. Once you start building a specific DiseaseModel you have to make a choice, but there is flexibility.

@clorton - thoughts?

[jonathanhhb]

I agree that it's nice to have an easy way to "just add a property", but there's going to be other code that assumes that property exists -- or doesn't exist -- step functions, initialization, maybe loading existing saved populations. So it feels like for any given implementation, there will be a schema that ties that code set (set of choices of our properties) together?

[krosenfeld-IDM]

yeah - that's a good question about how to structure/organize things. A schema is one idea. Could class hierarchy also work? Or a principle of "you want it, you write it" but make sure that the framework can enable flexibility and has lots of example to draw from?