About introductory paragraph in README

[avallecam]

The introductory paragraph is concrete and direct enough to grasp the aim of the package. However, I had the following doubts that I later clarified after reading the vignettes:

• Is final size refers clearly to infections and not deaths?
• Is the package currently “age group” specific?
• Which are the sources of between and within susceptibility variation?

Probably "age group" will be the only demographic grouping to use, due to the available contact data. However, could {finalsize} be open to any other demographic segmentation? (e.g., sex, regions within a country or city, socio-economic status, etc). If not, we can be more direct about age-groups in this paragraph and the rest of the documentation.

Given these questions, I thought it convenient to:

• express that final size refers to infections only, not deaths
• detail age as an example of demographic grouping (although this can change if not the case)
• briefly detail about common sources of between and within variation in susceptibility

Introductory paragraph: https://github.com/epiverse-trace/finalsize/blob/f0ac4127e54579754d08ee92754203f99c0f6ee9/README.Rmd#L25

Suggested edit:

finalsize provides calculations for the final size of an epidemic in a population, which is the overall number of infected individuals, depending on a demographic distribution (e.g., age groups) and their contact patterns, accounting for different susceptibility to disease between groups (e.g., from different attack rates or infection prevalences) and within groups (e.g., due to immunization programs).

[avallecam]

Final edit to this suggestion in https://github.com/epiverse-trace/finalsize/pull/121#discussion_r1072687073 emphasizing the age-related impairment or dysregulation of host immune response, as sources of difference in susceptibility between groups, instead of attack rates or infection prevalence which is the outcome of the package.

[pratikunterwegs]

Fixed in https://github.com/epiverse-trace/finalsize/pull/121/commits/46cc4529e9b72e0a3a8f0f74e91b8f55ff847c96

[avallecam]

Updated suggestion here https://github.com/epiverse-trace/finalsize/pull/121#discussion_r1074004317

[avallecam]

Solved in #121

[pratikunterwegs]

@avallecam these issues are linked to #121 and will be closed automatically once that is merged

[avallecam]

I found myself struggling to read the new first README paragraph including the "e.g." within the parenthesis. I confirmed this using Grammarly.

Thus, I think that we can return to having a very concrete and direct first line introducing the package (extracted from the Github description) and explaining it longer in a separate paragraph.

Here is a new suggestion:

finalsize is an R package to calculate the final size of a SIR epidemic in populations with heterogeneity in social contacts and disease susceptibility.

finalsize estimates the number of infected individuals in a population, which could depend on a demographic distribution (like age groups) and their contact patterns, accounting for heterogeneous susceptibility to disease between groups (due to age-group-specific immune responses) and within groups (due to immunisation programs).

[pratikunterwegs]

I can update this in #143.

[pratikunterwegs]

I'm updating this to the following, replacing "disease" with "infection".

finalsize is an R package to calculate the final size of a SIR epidemic in populations with heterogeneity in social contacts and infection susceptibility.

finalsize provides estimates for the total proportion of a population infected over the course of an epidemic, and can account for a demographic distribution (such as age groups) and demography-specific contact patterns, as well as for heterogeneous susceptibility to infection between groups (such as due to age-group specific immune responses) and within groups (such as due to immunisation programs).