R: Helper Function for Structuring GREML Data

mxGREMLDataHandler {OpenMx} | R Documentation

## Helper Function for Structuring GREML Data

### Description

This function takes a dataframe or matrix and uses it to setup the 'y' and 'X' matrices for a GREML analysis; this includes trimming out `NA`s from 'X' and 'y.' The result is a matrix the first column of which is the 'y' vector, and the remaining columns of which constitute 'X.'

### Usage

    mxGREMLDataHandler(data, yvars=character(0), Xvars=list(), addOnes=TRUE,
                      blockByPheno=TRUE, staggerZeroes=TRUE)

### Arguments

`data` | Either a dataframe or matrix, with column names, containing the variables to be used as phenotypes and covariates in 'y' and 'X,' respectively.
`yvars` | Character vector. Each string names a column of the raw dataset, to be used as a phenotype.
`Xvars` | A list of data column names, specifying the covariates to be used with each phenotype. The list should have the same length as argument `yvars`.
`addOnes` | Logical; should lead columns of ones (for the regression intercepts) be adhered to the covariates when assembling the 'X' matrix? Defaults to `TRUE`.
`blockByPheno` | Logical; relevant to polyphenotype analyses. If `TRUE` (default), then the resulting 'y' will contain phenotype #1 for individuals 1 thru n, phenotype #2 for individuals 1 thru n, ... If `FALSE`, then observations are "blocked by individual", and the resulting 'y' will contain individual #1's scores on phenotypes 1 thru p, individual #2's scores on phenotypes 1 thru p, ... Note that in either case, 'X' will be structured appropriately for 'y.'
`staggerZeroes` | Logical; relevant to polyphenotype analyses. If `TRUE` (default), then each phenotype's covariates in 'X' are "staggered," and 'X' is padded out with zeroes. If `FALSE`, then 'X' is formed simply by stacking the phenotypes' covariates; this requires each phenotype to have the same number of covariates (i.e., each character vector in `Xvars` must be of the same length). The default (`TRUE`) is intended for instances where the multiple phenotypes truly are different variables, whereas `staggerZeroes=FALSE` is intended for instances where the multiple "phenotypes" actually represent multiple observations on the same variable. One example of the latter case is longitudinal data where the multiple "phenotypes" are repeated measures on a single phenotype.

### Details

For a monophenotype analysis (only), argument `Xdata` can be a character vector. In a polyphenotype analysis, if the same covariates are to be used with all phenotypes, then `Xdata` can be a list of length 1.

Note the synergy between the output of `mxGREMLDataHandler()` and arguments `dataset.is.yX` and `casesToDropFromV` to `mxExpectationGREML()`.

If the dataframe or matrix supplied for argument `data` has n rows, and argument `yvars` is of length p, then the resulting 'y' and 'X' matrices will have np rows. Then, if either matrix contains any `NA`'s, the rows containing the `NA`'s are trimmed from both 'X' and 'y' before being returned in the output (in which case they will obviously have fewer than np rows). Function `mxGREMLDataHandler()` reports which rows of the full-size 'X' and 'y' were trimmed out due to missing observations. These row indices can be provided as argument `casesToDropFromV` to `mxExpectationGREML()`.

### Value

A list with these two components:

`yX` | Numeric matrix. The first column is the phenotype vector, 'y,' while the remaining columns constitute the 'X' matrix of covariates. If this matrix is used as the raw dataset for a model, then the model's GREML expectation can be constructed with `dataset.is.yX=TRUE` in `mxExpectationGREML()`.
`casesToDrop` | Numeric vector. Contains the indices of the rows of the 'y' and 'X' that were dropped due to containing `NA`'s. Can be provided as as argument `casesToDropFromV` to `mxExpectationGREML()`.

### References

The OpenMx User's guide can be found at https://openmx.ssri.psu.edu/documentation/.

### See Also

For more information generally concerning GREML analyses, including a complete example, see `mxExpectationGREML()`. More information about the OpenMx package may be found here.

### Examples

    dat <- cbind(rnorm(100),rep(1,100))
    colnames(dat) <- c("y","x")
    dat[42,1] <- NA
    dat[57,2] <- NA
    dat2 <- mxGREMLDataHandler(data=dat, yvars="y", Xvars=list("x"),
      addOnes = FALSE)
    str(dat2)

[Package OpenMx version 2.20.6 Index]