Functions Session 3: Tidy eval

[ijlyttle]

By the end of this session, you will be able to:

• build functions that call tidyverse functions, using bare-name arguments:
  • designed for interactive use, i.e. just like dplyr::group_by()
  • understand tidy eval nomenclature: data masking, tidy select, dynamic dots
• recognize other ways to use tidy eval:
  • functions that call tidyverse functions, using string-based arguments, e.g. for use with Shiny:
  • recognize the correspondence for each of the techniques used for bare-name arguments.
  • implementation of non-standard evaluation:
  • understand that theory and tools exist.

[ijlyttle]

This one is going to be a bear - it would not surprise me if it leaks into session 4 (by time). As a result, I plan to keep session 4 (by curriculum) light.

Section details

Our goal is to integrate tidyverse tidy-eval functions into your functions, so they work "seamlessly" for your users.

Tide eval overview [15 min]

• Tidy eval (and NSE generally in R) exists so that we can refer to data columns using bare names.
  • It makes things easier if you are working interactively.
  • It makes things more interesting if you are writing functions. Welcome to "more interesting".
• There are two families of functionality for tidy eval:
  • data-masking: evaluating a column-name in context of data frame: mutate(wt_kg = wt * 1000 / 2.2)
  • tidy-select: specifying columns within a data frame: select(starts_with("w"))
• There are two ways of expressing tidy eval:
  • using bare names: mutate(wt_kg = wt * 1000 / 2.2), what we do in interactive programming
  • using strings: mutate("wt_kg" := .data[["wt"]] * 1000 / 2.2), useful for Shiny (esp. with string variables)

Pass the dots [15 min]

• This is your "get out of jail free" card, if you can use it.
• If you can just pass your users' arguments straight to a tidyverse function, this is by far the simplest thing to do.
• add ... to formals of uss_get_matches(), pass ... to dplyr::filter().

.data and .env pronouns [10 mins]

• in data-masking functions use .data and .env pronouns to be unambiguous on the context of each variable.
• we have already been introduced to the .data pronoun
• add .env to your package-toolkit: usethis::use_import_from("rlang", ".data")
• demo: in uss_make_teams_matches(), use .env$at_home in mutate()

!!! [5 mins]

• splicing operator
• use to splice a vector or a list into a ... argument (similar to JavaScript destructuring)
• demo: in uss_make_teams_matches(), splice rename_home(), rename_visitor() into rename()

Naming new columns using "{}" and := [5 mins]

• in data-masking functions, e.g. dplyr::mutate(), dplyr::group_by(), sometimes you need to create new column-names programmatically.
• use "{}" as the left-side expression to create the name (uses glue internally)
• use := as the assignment operator
• no need to import anything, the data-masking functions will know what to do with the syntax.
• demo: in uss_make_teams_matches(), dplyr::mutate("{name_of_at_home}" := .env$at_home)

across() [10 mins]

• sometimes you want to do the same thing to a bunch of columns in a data frame
• doing somethings means using data-masking functions
• identifying columns means tidy-select
• dplyr::across() provides the bridge
• demo: in uss_make_teams_matches(), convert arrange() to use across()
• exercise: demonstrate use of uss_make_teams_matches() in package vignette.

Exercise: build uss_make_seasons_final() [15 mins]

This will be a free-form exercise, where:

• we start with seasons_intermediate() and uss_make_seasons_cumulative()
• the goal is to build a new function uss_make_seasons_final() which will be mostly a copy of uss_make_seasons_cumulative()
• write up uss_make_seasons_final() in package vignette

{{}} [15 mins]

• names: "embrace the argument", "curly curly", "interpolation"
• like glue, but for data-masking expressions
• demo: for uss_plot_seasons_tiers(), add aes_y formal to function, use {{}} to interpolate into ggplot2::aes().
• exercises:
  • write this up in package vignette
  • get snapshot testing working (show review by changing color of geom_point())
  • make another snapshot test using another measure (e.g. wins - losses)

At end

everything but the uss_results object.

References