format_triangle_births: Format labels for Lexis triangles used when tabulating births
In johnrbryant/demprep: Prepare Demographic Data

Description Usage Arguments Details Value See Also Examples

Format labels for Lexis triangles to be used with age groups and periods for tabulating births. These age groups and periods must all have the same length, which is set by the width parameter.

format_triangle_births(
  x,
  age,
  period,
  width = 5,
  break_min = 15,
  break_max = 50,
  recode_up = FALSE,
  recode_down = FALSE,
  month_start = "Jan",
  label_year_start = TRUE,
  origin = 2000
)

`x`	A vector of Lexis triangle labels.
`age`	A vector of age groups, the same length as `x`.
`period`	A vector of periods, the same length as `x`.
`width`	The width, in whole years, of the triangles to be created. Defaults to 5.
`break_min`	An integer or `NULL`. Defaults to 15.
`break_max`	An integer or `NULL`. Defaults to 50.
`recode_up`	If `TRUE`, births to parents aged less than `break_min` are treated as occurring to people in the youngest repoductive age group.
`recode_down`	If `TRUE`, births to parents aged `break_max` or more are treated as occurring to people in the oldest reproductive age group.
`month_start`	An element of `month.name`, or `month.abb`. Periods start on the first day of this month.
`label_year_start`	Logical. Whether a single-year period in `x` is labelled using the calendar year at the beginning of the period or the calendar year at the end. Defaults to `TRUE`.
`origin`	An integer. Defaults to 2000.

age and period define the age groups and periods to which the Lexis triangles in x belong. These age groups and periods can be narrower than width. Age groups and periods can be single-year ("23", "2023") or multi-year ("20-24", "2020-2025").

break_min and break_max specify the range of ages over which reproduction is assumed to occur, and recode_up and recode_down control the way that reported ages outside this range are handled. See format_age_births for details.

The values for width, break_min, break_max, and origin together define a new system of Lexis triangles. format_triangle_births calculates where the triangles defined by x, age, and period fall within this new system. For instance, if an upper triangle defined by x, age, and period falls entirely within a lower triangle in the new system, then format_triangle_births returns "Lower".

If recode_up is TRUE and an age is recoded upwards to fall within the youngest reproductive age group, then the corresponding Lexis triangle is set to "Lower". If recode_down is FALSE and an age is recoded downwards to fall within the lowest reproductive age group, then the corresponding Lexis triangle is set to "Upper".

A factor with the same length as x.

Other functions for creating Lexis triangles are format_triangle_year, format_triangle_multi, format_triangle_quarter, and format_triangle_month.

date_to_triangle_year creates Lexis triangles from dates.

## we construct 'x', 'age', and 'period'
## from dates information ourselves before
## calling 'format_triangle_multi'
date_birth <- c("2024-03-27", "2022-11-09")
dob_mother <- "2000-01-01"
x <- date_to_triangle_year(date = date_birth,
                           dob = dob_mother,
                           month_start = "Jul")
age <- date_to_age_year(date = date_birth,
                        dob = dob_mother)
period <- date_to_period_year(date = date_birth,
                              month_start = "Jul")
format_triangle_births(x = x,
                       age = age,
                       period = period)

## someone else has constructed
## 'x', 'age', and 'period' from
## dates information
x_processed <- c("Lower", "Upper", "Upper")
age_processed <- c("20", "30-34", "25")
period_processed <- c("2002", "2015-2020", "2011")
format_triangle_births(x = x_processed,
                       age = age_processed,
                       period = period_processed)

## recode up and down
x <- c("Upper", "Lower", "Upper")
age <- c("10", "50-54", "25")
period <- c("2002", "2015-2020", "2011")
format_triangle_births(x = x,
                       age = age,
                       period = period,
                       recode_up = TRUE,
                       recode_down = TRUE)