README for patientDatabaseManager software suite
(c) Emily Mankin, 2015
Additional code provided by Natalia Tchemodonav, Uri Maoz, and Ali Titiz
This software is designed for managing information flow from collecting data through processing it into a format in which relevant information is segmented into individual trials. It was written for use by the Itzhak Fried lab at UCLA, however with minor modifications, it could be extended to more general use.
To date, this code has been tested on on a MacBook Pro Retina, running OS X Yosemite, with Matlab version 2014b. Many features are still being implemented. Bug reports and feature requests may be submitted to Emily Mankin: emankin@g.ucla.edu.
TO ENTER DATA INTO A DATABASE:
Run patientDataManager. You will first be prompted to locate several directories. If you keep files of the different types in the same location, simply select the same directory for each. Please note, the PATIENT_DATABASE directory should be kept separate from other directories. The locations of the directories will be written to a file in the same location as the patientDataManager code, so if different users have different paths to the same data files, it is important that each user keep a local copy of the patientDataManager code.
You will be prompted for the following directories:
* pathToHoffmanDataFolder: this should be the base folder in which your data generally is stored. We have several subdirectories of this, but this is the starting point from which other subdirectories will be searched.
* rawDataPath: the location where raw data is expected to be stored.
* processedPath: the location where processed data should be stored.
* databasePath: the location where the patient database is stored.
To add a patient to the database, select “Enter or update patient information,” then fill in appropriate information, including electrode location.
For each experiment run, please add a session. You may do this by selecting “Add or update session for existing patient” from the patientDataManager menu, or you may run the following code from the command line:
>> patientDataManager_updateOrAddSession(patientNumber, sessionNumber)
On the left hand side of the updateOrAddSession panel, meta-data about the session should be entered. On the right hand side, each button is used for an analysis step. It is generally best to go top to bottom, on the left column, then the right column, then click the wide buttons at the bottom, however some flexibility is possible. The function of each button is described in that order:
Link to Raw Neural Data: Select the location of the raw file that is associated to this session.
Unpack Raw Data: This will call code that will convert the raw data into data that is readable by Matlab, including continuous recordings from each channel (CSC) and spikes. It will also launch automated-clustering of spikes for use with wave_clus spike sorting. Running this is generally a long process, and you may prefer to run it from a detachable Unix screen. To do so, launch matlab without JVM and run the following line from the command line (where sourcePath is the path to the raw neural data and destinationPath is the folder where you would like the resulting files saved). Afterward, click on “Unpack Raw Data” to link to the processed files.
>> batchProcessAll(sourcePath,destinationPath);
Launch Spike Sorting: this will launch wave_clus to allow you to do supervised spike sorting.
Verify Spike Sorting: Click on this button after you have done spike sorting. If you don’t want to sort all channels before continuing, you can uncheck electrodes from the left hand side of the panel prior to selecting this button, and it will only show you spikes from the checked channels. This allows you to double-check your spike sorting, classify each unit sorted in wave_clus as a single unit or multi-unit, and keep track of which channels have been verified. No spiking data from wave_clus will be included in analysis if it has not been verified through this step.
Filter LFP Data: As for Verify Spike Sorting, this button will do filtering on only the channels that are checked on the left hand side of the panel.
Paradigm-Specific Parameters: Based on the task name selected on the left hand side of the panel, this will ask questions that are necessary for parsing data from that paradigm. (Currently, only ObjectRecognition and Unity have been written.)
Stimulation Parameters: Click on this button to enter stimulation parameters, even if no stimulation was performed. You may choose “none” as stimulation type and leave the remainder of the questions blank.
Process and Verify TTLs: This will open the event file that corresponds to the raw data file, and process it according to the paradigm name selected on the left hand side of the panel. (Currently, only ObjectRecognition and Unity have been written.)
Select Trials to Exclude: If you have a reason to exclude certain trials or an entire experiment (e.g. because it was a practice experiment or because the patient fell asleep during the last 3 trials), you may enter that information on this panel. Please click on this button, even if you have no files to exclude. (If you had many trials in an experiment, the text may be quite small. The “submit” button is on the bottom, right.
Segment LFP into Trials for Selected Channels: Prior to clicking this button, be sure that the “Filter LFP Data” button is green. That will indicate that all channels that are currently checked have been filtered. All buttons on the far right column related to trial parsing must also be green. Now, click this button and it will split LFP data from the checked channels into a trial-by-trial data structure.
Segment Spiking into Trials for Selected Channels: Similarly, make sure that the “Verify Spike Sorting” button is green, and then click this button to segment spiking data into a trial-by-trial data structure.
All buttons should be green now — you’ve finished processing data for this session. You can move to the next or previous trial with the < and > buttons.
Please note that “Overwrite Previous” is currently not implemented.
EXTRACTING DATA FROM THE DATABASE
No GUI has been created yet, however data can be extracted using the function getTrialByTrialData. Here is the syntax:
[lfp,units,trialMetaData,channelMetaData,unitMetaData] = …
getTrialByTrialData(patient,paradigm,trialCharacteristics,…
channelCharacteristics,unitCharacteristics,timestampsAlignedTo,…
lfpBandsToLoad,includeExcludedTrials)
patient should be a single numeric value, the number of the patient whose data you want to extract
paradigm should be a single string, the name of the paradigm you want to analyze. This must correspond to the strings available on the drop-down menu of patientDataManager_AddOrUpdateSession.
trialCharacteristics select which subsets of trials should be returned. It should be a cell array of fieldname-value or fieldname-criterion pairs. If you enter a single value, trials whose value in ‘fieldname’ equals the value entered will be returned. For more sophisticated queries, you may enter an anonymous function of a single variable that evaluates to a logical. If running ‘filename’’s value through the anonymous function returns a value of true, that trial will be included. If you input multiple pairs, all criteria must evaluate to true to be included.
* note: The available fieldnames differ depending on the paradigm run. You may run getFieldNameChoices(paradigmName) to find out what your choices are.
channelCharacteristics select which channels’ data should be returned. The format is the same as trialCharacteristics. Currently the fieldnames available include ‘channel’, ‘electrodeNumber’, and ‘brainRegion’, though more filenames are expected soon.
unitCharacteristics select which unit data should be returned. The format is the same as trialCharacteristics. Available filenames include ‘channel’, ‘unit’, ‘electrodeNumber’, ‘brainRegion’,’classification’, and ‘notes.’
timestampsAlignedTo allows you to select a point within each trial to set as time 0. Choices are dependent on the filenames from trialCharacteristics. Typically ‘trialStartTime’, ’trialEndTime’, ’stimulusOnsetTime’, ’stimulusOffsetTime’, ‘stimulationOnsetTime’, and ‘stimulationOffsetTime’ are available. You may also select ‘none’ if you want actual time stamps.
lfpBandsToLoad is optional. List the names of the LFP bands you want. If you don’t enter anything, the bands returned by default are lfp (which is filtered to 1-300 Hz) and theta (which is filtered to 3-8 Hz).
includeExcludedTrials is optional. Its default value is 0. By default, trials that were excluded in the excludeTrials step will never be returned. If you have a reason why you want to see excluded trials, you may set this to 1.
The output arguments will be structures whose field names are experiment numbers corresponding to experiments from the paradigm requested. Within each experiment, there will be a struct whose field names are the relevant variables. The size of these fields will be nTrials-by-nChannels or nTrials-by-nUnits for lfp and units. MetaData will be corresponding sizes (nTrials-by-one, one-by-nChnnels, one-by-nUnits).