The data-dot mechanism

The data-dot mechanism injects automatically .data = . in the call to a function when it detects it is necessary (most of the time, when .data= is missing, or a unnamed first argument is not suitable as .data, i.e., it is not a data.frame). This is useful to avoid having to avoid writing . "everywhere" in your functions when you use the explicit pipe operator %>.%, or with .= ... constructs. The data-dot mechanism may fail with an error message if it cannot inject . as .data=, or when . is not found. It may also be prohibited if the variable .SciViews.implicit.data.dot is set to ,0 FALSE (see examples).

Examples

# Here is how you create a data-dot function
my_subset <- function(.data = (.), i, j) {
  # This makes it a data-dot function
  if (!prepare_data_dot(.data))
    return(recall_with_data_dot())

  # Code of the function
  # Second argument (i here) must not be a data.frame to avoid confusion
  message(".env has ", paste(names(.env), collapse = ", "))
  .data[i, j]
}
dtf1 <- data.frame(x = 1:3, y = 4:6)
my_subset(dtf1, 1, 'y')
#> .env has .__top_call__., .env, ., .data, i, j
#> [1] 4
# If .data is in '.', it can be omitted
.= dtf1
my_subset(1, 'y')
#> Error in recall_with_data_dot(): Data-dot mechanism activated, but no `.` object found.
#> ℹ Define `.` before calling this function, or provide `.data=` explicitly.
#> ℹ See `?svMisc::data_dot_mechanism()` for more infos.

# This mechanism is potentially confusing. You can inactivate it anywhere:
.SciViews.implicit.data.dot <- FALSE
# This time next call is wrong
try(my_subset(1, 'y'))
#> Error in recall_with_data_dot() : 
#>   Data-dot mechanism activated, but no `.` object found.
#> ℹ Define `.` before calling this function, or provide `.data=` explicitly.
#> ℹ See `?svMisc::data_dot_mechanism()` for more infos.
# You must indicate '.' explicitly in that case:
my_subset(., 1, 'y')
#> .env has .__top_call__., .env, ., .data, i, j
#> [1] 4
rm(.SciViews.implicit.data.dot) # Reactivate it
my_subset(1, 'y') # Implicit again
#> Error in recall_with_data_dot(): Data-dot mechanism activated, but no `.` object found.
#> ℹ Define `.` before calling this function, or provide `.data=` explicitly.
#> ℹ See `?svMisc::data_dot_mechanism()` for more infos.
# Note that, if you have not defined '.' and try to use it, you got
# an error:
rm(.)
try(my_subset(1, 'y'))
#> Error in recall_with_data_dot() : 
#>   Data-dot mechanism activated, but no `.` object found.
#> ℹ Define `.` before calling this function, or provide `.data=` explicitly.
#> ℹ See `?svMisc::data_dot_mechanism()` for more infos.

See also

Examples