manual for the nrec_analyse Matlab project

1. What is nrec_analyse?

nrec_analyse is a Matlab project to read and analyse nrec data that has been stored into hdf5-files.

2. System Requirements

You need Matlab R2009b to run nrec_analyse.

3. What do the columns of the TrialList Matrix mean?

In the columns the following values are stored trial by trial:

1. Trial number starting with 1 (Matlab-style).
2. Number of samples in the eyeposition data matrices EyeX, EyeY.
3. Pool number as specified by the parameters in the description file for the given paradigm type (see below).
4. 1 if valid, else 0. Trials usually are invalid in case of a fixation failure or a missing or invalid answer.
5. Level value of the currently active strategy. 0 if no strategy is used.
6. 1 if the given answer was correct, 0 otherwise.
7. The value of the given answer. Usually 2, 4, 8 or 16 in case of 4 available answer buttons.
8. The time at which the answer was given relative to trial starttime.
9. Starttime relative to starttime of first trial.
10. Stoptime relative to starttime of first trial.
11. and following can be specified by the numberOfExtraColumns and nameOfExtraColumnN parameters in the description file for the given paradigm type (see below).

4. How can i define the pool number that is stored into the TrialList matrix that contains the information for each of the trials?

• Find the textfile in the nrec_analyse directory that has the same name as your paradigm (e.g. "Saccades.txt").

• Open one of your data files using the hdfread tool.

• Find out where the parameters you want to read are stored below one of the trials.
• In the paradigm description text file you have located before, you can add values for telling nrec_analyse, to read these parameters from the hdf5-file and use them to calculate a pool number:
  • nameOfParameterGroup: Name of the group below the trialN-group where the parameters are stored.
  • numberOfParameters: How many parameters you want to use to calculate the pool number.
  • nameOfParameter1, nameOfParameter2, ...: path of the parameters below the parameter group specified by nameOfParameterGroup.
  • poolExpression: Matlab-evaluateable expression used to calculate the pool number. Use the variables p1, p2, ... for the parameters specified before. Examples:
    • "p1 + 10 * p2;" sets first parameter as second digit of the pool number and second one as first.

    • "(p1 == 17) * 6 + (p1 < 17) * 5 + (p1 > 17) * 7" sets pool number to be 5, 6 or 7 if p1 is smaller, equal or greater than 17 respectively.

• Alternative method for more complex calculations (e.g. based on strings):
  • set numberOfParameters to 0
  • set poolExpression to the name of an m-Script, where pool must be defined. This can not be a function, since all nrec_analyse functionality must be available.
  • In this script, you can read out h5-file values e.g. like this:

    • imageFileNameItem = hdf5read( h5filename, parameterGroup, 'FileName' );
      nameWithPath = imageFileNameItem.Data;
      %% cut path
      i=strfind(nameWithPath,'/');
      i=i(end);
      imageFileName = nameWithPath(i+1:end);
      pool = floor(str2double(imageFileName(1:3)));

5. How can i configure it to read certain values into the TrialList matrix that contains the information for each of the trials?

• Find the textfile in the nrec_analyse directory that has the same name as your paradigm (e.g. "Saccades.txt").

• Open one of your data files using the hdfread tool.

• Find out where the parameters you want to read are stored below one of the trials.

• In the paradigm description text file you have located before, you can add values for telling nrec_analyse to read these parameters from the hdf5-file and store it in columns 11, 12, ... of the TrialList matrix:

  • numberOfExtraColumns: How many parameters you want to read in.

  • nameOfExtraColumn1, nameOfExtraColumn2, ...: full path of the parameter below the trial group.

• There are special settings, if you want to read in a complete set of parameters, that are numbered in the way param0, param1, ... at once:
  • maxSizeOfExtraColumnsVector1: The expected maximum number of parameters in this vector.
  • nameOfExtraColumnsVector1: The prefix of the name of the parameters ('param' in the example above).
  • You can define 2 different vectors of parameters this way. Example:

    • nameOfExtraColumnsVector1
      Strategy/Answer
      maxSizeOfExtraColumnsVector1
      500
      nameOfExtraColumnsVector2
      Strategy/AnswerTime
      maxSizeOfExtraColumnsVector2
      500

  • This functionality will add a number of maxSizeOfExtraColumnsVectorN columns to the TrialList Matrix and fill them with -9999, if no more parameter can be found.

6. How can i configure it to read certain values into extra matrices that contain vector-information for each of the trials?

• Find the textfile in the nrec_analyse directory that has the same name as your paradigm (e.g. "Saccades.txt").

• Open one of your data files using the hdfread tool.

• Find out where the data you want to read are stored below one of the trials.
• In the paradigm description text file you have located before, you can add values for telling nrec_analyse to read this data from the hdf5-file and store it in columns 1, 2, ... of the ExtraVariableN matrices:
  • numberOfExtraVariables: How many vectors per trial you want to read in.

  • nameOfExtraVariable1, nameOfExtraVariable2, ...: full path of the parameter below the trial group.

  • data is stored trial by trial column-wise in and exported to the matrices called ExtraVariable1, ExtraVariable2, etc.