TrajTracker Analyze: Main concepts
This page describes some major points about the design of TrajTracker Analyze. This is complementary to the help provided as part of the toolbox (by running tt.Help)
Data structures and file orgnization
TrajTracker Analyze organizes the data in several levels. For details, run tt.DataFormat in matlab.
The data of a single trial is a Matlab object (OneTrialData class). It includes information such as the target stimulus (trial.Target), the duration from movement initiation to the end of the trial (trial.MovementTime), and whether the trial succeeded or failed (trial.ErrCode).
The finger trajectory is also a part of the trial (trial.Trajectory). The trajectory is a matrix with different rows representing different time points, and different columns representing different values that were calculated per time point (e.g., x/y coordinates, x/y speed, etc.). To access specific columns use the TrajCols class, e.g., trial.Trajectory(:, TrajCols.X) is the x coordinates throughout the trajectory.
A complete experiment session of a single subject is stored as an ExperimentData object. It includes the trials (expData.Trials) and other information such as the participants' details, the time of running the session, etc.
TrajTracker Analyze has a set of functions that filter ExperimentData to include only a subset of trials. This is useful when you want to analyze each subset of trials separately. For example, when the experiment included several conditions in mixed design, you might want to separate them and have each condition as a separate ExperimentData.
A dataset is the data from several subjects, each of which is represented as an ExperimentData object. For a given dataset, TrajTracker Analyze stores two ExperimentData objects per subject: one with all trials, including those that failed (i.e., the subject didn't stick to the experiment rules - e.g., lifting the finger in mid-trial would typically result in a trial failure). The second ExperimentData includes only the non-failed trials (which may still have correct or incorrect responses).
Technically, a dataset is represented in Matlab as a struct with two entries: raw, which is the unfiltered data of all subjects, and d, which is the filtered data. Both raw and d are Matlab structs with one entry per subject (e.g., dataset.d.gt is the ExperimentData that contains the non-failed trials of subject whose initials are "gt"). Both raw and d also include an all entry, with all trials. raw also includes an avg entry, with virtual trials that contain the average trajectory per target.
Because of this organization, a dataset cannot include two subjects with the same initials. If you have more than one subject with the same initials, modify the initials in their session.xml files before preprocessing the data.
The data files of a single dataset (results from TrajTracker Experiment) should be stored in a single directory on your file system. Run tt.DirStruct to learn more about this.
Loading the data
To load the data into TrajTracker Analyze, you should:
Save the experiment results in the directory structure expected by TrajTracker Analyze (run tt.DirStruct for details).
Preprocess the data in TrajTracker Analyze by calling the tt.preprocessDataset() function (this is done only once)
Load the data into matlab using the tt.loadDataset() function.
One way to analyze the TrajTracker data is via regressions. TrajTracker Analyze provides tools to easily create highly configurable
regression models. We demonstrate the basic concepts with examples of two regression models for analyzing the results of a number-to-position task. To see more details, run tt.Regressions.
In this example, we analyze how the average speed during the trial is affected by the numbers presented. The dependent variable is the trial's average speed, and the predictors are the target numbers of the current and previous trials.
Both the dependent variable and the predictors are trial-level measures, i.e., parameters that have a single value per trial. Our approach is that in such cases, we run one regression per participant. To get a group-level effect, we analyze the regression coefficients (b or beta) of all participants: typically, we calculate their average and standard deviation, we compare them to 0 with t-test to examine whether a certain predictor had a significant group-level effect, or we compare the b/beta values of two predictors with paired t-test.
We can also analyze how the finger's momentary speed is affected by the numbers presented. e.g., the dependent variable can be the momentary speed, and the predictors can be the same as above (the target numbers of the current and previous trials).
Here, the dependent variable is a within-trajectory measure, which we also call a dynamic measure: the finger's momentary speed has different values in different points along the trajectory. To run a regression, we have to pick one time point from each trial. Typically, we use the same absolute time from all trials (e.g., 100 ms after the finger started moving). For this time point, we run one regression per subject, just like above. To analyze how the effect changes throughout the trial, we would run the same analysis for several different time points. Namely, a typical analysis of this type would run one regression per subject and time point, for several time points in fixed intervals, and then present the average b/beta values of each predictor in each time point.
You can group time points from trials in any way you want. For example, you can regress the finger speed when it reached a specific y coordinate, or the finger speed when a certain event of interest occurred (e.g., when the finger started deviating).