lv2m {str2str}

List of (atomic) Vectors to Matrix

Description

lv2m converts a list of (atomic) vectors to a matrix. This function is similar to a hypothetical as.matrix.list method if it existed. Note, if the vectors are not all the same typeof, then the matrix will have the most complex typeof any vector in lv.

Usage

lv2m(lv, along, fill = FALSE, check = TRUE)

Arguments

lv

list of (atomic) vectors.

along

numeric vector of length 1 specifying either 1 for binding along rows (i.e., each list element is a row) and 2 for binding along columns (i.e., each list element in a column).

fill

logical vector of length 1 specifying whether 1) to allow the vectors in lv to have different lengths, names, or both, 2) to bind by the names of the vectors within lv rather than by their positions (unless no names are present in which case positions are used), and 3) fill in any missing values in the return object with NA.

check

logical vector of length 1 specifying whether to check the structure of the input arguments. For example, check whether lv is a list of atomic vectors. This argument is available to allow flexibility in whether the user values informative error messages (TRUE) vs. computational efficiency (FALSE).

Details

If fill = FALSE, lv2m uses a combination of do.call and rbind if along = 1 or do.call and cbind if along = 2. rownames and colnames of the returned data.frame are determined by the names of lv and the names of the first vector within lv. If either are NULL, then the positions are used as the dimension names. If fill = FALSE, then an error is returned ff the vectors in lv do not all have the same length. If fill = FALSE, there is no check to ensure the elements within each lv vector have the same names in the same order. The names are taken from the first vector in lv, and it is assumed those names and their order apply to each vector in lv. Essentially, if fill = FALSE, lv binds the vectors by positions and not names.

If fill = TRUE, lv2m uses plyr::rbind.fill.matrix if along = 1 or plyr::rbind.fill.matrix and t.default if along = 2. If fill = TRUE, lv2d binds the vectors by by names (and by positions if no names are present). Depending on what the user wants, fill = FALSE or TRUE could be safer. If the user wants an error returned when any vectors within lv have different lengths, then fill = FALSE should be used. If the user wants to bind by names rather than position, then fill = TRUE should be used.

Value

matrix with the elements of lv either as rows or columns and dimnames determined by the names of lv and lv[[1]]. The typeof is determined by the highest typeof in the elements of lv (i.e., highest to lowest: character > double > integer > logical).

Examples

# 1) `lv` has names; vectors have names
lv <- setNames(object = lapply(X = letters, FUN = setNames, nm = "alphabet"), nm = LETTERS)
lv2m(lv, along = 1)
lv2m(lv, along = 2)

# 2) `lv` has names; no vector names
lv <- setNames(object = as.list(letters), nm = LETTERS)
lv2m(lv, along = 1)
lv2m(lv, along = 2)

# 3) no `lv` names; vector have names
lv <- lapply(X = letters, FUN = setNames, nm = "alphabet")
lv2m(lv, along = 1)
lv2m(lv, along = 2)

# 4) no `lv` names; no vector names
lv <- as.list.default(letters)
lv2m(lv, along = 1)
lv2m(lv, along = 2)

# actual use case (sort of)
lv <- lapply(X = asplit(x = as.matrix(attitude), MARGIN = 1),
   FUN = undim) # need undim since asplit returns 1D arrays
cbind(lv) # not what we want
do.call(what = cbind, args = lv) # doesn't have useful dimnames
lv2m(lv, along = 2) # finally what we want

# when vectors have named elements in different positions
lv <- list("row_1" = c("col_A" = "col_A1", "col_B" = "col_B1", "col_C" = "col_C1"),
   "row_2" = c("col_B" = "col_B2", "col_C" = "col_C2", "col_A" = "col_A2"),
   "row_3" = c("col_C" = "col_C3", "col_A" = "col_A3", "col_B" = "col_B3"))
lv2m(lv, along = 1, fill = FALSE) # probably not what you want
lv2m(lv, along = 1, fill = TRUE) # what you want (See details)

# when you have a list with only one vector
lv <- list("A" = c("one" = 1, "two" = 2, "three" = 3))
x <- lv2m(lv, along = 1, fill = FALSE)
y <- lv2m(lv, along = 1, fill = TRUE)
identical(x, y)