format_triangle_multi: Format labels for multi-year Lexis triangles
In johnrbryant/demprep: Prepare Demographic Data

Description Usage Arguments Details Value See Also Examples

Format labels for multi-year Lexis triangles to be used with multi-year age groups and periods. These age groups and periods (apart from a possible open age group) all have the same width, which is set by the width parameter.

format_triangle_multi(
  x,
  age,
  period,
  width = 5,
  break_max = 100,
  open_last = TRUE,
  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_max`	An integer or `NULL`. Defaults to 100.
`open_last`	Whether the final age group has no upper limit. Defaults to `TRUE`.
`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 can be single-year ("23"), multi-year ("20-24") or open ("100+"), and periods can be single-year ("2023") or multi-year ("2020-2025").

The values for width, break_max, open_last, and origin together define a new system of Lexis triangles. format_triangle_multi 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_multi returns "Lower".

open_last determines whether the triangles need to account for an open age group, and break_max specifies the cut-off for the open age group. See format_age_multi for a description of how open_last and break_max determine age groups.

x and period must be based on the same starting month, so that if x uses years that start in July and end in June, then period must do so too. If x was created using function date_to_triangle_year and period was created using function date_to_period_year, then both should have used the same value for month_start. If x and period were not calculated from raw dates data, then it may be necessary to check the documentation for x and period to see which months of the year were used.

A factor with the same length as x.

Other functions for reformating triangle labels are format_triangle_year, format_triangle_births, 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_original <- c("2024-03-27", "2022-11-09")
dob_original <- "2020-01-01"
x <- date_to_triangle_year(date = date_original,
                           dob = dob_original,
                           month_start = "Jul")
age <- date_to_age_year(date = date_original,
                        dob = dob_original)
period <- date_to_period_year(date = date_original,
                              month_start = "Jul")
format_triangle_multi(x = x,
                      age = age,
                      period = period)

## someone else has constructed
## 'x', 'age', and 'period' from
## dates information
x_processed <- c("Lower", "Lower", "Lower")
age_processed <- c("10", "20+", "5")
period_processed <- c(2002, 2015, 2011)
format_triangle_multi(x = x_processed,
                      age = age_processed,
                      period = period_processed,
                      break_max = 20)

## alternative value for 'width'
format_triangle_multi(x = x_processed,
                      age = age_processed,
                      period = period_processed,
                      width = 10,
                      break_max = 20)

## alternative value for 'break_max'
format_triangle_multi(x = x_processed,
                      age = age_processed,
                      period = period_processed,
                      break_max = 10)