TrajTracker analysis toolbox: Data formats

Contents

Getting the raw results (from the experiment software) into matlab

After you ran an experiment, the results are downloaded as a set of 3 file per experiment session (session = one block of one subject):

  1. Session file - with general info about the session
  2. Trials file - a CSV file with one line per trial (including failed trials)
  3. Trajectory file - a CSV file with one line per sampled finger positions Click here for more details about the format of these files.

You then need to organize the files into datasets.

A dataset is the results of one or more subjects and it represents a basic analysis unit - i.e., this toolbox provides you with tools to analyze whole datasets.

In a simple experiment, the dataset will be all data of all subjects. In an experiment with two conditions, you may have two datasets. And so on.

All data files of a dataset should be placed in a single directory:

[base]/[subdir]/raw

Where [base] is the base path of all datasets (defined in the TrajTrackerDataPath function), and [subdir] is any path under [base].

You should also create a [base]/[subdir]/binary directory. This is where the toolbox will store files in matlab format (*.MAT)

Getting the data

To convert the data from raw format to the toolbox format, run the function tt.preprocessSet(subdir)

This will preprocess the dataset and save it in matlab format: [base]/[subdir]/binary/session_data.mat

To load the data as a matlab object, call tt.loadDataset(subdir)

In some cases you cannot break the raw data files into datasets - e.g., if you have two conditions with mixed design. Don't worry about this: save them as one dataset, prepreocess and load them as such, and then you can break them into multiple datasets.

How the data is stored as matlab objects

The TrajTracker toolbox organizes the experiment data in three levels:

1. Dataset: as explained above, this represents data of one dataset from one or more subjects. The way you break the data into datasets is your own decision, the TrajTracker toolbox doesn't care about this.

2. Subject data: the data of one subject in one dataset. This is stored as one object (see details below). In the documentation, we usually refer to this object as "expData".

.3 Single trial: each expData object contains a list of the trials. Each trial is itself an object. The object includes general properties of the trial (target, movement time, etc.) and details about the trajectory.

If you loaded a dataset using tt.loadDataset(), you will get a struct with two entries: "raw" and "d". Each of them is again a struct, with one entry per subject (containing that subject's information). "raw" and "d" are two copies of the same dataset, with one difference: "raw" contains all trials per subject, whereas "d" contains just the non-failed trials (i.e., it excludes trials that had non-"OK" status in the trials.csv file). Both "raw" and "d" also contains a dummy subject called "all", which contains data of all subjects. "raw" also has a dummy subject called "avg", which contains average trajectories over all subjects.

ExperimentData and OneTrialData object - details

Experiment and trial data are objects defined using matlab classes. If you are not familiar with matlab classes and objects, read this.

Data from number-line experiments is stored as NLExperimentData objects, data from discrete-choice experiments is stored as DCExperimentData objects. Both these classes derive from ExperimentData.

Data of one trial is a OneTrialData object.

OneTrialData object includes:

An ExperimentData object contains: