logData.m: Save the data!
You say "yo d-aah-ta", I say "yo d-ay-ta".
Sorry. Sometimes I can't help myself...
Running an experiment is pretty much worthless if you don't save the experimental data you are collecting, ideally in real time so you don't lose everything if an experiment crashes or has to be aborted part-way through.
Of course, that data can take any number of forms (number or letter responses, RTs in milliseconds, continuous x- and y- coordinates of a mouse movement, etc.). This makes the problem of storing that data quickly and conveniently a bit of a challenge. As I was developing scripts for running in PsychToolBox, I wanted an all-purpose function that would save any kind of data I gave it, without me having to waste time programming exactly what that data should be called, or having to use separate strategies for saving different kinds of data. I also wanted a function that could save multiple pieces of data at once, but was compact enough to fit on a single line of code, for easy readability when writing a program. What I ended up with was the logData function that you see below.
The function takes a minimum of three inputs: 1) the full path name to a data file where the information should be stored; 2) the index in the file where it should be stored (e.g., data for trial #1, trial #2, etc.); and 3) the data itself. Importantly, the function can either store a single piece of data at a time (e.g., a response time), or it can store multiple pieces of data at once (e.g., components of a trial such as the stimulus displayed, the response made, and the response time).
If you want to use logData in the first capacity, you would call it like this, using the data file, the trial number for storage (here #1) and the variable you want to store:
The logData function would then take this information, and append it to the file 'dataFileName', which contains a structure called Data. The Data structure has fields consisting of all data that has been saved up to that point. The function is written in such a way that you don't have to tell it what field to save into in the Data structure. It simply uses the variable name itself (i.e., "Response"). See lines XX-XX in the annotated code below to see how it does this. If you called it in the above manner, you would end up with a Data structure that would likely look like this afterwards:
The first three fields are created by the InitPTB function at the start of any study, and specify the subject ID, the session/task ID (in this case the first of two liking rating tasks), and the start time of the experiment. The last field is the one that we just made, with the data for trial #1 stored in the first index of the Data.Response field. If you called logData again, this time with trial #2, a new entry would be appended after the first one in the Data.Response field, and the value of the Response variable would be saved there.
If you want to use logData to save more than one variable at once, bundle up all of this data into a structure with field names that specify the names of the variables/data as you want them to be saved. For example, to store all trial-level information, you would first create a structure like this:
If this were the data for trial #6, call the logData function like so:
So, for example, after trial #6, the Data structure might look something like this:
As before, the first three fields are created by the InitPTB function at the start of any study. The last three fields consist of the trial-level data stored up to this point. The logData function is written such that if the variable it is given is a structure rather than a single value, it will add all values contained in the fields of the structure to the appropriate location of the corresponding fields in the Data structure.
Once you've saved the data in this manner, you can either use it within MATLAB to data analysis, or you can export it to another program like R, either directly using a package like readMat, or by creating a text file in a format conveniently readable by R. See the convertDataToText script for an example of the latter.
Below is the full code for logging data.