. . .

you may have seen these before you may have an intuition of what they are but do you really know what they do and how they work?

“dots”

those three little dots are, quite uncreatively, called dots. And they’re everywhere in R

dplyr::select(.data, ...)

One or more unquoted expressions separated by commas. Variable names can be used as if they were positions in the data frame, so expressions like x:y can be used to select a range of variables.

there’s a really good chance you’ve used the select function from dplyr select uses dots—albeit a special kind called dynamic dots—to let you select many different columns with freedom

dplyr::mutate(.data, ...)

Name-value pairs. The name gives the name of the column in the output.

dots are also used in the mutate function from dplyr to let you create any columns you’d like by passing in expressions to names

paste(...)

one or more R objects, to be converted to character vectors.

the function paste from base R lets you pass in as many R objects as you would like to create nice character strings

lapply(x, FUN, ...)

optional arguments to FUN

what is ... actually doing?

so if dots do all these things what do they actually do?

dots pass arguments

everything that dots do can be distilled to passing arguments.

how we do this and in what contexts we do this can be varied to a fabulous degree

2 primary uses

• passing arguments from one function to another
• with S3 methods

according to advanced R there are two primary uses of dots they are to pass arguments from one function to another and secondly, which we will not go over in this video, is the use of dots to allow different s3 methods to take different arguments (like the very very very many predict methods)

https://adv-r.hadley.nz/functions.html#fun-dot-dot-dot

pass args with ...

lets first look at how we can pass arguments direclty into another function using dots

print_dots <- function(...) {
}

to use dots in a function you have to specify an argument with the dots

print_dots <- function(...) {
  paste(...)
}

to pass the dots directly into another function you can include them as an argument.

R will match the arguments for us like magic.

here we paste together whatever we put in to the function

print_dots <- function(...) {
  paste(...)
}

print_dots("hello", "world")

[1] "hello world"

lacking creativity lets print hello world

print_dots("my favorite letter is", letters[1:10])

 [1] "my favorite letter is a" "my favorite letter is b"
 [3] "my favorite letter is c" "my favorite letter is d"
 [5] "my favorite letter is e" "my favorite letter is f"
 [7] "my favorite letter is g" "my favorite letter is h"
 [9] "my favorite letter is i" "my favorite letter is j"

a real example

this way of using dots, when you get it, is super powerful it’s actually underpinning a majority of the functions in my package sfdep. lets take a look at one of them as an example

sfdep::local_g

function (x, nb, wt, alternative = "two.sided", ...) 
{
    if (!is.null(attr(nb, "self.included"))) {
        cli::cli_alert_warning("attr `self.include` is `TRUE`. Reporting Gi*.")
    }
    listw <- recreate_listw(nb, wt)
    res <- spdep::localG(x, listw, alternative = alternative, 
        ...)
    unclass(res)
}
<bytecode: 0x15555c720>
<environment: namespace:sfdep>

here’es a helpful tip. if you remove the parens from a function it will print its definition this function takes 3 required arguments

function(x, nb, wt, alternative = "two.sided", ...) {
  listw <- recreate_listw(nb, wt)
  res <- spdep::localG(x, listw, alternative = alternative, ...)
  unclass(res)
}

Line 1: x, nb, wt, are required, alternative is set to a default value of two.sided and the dots as an argument.

the reason why dots in this case is so powerful is that it lets us take different objects, restructure them into the required format, then pass in arguments to another function

Line 2:

spdep uses a listw object which contains two lists. 1 for identifying neighbors and the 2nd to store the spatial weights for them.

In the line we turn our arguments nb and wt into an object called listw

Line 3:

then x and the new listw function are passed to localG if any other arguments are passed in via dots they are sent to spdep

spdep::localG(x, listw)

 [1]  0.68466144 -0.40605202  0.07383123  2.38196237  3.49570413 -0.75967568
 [7] -1.47075897 -0.80197945  0.63984614  3.68140093  2.71055652 -1.42476463
[13] -1.52840421 -1.18797787 -0.40025085 -0.94197599 -1.42699800 -1.27442420
[19]  0.95260051 -1.11613385 -0.87305053  1.53226882 -1.30140672 -0.48257276
[25] -0.99299807  1.19613531  3.43442369  3.00599480 -0.13401838 -0.62625063
[31]  0.10448258  1.96469389  1.24368535  1.24089584  0.63585914  0.59413290
[37] -0.11850431  0.01405564 -0.02251821 -1.39782829 -0.06004508  0.44914259
attr(,"internals")
              Gi      E(Gi)        V(Gi)       Z(Gi) Pr(z != E(Gi))
 [1,] 0.03410220 0.02439024 2.012155e-04  0.68466144   0.4935575875
 [2,] 0.02123678 0.02439024 6.031328e-05 -0.40605202   0.6847043809
 [3,] 0.02589994 0.02439024 4.181159e-04  0.07383123   0.9411446778
 [4,] 0.04301926 0.02439024 6.116597e-05  2.38196237   0.0172206570
 [5,] 0.06901709 0.02439024 1.629758e-04  3.49570413   0.0004728126
 [6,] 0.01581567 0.02439024 1.273997e-04 -0.75967568   0.4474484718
 [7,] 0.01428647 0.02439024 4.719369e-05 -1.47075897   0.1413563133
 [8,] 0.01886835 0.02439024 4.740770e-05 -0.80197945   0.4225648455
 [9,] 0.02930272 0.02439024 5.894531e-05  0.63984614   0.5222726301
[10,] 0.04686388 0.02439024 3.726665e-05  3.68140093   0.0002319559
[11,] 0.05558392 0.02439024 1.324391e-04  2.71055652   0.0067170399
[12,] 0.01060169 0.02439024 9.365938e-05 -1.42476463   0.1542252496
[13,] 0.01286235 0.02439024 5.688833e-05 -1.52840421   0.1264122108
[14,] 0.01283815 0.02439024 9.455934e-05 -1.18797787   0.2348421270
[15,] 0.01651766 0.02439024 3.868745e-04 -0.40025085   0.6889717664
[16,] 0.01642493 0.02439024 7.150328e-05 -0.94197599   0.3462049302
[17,] 0.01218072 0.02439024 7.320670e-05 -1.42699800   0.1535804724
[18,] 0.01203614 0.02439024 9.397114e-05 -1.27442420   0.2025131206
[19,] 0.03801004 0.02439024 2.044181e-04  0.95260051   0.3407925210
[20,] 0.01170106 0.02439024 1.292513e-04 -1.11613385   0.2643648453
[21,] 0.01452569 0.02439024 1.276662e-04 -0.87305053   0.3826355348
[22,] 0.03735296 0.02439024 7.156855e-05  1.53226882   0.1254561124
[23,] 0.01333262 0.02439024 7.219342e-05 -1.30140672   0.1931192740
[24,] 0.01771664 0.02439024 1.912473e-04 -0.48257276   0.6293991246
[25,] 0.01313099 0.02439024 1.285650e-04 -0.99299807   0.3207108935
[26,] 0.03220138 0.02439024 4.264500e-05  1.19613531   0.2316437614
[27,] 0.05423393 0.02439024 7.550872e-05  3.43442369   0.0005938152
[28,] 0.05030228 0.02439024 7.430649e-05  3.00599480   0.0026471353
[29,] 0.02308668 0.02439024 9.460981e-05 -0.13401838   0.8933880369
[30,] 0.01561661 0.02439024 1.962737e-04 -0.62625063   0.5311505602
[31,] 0.02513299 0.02439024 5.053475e-05  0.10448258   0.9167863921
[32,] 0.04314622 0.02439024 9.113587e-05  1.96469389   0.0494496780
[33,] 0.03833909 0.02439024 1.257928e-04  1.24368535   0.2136153893
[34,] 0.04203957 0.02439024 2.022951e-04  1.24089584   0.2146442303
[35,] 0.02933855 0.02439024 6.056084e-05  0.63585914   0.5248682387
[36,] 0.03105930 0.02439024 1.259972e-04  0.59413290   0.5524232308
[37,] 0.02348303 0.02439024 5.860676e-05 -0.11850431   0.9056680825
[38,] 0.02452575 0.02439024 9.294972e-05  0.01405564   0.9887855902
[39,] 0.02407140 0.02439024 2.004846e-04 -0.02251821   0.9820345879
[40,] 0.01226231 0.02439024 7.527763e-05 -1.39782829   0.1621646378
[41,] 0.02356882 0.02439024 1.871478e-04 -0.06004508   0.9521197274
[42,] 0.03326650 0.02439024 3.905635e-04  0.44914259   0.6533288014
attr(,"cluster")
 [1] High High High High High Low  Low  Low  Low  High High Low  Low  Low  Low 
[16] Low  Low  Low  High Low  Low  Low  Low  Low  Low  High High High Low  Low 
[31] High Low  Low  High High Low  Low  Low  Low  High Low  Low 
Levels: Low High
attr(,"gstari")
[1] FALSE
attr(,"call")
spdep::localG(x = x, listw = listw)
attr(,"class")
[1] "localG"

let’s try calling the function as it is with its default arugments using spdep directly

sfdep::local_g(x, nb, wt)

 [1]  0.68466144 -0.40605202  0.07383123  2.38196237  3.49570413 -0.75967568
 [7] -1.47075897 -0.80197945  0.63984614  3.68140093  2.71055652 -1.42476463
[13] -1.52840421 -1.18797787 -0.40025085 -0.94197599 -1.42699800 -1.27442420
[19]  0.95260051 -1.11613385 -0.87305053  1.53226882 -1.30140672 -0.48257276
[25] -0.99299807  1.19613531  3.43442369  3.00599480 -0.13401838 -0.62625063
[31]  0.10448258  1.96469389  1.24368535  1.24089584  0.63585914  0.59413290
[37] -0.11850431  0.01405564 -0.02251821 -1.39782829 -0.06004508  0.44914259
attr(,"internals")
              Gi      E(Gi)        V(Gi)       Z(Gi) Pr(z != E(Gi))
 [1,] 0.03410220 0.02439024 2.012155e-04  0.68466144   0.4935575875
 [2,] 0.02123678 0.02439024 6.031328e-05 -0.40605202   0.6847043809
 [3,] 0.02589994 0.02439024 4.181159e-04  0.07383123   0.9411446778
 [4,] 0.04301926 0.02439024 6.116597e-05  2.38196237   0.0172206570
 [5,] 0.06901709 0.02439024 1.629758e-04  3.49570413   0.0004728126
 [6,] 0.01581567 0.02439024 1.273997e-04 -0.75967568   0.4474484718
 [7,] 0.01428647 0.02439024 4.719369e-05 -1.47075897   0.1413563133
 [8,] 0.01886835 0.02439024 4.740770e-05 -0.80197945   0.4225648455
 [9,] 0.02930272 0.02439024 5.894531e-05  0.63984614   0.5222726301
[10,] 0.04686388 0.02439024 3.726665e-05  3.68140093   0.0002319559
[11,] 0.05558392 0.02439024 1.324391e-04  2.71055652   0.0067170399
[12,] 0.01060169 0.02439024 9.365938e-05 -1.42476463   0.1542252496
[13,] 0.01286235 0.02439024 5.688833e-05 -1.52840421   0.1264122108
[14,] 0.01283815 0.02439024 9.455934e-05 -1.18797787   0.2348421270
[15,] 0.01651766 0.02439024 3.868745e-04 -0.40025085   0.6889717664
[16,] 0.01642493 0.02439024 7.150328e-05 -0.94197599   0.3462049302
[17,] 0.01218072 0.02439024 7.320670e-05 -1.42699800   0.1535804724
[18,] 0.01203614 0.02439024 9.397114e-05 -1.27442420   0.2025131206
[19,] 0.03801004 0.02439024 2.044181e-04  0.95260051   0.3407925210
[20,] 0.01170106 0.02439024 1.292513e-04 -1.11613385   0.2643648453
[21,] 0.01452569 0.02439024 1.276662e-04 -0.87305053   0.3826355348
[22,] 0.03735296 0.02439024 7.156855e-05  1.53226882   0.1254561124
[23,] 0.01333262 0.02439024 7.219342e-05 -1.30140672   0.1931192740
[24,] 0.01771664 0.02439024 1.912473e-04 -0.48257276   0.6293991246
[25,] 0.01313099 0.02439024 1.285650e-04 -0.99299807   0.3207108935
[26,] 0.03220138 0.02439024 4.264500e-05  1.19613531   0.2316437614
[27,] 0.05423393 0.02439024 7.550872e-05  3.43442369   0.0005938152
[28,] 0.05030228 0.02439024 7.430649e-05  3.00599480   0.0026471353
[29,] 0.02308668 0.02439024 9.460981e-05 -0.13401838   0.8933880369
[30,] 0.01561661 0.02439024 1.962737e-04 -0.62625063   0.5311505602
[31,] 0.02513299 0.02439024 5.053475e-05  0.10448258   0.9167863921
[32,] 0.04314622 0.02439024 9.113587e-05  1.96469389   0.0494496780
[33,] 0.03833909 0.02439024 1.257928e-04  1.24368535   0.2136153893
[34,] 0.04203957 0.02439024 2.022951e-04  1.24089584   0.2146442303
[35,] 0.02933855 0.02439024 6.056084e-05  0.63585914   0.5248682387
[36,] 0.03105930 0.02439024 1.259972e-04  0.59413290   0.5524232308
[37,] 0.02348303 0.02439024 5.860676e-05 -0.11850431   0.9056680825
[38,] 0.02452575 0.02439024 9.294972e-05  0.01405564   0.9887855902
[39,] 0.02407140 0.02439024 2.004846e-04 -0.02251821   0.9820345879
[40,] 0.01226231 0.02439024 7.527763e-05 -1.39782829   0.1621646378
[41,] 0.02356882 0.02439024 1.871478e-04 -0.06004508   0.9521197274
[42,] 0.03326650 0.02439024 3.905635e-04  0.44914259   0.6533288014
attr(,"cluster")
 [1] High High High High High Low  Low  Low  Low  High High Low  Low  Low  Low 
[16] Low  Low  Low  High Low  Low  Low  Low  Low  Low  High High High Low  Low 
[31] High Low  Low  High High Low  Low  Low  Low  High Low  Low 
Levels: Low High
attr(,"gstari")
[1] FALSE
attr(,"call")
spdep::localG(x = x, listw = listw, alternative = alternative)

compare this to the function that calls spdep but with different arguments. the results are identical

args(spdep::localG)

function (x, listw, zero.policy = NULL, spChk = NULL, GeoDa = FALSE, 
    alternative = "two.sided", return_internals = TRUE) 
NULL

spdep::localG takes additional arguments that aren’t handled by sfdep directly we can try setting one of these arguments by dots

sfdep::local_g(x, nb, wt, return_internals = TRUE)

 [1]  0.68466144 -0.40605202  0.07383123  2.38196237  3.49570413 -0.75967568
 [7] -1.47075897 -0.80197945  0.63984614  3.68140093  2.71055652 -1.42476463
[13] -1.52840421 -1.18797787 -0.40025085 -0.94197599 -1.42699800 -1.27442420
[19]  0.95260051 -1.11613385 -0.87305053  1.53226882 -1.30140672 -0.48257276
[25] -0.99299807  1.19613531  3.43442369  3.00599480 -0.13401838 -0.62625063
[31]  0.10448258  1.96469389  1.24368535  1.24089584  0.63585914  0.59413290
[37] -0.11850431  0.01405564 -0.02251821 -1.39782829 -0.06004508  0.44914259
attr(,"internals")
              Gi      E(Gi)        V(Gi)       Z(Gi) Pr(z != E(Gi))
 [1,] 0.03410220 0.02439024 2.012155e-04  0.68466144   0.4935575875
 [2,] 0.02123678 0.02439024 6.031328e-05 -0.40605202   0.6847043809
 [3,] 0.02589994 0.02439024 4.181159e-04  0.07383123   0.9411446778
 [4,] 0.04301926 0.02439024 6.116597e-05  2.38196237   0.0172206570
 [5,] 0.06901709 0.02439024 1.629758e-04  3.49570413   0.0004728126
 [6,] 0.01581567 0.02439024 1.273997e-04 -0.75967568   0.4474484718
 [7,] 0.01428647 0.02439024 4.719369e-05 -1.47075897   0.1413563133
 [8,] 0.01886835 0.02439024 4.740770e-05 -0.80197945   0.4225648455
 [9,] 0.02930272 0.02439024 5.894531e-05  0.63984614   0.5222726301
[10,] 0.04686388 0.02439024 3.726665e-05  3.68140093   0.0002319559
[11,] 0.05558392 0.02439024 1.324391e-04  2.71055652   0.0067170399
[12,] 0.01060169 0.02439024 9.365938e-05 -1.42476463   0.1542252496
[13,] 0.01286235 0.02439024 5.688833e-05 -1.52840421   0.1264122108
[14,] 0.01283815 0.02439024 9.455934e-05 -1.18797787   0.2348421270
[15,] 0.01651766 0.02439024 3.868745e-04 -0.40025085   0.6889717664
[16,] 0.01642493 0.02439024 7.150328e-05 -0.94197599   0.3462049302
[17,] 0.01218072 0.02439024 7.320670e-05 -1.42699800   0.1535804724
[18,] 0.01203614 0.02439024 9.397114e-05 -1.27442420   0.2025131206
[19,] 0.03801004 0.02439024 2.044181e-04  0.95260051   0.3407925210
[20,] 0.01170106 0.02439024 1.292513e-04 -1.11613385   0.2643648453
[21,] 0.01452569 0.02439024 1.276662e-04 -0.87305053   0.3826355348
[22,] 0.03735296 0.02439024 7.156855e-05  1.53226882   0.1254561124
[23,] 0.01333262 0.02439024 7.219342e-05 -1.30140672   0.1931192740
[24,] 0.01771664 0.02439024 1.912473e-04 -0.48257276   0.6293991246
[25,] 0.01313099 0.02439024 1.285650e-04 -0.99299807   0.3207108935
[26,] 0.03220138 0.02439024 4.264500e-05  1.19613531   0.2316437614
[27,] 0.05423393 0.02439024 7.550872e-05  3.43442369   0.0005938152
[28,] 0.05030228 0.02439024 7.430649e-05  3.00599480   0.0026471353
[29,] 0.02308668 0.02439024 9.460981e-05 -0.13401838   0.8933880369
[30,] 0.01561661 0.02439024 1.962737e-04 -0.62625063   0.5311505602
[31,] 0.02513299 0.02439024 5.053475e-05  0.10448258   0.9167863921
[32,] 0.04314622 0.02439024 9.113587e-05  1.96469389   0.0494496780
[33,] 0.03833909 0.02439024 1.257928e-04  1.24368535   0.2136153893
[34,] 0.04203957 0.02439024 2.022951e-04  1.24089584   0.2146442303
[35,] 0.02933855 0.02439024 6.056084e-05  0.63585914   0.5248682387
[36,] 0.03105930 0.02439024 1.259972e-04  0.59413290   0.5524232308
[37,] 0.02348303 0.02439024 5.860676e-05 -0.11850431   0.9056680825
[38,] 0.02452575 0.02439024 9.294972e-05  0.01405564   0.9887855902
[39,] 0.02407140 0.02439024 2.004846e-04 -0.02251821   0.9820345879
[40,] 0.01226231 0.02439024 7.527763e-05 -1.39782829   0.1621646378
[41,] 0.02356882 0.02439024 1.871478e-04 -0.06004508   0.9521197274
[42,] 0.03326650 0.02439024 3.905635e-04  0.44914259   0.6533288014
attr(,"cluster")
 [1] High High High High High Low  Low  Low  Low  High High Low  Low  Low  Low 
[16] Low  Low  Low  High Low  Low  Low  Low  Low  Low  High High High Low  Low 
[31] High Low  Low  High High Low  Low  Low  Low  High Low  Low 
Levels: Low High
attr(,"gstari")
[1] FALSE
attr(,"call")
spdep::localG(x = x, listw = listw, alternative = alternative, 
    return_internals = TRUE)

the localG function has an argument return_internals that additional data as an attribute. this isn’t a defined argument in sfdep::local_g but it can be accessed through dots

when the object is printed the difference is quite pronounced!

dots are useful when used by themselves with no special sauce. but its not the only way that they can be utilized. we can actually “capture” … them

capture

by capture, i mean make them less ephemeral and “capturing” them into a data format the is familiar and useful like a list

dots <- function(...) {
  list(...)
}

capturing dots is actually quite simple. the list() function is acting like a pokeball. capturing and taming our wild arguments

dots <- function(...) {
  list(...)
}

dots(hello = "world")

$hello
[1] "world"

if we pass in the value “world” to an argument “hello” we receive a named list this is only true, though, if we use argument names if we don’t…

dots("hello", "world")

[[1]]
[1] "hello"

[[2]]
[1] "world"

we are returned a list without names

use case

crafting data frames

data_frame <- function(...) {
  dots <- list(...)
  list2DF(dots)
}

data_frame(x = 10, y = 20)

   x  y
1 10 20

we can define a simple function that captures dots into a list that then passes that list to list2DF to create a data frame

. . .

we can use it to create a data frame with two columns x and y but what about unnamed arguments to dots? . . .

this works but it has unnamed columns. that’s bad behaviortw

data_frame <- function(...) {
  dots <- list(...)
  dots_names <- names(dots)

  list2DF(dots)

}

data_frame <- function(...) {
  dots <- list(...)
  dots_names <- names(dots)

  if (is.null(dots_names) || "" %in% dots_names) {
    stop("all arguments must be named")
  }

  list2DF(dots)

}

data_frame(1:10, letters[1:10])

Error in data_frame(1:10, letters[1:10]): all arguments must be named

data_frame(id = 1:10, alphabet = letters[1:10])

   id alphabet
1   1        a
2   2        b
3   3        c
4   4        d
5   5        e
6   6        f
7   7        g
8   8        h
9   9        i
10 10        j

dots helpers

. . . rarely useful, but good to know!

reference by position

each argument as ..1, ..2, ..3, ..n

add2 <- function(...) {
  ..1 + ..2
}

add2(3, .14)

[1] 3.14

...length()

how many arguments?

nargs <- function(...) {
  ...length()
}

nargs(1, 2, 3, 4, 5)

[1] 5

arg n

...elt(n)

first and last args

first_last <- function(...) {
 arg1 <- ..1 
 n <- ...length()
 last_arg <- ...elt(n)
 
 list(arg1, last_arg)
}

first_last("first argument", 2, NA, Inf)

[[1]]
[1] "first argument"

[[2]]
[1] Inf

WARNING:

unused dots are “swallowed”

add2(3, 0.14, 10)

[1] 3.14

check yer dots

r-lib/ellipsis: Tools for Working with …

ellipsis::check_dots_used()

• error if any arguments passed to dots aren’t used

add2 <- function(...) {
  ellipsis::check_dots_used()
 
  ..1 + ..2
}

add2(3, 0.14)

[1] 3.14

add2(3, 0.14, 0.0015)

Error in `add2()`:
! Arguments in `...` must be used.
✖ Problematic argument:
• ..1 = 0.0015
ℹ Did you misspell an argument name?

{ellipsis} helpers

• check_dots_empty()
• check_dots_unnamed()

data_frame <- function(...) {
  dots <- list(...)
  ellipsis::check_dots_empty()
  
  list2DF(dots)
}

data_frame(y = pi, exp(1))

Error in `data_frame()`:
! `...` must be empty.
✖ Problematic arguments:
• y = pi
• ..2 = exp(1)
ℹ Did you forget to name an argument?

but wait, there’s more!

but that’s for a later time

{rlang} dynamic dots

https://rlang.r-lib.org/reference/dyn-dots.html

recap

Dots can:

• pass arguments from one function to another
• be collected using list()
• be sneaky and “swallow” arguments

You should check them with {ellipsis}

what’s next?

thanks!