Details on Casting Functions

Description

‘broadcast’ provides several "casting" functions.
These can facilitate complex forms of broadcasting that would normally not be possible.
But these "casting" functions also have their own merit, beside empowering complex broadcasting.

The following casting functions are available:

  • acast:
    Casts group-based subsets of an array into a new dimension.
    Useful for, for example, performing grouped broadcasted operations.

  • cast_hier2dim:
    Casts a nested/hierarchical list into a dimensional list (i.e. array of type list).
    Useful because one cannot broadcast through nesting, but one can broadcast along dimensions.

  • hier2dim, hiernames2dimnames:
    Helper functions for cast_hier2dim.

  • cast_dim2hier:
    Casts a dimensional list into a nested/hierarchical list; the opposite of cast_hier2dim.

  • cast_dim2flat:
    Casts a dimensional list into a flattened list, but with names that indicate their original dimensional positions.
    Mostly useful for printing or summarizing dimensional lists.

  • dropnests:
    Drop redundant nesting in lists; mostly used for facilitating the above casting functions.

Shared argument recurse_all

The dropnests, hier2dim, hiernames2dimnames, and cast_hier2dim methods all have the recurse_all argument.
By default recurse_all = FALSE, meaning these methods do not recurse through dimensional or classed lists (like data.frames).
Setting recurse_all = TRUE allows these methods to recurse through all list objects, even if they are dimensional and/or classed.

Shared Argument in2out

The hier2dim, hiernames2dimnames, cast_hier2dim, and cast_dim2hier methods all have the in2out argument.


[TRUE]
By default in2out is TRUE.
This means the call
y <- cast_hier2dim(x)
will cast the elements of the deepest valid depth of x to the rows of y, and elements of the depth above that to the columns of y, and so on until the surface-level elements of x are cast to the last dimension of y.

Similarly, the call
x <- cast_dim2hier(y)
will cast the rows of y to the inner most elements of x, and the columns of y to one depth above that, and so on until the last dimension of y is cast to the surface-level elements of x.

Consider the nested list x with a depth of 3, and the recursive array y with 3 dimensions, where their relationship can described as the following code:
y <- cast_hier2dim(x)
x <- cast_dim2hier(y).
Then it holds that:
x[[i]][[j]][[k]] corresponds to y[[k, j, i]],
\(\forall\)(i, j, k) , provided x[[i]][[j]][[k]] exists.


[FALSE]
If in2out = FALSE, the call
y <- cast_hier2dim(x, in2out = FALSE)
will cast the surface-level elements of x to the rows of y, and elements of the depth below that to the columns of y, and so on until the elements of the deepest valid depth of x are cast to the last dimension of y.

Similarly, the call
x <- cast_dim2hier(y, in2out = FALSE)
will cast the rows of y to the surface-level elements of x, and the columns of y to one depth below that, and so on until the last dimension of y is cast to the inner most elements of x.

Consider the nested list x with a depth of 3, and the recursive array y with 3 dimensions, where their relationship can described with the following code:
y <- cast_hier2dim(x, in2out = FALSE)
x <- cast_dim2hier(y, in2out = FALSE).
Then it holds that :
x[[i]][[j]][[k]] corresponds to y[[i, j, k]],
\(\forall\)(i, j, k) , provided x[[i]][[j]][[k]] exists.

Examples

library("broadcast")


x <- list(
  group1 = list(
    class1 = list(
      height = rnorm(10, 170),
      weight = rnorm(10, 80),
      sex = sample(c("M", "F", NA), 10, TRUE)
    ),
    class2 = list(
      height = rnorm(10, 170),
      weight = rnorm(10, 80),
      sex = sample(c("M", "F", NA), 10, TRUE)
    )
  ),
  group2 = list(
    class1 = list(
      height = rnorm(10, 170),
      weight = rnorm(10, 80),
      sex = sample(c("M", "F", NA), 10, TRUE)
    ),
    class2 = list(
      height = rnorm(10, 170),
      weight = rnorm(10, 80),
      sex = sample(c("M", "F", NA), 10, TRUE)
    )
  )
)

# predict dimensions x would have if casted as dimensional:
hier2dim(x, in2out = FALSE)
##       
## 2 2 3

# cast x to dimensional list:
x2 <- cast_hier2dim(x, in2out = FALSE)

# set dimnames of dimensionally casted list:
dimnames(x2) <- hiernames2dimnames(x, in2out = FALSE)

# print result:
print(x2) # very compact
## , , height
## 
##        class1     class2    
## group1 numeric,10 numeric,10
## group2 numeric,10 numeric,10
## 
## , , weight
## 
##        class1     class2    
## group1 numeric,10 numeric,10
## group2 numeric,10 numeric,10
## 
## , , sex
## 
##        class1       class2      
## group1 character,10 character,10
## group2 character,10 character,10
cast_dim2flat(x2) |> print() # less compact
## $`['group1', 'class1', 'height']`
##  [1] 169.2669 170.2367 168.9382 170.5442 170.8204 168.0740 169.6721 170.2472
##  [9] 169.3662 170.1853
## 
## $`['group2', 'class1', 'height']`
##  [1] 170.4432 168.1245 171.2279 170.1342 170.2633 170.9113 170.3466 173.1803
##  [9] 169.6348 171.5364
## 
## $`['group1', 'class2', 'height']`
##  [1] 170.2946 169.9109 169.3800 169.8165 170.9035 169.9816 172.9401 169.8262
##  [9] 170.6062 169.5551
## 
## $`['group2', 'class2', 'height']`
##  [1] 171.0235 169.7791 168.7454 170.1600 170.0507 171.2944 168.1184 170.9837
##  [9] 169.8123 170.5402
## 
## $`['group1', 'class1', 'weight']`
##  [1] 79.61643 80.82503 80.54455 81.61837 80.94181 81.59409 80.52448 77.64621
##  [9] 80.07591 79.72437
## 
## $`['group2', 'class1', 'weight']`
##  [1] 80.11665 80.96440 80.76536 80.26333 81.00792 81.70307 80.58215 81.38071
##  [9] 80.00661 78.44380
## 
## $`['group1', 'class2', 'weight']`
##  [1] 79.51710 80.03589 79.63715 81.81445 80.49802 80.12501 80.01528 80.57426
##  [9] 80.68996 79.99940
## 
## $`['group2', 'class2', 'weight']`
##  [1] 79.63271 80.85301 81.66676 80.47446 80.13308 80.16417 79.59062 79.29870
##  [9] 79.95957 82.49645
## 
## $`['group1', 'class1', 'sex']`
##  [1] "M" "F" "F" "M" NA  NA  NA  "M" "F" NA 
## 
## $`['group2', 'class1', 'sex']`
##  [1] NA  NA  "M" "M" NA  NA  "M" NA  NA  "F"
## 
## $`['group1', 'class2', 'sex']`
##  [1] "M" "F" NA  "F" "F" "F" "F" "F" "M" "M"
## 
## $`['group2', 'class2', 'sex']`
##  [1] "M" NA  "F" "F" "M" "M" "M" "F" NA  "M"

# cast dimensional list back to nested/hierarchical list:
x3 <- cast_dim2hier(x2, in2out = FALSE, distr.names = TRUE)
print(x3)
## $group1
## $group1$class1
## $group1$class1$height
##  [1] 169.2669 170.2367 168.9382 170.5442 170.8204 168.0740 169.6721 170.2472
##  [9] 169.3662 170.1853
## 
## $group1$class1$weight
##  [1] 79.61643 80.82503 80.54455 81.61837 80.94181 81.59409 80.52448 77.64621
##  [9] 80.07591 79.72437
## 
## $group1$class1$sex
##  [1] "M" "F" "F" "M" NA  NA  NA  "M" "F" NA 
## 
## 
## $group1$class2
## $group1$class2$height
##  [1] 170.2946 169.9109 169.3800 169.8165 170.9035 169.9816 172.9401 169.8262
##  [9] 170.6062 169.5551
## 
## $group1$class2$weight
##  [1] 79.51710 80.03589 79.63715 81.81445 80.49802 80.12501 80.01528 80.57426
##  [9] 80.68996 79.99940
## 
## $group1$class2$sex
##  [1] "M" "F" NA  "F" "F" "F" "F" "F" "M" "M"
## 
## 
## 
## $group2
## $group2$class1
## $group2$class1$height
##  [1] 170.4432 168.1245 171.2279 170.1342 170.2633 170.9113 170.3466 173.1803
##  [9] 169.6348 171.5364
## 
## $group2$class1$weight
##  [1] 80.11665 80.96440 80.76536 80.26333 81.00792 81.70307 80.58215 81.38071
##  [9] 80.00661 78.44380
## 
## $group2$class1$sex
##  [1] NA  NA  "M" "M" NA  NA  "M" NA  NA  "F"
## 
## 
## $group2$class2
## $group2$class2$height
##  [1] 171.0235 169.7791 168.7454 170.1600 170.0507 171.2944 168.1184 170.9837
##  [9] 169.8123 170.5402
## 
## $group2$class2$weight
##  [1] 79.63271 80.85301 81.66676 80.47446 80.13308 80.16417 79.59062 79.29870
##  [9] 79.95957 82.49645
## 
## $group2$class2$sex
##  [1] "M" NA  "F" "F" "M" "M" "M" "F" NA  "M"