Package {epidesc}

Title: Calculation of Epidemiological Descriptors
Version: 0.1.0
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' <doi:10.1371/journal.pntd.0010746>.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: https://github.com/BSC-ES/epidesc
BugReports: https://github.com/BSC-ES/epidesc/issues
Depends: R (≥ 4.1.0)
Imports: lubridate, nseq
Encoding: UTF-8
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
LazyData: true
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-31 09:38:09 UTC; cmilagar
Author: Raquel Martins Lana ORCID iD [aut], Carles Milà ORCID iD [aut, cre], Iasmin Ferreira de Almeida [aut], Claudia Torres Codeço ORCID iD [aut], Daniela Lührsen ORCID iD [aut], Diego Ricardo Xavier Silva ORCID iD [aut], Christovam Barcellos ORCID iD [aut], Raphael Saldanha ORCID iD [aut], Rachel Lowe ORCID iD [aut]
Maintainer: Carles Milà <carles.milagarcia@bsc.es>
Repository: CRAN
Date/Publication: 2026-08-07 22:00:09 UTC

epidesc: 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' doi:10.1371/journal.pntd.0010746.

Author(s)

Maintainer: Carles Milà carles.milagarcia@bsc.es (ORCID)

Authors:

See Also

Useful links:

Dengue in Rio de Janeiro state

Description

A data.frame containing weekly dengue cases for the different municipalities in the state of Rio de Janeiro for the period 2017-2022.

Usage

data(dengueRio)

Format

dengueRio

A data frame with 28,796 rows and 4 columns:

muni_code

Municipality code

date

Starting date of the week (Sunday)

cases

Number of dengue cases

pop

Population

Source

doi:10.1371/journal.pntd.0010746

Ap

Description

Maximum cases peak - amplitude.

Usage

desc_Ap(df)

Arguments

df

A data.frame with a numeric 'cases' column.

Details

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.

Value

The computed Ap epidescriptor.

Examples

# 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)

Cmax

Description

Maximum duration in consecutive weeks with at least 'x' cases.

Usage

desc_Cmax(df, x)

Arguments

df

A data.frame with a numeric 'cases' column.

x

Number of cases.

Details

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.

Value

The computed Cmax epidescriptor.

Examples

# 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)

Cmed

Description

Median duration in consecutive weeks with at least 'x' cases.

Usage

desc_Cmed(df, x)

Arguments

df

A data.frame with a numeric 'cases' column.

x

Number of cases.

Details

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.

Value

The computed Cmed epidescriptor.

Examples

# 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)

Cnf

Description

Frequency of periods of consecutive 'n' weeks or longer with at least 'x' cases.

Usage

desc_Cnf(df, n, x)

Arguments

df

A data.frame with a numeric 'cases' column.

n

Number of consecutive weeks.

x

Number of cases.

Details

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.

Value

The computed Cnf epidescriptor.

Examples

# 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)

Cwf

Description

Frequency of periods of consecutive weeks with at least 'n' weeks without cases.

Usage

desc_Cwf(df, n)

Arguments

df

A data.frame with a numeric 'cases' column.

n

Number of consecutive weeks.

Details

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.

Value

The computed Cwf epidescriptor.

Examples

# 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)

Cwmax

Description

Maximum duration in consecutive weeks without cases.

Usage

desc_Cwmax(df)

Arguments

df

A data.frame with a numeric 'cases' column.

Details

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.

Value

The computed Cwmax epidescriptor.

Examples

# 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)

Cwmed

Description

Median duration in consecutive weeks without cases.

Usage

desc_Cwmed(df)

Arguments

df

A data.frame with a numeric 'cases' column.

Details

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.

Value

The computed Cwmed epidescriptor.

Examples

# 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)

Inc

Description

Disease incidence per 'p' persons.

Usage

desc_Inc(df, p)

Arguments

df

A data.frame with numeric 'cases' and 'pop' columns.

p

Number of persons representing the scale of the incidence.

Details

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.

Value

The computed Inc epidescriptor.

Examples

# 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)

Isof

Description

Number of weeks with isolated cases, i.e. weeks with 0 cases both in the previous and following week.

Usage

desc_Isof(df)

Arguments

df

A data.frame with a numeric 'cases' column.

Details

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.

Value

The computed Isof epidescriptor.

Examples

# 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)

Tp

Description

Week where the maximum peak occurred.

Usage

desc_Tp(df)

Arguments

df

A data.frame with numeric 'cases' and 'epiweek' columns.

Details

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.

Value

The computed Tp epidescriptor.

Examples

# 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)

List of epidescriptors and their parameters

Description

List of epidescriptors and their parameters

Usage

desc_list()

Value

A data.frame with the functions, descriptions, classes and parameters of the descriptors included in the package.

Examples

desc_list()

p

Description

Proportion of weeks with at least 'x' cases.

Usage

desc_p(df, x)

Arguments

df

A data.frame with a numeric 'cases' column.

x

Number of cases.

Details

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.

Value

The computed p epidescriptor.

Examples

# 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)

Compute yearly epidescriptors

Description

Compute yearly epi descriptors based on weekly case counts.

Usage

desc_year(
  data,
  cases,
  time,
  space,
  descriptors,
  pop = NULL,
  sweek = 1,
  collapse53 = TRUE
)

Arguments

data

Data frame with the input data.

cases

Character. Name of the variable in data that contains the case counts.

time

Character. Name of the variable in data that contains the epiyearweek date temporal identifier (see epiyearweek). It must be of type character.

space

Character. Name of the variable in data that contains the spatial identifier for which a case count time series is available.

descriptors

A named list with the descriptor function and their arguments. See details.

pop

Character. Name of the variable in data that contains the population counts. Only required if the descriptor 'Inc' (incidence) is used.

sweek

Integer between 1-52 that determines the first week of the season for which the descriptors will be calculated; e.g. sweek=40 will compute descriptors between week 40 and week 39 next year. Defaults to 1.

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.

Details

The argument descriptors consists of a nested list where:

Please see the example to see it in practice.

Value

A data frame with the resulting descriptors for every epidemiological year.

See Also

desc_list to access the list of descriptors and its parameters.

Examples

# 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.

Description

Compute epiyearweek (yyyyww) indicators from dates.

Usage

epiyearweek(date, start = "Sunday")

Arguments

date

A date vector to compute epiweekyear.

start

First day of the epiweek. Defaults to 'Sunday', but can be also set to 'Monday'.

Details

The function uses lubridate's epi/iso week/year functions to compute the conversion.

Value

An epiweekyear character vector.

Examples

input_dates <- seq.Date(as.Date("2025-01-01"), length.out = 7, by = "week")
epiyearweek(input_dates)