cast_hier2dim

Cast Hierarchical List into Dimensional list

Description

cast_hier2dim() casts a hierarchical/nested list into a dimensional list (i.e. an array of type list).

This method comes with 2 helper functions:
hier2dim and hiernames2dimnames methods.
See their help page for details.

Usage

cast_hier2dim(x, ...)

## Default S3 method:
cast_hier2dim(
  x,
  in2out = TRUE,
  maxdepth = 16L,
  recurse_all = FALSE,
  padding = list(NULL),
  ...
)

Arguments

x a nested list.
If x has redundant nesting, it is advisable (though not necessary) to reduce the redundant nesting using dropnests.

… further arguments passed to or from methods.

in2out, recurse_all see broadcast_casting.

maxdepth a single, positive integer, giving the maximum depth to recurse into the list.
The surface-level elements of a list is depth 1.

padding a list of length 1, giving the padding value to use when padding is required.
Padding is used to ensure every all slices of the same dimension in the output have equal number of elements (for example, all rows must have the same number of columns).

Value

An array of type list, with the dimensions given by hier2dim.
If the output needs padding (indicated by hier2dim), the output will have more elements than x, filled with a padding value (as specified in the padding argument).

The array will not have dimnames; use hiernames2dimnames to find appropriate dimnames.

Examples

library("broadcast")



# Example 1: Basics ====
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 what dimensions `x` would have if casted as dimensional:
hier2dim(x)
##       
## 3 2 2

x2 <- cast_hier2dim(x) # cast as dimensional

# since the original list uses the same names for all elements within the same depth,
# dimnames can be set easily:
dimnames(x2) <- hiernames2dimnames(x)

print(x2)
## , , group1
## 
##        class1       class2      
## height numeric,10   numeric,10  
## weight numeric,10   numeric,10  
## sex    character,10 character,10
## 
## , , group2
## 
##        class1       class2      
## height numeric,10   numeric,10  
## weight numeric,10   numeric,10  
## sex    character,10 character,10


# Example 2: Cast from outside to inside ====
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)
    )
  )
)

# by default, `in2out = TRUE`;
# for this example, `in2out = FALSE` is used

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

x2 <- cast_hier2dim(x, in2out = FALSE) # cast as dimensional

# since the original list uses the same names for all elements within the same depth,
# dimnames can be set easily:
# because in2out = FALSE, go from the shallow names to the deeper names:
dimnames(x2) <- hiernames2dimnames(x, in2out = FALSE)

print(x2)
## , , 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



# Example 3: padding ====

# For Example 3, take the same list as before, but remove x$group1$class2:

x <- list(
  group1 = list(
    class1 = 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)
    )
  )
)


hier2dim(x) # as indicated here, dimension 2 (i.e. columns) will have padding
##         padding         
##       3       2       2

# casting this to a dimensional list will resulting in padding with `NULL`:
x2 <- cast_hier2dim(x)
print(x2)
## , , 1
## 
##      [,1]         [,2]
## [1,] numeric,10   NULL
## [2,] numeric,10   NULL
## [3,] character,10 NULL
## 
## , , 2
## 
##      [,1]         [,2]        
## [1,] numeric,10   numeric,10  
## [2,] numeric,10   numeric,10  
## [3,] character,10 character,10
# The `NULL` values are added for padding.
# This is because all slices of the same dimension need to have the same number of elements.  
# For example, all rows need to have the same number of columns.

# one can also use custom padding:
x2 <- cast_hier2dim(x, padding = list(~ "this is padding"))
print(x2)
## , , 1
## 
##      [,1]         [,2]              
## [1,] numeric,10   ~"this is padding"
## [2,] numeric,10   ~"this is padding"
## [3,] character,10 ~"this is padding"
## 
## , , 2
## 
##      [,1]         [,2]        
## [1,] numeric,10   numeric,10  
## [2,] numeric,10   numeric,10  
## [3,] character,10 character,10

dimnames(x2) <- hiernames2dimnames(x)

print(x2)
## , , group1
## 
##        class1       class2            
## height numeric,10   ~"this is padding"
## weight numeric,10   ~"this is padding"
## sex    character,10 ~"this is padding"
## 
## , , group2
## 
##        class1       class2      
## height numeric,10   numeric,10  
## weight numeric,10   numeric,10  
## sex    character,10 character,10


# we can also use in2out = FALSE:
x2 <- cast_hier2dim(x, in2out = FALSE, padding = list(~ "this is padding"))
dimnames(x2) <- hiernames2dimnames(x, in2out = FALSE)
print(x2)
## , , height
## 
##        class1     class2            
## group1 numeric,10 ~"this is padding"
## group2 numeric,10 numeric,10        
## 
## , , weight
## 
##        class1     class2            
## group1 numeric,10 ~"this is padding"
## group2 numeric,10 numeric,10        
## 
## , , sex
## 
##        class1       class2            
## group1 character,10 ~"this is padding"
## group2 character,10 character,10