Author: tatooheene team
Date: 2025-12-15

# Friction period: lookups in days/weeks (1-year vs 5-year average)

#### tatooheene team

#### 2025-12-15

## What this vignette covers

- What the friction period is and where it lives in `tatooheene::df_fp`.
- How to use `friction_period()` to:
  - get weeks or days,
  - choose 1‑year vs 5‑year average, and
  - return either a table or a single value.

> The function is . Column names reflect the CBS table embedded in `df_fp`.

## The underlying data

    df_fp %>%
      select(Year,
             `Friction period in days`,
             `Friction period days average over 5 years`,
             `Friction period in weeks`,
             `Friction period weeks average over 5 years`) %>%
      head()
    #> # A tibble: 6 × 5
    #>    Year `Friction period in days` Friction period days …¹ Friction period in w…²
    #>   <dbl>                     <dbl>                   <dbl>                  <dbl>
    #> 1  1997                      NA                      NA                     NA
    #> 2  1998                      87.6                    NA                     12.5
    #> 3  1999                      97.5                    NA                     13.9
    #> 4  2000                     103.                     NA                     14.7
    #> 5  2001                     101.                     NA                     14.5
    #> 6  2002                      98.3                    97.5                   14.0
    #> # ℹ abbreviated names: ¹​`Friction period days average over 5 years`,
    #> #   ²​`Friction period in weeks`
    #> # ℹ 1 more variable: `Friction period weeks average over 5 years` <dbl>

## Quick starts

### 1) Default: all years, weeks, 5‑year average

    tatooheene::friction_period()
    #> # A tibble: 27 × 2
    #>     Year `Friction period weeks average over 5 years`
    #>    <dbl>                                        <dbl>
    #>  1  1997                                         NA
    #>  2  1998                                         NA
    #>  3  1999                                         NA
    #>  4  2000                                         NA
    #>  5  2001                                         NA
    #>  6  2002                                         13.9
    #>  7  2003                                         13.9
    #>  8  2004                                         13.7
    #>  9  2005                                         13.5
    #> 10  2006                                         13.6
    #> # ℹ 17 more rows

### 2) Specific year, weeks, 5‑year average → single value

    tatooheene::friction_period(year = 2019, units = "weeks", avg = "5yr", output = "value")
    #> [1] 14.26372

### 3) Days, 1‑year values for a range of years

    tatooheene::friction_period(year = 2018:2020, units = "days", avg = "1yr")
    #> # A tibble: 3 × 2
    #>    Year `Friction period in days`
    #>   <dbl>                     <dbl>
    #> 1  2018                      107.
    #> 2  2019                      111.
    #> 3  2020                      102.

### 4) Multiple selections return multiple columns

    tatooheene::friction_period(
      year  = 2015:2019,
      units = c("days", "weeks"),
      avg   = "1yr"       # try c("1yr","5yr") to get four columns
    )
    #> # A tibble: 5 × 3
    #>    Year `Friction period in days` `Friction period in weeks`
    #>   <dbl>                     <dbl>                      <dbl>
    #> 1  2015                      87.2                       12.5
    #> 2  2016                      92.2                       13.2
    #> 3  2017                     101.                        14.5
    #> 4  2018                     107.                        15.3
    #> 5  2019                     111.                        15.9

## Error messages you might see

- “Year out of range …”
  You asked for a year outside `range(df_fp$Year)`. Use a valid year or pass `NULL` for all years.

- “For `output = "value"`, provide exactly one `year` and a single (units, avg) combination.”
  Single value mode needs exactly one year and one `(units, avg)`.