Add brief explaination about the matrix operations

[avallecam]

I suggest adding a coloured box, code folding, or redirecting to an external reference for the following questions:

• Why contact matrix is transposed?
  

  finalsize/vignettes/finalsize.Rmd

  Line 100 in f0ac412

  contact_matrix <- t(contact_data$matrix)

• Why largest eigenvalue in the contact matrix should be 1.0?
  

  finalsize/vignettes/finalsize.Rmd

  Lines 104 to 107 in f0ac412

  	# scale the contact matrix so the largest eigenvalue is 1.0
  	# this is to ensure that the overall epidemic dynamics correctly reflect
  	# the assumed value of R0
  	contact_matrix <- contact_matrix / max(eigen(contact_matrix)$values)

  • Is it part of a normalization procedure or it aims to resemble a probability of contact between 0-1?
  • Can you explain further about the statement:

    To ensure that the overall epidemic dynamics correctly reflect the assumed value of R0

• Why divide the contact matrix with its respective age group population size?
  

  finalsize/vignettes/finalsize.Rmd

  Lines 109 to 112 in f0ac412

  	# divide each row of the contact matrix by the corresponding demography
  	# this reflects the assumption that each individual in group {j} make contacts
  	# at random with individuals in group {i}
  	contact_matrix <- contact_matrix / demography_vector

  • Can you explain further about the statement:

    To reflect the assumption that each individual in group {j} make contacts at random with individuals in group {i}

• Are both operations of a preliminary process recommended for all formal analyses? Probably depends on the input format, but this reason is strong enough to create a function for this task?

[pratikunterwegs]

This is a question for the epi folks - I'm not certain of the theory underlying these steps. This also relates to the need for epi training for the RSEs.

[avallecam]

I understand. As a first step, we could add more resolution to the math concepts that a user needs to know before relating them with the math/code steps and an epi interpretation. We could invite an applied epi mathematician to the conversation, if needed.

Also, Is there a reference code (in repo or paper) you used to write these steps? It could help to understand it.

[pratikunterwegs]

The most convenient reference is probably the Miller (2012) paper: https://doi.org/10.1007/s11538-012-9749-6, but I haven't really understood a lot of it beyond the initial steps. Could ask @rozeggo, @adamkucharski or @BlackEdder to write two sentences on each operation - they would know the most

[sbfnk]

I think you could remove the matrix operations if you called contact_matrix with split=TRUE (see corresponding section in the package vignette).

[pratikunterwegs]

I think you could remove the matrix operations if you called contact_matrix with split=TRUE (see corresponding section in the package vignette).

Thanks @sbfnk, will check if the vignettes build with this option. Still, it would be good to have a couple of sentences on why these operations are necessary, wherever they actually happen