Skip to contents

Cut integer sequences into labeled blocks (ages or years)

Source: R/prep.R
cut_int.Rd

cut_int() turns an integer vector into labeled blocks using an increasing vector of break points.

Labels are of the form "start-end" for multi-year/age blocks and "k" for single blocks. The last label always ends at max(x) (e.g. "2003-2025" or "14").

Convenience wrappers cut_ages() and cut_years() call cut_int() with argument names that read naturally for common assessment inputs.

Usage

cut_int(x, breaks, ordered = FALSE)

cut_ages(ages, breaks)

cut_years(years, breaks)

Arguments

x, ages, years

Integer vector to be grouped.

breaks

Integer vector of group starts (strictly increasing). Must start at min(x) and end at max(x).

ordered

Logical; should the returned factor be ordered? Default is FALSE.

Value

A factor with the same length as x, whose levels enumerate the blocks in increasing order.

Details

Breaks normally mark the first value in each block. The final break must equal max(x). If the gap between the last two breaks exceeds one, the final break closes the preceding block rather than starting a singleton. For example, c(2, 5, 8) gives 2-4 and 5-8, whereas c(2, 5, 7, 8) gives 2-4, 5-6, 7, and 8. This convention also defines M age blocks.

Input requirements (enforced):

  • x, ages, years are numeric, integer-valued, and non-NA.

  • breaks is numeric, increasing, and non-NA.

  • min(x) == breaks[1] and max(x) == tail(breaks, 1).

See also

base::findInterval(), stats::model.matrix()

Examples

# Ages: single-year blocks
cut_ages(2:14, 2:14)
#>  2  3  4  5  6  7  8  9 10 11 12 13 14 
#>  2  3  4  5  6  7  8  9 10 11 12 13 14 
#> Levels: 2 3 4 5 6 7 8 9 10 11 12 13 14

# Ages: a wide block then singletons
cut_ages(2:14, c(2, 10, 11:14))
#>   2   3   4   5   6   7   8   9  10  11  12  13  14 
#> 2-9 2-9 2-9 2-9 2-9 2-9 2-9 2-9  10  11  12  13  14 
#> Levels: 2-9 10 11 12 13 14

# Ages: even-width blocks, last block closes at max age
cut_ages(2:14, seq(2, 14, by = 2))
#>     2     3     4     5     6     7     8     9    10    11    12    13    14 
#>   2-3   2-3   4-5   4-5   6-7   6-7   8-9   8-9 10-11 10-11 12-14 12-14 12-14 
#> Levels: 2-3 4-5 6-7 8-9 10-11 12-14

# Years: management-era blocks
cut_years(1983:2025, c(1983, 1992, 1997, 2003, 2025))
#>      1983      1984      1985      1986      1987      1988      1989      1990 
#> 1983-1991 1983-1991 1983-1991 1983-1991 1983-1991 1983-1991 1983-1991 1983-1991 
#>      1991      1992      1993      1994      1995      1996      1997      1998 
#> 1983-1991 1992-1996 1992-1996 1992-1996 1992-1996 1992-1996 1997-2002 1997-2002 
#>      1999      2000      2001      2002      2003      2004      2005      2006 
#> 1997-2002 1997-2002 1997-2002 1997-2002 2003-2025 2003-2025 2003-2025 2003-2025 
#>      2007      2008      2009      2010      2011      2012      2013      2014 
#> 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 
#>      2015      2016      2017      2018      2019      2020      2021      2022 
#> 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 2003-2025 
#>      2023      2024      2025 
#> 2003-2025 2003-2025 2003-2025 
#> Levels: 1983-1991 1992-1996 1997-2002 2003-2025

# Direct use with ordered = TRUE (if useful for contrasts)
cut_int(2:10, c(2, 5, 8, 10), ordered = TRUE)
#>    2    3    4    5    6    7    8    9   10 
#>  2-4  2-4  2-4  5-7  5-7  5-7 8-10 8-10 8-10 
#> Levels: 2-4 < 5-7 < 8-10