# Contact probabilities and Demographics

MetaWards implements the mixing of demographics by merging together the force of infections (FOIs) calculated for each network. By default this mixing takes no account of the number of individuals (N) in each ward in each demographic.

The FOI, $$F(w)$$ calculated in each ward, $$w$$ is calculated separately for each demographic via the equations described here.

The merged FOI for ward $$w$$ for demographic $$i$$, $$F_i'(w)$$, is calculated as the sum of the FOIs calculated for ward $$w$$ across all demographics, $$i, j, k...$$ scaling by row $$i$$ of the interaction matrix $$M$$ via;

$$F_i'(w) = M_{ii} F_i(w) + M_{ij} F_j(w) + M_{ik} F_k(w) + ...$$

This is then divided by the number of individuals in ward $$w$$ in demographic $$i$$, $$N_i(w)$$ before it is converted into a probability of infection.

This normalisation by $$N_i(w)$$ means that it is up to you to account for the contact probability in the interation matrix. The individual terms should account for both the different infectivity of the different demographics, as well as the probability that individuals in one demographic will come into contact with individuals of other demographics.

However, accounting for these different contact rates using just the interaction matrix is difficult (or impossible) for cases where you have multiple wards that have different numbers of individuals. This is because different normalisation factors would be needed for the FOIs calculated for different wards in different demographics.

## Modelling demographics as part of the same population

If all demographics are part of the same population then we assume that any member in a ward of any demographic is equally likely to contact any other member of the same ward in any other demographic.

In this case, the normalisation factor should be the total number of individuals in that ward summed over all demographics, $$N(w)$$. This is calculated via;

$$N(w) = N_i(w) + N_j(w) + N_k(w) + ...$$

The merge function merge_matrix_single_population() calculates the merged FOI via the equation;

$$F_i'(w) = M_{ii} F_i(w) \frac{N_i(w)}{N(w)} + M_{ij} \frac{N_i(w)}{N(w)} F_j(w) + M_{ik} \frac{N_i(w)}{N(w)} F_k(w) + ...$$

Because this FOI is divided by $$N_i(w)$$ before it is converted into an infection probability, this is equivalent to using $$N(w)$$ as the normalisation factor for ward $$w$$ in all demographics.

This therefore models the demographics as a single population where individuals in a ward across all demographics have an equal probability of contact with each other. The interaction matrix has the effect of scaling $$\beta$$, i.e. the probability of infection at each contact between members of different demographics. You can pass in a custom interaction matrix if you want control of this, or can use the convenience mixer functions mix_evenly_single_population(), and mix_none_single_population() if you want to use an interactions matrix of all ones ($$M = |1|$$) that represents even infections, or a identity interaction matrix with a diagonal of 1 and off-diagonal of 0, that represents no infections between members of different demographics, respectively.

## Modelling demographics as multiple populations

It may be that the demographics represent different populations that have a differnet probability of meeting each other. This would be the case for the classic use of demographics, e.g. using demographics to represent different age groups, and having a different contact probability between individuals of different age groups.

In this case, the FOI calculated from each demographic must be normalised by the number of individuals in that demographic before it is combined into the merged demographic. To achieve this, the merge function merge_matrix_multi_population() calculates the merged FOI via the equation;

$$F_i'(w) = M_{ii} F_i(w) \frac{N_i(w)}{N_i(w)} + M_{ij} \frac{N_i(w)}{N_j(w)} F_j(w) + M_{ik} \frac{N_i(w)}{N_k(w)} F_k(w) + ...$$

Because this FOI is divided by $$N_i(w)$$ before it is converted into an infection probability, this is equivalent to using $$N_x(w)$$ as the normalisation factor for ward $$w$$ for demographic $$x$$.

This therefore models the demographics as being part of separate populations where the probability of contact between individuals in the same ward in different demographics depends on the number of individuals in each demographic.

The interaction matrix has the effect of scaling $$\beta$$, i.e. the probability of infection at each contact between members of different demographics. You can pass in a custom interaction matrix if you want control of this, or can use the convenience mixer functions mix_evenly_multi_population(), and mix_none_multi_population() if you want to use an interactions matrix of all ones ($$M = |1|$$) that represents even infections, or a identity interaction matrix with a diagonal of 1 and off-diagonal of 0, that represents no infections between members of different demographics, respectively.

## Modelling more complex population dynamics

For more complex population dynamics you will need to write your own custom mixer function that accounts for the number of individuals in each demographic in each ward, $$N_x(w)$$. Because this will be potentially an expensive function, you should write it as a cython plugin using the pyx extension. MetaWards will automatically compile and load this plugin at runtime.

You should take inspiration from merge_matrix_single_population() and merge_matrix_multi_population(). These show how the FOIs calculated for each ward are combined with the interaction matrix and the number of individuals in each ward in each demographic. Note that the code is slightly more complex than described here, as the FOIs and number of individuals are calculated separately both for daytime and nighttime, and the number of individuals is the sum of the number of players (who make random movements during the day) and the number of workers (who make predictable movements during the day).

If you have any questions or would like help, please feel free to get in touch by raising an issue on the GitHub repository.