| Title: | Calculation of Epidemiological Descriptors |
|---|---|
| Description: | Provides tools to easily compute a series of epidemiological indicators to characterise different transmission profiles of infectious diseases with a simple pipeline: format the dates in epiyearweek format, choose the descriptors and their parameters, and compute them. The package is based on the publication 'How heterogeneous is the dengue transmission profile in Brazil? A study in six Brazilian states' by Ferreira de Almeida et al (2002) <doi:10.1371/journal.pntd.0010746>. |
| Authors: | Raquel Martins Lana [aut] (ORCID: <https://orcid.org/0000-0002-7573-1364>), Carles Milà [aut, cre] (ORCID: <https://orcid.org/0000-0003-0470-0760>), Iasmin Ferreira de Almeida [aut], Claudia Torres Codeço [aut] (ORCID: <https://orcid.org/0000-0003-1174-178X>), Daniela Lührsen [aut] (ORCID: <https://orcid.org/0009-0002-6340-5964>), Diego Ricardo Xavier Silva [aut] (ORCID: <https://orcid.org/0000-0001-5259-7732>), Christovam Barcellos [aut] (ORCID: <https://orcid.org/0000-0002-1161-2753>), Raphael Saldanha [aut] (ORCID: <https://orcid.org/0000-0003-0652-8466>), Rachel Lowe [aut] (ORCID: <https://orcid.org/0000-0003-3939-7343>) |
| Maintainer: | Carles Milà <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.1.0 |
| Built: | 2026-10-09 10:14:33 UTC |
| Source: | https://github.com/bsc-es/epidesc |
A data.frame containing weekly dengue cases for the different municipalities in the state of Rio de Janeiro for the period 2017-2022.
data(dengueRio)data(dengueRio)
dengueRioA data frame with 28,796 rows and 4 columns:
Municipality code
Starting date of the week (Sunday)
Number of dengue cases
Population
doi:10.1371/journal.pntd.0010746
Maximum cases peak - amplitude.
desc_Ap(df)desc_Ap(df)
df |
A data.frame with a numeric 'cases' column. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Ap epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Ap(oneyear)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Ap(oneyear)
Maximum duration in consecutive weeks with at least 'x' cases.
desc_Cmax(df, x)desc_Cmax(df, x)
df |
A data.frame with a numeric 'cases' column. |
x |
Number of cases. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Cmax epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cmax(oneyear, 50)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cmax(oneyear, 50)
Median duration in consecutive weeks with at least 'x' cases.
desc_Cmed(df, x)desc_Cmed(df, x)
df |
A data.frame with a numeric 'cases' column. |
x |
Number of cases. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Cmed epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cmed(oneyear, 50)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cmed(oneyear, 50)
Frequency of periods of consecutive 'n' weeks or longer with at least 'x' cases.
desc_Cnf(df, n, x)desc_Cnf(df, n, x)
df |
A data.frame with a numeric 'cases' column. |
n |
Number of consecutive weeks. |
x |
Number of cases. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Cnf epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cnf(oneyear, 3, 50)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cnf(oneyear, 3, 50)
Frequency of periods of consecutive weeks with at least 'n' weeks without cases.
desc_Cwf(df, n)desc_Cwf(df, n)
df |
A data.frame with a numeric 'cases' column. |
n |
Number of consecutive weeks. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Cwf epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cwf(oneyear, 3)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cwf(oneyear, 3)
Maximum duration in consecutive weeks without cases.
desc_Cwmax(df)desc_Cwmax(df)
df |
A data.frame with a numeric 'cases' column. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Cwmax epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cwmax(oneyear)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cwmax(oneyear)
Median duration in consecutive weeks without cases.
desc_Cwmed(df)desc_Cwmed(df)
df |
A data.frame with a numeric 'cases' column. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Cwmed epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cwmed(oneyear)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Cwmed(oneyear)
Disease incidence per 'p' persons.
desc_Inc(df, p)desc_Inc(df, p)
df |
A data.frame with numeric 'cases' and 'pop' columns. |
p |
Number of persons representing the scale of the incidence. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Inc epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Inc(oneyear, 100000)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Inc(oneyear, 100000)
Number of weeks with isolated cases, i.e. weeks with 0 cases both in the previous and following week.
desc_Isof(df)desc_Isof(df)
df |
A data.frame with a numeric 'cases' column. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Isof epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Isof(oneyear)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_Isof(oneyear)
List of epidescriptors and their parameters
desc_list()desc_list()
A data.frame with the functions, descriptions, classes and parameters of the descriptors included in the package.
desc_list()desc_list()
Proportion of weeks with at least 'x' cases.
desc_p(df, x)desc_p(df, x)
df |
A data.frame with a numeric 'cases' column. |
x |
Number of cases. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed p epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_p(oneyear, 50)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] desc_p(oneyear, 50)
Week where the maximum peak occurred.
desc_Tp(df)desc_Tp(df)
df |
A data.frame with numeric 'cases' and 'epiweek' columns. |
This function is designed to be called by desc_year on data that has already been split into a single epidemiological year for a single spatial unit. Using it directly outside of that context is not recommended, as no input validation is performed.
The computed Tp epidescriptor.
# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] oneyear$epiweek <- as.numeric(substr(oneyear$time, 5, 6)) desc_Tp(oneyear)# Single spatial unit and epidemiological year oneyear <- dengueRio[dengueRio$muni_code == 330455, ] oneyear$time <- epiyearweek(oneyear$date) oneyear <- oneyear[substr(oneyear$time, 1, 4) == "2019", ] oneyear$epiweek <- as.numeric(substr(oneyear$time, 5, 6)) desc_Tp(oneyear)
Compute yearly epi descriptors based on weekly case counts.
desc_year( data, cases, time, space, descriptors, pop = NULL, sweek = 1, collapse53 = TRUE )desc_year( data, cases, time, space, descriptors, pop = NULL, sweek = 1, collapse53 = TRUE )
data |
Data frame with the input data. |
cases |
Character. Name of the variable in |
time |
Character. Name of the variable in |
space |
Character. Name of the variable in |
descriptors |
A named list with the descriptor function and their arguments. See details. |
pop |
Character. Name of the variable in |
sweek |
Integer between 1-52 that determines the first week of
the season for which the descriptors will be calculated; e.g. |
collapse53 |
If TRUE (default), collapse week 53 such that half of the cases are assigned to the previous (w52) and next (w01) weeks. It is recommended so that all years have the same number of weeks. |
The argument descriptors consists of a nested list where:
The name of the first level will determine the name of the descriptor.
The elements of the first levels should also be a list with elements
fun (descriptor type) and the parameters n, x or p if necessary.
Please see the example to see it in practice.
A data frame with the resulting descriptors for every epidemiological year.
desc_list to access the list of descriptors and its parameters.
# Spatiotemporal data(dengueRio) dengue <- dengueRio # Prepare epiyearweeks dengue$yearweek <- epiyearweek(dengue$date) # List of descriptors to be computed descriptors <- list( "Ap" = list(fun = "Ap"), "Tp" = list(fun = "Tp"), "Cnf" = list(fun = "Cnf", n = 3, x = 5), "Cnf2" = list(fun = "Cnf", n = 6, x = 5), "Cmax" = list(fun = "Cmax", x = 5), "Cmed" = list(fun = "Cmed", x = 5), "p" = list(fun = "p", x = 5), "Cwf" = list(fun = "Cwf", n = 3), "Cwf2" = list(fun = "Cwf", n = 6), "Cwmax" = list(fun = "Cwmax"), "Cwmed" = list(fun = "Cwmed"), "Inc" = list(fun = "Inc", p = 1e5) ) # Compute them res <- desc_year( dengue, cases = "cases", time = "yearweek", space = "muni_code", pop = "pop", sweek = 40, descriptors = descriptors )# Spatiotemporal data(dengueRio) dengue <- dengueRio # Prepare epiyearweeks dengue$yearweek <- epiyearweek(dengue$date) # List of descriptors to be computed descriptors <- list( "Ap" = list(fun = "Ap"), "Tp" = list(fun = "Tp"), "Cnf" = list(fun = "Cnf", n = 3, x = 5), "Cnf2" = list(fun = "Cnf", n = 6, x = 5), "Cmax" = list(fun = "Cmax", x = 5), "Cmed" = list(fun = "Cmed", x = 5), "p" = list(fun = "p", x = 5), "Cwf" = list(fun = "Cwf", n = 3), "Cwf2" = list(fun = "Cwf", n = 6), "Cwmax" = list(fun = "Cwmax"), "Cwmed" = list(fun = "Cwmed"), "Inc" = list(fun = "Inc", p = 1e5) ) # Compute them res <- desc_year( dengue, cases = "cases", time = "yearweek", space = "muni_code", pop = "pop", sweek = 40, descriptors = descriptors )
Compute epiyearweek (yyyyww) indicators from dates.
epiyearweek(date, start = "Sunday")epiyearweek(date, start = "Sunday")
date |
A date vector to compute epiweekyear. |
start |
First day of the epiweek. Defaults to 'Sunday', but can be also set to 'Monday'. |
The function uses lubridate's epi/iso week/year functions to compute the conversion.
An epiweekyear character vector.
input_dates <- seq.Date(as.Date("2025-01-01"), length.out = 7, by = "week") epiyearweek(input_dates)input_dates <- seq.Date(as.Date("2025-01-01"), length.out = 7, by = "week") epiyearweek(input_dates)