In jonkeane/mocapGrip: Illusion-Grip Motion Capture Package

Data objects store all of the information about the data, dataSets, and analyses after they are read in from the extracted annotations (or after the models are run in the case of analyses). They are a critical component that houses the dataSets to be analyzed, the analyses after the models are fit, and they are used to write reports.

library(mocapGrip)

pathToExtractedData <- system.file("extData", "minimalSubset", "extractedData", package = "mocapGrip")

Throughout this guide, we will use pathToExtractedData to stand in for the path to the extracted motion capture data (on your computer). This will look something like "./extractedData/". Remember when you run the code on your compute to replace pathToExtractedData with a string that matches the folder structure on your computer. If you want to be able to cut and paste these examples, you can store the path (either from R's working directory or as an absolute path) in the variable pathToExtractedData (like that shown below), and then each of these commands will look in that specific location on your computer for the extracted data.

pathToExtractedData <- "./path/to/extracted/data"

First, we should create a data object:

data <- readExtractedMocapData(pathToExtractedData, c("action", "estimation"), includeFullData = TRUE)

data <- modelAllData(data)

Structure

Data objects are a list of lists (of lists...).

dataSets

The first level of lists are all of the dataSets^[If the data object includes the full data, there will be one more level here called fullData which is a dataframe of all of the motion capture data that was read in by readExtractedMocapData. See the fullData section of this vignette for more information.] that are included with the data object (e.g. action and estimation).

You can access each level (action or estimation in our example) with the data$level operator or the data[[level]] construction. For example if we want the action dataSet we can use data$action.

Within each dataSet the next level has the following:

1. data
   a dataframe that has the processed data for this data set.
2. warnings
   warnings that were encountered when the dataSet was processed (occlusion, for example)
3. analysesToRun
   a vector of model names to run (for example, for action, by default this will be "maxGrip.stickAsContinuous")
4. analyses (sometimes)
   The analyses that have already been fit, which will be described in detail in the next section

Using our example data object above, we can look at the action dataSet's data (which is contained in a dataframe) like this. We wrap the command that specifies the dataframe in the head() command so that it only displays the first few rows of the data.

head(data$action$data)

analyses structure

The analyses part of a dataSet within a data object has more structure inside of them. These will only exist if the dataSet has been modeled (for example, with the modelAllData() command). The first level is the name of the model that was fit (there can be more than one model fit here if there is more than one model listed in the analysesToRun above.) This name corresponds to the names in the analyses section of the model section in modelMetadata. Each one has a unique name, and a unique set of outcome and predictor variables (see the model metadata vignette for more information).

Each of these analyses will have two levels below it:

1. bestModel
   This is the model that was chosen as the best model when the models were fit. Best here is typically defined as the most complex model that did not have an error or warning when it was fit^[For more details about fitting and convergence warnings and errors, see the lme4 documentation, as well as the glmm faq and r-sig-mixed-models list]. The level under this has a name that corresponds to the kind of model (for example interactionInPredAndGroup) (which is described in more detail in the model levels section below)
2. allModels
   This level has all of the models that were fit (or attempted to be fit). Each one has the same structure (which is described in more detail in the model levels section below).

To reiterate, the difference between allModels and bestModel is that bestModel has just one model, where as allModels has all of the models that were fit.

model levels

The name of this level describes what kind of model was fit. For now, the only differences between the kinds of models are if they include interactions or not. More details about these are given in the modelStructures section of the model metadata vignette

This object has the following levels:

1. modelObject
   This is the model object that was fit using the lme4 package. This is useful if you need to manually inspect the model.
2. converged
   This is a logical that is TRUE if the model converged and FALSE if the model did not converge.
3. convWarnCode
   This is the warning code that lme4 produced if there was a convergence warning. (It will be 0 if the model converged / fit successfully)
4. convWarnMsgs
   This is the warning messages that lme4 produced if there was a convergence warning.

Using our example data object above, we can look at the action dataSet's maxGrip.stickAsContinuous analysis' best model structure (which is interactionInPredAndGroup) and which has a model object:

data$action$analyses$maxGrip.stickAsContinuous$bestModel$interactionInPredAndGroup$modelObject

Additionally, we can see that converged is TRUE, there are convWarnCode is 0 and there are no convWarnMsgs:

data$action$analyses$maxGrip.stickAsContinuous$bestModel$interactionInPredAndGroup$converged

data$action$analyses$maxGrip.stickAsContinuous$bestModel$interactionInPredAndGroup$convWarnCode

data$action$analyses$maxGrip.stickAsContinuous$bestModel$interactionInPredAndGroup$convWarnMsgs

All of the model structures (interactionInPredAndGroup, interactionInPred, and noInteraction) are fit for the maxGrip.stickAsContinuous analysis and we can see those models with commands like:

data$action$analyses$maxGrip.stickAsContinuous$allModels$interactionInPredAndGroup$modelObject

data$action$analyses$maxGrip.stickAsContinuous$allModels$interactionInPred$modelObject

data$action$analyses$maxGrip.stickAsContinuous$allModels$noInteraction$modelObject

The convergence codes and warnings work the same way for all Models as they do for the single best model.

There is no difference between the model that is selected as best (here interactionInPredAndGroup) in the bestModel level or in the allModels level, which we can test by seeing if the model objects are the same:

all.equal(
data$action$analyses$maxGrip.stickAsContinuous$bestModel$interactionInPredAndGroup$modelObject, data$action$analyses$maxGrip.stickAsContinuous$allModels$interactionInPredAndGroup$modelObject
  )

fullData

If the data object includes the full data, there will be one more level at the top of the data object called fullData which is a dataframe of all of the motion capture data that was read in by readExtractedMocapData. This includes each and every observation (millisecond by millisecond) from the mocap system, with columns for subject, trial, condition, etc. which is a lot of data usually.

Because this is a lot of data, in the example here we wrap the data object (and the level selector) with the head() command so that R will only print the first few rows of the dataframe.

head(data$fullData)

This full data can be useful if you want to extract more dataSets without reading in the data over and over, or if there are manual analyses or processing that must be run.

jonkeane/mocapGrip documentation built on May 19, 2019, 7:30 p.m.