transformArray: Data preparation mainly aimed at facilitating plotting in...

In tdeenes/eegR: Analyze EEG Signals

Description

transformArray provides several options to transform an array to a a data.frame which enables direct plotting in lattice or ggplot2 afterwards. It can also be used for analyses purposes without data.frame conversion if compact code is desirable.

Usage

transformArray(
  formula,
  data,
  group = NULL,
  group_fun = "avgDims",
  subset = NULL,
  datfr = TRUE,
  auto_convert = TRUE,
  ...
)

Arguments

formula	an object of class "formula" (or one that can be coerced to that class, e.g., a character string): a symbolic description of the transformation steps before converting the array to a data.frame. See Details.
data	a matrix or an array. Must have named dimnames.
group	a list of grouping factors in the order of appearance in the transformation formula (see 'Details'). If a named list is provided, those names are used as the names of dimnames for the given grouping dimensions. It can be a simple vector if there is only one splitting factor.
group_fun	a function (or symbol or character string naming a function) which should be performed on the groups (i.e., on the list of arrays after splitting). group_fun must be a function which expects an array and a vector of dimension names as input and returns an array (or vector). Defaults to avgDims, which collapses (averages over) the grouping dimensions.
subset	a list of subsetting vectors on the input array passed to subsetArray before any transformation steps
datfr	a logical value (default: TRUE) if the resulting array shall be transformed to a data.frame
auto_convert	a logical value whether automatic conversion of dimension names (i.e., characters to numeric (if possible) or to factors) should be performed (default: TRUE). Set to FALSE and call autoConvert directly on the returned data frame if you need more control.
...	additional parameters to be passed to array2df

Details

The formula interface of transformArray shall be given in the form of

fun(y[d1, d2], fun_args) ~ . - d3 | d4 + d5

where

fun

optional; an arbitrary function whose first argument is the data, and returns an array (optional)

y

the name of the variable which holds the values in the returned data.frame (if 'datfr' is TRUE). See also array2df.

[d1,d2]

optional; the dimensions of the data array whose levels should be treated as separate value-variables in the returned data.frame should be listed between squared brackets after the general name of the value variable. If you do not want to have a general name, place a dot (.) before the brackets. See also array2df.

.

a dot on the right-hand side [RHS] of the formula means 'all dimensions of the data array which are not explicitly mentioned in the formula'. The dimension names can be explicitly provided as well, separated by +.

d3

optional; any dimension of the data array which is preceeded by a minus sign or any dimension which is not present in the formula will be collapsed (averaged over)

d4,d5

dimensions after the | sign are treated as conditioning (grouping) dimensions, and shall be separated by + or *.

transformArray performs the following actions:

1. Takes the input array ('data') and subsets it if 'subset' is not NULL or an empty list.

2. Calls avgDims on the (subsetted) data, and collapses over all dimensions which are preceeded by - in the formula or are not present in any other part of the formula.

3. Calls splitArray on the averaged data with the conditioning dimensions in the formula. The 'group' argument is passed to the splitArray as the grouping argument ('f' in splitArray). For each data array which is returned after splitting, group_fun is called with the character vector of the grouping dimension names as its second argument. The resulting arrays are merged back to form one array.

4. If the left-hand side of the formula contains a function (see fun above), this function is called on the merged array with its arguments as given in fun_args.

5. If 'datfr' is TRUE (the default), the resulting array is transformed to a data.frame by calling array2df.

Value

The function returns a data.frame if 'datfr' is TRUE, and an array if 'datfr' is FALSE.

Examples

# example dataset
data(erps)
dat_id <- attr(erps, "id") # to get reading group memberships

# compute simple grand averages (collapse over the 'id' dimension) and
# return it as a data.frame
DF <- transformArray(~ . - id, erps)
head(DF, 10)

# compute the grand averages for each level of pairtype in each channel and
# time points; return the amplitudes of pairtype as separate variables in 
# a data.frame
DF <- transformArray(ampl[pairtype] ~ time + chan, erps)
head(DF, 10)

# compute the grand averages of dyslexic and control subjects, and also 
# compute the Global Field Power (and transform to data.frame)
res1 <- transformArray(compGfp(ampl, keep_channels = TRUE) ~ . | id,
                       erps, list(readgroup = dat_id$group))

# the same with much more typing, and it would be even longer to make
# it safer (e.g., match the order of dimensions, handle more grouping
# dimensions, etc.)
res2 <- splitArray(erps, "id", list(readgroup = dat_id$group))
res2[] <- lapply(res2, avgDims, "id")
res2 <- bindArrays(res2, along_name = "readgroup")
res2 <- compGfp(res2, keep_channels = TRUE)
res2 <- array2df(res2, value_name = "ampl", auto_convert = TRUE)
stopifnot(identical(res1, res2))

tdeenes/eegR documentation built on April 19, 2021, 4:17 p.m.