Package 'str2str'

Description

str2str is a package for converting R objects to different structures. It focuses on four primary R objects: (atomic) vectors, matrices, data.frames, and arrays as well as lists of these objects. For example, converting a (atomic) vector to a data.frame (i.e., v2d()) or a list of (atomic) vectors to a matrix (i.e., lv2m(). The current version of the package does not have a function for every convertion (e.g., a2m()), but some additional convertion functions may be included in future versions if I find a use for them. The package was motivated by limitations of the base R as.<str>.<method> suite of functions and the plyr R package **ply(.fun = NULL) suite of functions for converting R objects to different structures. While those functions are often useful, there are times different conversions are desired or different naming schemes are desired. That is what this package offers R users. It also contains various utility functions for working with common R objects. For example, is.colnames and ndim.

Limitations

This packages does NOT handle the nuances of R objects. It is not for comprehensive restructuring of any version of R objects, but rather for restructuring commonly used versions of R objects. For example, the functions are not tested with the raw and complex typeof atomic vectors, list arrays, or data.frames containing non-atomic vector columns (e.g., matrix or list columns). The base R as.<str>.<method> functions allow for comprehensive restructuring of R objects; however, at the cost of less convenient convertions for commonly used versions of R objects. The str2str package seeks to fill that gap in useability.

Abbreviations

See the table below

v

(atomic) vector

m

matrix

d

data.frame

a

(3D+) array

l

list

el

elements

nm

names

uv

unique values

lgl

logical

int

integer

dbl

double

num

numeric

chr

character

fct

factor

lvl

levels

vrb

variable

frm

formula

fun

function

rtn

return

str

structure

Author(s)

Maintainer: David Disabato [email protected]

Description

a2d converts a (3D+ array) to a data.frame. It allows you to specify a dimension of the array to be the columns. All other dimensions are variables in the data.frame. This is different than as.data.frame.array which converts the (3D+) array to a matrix first; although it is very similar to as.data.frame.table when col = 0.

Usage

a2d(a, col = 0, stringsAsFactors = FALSE, check = TRUE)

Arguments

Details

a2d is mostly a wrapper for reshape::melt.array (+ reshape::cast) that allows for the variable dimensions to be character vectors rather than factors.

Value

data.frame of a's elements. The colnames of the variable dimensions are the dimlabels in a. If there were no dimlabels in a, then each dimension is named after its number with an X in front. If col is not 0, then the rest of the colnames are the dimnames of that dimension from a. If col is 0, then the names of the single column with a's elements is "element".

Examples

a2d(HairEyeColor)
a2d(HairEyeColor, col = 1)
a2d(HairEyeColor, col = "Hair", stringsAsFactors = TRUE)
a2d(HairEyeColor, col = 2)
a2d(HairEyeColor, col = "Sex", stringsAsFactors = TRUE)
try_expr(a2d(as.matrix(attitude))) # error due to inputting a matrix. Instead use `m2d`.

# correlation array example from psych::corr.test(attitude[1:3])
# corr_test <- psych::corr.test(attitude[1:3])
# a <- lm2a(corr_test[c("r","se","t","p")])
r <- matrix(c(1.0000000, 0.8254176, 0.4261169, 0.8254176, 1.0000000, 0.5582882,
   0.4261169, 0.5582882, 1.0000000), nrow = 3, ncol = 3, byrow = FALSE)
se <- matrix(c(0.0000000, 0.1066848, 0.1709662, 0.1066848, 0.0000000, 0.1567886,
   0.1709662, 0.1567886, 0.0000000), nrow = 3, ncol = 3, byrow = FALSE)
t <- matrix(c(Inf, 7.736978, 2.492404, 7.736978, Inf, 3.560771,
   2.492404, 3.560771, Inf), nrow = 3, ncol = 3, byrow = FALSE)
p <- matrix(c(0.000000e+00, 1.987682e-08, 1.887702e-02, 5.963047e-08, 0.000000e+00,
   1.345519e-03, 0.018877022, 0.002691039, 0.000000000), nrow = 3, ncol = 3, byrow = FALSE)
a <- abind::abind(r, se, t, p, along = 3L)
dimnames(a) <- list(names(attitude[1:3]), names(attitude[1:3]), c("r","se","t","p"))
d <- a2d(a = a, col = 3)

Description

a2la converts an (3D+) array to a list of (3D+) arrays. This function is a simple wrapper for asplit(x = a, MARGIN = along).

Usage

a2la(a, along = ndim(a), check = TRUE)

Arguments

Value

list of arrays where each array is one dimension less than a and the names of the list are dimnames(a)[[along]].

Examples

# without dimnames
a <- abind::abind(HairEyeColor*1, HairEyeColor*2, HairEyeColor*3, along = 4L)
a2la(a)
# with dimnames
a <- abind::abind("one" = HairEyeColor*1, "two" = HairEyeColor*2,
   "three" = HairEyeColor*3, along = 4L)
a2la(a)
a2la(a, along = 1) # along = 1

Description

a2ld converts a 3D array to a list of data.frames. This is a simple call to a2lm followed by m2d. The default is to convert the third dimension to the list dimension.

Usage

a2ld(a, along = 3L, stringsAsFactors = FALSE, check = TRUE)

Arguments

Value

list of data.frames - all with the same dimensions.

Examples

a2ld(HairEyeColor)
a2ld(HairEyeColor, along = 1)
try_expr(a2ld(mtcars)) # error b/c not a 3D array

Description

a2lm converts a (3D) array to a list of matrices. This is a simple call to asplit with a default to convert the third dimension to a list dimension.

Usage

a2lm(a, along = 3L, check = TRUE)

Arguments

Value

list of matrices - all with the same dimensions.

Examples

a2lm(HairEyeColor)
a2lm(HairEyeColor, along = 1)
try_expr(a2lm(mtcars)) # error b/c  not a 3D array

Description

a2v converts a matrix to a (atomic) vector. The benefit of m2v over as.vector or c is that 1) the vector can be formed along rows any sequence of dimensions and 2) the dimnames from a can be used for the names of the returned vector.

Usage

a2v(a, along = ndim(a):1, use.dimnames = TRUE, sep = "_", check = TRUE)

Arguments

Value

(atomic) vector of length = length(a) where the order of elements from a has been determined by along and the names determined by the use.dimnames, dimnames(a), and sep.

Examples

a2v(HairEyeColor) # layers, then columns, then rows (default)
a2v(HairEyeColor, along = c(3,1,2)) # layers, then rows, then columns
a2v(HairEyeColor, along = 1:3) # rows, then columns, then layers
a2v(HairEyeColor, along = 1:3, use.dimnames = FALSE)

Description

Some traditional R folks may find this function uncomfortable. R is famous for limiting side effects, except for a few notable exceptions (e.g., `[<-` and `names<-`). Part of the reason is that side effects can be computationally inefficient in R. The entire object often has to be re-constructed and re-saved to memory. For example, a more computationally efficient alternative to abind(ary) <- mat1; abind(ary) <- mat2; abind(ary) <- mat3 is ary1 <- do.call(what = abind, args = list(ary, mat1, mat2, mat3)). However, `abind<-` was not created for R programming use when computational efficiency is valued; it is created for R interactive use when user convenience is valued.

Usage

abind(
  a,
  along = ndim(a),
  after = dim(a)[along],
  dim.nm = NULL,
  overwrite = FALSE
) <- value

Arguments

Value

Like other similar functions (e.g., `names<-` and `[<-`), `rbind<-` does not appear to have a return object. However, it technically does as a side effect. The argument data will have been changed such that value has been added as rows. If a traditional return object is desired, and no side effects, then it can be called like a traditional function: dat2 <- 'rbind<-'(dat1, value = add1).

Examples

# abind along the last dimension
# default `along` and `after`
HairEyeColor2 <- HairEyeColor
intersex_ary <- array(1:16, dim = c(4,4,1), dimnames = list(NULL, NULL, "Sex" = "Intersex"))
abind(HairEyeColor2) <- intersex_ary
print(HairEyeColor2)
# user-specified `along` and `after`
HairEyeColor2 <- HairEyeColor
intersex_ary <- array(1:16, dim = c(4,4,1), dimnames = list(NULL, NULL, "Sex" = "Intersex"))
abind(HairEyeColor2, along = "Sex", after = 0L) <- intersex_ary
print(HairEyeColor2)
# matrix as `value`
HairEyeColor2 <- HairEyeColor
intersex_mat <- matrix(1:16, nrow = 4, ncol = 4)
abind(HairEyeColor2, dim.nm = "Intersex") <- intersex_mat
print(HairEyeColor2)

# abind along the first dimension
# array as `value`
HairEyeColor2 <- HairEyeColor
auburn_ary <- array(1:8, dim = c(1,4,2), dimnames = list("Hair" = "Auburn", NULL, NULL))
abind(HairEyeColor2, along = 1L) <- auburn_ary
print(HairEyeColor2)
# matrix as `value`
HairEyeColor2 <- HairEyeColor
auburn_mat <- matrix(1:8, nrow = 4, ncol = 2) # rotate 90-degrees counter-clockwise in your mind
abind(HairEyeColor2, along = 1L, dim.nm = "Auburn") <- auburn_mat
print(HairEyeColor2)
# `after` in the middle
HairEyeColor2 <- HairEyeColor
auburn_mat <- matrix(1:8, nrow = 4, ncol = 2) # rotate 90-degrees counter-clockwise in your mind
abind(HairEyeColor2, along = 1L, after = 2L, dim.nm = "Auburn") <- auburn_mat
print(HairEyeColor2)

# abind along the second dimension
# array as `value`
HairEyeColor2 <- HairEyeColor
amber_ary <- array(1:8, dim = c(4,1,2), dimnames = list(NULL, "Eye" = "Amber", NULL))
abind(HairEyeColor2, along = 2L) <- amber_ary
print(HairEyeColor2)
# matrix as `value`
HairEyeColor2 <- HairEyeColor
amber_mat <- matrix(1:8, nrow = 4, ncol = 2)
abind(HairEyeColor2, along = 2L, dim.nm = "Amber") <- amber_mat
print(HairEyeColor2)
# `after` in the middle
HairEyeColor2 <- HairEyeColor
amber_mat <- matrix(1:8, nrow = 4, ncol = 2)
abind(HairEyeColor2, along = 2L, after = "Blue", dim.nm = "Amber") <- amber_mat
print(HairEyeColor2)

Description

all_diff tests if all elements are different. The elements could be either from an atomic vector, list vector, or list. If x does not have any unique values (e.g., NULL), then FALSE is returned.

Usage

all_diff(x)

Arguments

Details

The machine precision of all_diff for numeric vectors is the same as unique. This can causes a problem for some floating-point numbers.

Value

logical vector of length 1 specifying whether all the elements in x are the same (TRUE) or not (FALSE).

Examples

all_diff(1:10)
all_diff(c(1:10, 10))
all_diff(c(1.0000000, 1.0000001, 0.9999999)) # machine precision good for most cases
all_diff(1) # works for vectors of length 1

Description

all_same tests if all elements are the same. The elements could be either from an atomic vector, list vector, or list. If x does not have any unique values (e.g., NULL), then FALSE is returned.

Usage

all_same(x)

Arguments

Details

The machine precision of all_same for numeric vectors is the same as unique. This can causes a problem for some floating-point numbers.

Value

logical vector of length 1 specifying whether all the elements in x are the same (TRUE) or not (FALSE).

Examples

all_same(rep.int("a", times = 10))
all_same(rep.int(1, times = 10))
all_same(c(1.0000000, 1.0000001, 0.9999999)) # machine precision good for most cases
all_same(1) # works for vectors of length 1

Description

`append<-` adds elements to vectors as a side effect. The purpose of the function is to replace the need to use vec2 <- append(vec1, add1); vec3 <- append(vec2, add2); vec4 <- append(vec3, add3), etc. It functions similarly to `[<-.default`, but allows you to specify the location of the elements similar to append (vs. c).

Usage

append(x, after = length(x), nm = NULL, overwrite = TRUE) <- value

Arguments

Details

Some traditional R folks may find this function uncomfortable. R is famous for limiting side effects, except for a few notable exceptions (e.g., `[<-` and `names<-`). Part of the reason is that side effects can be computationally inefficient in R. The entire object often has to be re-constructed and re-saved to memory. For example, a more computationally efficient alternative to append(vec) <- add1; append(vec) <- add2; append(vec) <- add3 is vec1 <- do.call(what = c, args = list(dat, add1, add2, add3)). However, `append<-` was not created for R programming use when computational efficiency is valued; it was created for R interactive use when user convenience is valued.

Value

Like other similar functions (e.g., `names<-` and `[<-`), it does not appear to have a return object. However, it technically does as a side effect. The argument x will have been changed such that value has been added as elements. If a traditional return object is desired, and no side effects, then it can be called like a traditional function: vec2 <- 'append<-'(vec1, value = add1).

Examples

# no names
x <- letters
append(x) <- LETTERS
append(x, after = match("z", table = x)) <- "case_switch" # with the position
   # of the added value specified

# ya names
y <- setNames(object = letters, nm = LETTERS)
append(y) <- c("ONE" = 1, "TWO" = 2, "THREE" = 3) # with names provided by `value`
tmp <- 1:(length(y) - 3)
y <- y[tmp] # if I put a () inside of a [], Roxygen doesn't like it
append(y, nm = c("ONE","TWO","THREE")) <- c(1,2,3) # with names specified by `nm`
append(y, after = "Z", nm = "ZERO") <- "0" # using name to provide `after`

# using overwrite
append(y, overwrite = TRUE) <- c("ONE" = "one","TWO" = "two", "THREE" = "three")
append(y, overwrite = FALSE) <- c("ONE" = "one","TWO" = "two", "THREE" = "three")

Description

cat0 concatenates and prints objects without any separator. cat0 is to cat as paste0 is to paste. It also allows you to specify line breaks before (n.before) and after (n.after) the the printing of the concatenated R objects. cat0 function can be useful in conjunction with sink for quick and dirty exporting of results.

Usage

cat0(
  ...,
  n.before = 1L,
  n.after = 1L,
  file = "",
  fill = FALSE,
  labels = NULL,
  append = FALSE
)

Arguments

Value

nothing as the function only prints and does not return an R object.

Examples

cat0(names(attitude))
cat0("MODEL COEFFICIENTS:", coef(lm(rating ~ critical + advance, data = attitude)),
   n.before = 0, n.after = 2)

Description

cbind_fill binds together matrix-like objects by columns. The input objects will all internally be converted to data.frames by the generic function as.data.frame. When some objects do not contain rows that are present in other objects, NAs will be added to fill up the returned combined data.frame. If a matrix doesn't have rownames, the row number is used. Note that this means that a row with name "1" is merged with the first row of a matrix without name and so on. The returned matrix will always have row names. Colnames are ignored.

Usage

cbind_fill(...)

Arguments

Details

cbind_fill ensures each object has unique colnames and then calls Join(by = "0"). It is intended to be the column version of plyr::rbind.fill; it differs by allowing inputs to be matrices or vectors in addition to data.frames.

Value

data.frame created by combining all the objects input together. It will always have rownames. If colnames are not provided to the matrix-like objects, the returned colnames can be rather esoteric since default colnaming will be revised to ensure each colname is unique. If ... is a list of vectors, then the colnames will be the names of the list.

See Also

cbind_fill_matrix rbind.fill

Examples

# standard use
A <- data.frame("first" = 1:2, "second" = 3:4)
B <- data.frame("third" = 6:8, "fourth" = 9:11)
print(A)
print(B)
cbind_fill(A, B)

# help with unstack()
row_keep <- sample(1:nrow(InsectSprays), size = 36)
InsectSprays2 <- InsectSprays[row_keep, ]
unstacked <- unstack(InsectSprays2)
cbind_fill(unstacked)

# using rownames for binding
rownames(A) <- c("one", "two")
rownames(B) <- c("three","two","one")
print(A)
print(B)
cbind_fill(A, B)

# matrices as input
A <- matrix(1:4, 2)
B <- matrix(6:11, 3)
print(A)
print(B)
cbind_fill(A, B)

# atomic vector input
A <- data.frame("first" = 1:2, "second" = 3:4)
B <- data.frame("third" = 6:8, "fourth" = 9:11)
C <- c(12,13,14,15)
D <- c(16,17,18,19)
cbind_fill(A, B, C, D)

# same as plyr::rbind.fill, it doesn't handles well some inputs with custom rownames
# and others with default rownames
rownames(A) <- c("one", "two")
print(A)
print(B)
cbind_fill(A, B)

Description

cbind_fill_matrix binds together matrix-like objects by columns. The input objects will all internally be converted to matrices by the generic function as.matrix. When some objects do not contain rows that are present in other objects, NAs will be added to fill up the returned combined matrix. If a matrix doesn't have rownames, the row number is used. Note that this means that a row with name "1" is merged with the first row of a matrix without name and so on. The returned matrix will always have row names. Colnames are ignored.

Usage

cbind_fill_matrix(...)

Arguments

Details

cbind_fill_matrix is t.default + plyr::rbind.fill.matrix + t.default and is based on the code within plyr::rbind.fill.matrix.

Value

matrix created by combining all the objects input together. It will always have rownames. It will only have colnames if ... is a list of vectors, in which the colnames will be the names of the list.

See Also

cbind_fill rbind.fill.matrix

Examples

# standard use
A <- matrix(1:4, 2)
B <- matrix(6:11, 3)
print(A)
print(B)
cbind_fill_matrix(A, B)

# help with unstack()
row_keep <- sample(1:nrow(InsectSprays), size = 36)
InsectSprays2 <- InsectSprays[row_keep, ]
unstacked <- unstack(InsectSprays2)
cbind_fill_matrix(unstacked)

# using rownames for binding
rownames(A) <- c("one", "two")
rownames(B) <- c("three","two","one")
print(A)
print(B)
cbind_fill_matrix(A, B)

# data.frame input
C <- data.frame("V1" = c(12,13,14,15), row.names = c("one","two","three","four"))
print(C)
cbind_fill_matrix(A, B, C)

# atomic vector input
A <- matrix(1:4, 2)
B <- matrix(6:11, 3)
C <- c(12,13,14,15)
cbind_fill_matrix(A, B, C)

# same as plyr::rbind.fill.matrix, cbind_fill_matrix doesn't like some input
# with dimnames and others without...
rownames(A) <- c("one", "two")
print(A)
print(B)
cbind_fill_matrix(A, B)

Description

`cbind<-` adds columns to data objects as a side effect. The purpose of the function is to replace the need to use dat2 <- cbind(dat1, add1); dat3 <- cbind(dat2, add2); dat4 <- cbind(dat3, add3), etc. For data.frames, it functions similarly to `[<-.data.frame`, but allows you to specify the location of the columns similar to append (vs. c) and overwrite columns with the same colnames. For matrices, it offers more novel functionality since `[<-.matrix` does not exist.

Usage

cbind(data, after = ncol(data), col.nm = NULL, overwrite = TRUE) <- value

Arguments

Details

Some traditional R folks may find this function uncomfortable. R is famous for limiting side effects, except for a few notable exceptions (e.g., `[<-` and `names<-`). Part of the reason is that side effects can be computationally inefficient in R. The entire object often has to be re-constructed and re-saved to memory. For example, a more computationally efficient alternative to cbind(dat) <- add1; cbind(dat) <- add2; cbind(dat) <- add3 is dat1 <- do.call(what = cbind, args = list(dat, add1, add2, add3)). However, `cbind<-` was not created for R programming use when computational efficiency is valued; it is created for R interactive use when user convenience is valued.

Similar to `cbind`, `cbind<-` works with both data.frames and matrices. This is because `cbind` is a generic function with a default method that works with matrices and a data.frame method that works with data.frames. Similar to `cbind`, if colnames of value are not given and col.nm is left NULL, then the colnames of the return object are automatically created and can be dissatisfying.

Value

Like other similar functions (e.g., `names<-` and `[<-`), `cbind<-` does not appear to have a return object. However, it technically does as a side effect. The argument data will have been changed such that value has been added as columns. If a traditional return object is desired, and no side effects, then it can be called like a traditional function: dat2 <- 'cbind<-'(dat1, value = add1).

Examples

attitude2 <- attitude
cbind(attitude2) <- rowMeans(attitude2) # defaults to colnames = "value"
attitude2["value"] <- NULL
cbind(attitude2, col.nm = "mean") <- rowMeans(attitude2) # colnames specified by `col.nm`
attitude2["mean"] <- NULL
cbind(attitude2, after = "privileges", col.nm = c("mean","sum")) <-
   cbind(rowMeans(attitude2), rowSums(attitude2)) # `value` can be a matrix
attitude2[c("mean","sum")] <- NULL
attitude2 <- `cbind<-`(data = attitude2, value = rowMeans(attitude2)) # traditional call
attitude2["value"] <- NULL
cbind(attitude2, after = "privileges", col.nm = "mean") <-
   rowMeans(attitude2) # `data` can be a matrix
cbind(attitude2) <- data.frame("mean" = rep.int(x = "mean", times = 30L)) # overwrite = TRUE
cbind(attitude2, overwrite = FALSE) <-
   data.frame("mean" = rep.int(x = "mean", times = 30L)) # overwrite = FALSE
cbind(attitude2) <- data.frame("mean" = rep.int(x = "MEAN", times = 30L),
   "sum" = rep.int(x = "SUM", times = 30L)) # will overwrite only the first "mean" column
   # then will append the remaining columns

Description

codes returns the integer codes for each factor level from a factor.

Usage

codes(fct)

Arguments

Value

integer vector with length = length(levels(fct)), elements = integer codes of fct and names = levels(fct).

Examples

codes(state.region)
codes(iris$"Species")

Description

d2a converts a data.frame to a (3D+) array or matrix. This function assumes the data.frame contains 2+ variable dimensions, which will correspond to the returned arrays/matrix dimensions. One or multiple variables can contain the elements of the returned array (only one variable can contain the elements for returning a matrix). In the case of multiple variables, they will be binded as the last dimension in the returned array with dimnames equal to the variable names.

Usage

d2a(d, dim.nm = names(d)[-ncol(d)], rtn.dim.lab = "el_nm", check = TRUE)

Arguments

Details

d2a is a wrapper for reshape::cast with the addition of reordering the dimnames by position, which sorts the dimnames by the position they first appear in the variable dimensions of the data.frame (reshape::cast sorts all the dimnames alphabetically).

Value

(3D+) array or matrix formed from the dimensions d[dim.nm] with dimlabels = dim.nm (and rtn.dim.lab if there are multiple element columns). The dimnames are the unique elements d[dim.nm] and are ordered by position (rather than alphabetically), which allow for conversions back to the original array after a call to a2d() or matrix after a call to m2d().

Examples

# 3D array
print(HairEyeColor)
d <- reshape::melt.array(HairEyeColor)
a <- reshape::cast(d, Hair ~ Eye ~ Sex)
identical(a, unclass(HairEyeColor)) # not the same as HairEyeColor
d <- a2d(HairEyeColor)
a <- d2a(d, dim.nm = c("Hair","Eye","Sex"))
identical(a, unclass(HairEyeColor)) # yes the same as HairEyeColor

# matrix
attitude_mat <- d2m(attitude)
d <- m2d(attitude_mat, col = 0)
m <- d2a(d)
identical(m, attitude_mat) # yes the same as attitude_mat

# correlation data.frame example for p-values using psych::corr.test(attitude[1:3])
# corr_test <- psych::corr.test(attitude)
# a <- lm2a(corr_test[c("r","se","t","p")])
r <- matrix(c(1.0000000, 0.8254176, 0.4261169, 0.8254176, 1.0000000, 0.5582882,
   0.4261169, 0.5582882, 1.0000000), nrow = 3, ncol = 3, byrow = FALSE)
se <- matrix(c(0.0000000, 0.1066848, 0.1709662, 0.1066848, 0.0000000, 0.1567886,
   0.1709662, 0.1567886, 0.0000000), nrow = 3, ncol = 3, byrow = FALSE)
t <- matrix(c(Inf, 7.736978, 2.492404, 7.736978, Inf, 3.560771,
   2.492404, 3.560771, Inf), nrow = 3, ncol = 3, byrow = FALSE)
p <- matrix(c(0.000000e+00, 1.987682e-08, 1.887702e-02, 5.963047e-08, 0.000000e+00,
   1.345519e-03, 0.018877022, 0.002691039, 0.000000000), nrow = 3, ncol = 3, byrow = FALSE)
a <- abind::abind(r, se, t, p, along = 3L)
dimnames(a) <- list(names(attitude[1:3]), names(attitude[1:3]), c("r","se","t","p"))
d <- a2d(a = a, col = 3)
a2 <- d2a(d = d, dim.nm = c("X1","X2"))
all.equal(a, a2) # dimlabels differ
dimnames(a2) <- unname(dimnames(a2))
all.equal(a, a2) # now it is true

# correlation data.frame example for confidence intervals using psych::corr.test(attitude[1:3])
# corr_test <- psych::corr.test(attitude[1:3])
# d <- corr_test[["ci"]][c("r","p","lower","upper")]
# cbind(d, after = 0L) <- reshape::colsplit(row.names(d), split = "-", names = c("X1","X2"))
# tmp <- d[c("X2","X1","r","p","lower","upper")]
# d2 <- plyr::rename(tmp, c("X1" = "X2", "X2" = "X1"))
# short_nm <- unique(c(fct2v(d[["X1"]]), fct2v(d[["X2"]])))
# d3 <- data.frame("X1" = short_nm, "X2" = short_nm,
#    "r" = NA_real_, "p" = NA_real_, "lower" = NA_real_, "upper" = NA_real_)
# d_all <- ld2d(ld = list(d, d2, d3), rtn.listnames.nm = NULL, rtn.rownames.nm = NULL)
d_all <- data.frame(
   "X1" = c("ratng","ratng","cmpln","cmpln","prvlg","prvlg","ratng","cmpln","prvlg"),
   "X2" = c("cmpln","prvlg","prvlg","ratng","ratng","cmpln","ratng","cmpln","prvlg"),
   "r" = c(0.8254176, 0.4261169, 0.5582882, 0.8254176, 0.4261169, 0.5582882, NA, NA, NA),
   "p" = c(1.987682e-08, 1.887702e-02, 1.345519e-03, 1.987682e-08,
      1.887702e-02, 1.345519e-03, NA, NA, NA),
   "lower" = c(0.66201277, 0.07778967, 0.24787510, 0.66201277, 0.07778967,
      0.24787510, NA, NA, NA),
   "upper" = c(0.9139139, 0.6817292, 0.7647418, 0.9139139, 0.6817292,
      0.7647418, NA, NA, NA)
)
tmp <- d2a(d = d_all, dim.nm = c("X1","X2"), rtn.dim.lab = "stat")
short_nm <- c("ratng","cmpln","prvlg")
dim_names <- list(short_nm, short_nm, c("r","p","lower","upper"))
a <- do.call(what = `[`, args = c(list(tmp), dim_names))
print(a)

Description

d2d converts a data.frame to a modified version of the data.frame. It is used to convert factors, character vectors, and logical vectors to different classes/types (e.g., factors to character vectors).

Usage

d2d(
  d,
  fct = "chr",
  chr = "chr",
  lgl = "int",
  order.lvl = "alphanum",
  decreasing = FALSE,
  na.lvl = FALSE,
  check = TRUE
)

Arguments

Details

d2d internally uses the fct2v and v2fct functions. See them or more details about how column conversions work.

Value

data.frame with the same dim and dimnames as d, but with potentially altered columns which were factors, character vectors, and/or integer vectors.

Examples

dat <- data.frame(
"lgl_1" = c(TRUE, FALSE, NA),
"lgl_2" = c(FALSE, TRUE, NA),
"int_1" = c(1L, NA, 2L),
"int_2" = c(2L, NA, 1L),
"dbl_1" = c(1.1, NA, 2.2),
"dbl_2" = c(2.2, NA, 1.1),
"chr_1" = c(NA, "a","b"),
"chr_2" = c(NA, "b","a"),
"fct_1" = factor(c(NA, "one","two")),
"fct_2" = factor(c(NA, "two","one"))
)
str(dat)
x <- d2d(dat); str(x) # default
x <- d2d(dat, fct = "fct", chr = "fct", lgl = "fct"); str(x) # all to factors
x <- d2d(dat, fct = "int", chr = "int"); str(x) # all to integers

Description

d2ld converts a data.frame to a list of data.frames. This is a simple call to split.data.frame splitting the data.frame up by groups.

Usage

d2ld(
  d,
  by,
  keep.by = TRUE,
  drop = FALSE,
  sep = ".",
  lex.order = FALSE,
  check = TRUE
)

Arguments

Value

list of data.frames split by the groups specified in the by columns. The list names are the group names (with sep if there are multiple by columns).

Examples

# one grouping variable
d2ld(d = mtcars, by = "vs")
d2ld(d = mtcars, by = "gear")

# two grouping variables
d2ld(d = mtcars, by = c("vs","gear"))
d2ld(d = mtcars, by = c("vs","gear"), lex.order = TRUE)

# keep.by argument
d2ld(d = mtcars, by = "vs", keep.by = FALSE)
d2ld(d = mtcars, by = "gear", keep.by = FALSE)
d2ld(d = mtcars, by = c("vs","gear"), keep.by = FALSE)

Description

d2lv converts a data.frame to a list of (atomic) vectors. This function is really only worthwhile when along = 1 since when along = 2, the function is essentially as.list.data.frame(d).

Usage

d2lv(d, along, check = TRUE)

Arguments

Value

list of (atomic) vectors. If along = 1, then the names are the rownames of d and the vectors are rows from d. If along = 2, then the names are the colnames of d and the vector are columns from d. Note, the vectors always have the same length as nrow(d).

Examples

d2lv(mtcars, along = 1)
d2lv(mtcars, along = 2)
d2lv(CO2, along = 1) # all vectors converted to typeof character
d2lv(CO2, along = 2) # each column stays its own typeof (or class for factors)
# check = FALSE
try_expr(d2lv(mtcars, along = 3, check = FALSE)) # less informative error message
try_expr(d2lv(mtcars, along = 3, check = TRUE)) # more informative error message

Description

d2m converts a data.frame to a matrix. The user can specify how to convert factors, character vectors, and integer vectors in the data.frame through the internal use of the d2d function. After the call to d2d, d2m simply calls as.matrix.data.frame(rownames.force = TRUE), which will return a matrix of the most complex typeof of any column in the data.frame (most complex to least complex: character, double, integer, logical). Therefore, if any factors or character vectors are left in the data.frame, it will return a character matrix. On the other side of things, if all columns in the data.frame are logical, then it will return a logical matrix. However, if every column in the data.frame is logical except for one factor or character vector, then it will return a character matrix. (If you have a data.frame where 2 columns are the matrix dimnames and one column is the matrix elements, then use d2a()).

Usage

d2m(
  d,
  fct = "chr",
  chr = "chr",
  lgl = "int",
  order.lvl = "alphanum",
  decreasing = FALSE,
  na.lvl = FALSE,
  check = TRUE
)

Arguments

Value

matrix with the same dim and dimnames as d. After applying the factor, character vector, and/or integer vector conversions through d2d, the matrix will have typeof = most complex typeof of any column in the modified data.frame.

Examples

x <- d2m(mtcars); str(x)
dat <- as.data.frame(CO2)
x <- d2m(dat); str(x)
x <- d2m(dat, fct = "int"); str(x)

Description

d2v converts a data.frame to a matrix. The user can specify how to convert factors, character vectors, and integer vectors in the data.frame through the internal use of the d2d function. After the call to d2d, the data.frame is simplied to an atomic vector, which will return a vector of the most complex typeof of any column in the data.frame (most complex to least complex: character, double, integer, logical). Therefore, if any factors or character vectors are left in the data.frame, it will return a character vector. On the other side of things, if all columns in the data.frame are logical, then it will return a logical vector. However, if every column in the data.frame is logical except for one factor or character vector, then it will return a character vector.

Usage

d2v(
  d,
  along = 2,
  use.dimnames = TRUE,
  sep = "_",
  fct = "chr",
  chr = "chr",
  lgl = "int",
  order.lvl = "alphanum",
  decreasing = FALSE,
  na.lvl = FALSE,
  check = TRUE
)

Arguments

Value

(atomic) vector with elements from d. If d had one row, then the names of the return object are names(d). If d has one column, then the names of the return object are row.names(d).

Examples

# general data.frame
d2v(mtcars) # default
d2v(d = mtcars, along = 1) # concatenate along rows
d2v(d = mtcars, sep = ".") # change the sep of the rownames(d) and colnames(d)
d2v(d = mtcars, use.dimnames = FALSE) # return object has no names
# one row/column data.frame
one_row <- mtcars[1,, drop = FALSE]
d2v(one_row)
one_col <- mtcars[, 1, drop = FALSE]
d2v(one_col)
one_all <- mtcars[1,1, drop = FALSE]
d2v(one_all)
d2v(one_all, use.dimnames = FALSE)

Description

dimlabels returns the the dimension labels (i.e., names of dimnames) of an object. This is most useful for arrays, which can have anywhere from 1 to 1000+ dimensions.

Usage

dimlabels(x)

Arguments

Details

dimlabels is a very simple function that is simply names(dimnames(x)).

Value

character vector of length = ndim(x) specifying the dimension labels (i.e., names of dimnames) of x. If x does not have any dimensions, or has dimensions but no dimension labels, then NULL is returned.

Examples

dimlabels(state.region)
dimlabels(attitude)
dimlabels(HairEyeColor)

Description

`dimlabels<-` adds elements to vectors as a side effect. The purpose of the function is to replace names(dimnames(x)) with a single function call.

Usage

dimlabels(x) <- value

Arguments

Value

Like other similar functions (e.g., `names<-` and `[<-`), it does not appear to have a return object. However, it technically does as a side effect. The argument x will have been changed such that value has been added as dimlabels. If a traditional return object is desired, and no side effects, then it can be called like a traditional function: obj2 <- 'dimlabels<-'(x = obj, value = dimlab).

Examples

a <- array(c(letters, NA), dim = c(3,3,3),
   dimnames = replicate(3, expr = 1:3, simplify = FALSE))
dimlabels(a) <- c("first","second","third")
dimlabels(a)[[2]] <- c("2nd")
dimlabels(a)[c(1,3)] <- c("1st","3rd")
print(a)

Description

e2l converts an environment to a list. The function assumes you don't want *all* objects in an environment and uses pick to determine which objects you want included. If you want all objects in an environment, then use grab(x = objects(envir, all.names = TRUE), envir).

Usage

e2l(
  e = sys.frame(),
  val,
  pat = FALSE,
  not = FALSE,
  fixed = FALSE,
  sorted = FALSE,
  check = TRUE
)

Arguments

Value

list with object contents from environment e with names as the object names.

Examples

model_1 <- lm(v2frm(names(attitude)), data = attitude)
model_2 <- lm(v2frm(names(mtcars)), data = mtcars)
model_3 <- lm(v2frm(names(airquality)), data = airquality)
e2l(val = "model_", pat = TRUE)

Description

fct2v converts a factor to an (atomic) vector. It allows the user to specify whether they want the factor to always return a character vector (simplify = TRUE), simplified if possible (simplify = FALSE), or just return the integer codes (codes = TRUE).

Usage

fct2v(fct, simplify = TRUE, codes = FALSE, check = TRUE)

Arguments

Details

When simplify = TRUE, fct2v uses type.convert to try to simplify the factor. Note, missing values are assumed to be "NA" and decimals are assumed to be "."; however, "L" after a number is not interpreted as an integer specifier.

Value

(atomic) vector of the same length as fct. If codes = TRUE, then the returned vector is typeof integer containing the underlying factor codes. If codes = FALSE and simplify = FALSE, then the returned vector is typeof character containing the factor levels. If codes = FALSE, and simplify = TRUE, then the returned vector is the simpliest typeof possible without having to coerce any elements to NA. For example, if fct contains all integer numerals (e.g., "1", "2", "3", etc), then it will be converted to an integer vector. See examples.

Examples

fct2v(state.region)
fct2v(fct = factor(c("7.00001","8.54321","9.99999"))) # double
fct2v(fct = factor(c("7","8","9")), simplify = FALSE) # character
fct2v(fct = factor(c("7","8","9")), simplify = TRUE) # integer
fct2v(fct = factor(c("7","8","9")), codes = TRUE) # integer codes
fct2v(fct = factor(c("7L","8L","9L")),
   simplify = TRUE) # does not understand "L" for integers

Description

grab extracts the contents of objects in an environment based on their object names as a character vector. The object contents are stored to a list where the names are the object names.

Usage

grab(x, envir = sys.frame())

Arguments

Value

list of objects with names x.

Examples

grab(x = c("attitude","mtcars","airquality"))
grab(x = c("mean.default","mean.Date","mean.difftime"))

Description

inbtw extracts all elements inbetween (by position) two specific elements of a (atomic) vector. This can be useful when working with rownames and colnames since seq does not work with names. Primary for character vectors but can be used with other typeof.

Usage

inbtw(x, from, to, left = TRUE, right = TRUE)

Arguments

Details

An error is returned if either from or to don't appear in x or appear more than once in x.

Value

vector of the same type as x that only includes elements in x inbetween (by position) from and to, which may or may not include from and to themselves, depending on left and right, respectively.

Examples

# character vector
row_names <- inbtw(x = row.names(LifeCycleSavings), from = "China", to = "Peru")
LifeCycleSavings[row_names, ] # default use
row_names <- inbtw(x = row.names(LifeCycleSavings), from = "China", to = "Peru",
   right = FALSE, left = FALSE)
LifeCycleSavings[row_names, ] # use with right and left arguments FALSE
try_expr(inbtw(x = row.names(LifeCycleSavings), from = "china",
   to = "peru")) # error due to `from` and `to` not appearing in `x`
try_expr(inbtw(x = rep.int(x = row.names(LifeCycleSavings), times = 2), from = "China",
   to = "Peru")) # error due to `from` and `to` appearing more than once in `x`
# numeric vector
vec <- sample(x = 150:199, size = 50)
inbtw(x = vec, from = 150, to = 199)
# list vector (error)
lst <- list(FALSE, 3L, 9.87, "abc", factor("lvl"))
try_expr(inbtw(x = lst, from = 3L, to = "abc")) # error because `lst` is a
   # list vector and not an atomic vector

Description

is.avector returns whether an object is an atomic vector with typeof character, logical, integer, or double.

Usage

is.avector(x, attr.ok = TRUE, fct.ok = TRUE)

Arguments

Details

is.avector is simply a logical "and" of is.atomic and is.vector.

Value

logical vector with length 1 specifying whether x is an atomic vector. If attr.ok is TRUE then non-core attributes are allowed (e.g., "value.labels"). If fct.ok is TRUE then factors are allowed.

Examples

# normal use
is.avector(x = c(1,2,3))
is.avector(x = c("one" = 1, "two" = 2, "three" = 3)) # names are always okay
is.avector(x = array(c(1,2,3))) # returns false for arrays
is.avector(x = list(1,2,3)) # returns false for lists

# non-core attributes
x <- structure(.Data = c(1,2,3), "names" = c("one","two","three"),
   "value.labels" = c("woman","man","non-binary"))
attributes(x)
is.avector(x)
is.avector(x, attr.ok = FALSE)

# factors
x <- factor(c(1,2,3), labels = c("one","two","three"))
is.avector(x)
is.avector(x, fct.ok = FALSE)

Description

is.cnumeric returns whether an object is a character vector with all number strings.

Usage

is.cnumeric(x, warn = FALSE)

Arguments

Details

is.cnumeric is useful for ensuring that converting a character vector to a numeric vector is safe (i.e., won't introduce NAs).

Value

logical vector with length 1 specifying whether 'x' is a character vector with all number strings.

Examples

is.cnumeric(x = c("1","2","3")) # returns TRUE
is.cnumeric(x = c("1","number","3")) # returns FALSE
is.cnumeric(x = c("1","number","3"), warn = TRUE) # includes the warning
is.cnumeric(x = c(1,2,3)) # returns false because not a character vector

Description

is.colnames returns whether elements of a character vector are colnames of an object.

Usage

is.colnames(nm, x)

Arguments

Details

If the object does not have any colnames, then the function will return 'FALSE' for each element of the character vector.

Value

TRUE for every element of 'nm' that is a colname of x and FALSE otherwise. The structure is a logical vector with length = length('nm') and names = 'nm'. See details for special cases.

Examples

data("mtcars")
is.colnames(x = as.matrix(mtcars), nm = c("MPG","mpg"))

Description

is.Date returns whether an object is a Date object (aka has class = "Date").

Usage

is.Date(x)

Arguments

Value

TRUE is x has class "Date" and FALSE if x does not have class "Date".

Examples

date <- as.Date("2021-05-24", format = "%Y-%m-%d") # as.Date.character
is.Date(date)
class(date) <- append(class(date), "extra_class")
is.Date(date) # classes other than Date are allowed
is.Date(list(date)) # returns FALSE

Description

is.dummy returns whether a numeric vector is a dummy variable, meaning all elements one of two observed values (or missing values). Depending on the argument any.values, the two observed values are required to be 0 and 1 or any values.

Usage

is.dummy(x, any.values = FALSE)

Arguments

Value

TRUE if 'x' is a dummy variable; FALSE otherwise.

Examples

# any.values = FALSE (default)
is.dummy(mtcars$"am") # TRUE
is.dummy(c(mtcars$"am", NA, NaN)) # works with missing values
is.dummy(c(as.integer(mtcars$"am"), NA, NaN)) # works with typeof integer
x <- ifelse(mtcars$"am" == 1, yes = 2, no = 1)
is.dummy(x) # FALSE

# any.values = TRUE
is.dummy(x, any.values = TRUE) # TRUE
is.dummy(c(x, NA), any.values = TRUE) # work with missing values
is.dummy(c(as.character(x), NA), any.values = TRUE) # work with typeof character
is.dummy(mtcars$"gear") # FALSE for nominal variables with more than 2 levels

Description

is.empty returns whether elements of a character vector are empty (i.e., "").

Usage

is.empty(x, trim = FALSE)

Arguments

Value

TRUE for every element of 'x' that is empty (i.e., "") and FALSE otherwise. The structure is a logical vector with length = length('x') and names = names('x').

Examples

v <- c("1", " ", "")
is.empty(v)

Description

is.names returns whether elements of a character vector are names of an object.

Usage

is.names(nm, x)

Arguments

Details

If the object does not have any names, then the function will return 'FALSE' for each element 'nm'.

Value

TRUE for every element of 'nm' that is a name of 'x' and FALSE otherwise. The structure is a logical vector with length = length('nm') and names = 'nm'. See details for special cases.

Examples

v <- setNames(object = letters, nm = LETTERS)
is.names(x = v, nm = c("A","a"))
data("mtcars")
is.names(x = mtcars, nm = c("MPG","mpg"))

Description

is.POSIXct returns whether an object is a POSIXct object (aka has class = "POSIXct").

Usage

is.POSIXct(x)

Arguments

Value

TRUE is x has class "POSIXct" and FALSE if x does not have class "POSIXct".

Examples

tmp <- as.POSIXlt("2021-05-24 21:49:11", tz = "America/New_York",
   format = "%Y-%m-%d %H:%M:%OS") # as.POSIXlt.character
time <- as.POSIXct(tmp) # as.POSIXct.POSIXlt
is.POSIXct(time)
class(time) <- append(class(time), "extra_class")
is.POSIXct(time) # classes other than POSIXct are allowed
is.POSIXct(list(time)) # returns FALSE

Description

is.POSIXlt returns whether an object is a POSIXlt object (aka has class = "POSIXlt").

Usage

is.POSIXlt(x)

Arguments

Value

TRUE is x has class "POSIXlt" and FALSE if x does not have class "POSIXlt".

Examples

time <- as.POSIXlt("2021-05-24 21:49:11", tz = "America/New_York",
   format = "%Y-%m-%d %H:%M:%OS") # as.POSIXlt.character
is.POSIXlt(time)
class(time) <- append(class(time), "extra_class")
is.POSIXlt(time) # classes other than POSIXlt are allowed
is.POSIXlt(list(time)) # returns FALSE

Description

is.row.names returns whether elements of a character vector are row.names of an object.

Usage

is.row.names(nm, x)

Arguments

Details

If the object does not have any row.names, then the function will return 'FALSE' for each element of the character vector. As a reminder, row.names does not respond to a manually added "row.names" attribute (e.g., to a vector). If this is tried, then is.row.names will return 'FALSE' for each element 'nm'.

Value

TRUE for every element of 'nm' that is a row.name of x and FALSE otherwise. The structure is a logical vector with length = length('nm') and names = 'nm'. See details for special cases.

Examples

data("mtcars")
is.row.names(x = mtcars, nm = c("Mazda RX4","mazda RX4"))

Description

is.rownames returns whether elements of a character vector are rownames of an object.

Usage

is.rownames(nm, x)

Arguments

Details

If the object does not have any rownames, then the function will return 'FALSE' for each element of the character vector.

Value

TRUE for every element of 'nm' that is a rowname of x and FALSE otherwise. The structure is a logical vector with length = length('nm') and names = 'nm'. See details for special cases.

Examples

data("mtcars")
is.rownames(x = as.matrix(mtcars), nm = c("Mazda RX4","mazda RX4"))

Description

is.whole returns whether elements of a numeric vector are whole numbers.

Usage

is.whole(x, tol = .Machine[["double.eps"]])

Arguments

Value

TRUE for every element of 'x' that is a whole number and FALSE otherwise. The structure is a logical vector with length = length('x') and names = names('x').

Examples

v <- c(1.0, 1L, 1.1)
is.whole(v)

Description

Join merges a list of data.frames into a single data.frame. It is a looped version of plyr::join that allows you to merge more than 2 data.frames in the same function call. It is different from plyr::join_all because it allows you to join by the row.names.

Usage

Join(
  data.list,
  by,
  type = "full",
  match = "all",
  rownamesAsColumn = FALSE,
  rtn.rownames.nm = "row_names"
)

Arguments

Details

Join is a polished rendition of Reduce(f = plyr::join, x = data.list). A future version of the function might allow for the init and right arguments from Reduce.

Value

data.frame of all uniquely colnamed columns from data.list with the rows included specified by type and rownames specified by rownamesAsColumn. Similar to plyr::join, Join returns the rows in the same order as they appeared in data.list.

See Also

join_all join merge

Examples

# by column
mtcars1 <- mtcars
mtcars1$"id" <- row.names(mtcars)
mtcars2 <- data.frame("id" = mtcars1$"id", "forward" = 1:32)
mtcars3 <- data.frame("id" = mtcars1$"id", "backward" = 32:1)
mtcars_list <- list(mtcars1, mtcars2, mtcars3)
by_column <- Join(data.list = mtcars_list, by = "id")
by_column2 <- Join(data.list = mtcars_list, by = "id", rownamesAsColumn = TRUE)
by_column3 <- Join(data.list = mtcars_list, by = NULL)

# by rownames
mtcars1 <- mtcars
mtcars2 <- data.frame("forward" = 1:32, row.names = row.names(mtcars))
mtcars3 <- data.frame("backward" = 32:1, row.names = row.names(mtcars))
by_rownm <- Join(data.list = list(mtcars1, mtcars2, mtcars3), by = "0")
by_rownm2 <- Join(data.list = list(mtcars1, mtcars2, mtcars3), by = "0",
   rownamesAsColumn = TRUE)
identical(x = by_column[names(by_column) != "id"],
   y = by_rownm) # same as converting rownames to a column in the data
identical(x = by_column2[names(by_column2) != "id"],
   y = by_rownm2) # same as converting rownames to a column in the data

# inserted NAs (by columns)
mtcars1 <- mtcars[1:4]
mtcars2 <- setNames(obj = as.data.frame(scale(x = mtcars1[-1],
   center = TRUE, scale = FALSE)), nm = paste0(names(mtcars1[-1]), "_c"))
mtcars3 <- setNames(obj = as.data.frame(scale(x = mtcars1[-1],
   center = FALSE, scale = TRUE)), nm = paste0(names(mtcars1[-1]), "_s"))
tmp <- lapply(X = list(mtcars1, mtcars2, mtcars3), FUN = function(dat)
   dat[sample(x = row.names(dat), size = 10), ])
mtcars_list <- lapply(X = tmp, FUN = reshape::namerows)
by_column_NA <- Join(data.list = mtcars_list, by = "id") # join by row.names
by_column_NA2 <- Join(data.list = mtcars_list, by = "id", rownamesAsColumn = TRUE)
identical(x = row.names(by_column_NA), # rownames from any data.frame are retained
   y = Reduce(f = union, x = lapply(X = mtcars_list, FUN = row.names)))

# inserted NAs (by rownames)
mtcars1 <- mtcars[1:4]
mtcars2 <- setNames(obj = as.data.frame(scale(x = mtcars1, center = TRUE, scale = FALSE)),
   nm = paste0(names(mtcars1), "_c"))
mtcars3 <- setNames(obj = as.data.frame(scale(x = mtcars1, center = FALSE, scale = TRUE)),
   nm = paste0(names(mtcars1), "_s"))
mtcars_list <- lapply(X = list(mtcars1, mtcars2, mtcars3), FUN = function(dat)
   dat[sample(x = row.names(dat), size = 10), ])
by_rownm_NA <- Join(data.list = mtcars_list, by = "0") # join by row.names
by_rownm_NA2 <- Join(data.list = mtcars_list, by = "0", rownamesAsColumn = TRUE)
identical(x = row.names(by_rownm_NA), # rownames from any data.frame are retained
   y = Reduce(f = union, x = lapply(X = mtcars_list, FUN = row.names)))

# types of joins
Join(data.list = mtcars_list, by = "0", type = "left") # only rows included in mtcars1
Join(data.list = mtcars_list, by = "0", type = "right") # only rows included in mtcars3
Join(data.list = mtcars_list, by = "0", type = "inner") # only rows included in
   # all 3 data.frames (might be empty due to random chance from sample() call)

# errors returned
tmp <- str2str::try_expr(
   Join(data.list = list(mtcars, as.matrix(mtcars), as.matrix(mtcars)))
)
print(tmp[["error"]]) # "The elements with the following positions in
   # `data.list` are not data.frames: 2 , 3"
tmp <- str2str::try_expr(
   Join(data.list = replicate(n = 3, mtcars, simplify = FALSE), by = 0)
)
print(tmp[["error"]]) # "Assertion on 'by' failed: Must be of type
   # 'character' (or 'NULL'), not 'double'."
tmp <- str2str::try_expr(
   Join(data.list = replicate(n = 3, mtcars, simplify = FALSE), by = c("0","mpg"))
)
print(tmp[["error"]]) # "If '0' is a value in `by`, then it must be the
   # only value and `by` must be length 1."
tmp <- str2str::try_expr(
   Join(data.list = list(attitude, attitude, mtcars), by = "mpg")
)
print(tmp[["error"]]) # "The data.frames associated with the following positions in
   # `data.list` do not contain the `by` columns: 1 , 2"

Description

la2a converts a list of (3D+) arrays to a one dimension larger (3D+) array where the list dimension becomes the additional dimension of the array. la2a is a simple wrapper function for abind::abind. If you have a list of matrices, then use lm2a.

Usage

la2a(la, dim.order = 1:(ndim(la[[1]]) + 1L), dimlab.list = NULL, check = TRUE)

Arguments

Value

3D+ array where the list elements of la is now a dimension. The order of the dimensions is determined by the argument dim.order. The dimnames of the returned array is determined by the dimnames in la[[1]] and names(la).

Examples

la <- list("one" = HairEyeColor, "two" = HairEyeColor*2, "three" = HairEyeColor*3)
la2a(la) # default
la2a(la, dimlab.list = "Multiple")
la2a(la, dim.order = c(4,3,1,2))
la2a(la, dim.order = c(4,3,1,2), dimlab.list = "Multiple")

Description

laynames returns the names of the layers - the third dimension - of an array. If the object does not have a third dimension (e.g., matrix), then the function will return NULL. If the object does not have any dimensions (e.g., atomic vector), then the function will also return NULL.

Usage

laynames(x)

Arguments

Details

R does not have standard terminology for the third dimension. There are several common terms people use including "height" and "page". I personally prefer "layer" as it makes sense whether the user visualizes the third dimension as going into/ontop a desk or into/ontop a wall.

Value

Names of the layers (the third dimension) of x. The structure is a character vector with length = nlay(x). See details for special cases.

Examples

laynames(HairEyeColor)
a <- array(data = NA, dim = c(6,7,8,9))
laynames(a)
laynames(c(1,2,3))

Description

ld2a converts a list of data.frames to a 3D array. The data.frames must have the same dimensions.

Usage

ld2a(
  ld,
  dim.order = c(1, 2, 3),
  dimlab.list = NULL,
  fct = "chr",
  chr = "chr",
  lgl = "int",
  order.lvl = "alphanum",
  decreasing = FALSE,
  na.lvl = FALSE,
  check = TRUE
)

Arguments

Details

If the columns of the data.frames in ld are not all the same typeof, then the return object is coerced to the most complex type of any data.frame column (e.g., character > double > integer > logical). See unlist for details about the hierarchy of object types.

Value

3D array with all the elements from ld organized into dimensions specified by dim.order.

Examples

ld <- list("first" = BOD, "second" = BOD*2, "third" = BOD*3)
ld2a(ld)
ld <- list("cars" = cars, "mtcars" = mtcars)
try_expr(ld2a(ld)) # error

Description

ld2d converts a list of data.frames to a data.frame. The function is primarily for rbinding a list of data.frames (along = 1). An option to cbind the list of data.frames is included (along = 2), but is just a call to data.frame(ld, stringsAsFactors = stringsAsFactors, check.names = check.names).

Usage

ld2d(
  ld,
  along = 1,
  fill = FALSE,
  rtn.listnames.nm = "list_names",
  rtn.rownames.nm = "row_names",
  stringsAsFactors = FALSE,
  check.names = FALSE,
  check = TRUE
)

Arguments

Value

data.frame with the rows (if along = 1) or columns (if along = 2) of ld binded together.

Examples

# without listnames and default rownames
ld <- list(BOD*1, BOD*2, BOD*3)
ld2d(ld)
# with listnames and default rownames
names(ld) <- LETTERS[1:3]
ld2d(ld)
# without listnames and custom rownames
ld <- lapply(unname(ld), FUN = `row.names<-`, letters[1:6])
ld2d(ld)
# with listnames and custom rownames
ld <- setNames(ld, LETTERS[1:3])
ld2d(ld)
# can handle same named columns in different positions
ld <- list(BOD*1, rev(BOD*2), rev(BOD*3))
ld2d(ld)
# can handle some columns being absent with fill = TRUE
ld[[2]]$"demand" <- NULL
try_expr(ld2d(ld, fill = FALSE)) # error
ld2d(ld, fill = TRUE) # NAs added
# along = 2 for cbinding
ld2d(ld, along = 2) # does not check/rename for double colnames
ld2d(ld, along = 2, check.names = TRUE) # makes unique colnames
ld2d(setNames(ld, nm = c("One","Two","Three")), along = 2,
   check.names = TRUE) # does not add prefixes from list names

Description

ld2v converts a list of data.frames to a (atomic) vector. This function is a combination of d2v and lv2v. This function can be useful in conjunction with the boot::boot function when wanting to generate a statistic function that returns an atomic vector.

Usage

ld2v(
  ld,
  along = 2,
  use.listnames = TRUE,
  use.dimnames = TRUE,
  sep = "_",
  fct = "chr",
  chr = "chr",
  lgl = "int",
  order.lvl = "alphanum",
  decreasing = FALSE,
  na.lvl = FALSE,
  check = TRUE
)

Arguments

Details

When use.listnames and use.dimnames are both TRUE (default), the returned vector elements the following naming scheme: "[listname][sep][rowname][sep][colname]".

If the columns of the data.frames in ld are not all the same typeof, then the return object is coerced to the most complex type of any data.frame column (e.g., character > double > integer > logical). See unlist for details about the hierarchy of object types.

Value

(atomic) vector with an element for each element from ld.

Examples

ld <- list("cars" = cars, "mtcars" = mtcars)
# use.listnames = TRUE & use.dimnames = TRUE
ld2v(ld) # the first part of the name is the list names followed by the dimnames
# use.listnames = FALSE & use.dimnames = TRUE
ld2v(ld, use.listnames = FALSE) # only dimnames used,
   # which can result in repeat names
# use.listnames = TRUE & use.dimnames = FALSE
ld2v(ld, use.dimnames = FALSE) # listnames and vector position without any
   # reference to matrix dimensions
# use.listnames = FALSE & use.dimnames = FALSE
ld2v(ld, use.listnames = FALSE, use.dimnames = FALSE) # no names at all
# when list does not have names
ld <- replicate(n = 3, expr = attitude, simplify = FALSE)
ld2v(ld) # the first digit of the names is the list position and
   # the subsequent digits are the matrix dimnames
ld2v(ld, use.listnames = FALSE) # only dimnames used,
   # which can result in repeat names

Description

lm2a converts a list of matrices to a 3D array where the list dimension becomes the third dimension of the array (layers). lm2a is a simple wrapper function for abind::abind.

Usage

lm2a(lm, dim.order = c(1, 2, 3), dimlab.list = NULL, check = TRUE)

Arguments

Value

3D array where the list elements of lm is now a dimension. The order of the dimensions is determined by the argument dim.order with dimnames specified by names(lm). The dimnames of the returned array is determined by the dimnames in lm[[1]] and names(lm).

Examples

lm <- asplit(HairEyeColor, MARGIN = 3L)
lm2a(lm) # default
lm2a(lm, dimlab.list = "Sex")
lm2a(lm, dim.order = c(3,1,2))
lm2a(lm, dim.order = c(3,1,2), dimlab.list = "Sex")

Description

lm2d converts a list of matrices to a data.frame. The function is primarily for rbinding a list of matrices (along = 1). An option to cbind the list of matrices is included (along = 2), but is just a call to data.frame(lapply(lm, m2d), stringsAsFactors = stringsAsFactors, check.names = check.names).

Usage

lm2d(
  lm,
  along = 1,
  fill = FALSE,
  rtn.listnames.nm = "list_names",
  rtn.rownames.nm = "row_names",
  stringsAsFactors = FALSE,
  check.names = FALSE,
  check = TRUE
)

Arguments

Details

Another way to convert a list of matrices to a data.frame is to convert the list dimension, row dimension, and column dimension in the list of matrices all to variable dimensions in the data.frame. If this is desired, call a2d(lm2a(lm)) instead of lm2d.

Value

data.frame with the rows (if along = 1) or columns (if along = 2) of lm binded together.

Examples

# list names and rownames
lm <- asplit(HairEyeColor, MARGIN = 3L)
lm2d(lm) # default
lm2d(lm, rtn.listnames.nm = "Sex", rtn.rownames.nm = "Hair")
# no list names
lm2 <- `names<-`(lm, value = NULL)
lm2d(lm2)
lm2d(lm2, rtn.listnames.nm = NULL)
# no rownames too
lm3 <- lapply(lm2, `rownames<-`, value = NULL)
lm2d(lm3)
lm2d(lm3, rtn.rownames.nm = NULL)
lm2d(lm3, rtn.listnames.nm = NULL, rtn.rownames.nm = NULL)
# cbinding as columns
lm2d(lm3, along = 2)
lm2d(lm3, along = 2, check.names = TRUE)

Description

lm2v converts a list of matrices to a (atomic) vector. This function is a combination of m2v and lv2v. This function can be useful in conjunction with the boot::boot function when wanting to generate a statistic function that returns an atomic vector.

Usage

lm2v(
  lm,
  along = 2,
  use.listnames = TRUE,
  use.dimnames = TRUE,
  sep = "_",
  check = TRUE
)

Arguments

Details

When list.names and use.dimnames are both TRUE (default), the returned vector elements the following naming scheme: "[listname][sep][rowname][sep][colname]".

If the matrices in lm are not all the same typeof, then the return object is coerced to the most complex type of any matrix (e.g., character > double > integer > logical). See unlist for details about the hierarchy of object types.

Value

(atomic) vector with an element for each element from 'lm'.

Examples

lm <- list("numeric" = data.matrix(npk), "character" = as.matrix(npk))
# use.listnames = TRUE & use.dimnames = TRUE
lm2v(lm) # the first part of the name is the list names followed by the dimnames
# use.listnames = FALSE & use.dimnames = TRUE
lm2v(lm, use.listnames = FALSE) # only dimnames used,
   # which can result in repeat names
# use.listnames = TRUE & use.dimnames = FALSE
lm2v(lm, use.dimnames = FALSE) # listnames and vector position without any
   # reference to matrix dimensions
# use.listnames = FALSE & use.dimnames = FALSE
lm2v(lm, use.listnames = FALSE, use.dimnames = FALSE) # no names at all
# when list does not have names
lm <- replicate(n = 3, expr = as.matrix(attitude, rownames.force = TRUE), simplify = FALSE)
lm2v(lm) # the first digit of the names is the list position and
   # the subsequent digits are the matrix dimnames
lm2v(lm, use.listnames = FALSE) # no listnames; only dimnames used,
   # which can result in repeat names

Description

lv2d converts a list of (atomic) vectors to a data.frame. This function is similar to as.data.frame.list, but allows for more flexibility in how the data.frame will be structured (e.g., rowwise), while simplifying the dimension naming process.

Usage

lv2d(
  lv,
  along,
  fill = FALSE,
  risky = FALSE,
  stringsAsFactors = FALSE,
  check = TRUE
)

Arguments

Details

If fill = FALSE, lv2d 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, lv2d uses plyr::rbind.fill if along = 1 or plyr::join_all by the vector names 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

data.frame with the elements of 'lv' either as rows or columns and dimnames determined along the names of 'lv' and 'lv'[[1]].

Examples

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

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

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

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

# we want vectors combined along rows
lv <- lapply(X = unclass(mtcars), FUN = `names<-`, value = row.names(mtcars))
rbind(lv) # not what we want (array list)
rbind.data.frame(lv) # also not what we want (combined along cols)
do.call(what = rbind.data.frame, args = lv) # doesn't have useful dimnames
lv2d(lv, along = 1) # finally what we want

# fill = TRUE
tmp <- lapply(X = unclass(mtcars), FUN = `names<-`, value = row.names(mtcars))
lv <- lapply(X = tmp, FUN = function(v) v[-(sample(x = seq_along(v), size = 9))])
lv2d(lv, along = 1L, fill = TRUE) # NA for missing values in any given row
tmp <- lapply(X = unclass(as.data.frame(t(mtcars))), FUN = `names<-`, value = names(mtcars))
lv <- lapply(X = tmp, FUN = function(v) v[-(sample(x = seq_along(v), size = 3))])
lv2d(lv, along = 2L, fill = TRUE) # NA for missing values in any given column

# actual use case
lv <- lapply(X = sn(1:30), FUN = function(i)
   coef(lm(v2frm(names(attitude)), data = attitude[-i, ])))
lv2d(lv, along = 2) # coefs in a data.frame

# when vectors have named elements in different positions use fill = TRUE
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"))
lv2d(lv, along = 1, fill = FALSE) # probably not what you want (See details)
lv2d(lv, along = 1, fill = TRUE) # what we want

# 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)

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

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)

Description

lv2v converts a list of (atomic) vectors to an (atomic) vector. lv2v is simply a wrapper function for unlist that allows for more control over the names of the returned (atomic) vector.

Usage

lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE, sep = "_", check = TRUE)

Arguments

Details

There are four different scenarios. Each scenario is given as well as the structure of the returned object when both use.listnames and use.vecnames are TRUE (default): 1) if both lv and its vectors have names, then the names of the return object will be a pasted combination of the lv element's name and the vector element's name separated by sep; 2) if only lv has names and its vectors do not, then the names of the returned vector will be a pasted combination of the lv element's name and the vector element's position separated by sep; 3) if the vectors have names and lv does not, then the names of the returned vector will be a pasted combination of the lv positions and vector names separated by sep; 4) if both lv and its vectors do not have names, then the names of the returned vector will be the pasted combination of the lv positions and vector element's positions separated by sep.

If you want to convert a list of vectors where each vector has length = 1 and the list has names, then you probably want to specify use.vecnames = FALSE. This will replicate the functionality of unlist(lv). See the last example.

If you want have a list of vectors where each vector has length > 1 and you want to convert it to a list vector (i.e., all vectors with length = 1), then you can combine lv2v with v2lv via v2lv(lv2v(v)).

Value

atomic vector with length = sum of the lengths of the atomic vectors in lv and typeof = the highest typeof present in the atomic vectors in lv (i.e., from high to low: character > double > integer > logical). See the argument use.listnames for how names are created.

Examples

# 1) both `lv` and its atomic vectors have names
lv <- setNames(object = Map(object = 1:26, nm = letters, f = setNames), nm = LETTERS)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE)
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# 2) only `lv` has names
lv <- list("lower" = letters, "upper" = LETTERS)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE) # FYI - results in repeat names
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# 3) only the atomic vectors have names
lv <- list(setNames(object = 1:26, nm = letters), setNames(object = 1:26, nm = LETTERS))
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE)
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# 4) neither `lv` nor its atomic vectors have names
lv <- as.list(1:26)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE) # FYI - results in repeat names
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE)
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
# common use case for when vectors are all length 1 and list has names
lv <- setNames(as.list(letters), nm = LETTERS)
lv2v(lv, use.listnames = TRUE, use.vecnames = TRUE)
lv2v(lv, use.listnames = FALSE, use.vecnames = TRUE)
lv2v(lv, use.listnames = TRUE, use.vecnames = FALSE) # FYI - probably what you want
lv2v(lv, use.listnames = FALSE, use.vecnames = FALSE)
identical(unlist(lv), lv2v(lv, use.vecnames = FALSE)) # identical to unlist()