====== Subject ID Overview ======

There is a set of functionality for keeping track of subjects and what experiments have been done. Basically, you can set parameters on an experiment computer to require that a subject ID is set and if so, the stimfile will get saved to a subject specific directory and a log will be saved that logs what experiments have been run (which can be used for reporting experiments and keeping track of what experiments have been run).

====== Basic usage ======

Once subject ID settings have been setup (see [[#Setup|below]]), every time you run an experiment, you will need to set the subject ID:

  mglSetSID('s001');

or, if you don't know the subject ID for the experiment, you can do:

  mglSetSID('justin')

and it will look up the subject in the encrypted database. To access the encrypted database you will need to put in the password:

  >> mglSetSID('justin')
  (mglSetSID) Loading SID database, enter password
  enter des-ede3-cbc decryption password:
  (mglSetSID) Found subject: Justin Gardner (s001)
  (mglSetSID) Setting SID: s001

If you are just testing code, you can put in:

  mglSetSID(-1);

If you need to add a new subject, see [[#adding_new_subjects|below]].

Note that your experiment will not run until you have set an SID (initScreen requires that you set the subject ID). You will get a warning like the following:

  >> testExperiment
  (initScreen) !!! You must set a SID before running. !!!
  Quit out of debug mode K>> by doing dbquit then run mglSetSID

In which case dbquit out of keyboard mode and set the SID. Once your SID has been set, then your stimfile will be saved into the following directory:

  ~/data/taskprogramname/subjectID

See ([[#stimfile_location|below]]) for more about this. 

When your experiment has finished running, it will save a [[#Task_log|task log]].


====== Setup ======


To enable this functionality, you set the following variables.

  mglSetParam('sidDatabaseFilename','/Users/Shared/.sidDatabase',2);
  mglSetParam('mustSetSID',true,2);
  mglSetParam('writeTaskLog',true,2);
  mglSetParam('logpath','/Users/shared/.mgllogpath',2);

Make sure to make an accessible directory for where the logs will be stored:

  mkdir /Users/shared/.mgllogpath
  chmod +w /Users/shared/.mgllogpath

The setting for sidDatabaseFilename sets where the encrypted SID database will be saved. Note that mglSetParam is being passed the 2 argument which saves it for all users on the computer (by saving the settings in /Users/Shared). The mustSetSID sets it so that when initScreen is run, it will check for whether a subjectID has been set with mglSetSID (more below). The writeTaskLog setting makes sure that at the end of a run, a log is saved of what has been run. The log is saved in the logpath location.


Note that once you set the SID it is valid for all subsequent experiments, but will expire after some time - it expires so that if someone else sits down at the same computer to run a different experiment, they will be prompted to set the SID again. The timeout interval is set by:

  mglSetParam('sidValidIntervalHours',2,1);

The above will set the validity interval for an SID to two hours.

Also, you may want to set a warning for underage subjects (which could be a protocol violation):

  mglSetParam('sidAgeLimit',20);

====== Adding new subjects ======

If this is a new subject, add them using mglSetSID('add') and filling out the dialog. Note that when using the mglSetSID('edit') functionality, you may have problems because old subjects were added without all fields that are currently required being filled out. Thus, when you enter your new subject's information, the system will complain that you haven't told it about older subject's information. Instead of using 'edit', simply type:

  mglSetSID('add');

Enter the lab password when prompted and fill out the dialog with a new SID, and all your subject and demographic information.

The following information is outdated and is retained for historical reference and because the mglSetSID('edit') functionality may be helpful if we ever want to correct and/or sanitize the old database (possibly by filling in required fields with a flag for lost/unknown information for older subjects).

[Old info about how to edit using mglSetSID('edit') follows...]

 If this is a new subject, then you may need to add them to the SID database, you can do this by editing the database:

  mglSetSID('edit');

You will then need to put in the password for the database. It will bring up a dialog like the following:

<html><div></html>
{{:mgl:sidedit.png|}}
<html></div></html>

Fill in details for the new subject. Note that the "dateAdded" field is added automatically and you cannot edit it. If you have the setting:

  mglSetParam('sidRaceEthnicity',true,2);

Then you will also need to enter ethnicity and racial information for subjects. This is intended to fulfill [[http://grants.nih.gov/grants/guide/notice-files/NOT-OD-01-053.html|requirements from NIH]]. Note that you should ask subjects to self report. They may decline reporting, in which case you should fill in the values "declined" for ethnicity and race. Also, subjects may report more than one race, and these should be filled in "otherRace" fields - order does not matter.

====== stimfile location ======

Once you have set SID using mglSetSID, then after your stimulus program runs, it will create a directory:

  ~/data/taskprogramname/subjectID

in which the data will be saved. Make sure that subjectID and your task program name are valid directory names. If SID=[], then the data will be saved to:

  ~/data/taskprogramname

You can also specify a folder name underneath the subjectID if you want, by adding:

  myscreen.subjectFolder = 'folderName';
  initScreen(myscreen);

before running initScreen. This will make the dataDir:

  ~/data/taskprogramname/subjectId/subjectFolder

You can also load the latest stimfile from that directory (if you want to continue a staircase for example), by doing:

  s = getLastStimfile(myscreen);

====== Task log ======

If you would like to view the logs that are created, you can do:

  mglTaskLog

If you want a complete listing for the year 2014, do:

  mglTaskLog(2014,true);