hier2dim

Helper Functions For cast_hier2dim

Description

hier2dim() takes a hierarchical/nested list, and predicts what dimensions the list would have, if casted by the cast_hier2dim function.

hiernames2dimnames() takes a hierarchical/nested list, and intelligently tries to compose dimnames for the result of cast_hier2dim.

Usage

hier2dim(x, ...)

hiernames2dimnames(x, ...)

## Default S3 method:
hier2dim(x, in2out = TRUE, maxdepth = 16L, recurse_all = FALSE, ...)

## Default S3 method:
hiernames2dimnames(
  x,
  in2out = TRUE,
  maxdepth = 16L,
  recurse_all = FALSE,
  direction = 1,
  ...
)

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.

direction A single number, giving the direction in which to search for names. Must be either 1 (to search from start to end) or -1 (to search from end to start).

Value

For hier2dim():
An integer vector, giving the dimensions x would have, if casted by cast_hier2dim().
The names of the output indicates if padding is required (name "padding"), or no padding is required (no name) for that dimension;
Padding will be required if not all list-elements at a certain depth have the same length.

For hiernames2dimnames():
A list of dimnames; these can be assigned to the dimnames of the result of cast_hier2dim.

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