Move hardcoded `percent_day_away=0.5` to config file

[twallema]

Description

I'm currently setting up a spatially-explicit SIR model with commuter mobility for Belgium at the municipality level (581 spatial patches, no other stratifications for now). I have a mobility matrix extracted from the Belgian census representing the number of individuals residing in their "home" patch i commuting to their "work" patch j. I want to model commuters making a subset of their total number of contacts N=17 at work (so in their visited patch), governed by a parameter included in the configuration file f_v.

From flepimop's publication in Epidemics, @saraloo deduced there is a parameter p_a, defaulting to 0.5 and representing the amount of time that travelers spend on their visited patches, that should do exactly what I want to accomplish with f_v. I found this parameter hardcoded as percent_day_away=0.5 on line 55 of steps_rk4.py. Modifying it to percent_day_away=0 disabled the spatial spread beyond the seed patch, shifting its value closer to one made the epidemic peak earlier, as expected.

Proposed modification

To start, we should make it possible to control this parameter from the configuration files. If the model only has subpop as its stratifications, and no other stratifications like age groups/immunity we could make it an intrinsic part of the subpop setup.

name: spatial_SIR
setup_name: BE
start_date: 2024-01-01
end_date: 2024-05-01
nslots: 1

subpop_setup:
  geodata: model_input/demography.csv
  mobility: model_input/mobility.csv
  percent_day_away: 0.5

or perhaps even load it from a .csv if we want a different percent_day_away in every spatial patch?

But what if there are more stratifications?

I haven't gotten here yet, but I want to add age groups to this model next, meaning the contacts will be governed by a contact matrix. I would then like to define two contact matrices: N_total and N_work and have all individuals have N_total - N_work contacts on their home patch, and N_work contacts on their visited patch. In other words, approximating the work contact matrix as a fraction p_a of the total contact matrix is too simplistic if age groups are added to the model.

I'm curious how this will be coded up. I'm under the impression the mobility model is only applied if there is more than one value in the proportional_to; based on reading thru steps_rk4.py (@jcblemai is this correct?). However, it may be more sensible to apply the mobility model to all transitionings and include a parameter called apply_mobility. That would allow to code my desired logic up as follows,

transitions:
    - source: ["S"]
      destination: ["I"]
      rate: ["beta *( N_total - N_work)"]
      proportional_to: [["S"],["I"]]
      proportion_exponent: ["1","1"]
      apply_mobility: 0
    - source: ["S"]
      destination: ["I"]
      rate: ["beta * N_work"]
      proportional_to: [["S"],["I"]]
      proportion_exponent: ["1","1"]
      apply_mobility: 1

This would mean the S and I are brought into contact on their home patch to have N_total - N_work contacts, and then S and I travel to work and are brought into contact to have N_work contacts. By default, apply_mobility could be zero. Alternatively, if the performance would take too big a hit, an apply_mobility: True with a multiplier for greyshades mobility_multiplier: 0.5 might do the trick.

Might change or add stuff as I get wiser regarding the use of multiple stratifications. To be continued.

[jcblemai]

Thanks @twallema,

percent_day_away

This is a regression indeed, and we need to have this as a parameter. I tried to code it rapidely, but there are questions: while it can be a subpop setup parameter as you show, it would make sense to have it as a "reserved" parameter so we can apply modifier to it and have it change in time (and subpop, perhaps).

(also: percent_day_away should be renamed prop_mixing because it not a percentage)

Multiple matrices

That's also a very good point we have discussed in the past and we need a good way to do this. I also dislike the automatic way of applying mobility if there is more than one proportional_to (yes, your assumption is correct). Can I let you open another issue about it ? So we don't loose track of it as it is very important :)

[twallema]

@jcblemai If I understand correctly you can implement a short-term fix?

But we agree that this parameters should ideally have:

1. A means to implement a time-dependency,
2. A means to broadcast this parameter over non-spatial dimensions (also time-dependent?), so f.i. mobility can be different for individuals in different age groups.

Which we retain for a further stage of development?