Data description
The file entitled 'modular.Rmd' contains the source code. The secondary data can be found in the 'Data' folder. Within the folder, 'all.csv' contains all the COVID-19 incidence data publicly available in Our World in Data. The file 'state-abbrevs.csv', 'state-areas.csv' and 'state-population.csv' include the abbreviations of the states of the USA, their areas and their population respectively.
Experimental design, materials and methods
The program was written in R language version 4.1.2, in the Tidyverse ecosystem.
The following variables are defined in the global environment, initiated as NULL if not mentioned otherwise and populated later at the invocation of the final() function.
The 'tune_spread' parameter determines the probability of transmitting the disease from one infected block to a susceptible block, a unit block-length away, at a fixed time from the contraction of the infection by the infector. There are several factors that affect the spread parameter like the intrinsic virulence of the virus and protective measures such as wearing masks and hand washing.
The 'total_infective_period' determines the total time duration an infected block can remain infectious. The model by default assumes a negative linear relationship between the time and infectivity for each infected cell. Still, the user can explicitly define a custom function for the infectivity over time.
The size of the population 'sq' is the number of total cells, which has to be a square number.
'g_t' is the main population statistics table initially populated by the generate_pop_stat_table function as described later.
'p_list' is the list object storing the generated graphs, and 'current_s' is the current time-step initiated as 0.
'master_tbl' is the data frame storing all the daily population statistics with timestamps,
'c_plt' is a data frame of daily SIR compartment counts, and 'df' is a numeric vector of the cumulative cases.
The functions defined in the global environment are summarized in table 1.
Table 1 - The functions defined in the global environment
| Function | Parameters | Return | Comments |
|---|---|---|---|
| generate_pop_vector | Number of squares, number of populated cell blocks | A sorted vector of indexes | The indexes represent the populated cell blocks |
| generate_pop_stat_table | Population indexes vector, number of infectors at the initiation | A list object of cell id, index, day and the infectivity | Generates the initial statistic table for the population. Default is to start with one randomly generated infective individual. The initial population is always unvaccinated. |
| get_infectivity_v | Compartment state of the cell, day | Numeric | A vectorized version of the function 'get_infectivity'. Calculates the infectivity of the cell block. |
| get_a_position | Current position coordinates(I,j), matrix representation of the space, mobility level, Boolean value of infectiveness. | A list object with the updated space matrix and the new position (index) value | Calculates new position coordinates for the individual at position i, j with a given mobility threshold. |
| get_i_v, get_j_v | Position value | Numeric | Vectorized functions. Decomposes the position value of a cell into its x and y coordinates in the space matrix. |
| get_pos_v | x and y coordinates of the cell block in the space matrix | Numeric | A vectorized version of the function 'get_pos' calculates the position value from x and y coordinates of a cell block. (Inverse of the get_i, get_j) |
| get_v0 | A list object with the format of 'generate_pop_stat_table' return value | A numeric square matrix | Constructs the space matrix, a two-dimensional representation of the space, using the main population stat table. |
| plt | - | A ggplot jitter plot of the space matrix | Creates snapshot jitter-plots of the current space matrix. |
| dyn_gt | - | Dataframe of the updated population stat table | Creates a data frame from the current population stat table with the current timestamp and appends the data to the master table |
| mobilize | Population stat table, mobility level, infectious radius, infectivity threshold for quarantine, quarantine efficacy, vaccination fraction, vaccination efficacy and Boolean value of the status of the timeline feature | No return value.Updates the current_s, df, g_t global variables and appends the master table by calling dyn_gt() | This is the key function that calls the other helpers. It updates the global variables and performs one simulation iteration. |
| contract_v | Infectivity | Boolean | A vectorized function. Determines if a cell gets infected by a nearby infector. The probability of a TRUE is proportional to the infectivity and the tune_spread. |
| alter | Population stat table and the infective radius | The updated population stat table | Determines the new compartment status of each cell. |
| vaccinate | Population stat table, vaccination fraction and the vaccination efficacy | The updated population stat table | Performs a vaccination cycle. |
| get_r0 | Scaling factors of the time-steps and the population | A list object containing a data frame of R0 values and error plots | Performs LOESS modelling for expansion of the time and population for R0 calculation. The serial interval and the generation time distribution of the virus are coded into the function body and are not parameters for the model. |
| final | Number of time-steps, mobility level, infective radius, size of the space, number of initially populated cell blocks, initial infectors, the tune_spread parameter, smoothing parameter for graphs, vaccination fraction, vaccination efficacy, scale factor for time, scale factor for population, threshold infectivity for triggering quarantine, quarantine efficacy, total infective period, Boolean for generating snapshots, frames per second for animations, number of frames for animations, filename suffix for animations, Boolean for using the dark theme, starting time of quarantine, starting time of vaccination, Boolean for generating SIR graphs, Boolean for using the timeline feature | - | The function wraps all the other helper functions. |
| anim | Output filename, frames per second, number of frames, Boolean for generating SIR graphs, Boolean for using dark theme | Writes to GIF files | Creates GIF animations using the master table. |
| quarantine | Population stat table, threshold infectivity for quarantine, quarantine efficacy | The updated population stat table | Performs a cycle of quarantine. |
| calibrate | Same parameters as for the final() function, but with data frames of values as tune grids with the target maximum caseload | A list object with best parameter estimates | The function takes the observed maximum caseload of an epidemic and multiple tune grids of parameters. Brute-force parameter search is performed to minimize the root mean squared error for cumulative caseload to estimate best model parameters. |
The 'mobility', 'vaccine' and 'radius' are the three variables that are incorporated into dynamic modules. These parameters are initiated as data frames containing time and value pairs. The mobilize() function calls three modules in each iteration and checks for necessary parameter adjustments.
The program is executed by calling the final() function which wraps around the helper functions and calls them in the required sequence.
Example code for simulating epidemic curve for California is as follows.
final(s = 65, rad = 0.05, size = 90^2, pop = 4000, vaccination_frac = 0.5, thresh = 0.28, spread = 0.048,infective_period = 4, q_eff = 0.7, q_inf = 0.7, sc_time = 7, graph_span = 0.2, sc_pop = 10000, vaccination_begin = 0, quarentine_begin = 0, filename = 'v_0_q_0_')