The zeallot package defines an operator for unpacking assignment, sometimes called parallel assignment or destructuring assignment in other programming languages. The operator is written as %<-% and used like this.
{ lat : lng } %<-% list(38.061944, -122.643889)The result is that the list is unpacked into its elements, and the elements are assigned to lat and lng.
lat
#> [1] 38.06194
lng
#> [1] -122.6439You can also unpack the elements of a vector. Omit the braces ({}) in that case.
lat : lng %<-% c(38.061944, -122.643889)
lat
#> [1] 38.06194
lng
#> [1] -122.6439You can unpack much longer structures, too, of course, such as the 6-part summary of a vector.
min_wt : q1_wt : med_wt : mean_wt : q3_wt : max_wt %<-% summary(mtcars$wt)
min_wt
#> [1] 1.513
q1_wt
#> [1] 2.581
med_wt
#> [1] 3.325
mean_wt
#> [1] 3.217
q3_wt
#> [1] 3.61
max_wt
#> [1] 5.424If the left-hand side and right-hand sides do not match, an error is raised. This guards against missing or unexpected values.
{ stg1 : stg2 : stg3 } %<-% list("Moe", "Donald")
#> Error: expecting 3 values, but found 2{ stg1 : stg2 : stg3 } %<-% list("Moe", "Larry", "Curley", "Donald")
#> Error: too many values to unpackA common use-case is when a function returns a list of values and you want to extract the individual values. In this example, the list of values returned by coords_list() is unpacked into the variables lat and lng.
#
# A function which returns a list of 2 numeric values.
#
coords_list <- function() {
list(38.061944, -122.643889)
}
{ lat : lng } %<-% coords_list()
lat
#> [1] 38.06194
lng
#> [1] -122.6439As in the earlier example, colon and braces on the left-hand side of the assignment tell the assignment operator to expect a list.
In this example, we call a function that returns a vector. Now we omit the braces.
#
# Convert cartesian coordinates to polar
#
to_polar = function(x, y) {
c(sqrt(x^2 + y^2), atan(y / x))
}
radius : angle %<-% to_polar(12, 5)
radius
#> [1] 13
angle
#> [1] 0.3947911You can directly unpack the coefficients of a simple linear regression into the intercept and slope.
inter : slope %<-% coef(lm(mpg ~ cyl, data = mtcars))
inter
#> [1] 37.88458
slope
#> [1] -2.87579safelyThe purrr package includes the safely function. It wraps a given function to create a new, “safe” version of the original function.
safe_log <- purrr::safely(log)The safe version returns a list of two items. The first item is the result of calling the original function, assuming no error occurred; or NULL if an error did occur. The second item is the error, if an error occurred; or NULL if no error occurred. Whether or not the original function would have thrown an error, the safe version will never throw an error.
pair <- safe_log(10)
pair$result
#> [1] 2.302585
pair$error
#> NULLpair <- safe_log('donald')
pair$result
#> NULL
pair$error
#> <simpleError in .f(...): non-numeric argument to mathematical function>You can tighten and clarify calls to the safe function by using %<-%.
{ res : err } %<-% safe_log(10)
res
#> [1] 2.302585
err
#> NULLA data frame is simply a list of columns, so the zeallot assignment does what you expect. It unpacks the data frame into individual columns.
{ mpg : cyl : disp : hp } %<-% mtcars[, 1:4]
head(mpg)
#> [1] 21.0 21.0 22.8 21.4 18.7 18.1
head(cyl)
#> [1] 6 6 4 6 8 6
head(disp)
#> [1] 160 160 108 258 360 225
head(hp)
#> [1] 110 110 93 110 175 105Bear in mind that a list of data frames is still just a list. The assignment will extract the list elements (which are data frames) but not unpack the data frames themselves.
quartet <- lapply(1:4, function(i) anscombe[, c(i, i + 4)])
{ an1 : an2 : an3 : an4 } %<-% lapply(quartet, head, n = 3)
an1
#> x1 y1
#> 1 10 8.04
#> 2 8 6.95
#> 3 13 7.58
an2
#> x2 y2
#> 1 10 9.14
#> 2 8 8.14
#> 3 13 8.74
an3
#> x3 y3
#> 1 10 7.46
#> 2 8 6.77
#> 3 13 12.74
an4
#> x4 y4
#> 1 8 6.58
#> 2 8 5.76
#> 3 8 7.71The %<-% operator assigned four data frames to four variables, leaving the data frames intact.
In addition to unpacking flat lists, you can unpack lists of lists.
{a : { b : c } : d } %<-% list('begin', list('middle1', 'middle2'), 'end')
a
#> [1] "begin"
b
#> [1] "middle1"
c
#> [1] "middle2"
d
#> [1] "end"Not only does this simplify extracting individual elements, it also adds a level of checking. If the described list structure does not match the actual list structure, an error is raised.
{a : { b : c : x} : d } %<-% list('begin', list('middle1', 'middle2'), 'end')
#> Error: expecting 3 values, but found 2The previous examples dealt with unpacking a list or vector into its elements. You can also split certain kinds of individual values into subvalues.
You can assign individual characters of a string to variables. Since character strings are vectors, do not forget to exclude braces from the assignment expression.
ch1 : ch2 : ch3 %<-% 'abc'
ch1
#> [1] "a"
ch2
#> [1] "b"
ch3
#> [1] "c"You can split a Date into its year, month, and day, and assign the parts to variables.
y : m : d %<-% Sys.Date()
y
#> [1] 2017
m
#> [1] 1
d
#> [1] 27zeallot includes implementations of destructure for character strings, complex numbers, data frames, date objects, and linear model summaries. However, because destructure is a generic function, you can define new implementations for custom classes. When defining a new implementation keep in mind the implementation needs to return a list so that values are properly unpacked.
In some cases, you want the first few elements of a list or vector but do not care about the trailing elements. The summary function of lm, for example, returns a list of 11 values, and you might want only the first few. Fortunately, there is a way to capture those first few and say “don’t worry about everything else”.
f <- lm(mpg ~ cyl, data = mtcars)
{ fcall : fterms : resids : ...rest } %<-% summary(f)
fcall
#> lm(formula = mpg ~ cyl, data = mtcars)
fterms
#> mpg ~ cyl
#> attr(,"variables")
#> list(mpg, cyl)
#> attr(,"factors")
#> cyl
#> mpg 0
#> cyl 1
#> attr(,"term.labels")
#> [1] "cyl"
#> attr(,"order")
#> [1] 1
#> attr(,"intercept")
#> [1] 1
#> attr(,"response")
#> [1] 1
#> attr(,".Environment")
#> <environment: R_GlobalEnv>
#> attr(,"predvars")
#> list(mpg, cyl)
#> attr(,"dataClasses")
#> mpg cyl
#> "numeric" "numeric"
head(resids)
#> Mazda RX4 Mazda RX4 Wag Datsun 710 Hornet 4 Drive
#> 0.3701643 0.3701643 -3.5814159 0.7701643
#> Hornet Sportabout Valiant
#> 3.8217446 -2.5298357Here, rest will capture everything else.
str(rest)
#> List of 8
#> $ coefficients : num [1:2, 1:4] 37.885 -2.876 2.074 0.322 18.268 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:2] "(Intercept)" "cyl"
#> .. ..$ : chr [1:4] "Estimate" "Std. Error" "t value" "Pr(>|t|)"
#> $ aliased : Named logi [1:2] FALSE FALSE
#> ..- attr(*, "names")= chr [1:2] "(Intercept)" "cyl"
#> $ sigma : num 3.21
#> $ df : int [1:3] 2 30 2
#> $ r.squared : num 0.726
#> $ adj.r.squared: num 0.717
#> $ fstatistic : Named num [1:3] 79.6 1 30
#> ..- attr(*, "names")= chr [1:3] "value" "numdf" "dendf"
#> $ cov.unscaled : num [1:2, 1:2] 0.4185 -0.0626 -0.0626 0.0101
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:2] "(Intercept)" "cyl"
#> .. ..$ : chr [1:2] "(Intercept)" "cyl"The assignment operator noticed that ...rest is prefixed with ..., and it created a variable called rest for the trailing values of the list. If you omitted the “everything else” prefix, there would be an error because the lengths of the left- and right-hand sides of the assignment would be mismatched.
{ fcall : fterms : resids : rest } %<-% summary(f)
#> Error: too many values to unpackIf multiple collector variables are specified at a particular depth it is ambiguous which values to assign to which collector and an error will be raised.
In addition to collecting trailing values, you can also collect initial values and assign specific remaining values.
{ ...skip : e : f } %<-% list(1, 2, 3, 4, 5)
skip
#> [[1]]
#> [1] 1
#>
#> [[2]]
#> [1] 2
#>
#> [[3]]
#> [1] 3
e
#> [1] 4
f
#> [1] 5Or you can assign the first value, skip values, and then assign the last value.
{ begin : ...middle : end } %<-% list(1, 2, 3, 4, 5)
begin
#> [1] 1
middle
#> [[1]]
#> [1] 2
#>
#> [[2]]
#> [1] 3
#>
#> [[3]]
#> [1] 4
end
#> [1] 5You can skip one or more values without raising an error by using a period (.) instead of a variable name. For example, you might care only about the min, mean, and max values of a vector’s summary.
min_wt : . : . : mean_wt : . : max_wt %<-% summary(mtcars$wt)
min_wt
#> [1] 1.513
mean_wt
#> [1] 3.217
max_wt
#> [1] 5.424By combining an anonymous element (.) with the collector prefix, (...), you can ignore whole sublists.
{begin: ....: end} %<-% list('hello', 'blah', list('blah'), 'blah', 'world!')
begin
#> [1] "hello"
end
#> [1] "world!"You can mix periods and collectors together to selectively keep and discard elements.
{ begin : . : ...middle : end } %<-% as.list(1:5)
begin
#> [1] 1
middle
#> [[1]]
#> [1] 3
#>
#> [[2]]
#> [1] 4
end
#> [1] 5A handy trick is swapping values without the use of a temporary variable.
first : last %<-% c('Ai', 'Genly')
first
#> [1] "Ai"
last
#> [1] "Genly"
first : last %<-% c(last, first)
first
#> [1] "Genly"
last
#> [1] "Ai"or
cat <- 'meow'
dog <- 'bark'
cat : dog : fish %<-% c(dog, cat, dog)
cat
#> [1] "bark"
dog
#> [1] "meow"
fish
#> [1] "bark"