create_agegroups: Create Age Groups from Numeric Values

In ggsurveillance: Tools for Outbreak Investigation/Infectious Disease Surveillance

Create Age Groups from Numeric Values

Description

Creates age groups from numeric values using customizable break points and formatting options. The function allows for flexible formatting and customization of age group labels.

If a factor is returned, this factor includes factor levels of unobserved age groups. This allows for reproducible age groups, which can be used for joining data (e.g. adding age grouped population numbers for incidence calculation).

Usage

create_agegroups(
  values,
  age_breaks = c(5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90),
  breaks_as_lower_bound = TRUE,
  first_group_format = "0-{x}",
  interval_format = "{x}-{y}",
  last_group_format = "{x}+",
  pad_numbers = FALSE,
  pad_with = "0",
  collapse_single_year_groups = FALSE,
  na_label = NA,
  return_factor = FALSE
)

Arguments

values	Numeric vector of ages to be grouped
age_breaks	Numeric vector of break points for age groups. Default: c(5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90)
breaks_as_lower_bound	Logical; if TRUE (default), breaks define the the lower bounds of the intervals (e.g., a break at 5 starts the '5-9' group). If FALSE, breaks define the upper bound (e.g., a break at 5 ends the '0-5' group).
first_group_format	Character string template for the first age group. Uses glue::glue syntax. The variable x represents the upper bound of the first interval. Default: "0-{x}". Other common styles: "<={x}", "<{x+1}"
interval_format	Character string template for intermediate age groups. Uses glue::glue syntax. The variables x and y represent the lower and upper bounds of the interval, respectively. Default: "{x}-{y}". Other common styles: "{x} to {y}"
last_group_format	Character string template for the last age group. Uses glue::glue syntax. The variable x represents the lower bound of the last interval. Default: "{x}+". Other common styles: ">={x}",">{x-1}"
pad_numbers	Logical or numeric; if numeric, pad numbers up to the specified length (Tip: use 2). Not compatible with calculations within glue formats. Default: FALSE
pad_with	Character to use for padding numbers. Default: "0"
collapse_single_year_groups	Logical; if TRUE, groups spanning a single year (e.g., from age_breaks = c(1, 2)) are formatted as a single number (e.g., "1") instead of a range (e.g., "1-1"). Default: FALSE
na_label	Label for NA values. If NA, keeps default NA handling. Default: NA
return_factor	Logical; if TRUE, returns a factor, if FALSE returns character vector. Default: FALSE

Value

Vector of age group labels (character or factor depending on return_factor)

Examples

# Basic usage
create_agegroups(1:100)

# Custom formatting with upper bounds
create_agegroups(1:100,
  breaks_as_lower_bound = FALSE,
  interval_format = "{x} to {y}",
  first_group_format = "0 to {x}"
)

# Ages 1 to 5 are kept as numbers by collapsing single year groups
create_agegroups(1:10,
  age_breaks = c(1, 2, 3, 4, 5, 10),
  collapse_single_year_groups = TRUE
)

ggsurveillance documentation built on July 2, 2025, 5:09 p.m.