ggsurveillance (version 0.5.1)

create_agegroups: 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
)

Value

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

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

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
)