nutmeg:TFBF
From NITRC Wiki
Contents |
Generating NUTMEG session file
See Getting started and lead field computation sections for help on this part. A separate session file needs to be created for every subject and every set of data you are putting together.
Running in Matlab using non-compiled code
GUI method
- The easiest way is to use the GUI via "Source Analysis: Time-Freq" button, or type nut_tfbf_gui.
- Set the time windows, filter, and inverse solution parameters. Remember to save the parameters to a file each time you make changes in the GUI, otherwise they will not be taken into account!
Time Window Setup
- You only need to create time window parameters once for each study, and can then apply them to all your subjects.
- Create the time windows of duration in mind for which frequency band you plan to apply to. Create a window 2-4 times as long as the period of the lowest frequency in your bandpass. For example, for a 25-50Hz band, the period of 25Hz is 40ms, so use a window between 80-160ms. However, for theta band 4-8Hz, the period of 4Hz is 250ms, so use a window between 500-1000ms long.
- You can use different time window durations for different frequency bands, but then you have to adjust start and end times. To do the adjustment automatically, you can use the command line function nut_constructTFBFparams, and load the created time window files in the GUI.
- It's better to leave off some edges of the data not included in either active or control periods, as all frequency filters are imperfect and will have some artificial ringing effects at the edges of each trial.
Filtering parameters
- You may use example filter setup files in */nutmeg/tfbf/params, or create new files.
- The choice of the filter class depends on your data. For short trials, it may be better to use IIR filters such as Butterworth or Elliptoid. For very narrow bandpass filters, it may be preferable to use a firls filter. In any case, you should check the effect of you filter by plotting some channels and trials of the filtered data.
- If you are unsure which filter order to use, just set to "auto".
Inverse solution parameters
- You may use example filter setup files in */nutmeg/tfbf/params, or create new files.
- Output: For basic time-frequency power decompositions, you only need "Power". For connectivity maps, you additionally need the filtered data and weight matrices.
- Dual vs. single state: "dual state" uses a baseline window and calculates changes in active window relative to the baseline. "Single state" only uses active time windows (needed, e.g., for connectivity maps).
- The "send to qsub" option will only work if you are using Linux with direct access to a cluster. For command line usage of the cluster see below.
Frequency Bands
- Set the cutoffs of the frequency bands you want to analyze. For low- or highpass filtering, set one of the cutoff values to 0.
Run
- Click on "Run Current", or
- you can submit multiple frequency bands to a batch file and run them all with one click.
- Once the decomposition is done, you need to assemble the multiple output files of each time window and freq band to a single s_beamtf*.mat file, by clicking on the corresponding button.
View Results
- All s_beamtf*.mat files in the current working directory are listed in the box on the bottom right, and viewed by clicking on the "View" button.
- To start the statistics GUI, click on "Time-Frequency Statistics"
Command line method
- Have created the session file, filter setting file, and params file.
Time window setup on command line
- Create a new directory that will contain the study's time window parameters.
- Then, type:
cd your_directory_name % to see an extensive help text on creation of time window parameters: nut_constructTFBFparams % to create the parameter files: nut_constructTFBFparams(active start,active stop,windowsize,stepsize,control/baseline start, control stop) % example: nut_constructTFBFparams(0,6700,[100 150 200 300],50,7400,7500);
- You can make the time windows relative to CTF markers at a later step.
- See examples of the output in */nutmeg/tfbf/examples
Run TFBF
- Call tfbf to run the space-time-freq decomposition:
- the following are examples only! you should use the appropriate time-frequency windows for your study
tfbf('session.mat','300ms',8,12,'firlsbp200','SAMcn');
tfbf('session.mat','200ms',12,30,'firlsbp200','SAMcn');
tfbf('session.mat','150ms',30,45,'firlsbp200','SAMcn');
tfbf('session.mat','100ms',55,95,'firlsbp200','SAMcn');
tfbf('session.mat','100ms',105,145,'firlsbp200,'SAMcn');
tfbf('session.mat','100ms',155,195,'firlsbp200','SAMcn');
- then use nut_tfbf2timef to assemble multiple outputs to a single s_beamtf*.mat file, e.g.:
nut_tfbf2timef session_firls200_dsSAMcn SAM
Alternatively, if you wish to save intermediate outputs
Update 08/2010: Note that the tfbf function now allows saving intermediate outputs such as the filtered data and weight files. These functions may therefore not be necessary anymore.
- such as the data covariance windows per time-freq window
- this option is useful for debugging, but is slower and saves very large files (e.g. can generate over 200GB of saved files overnight depending on your dataset!)
- then do some modification of the following, using Time-Freq windows appropriate for your study:
nut_savefilternuts('session.mat',4,8,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',8,12,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',12,20,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',20,30,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',30,39,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',39,48,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',52,75,'firlsbp200cn.mat')
nut_savefilternuts('session.mat',75,98,'firlsbp200cn.mat')
%
nut_calltfcov('session.mat','1000ms',4,8,'firlsbp200cn.mat')
nut_calltfcov('session.mat','650ms',8,12,'firlsbp200cn.mat')
nut_calltfcov('session.mat','550ms',12,20,'firlsbp200cn.mat')
nut_calltfcov('session.mat','450ms',20,30,'firlsbp200cn.mat')
nut_calltfcov('session.mat','450ms',30,39,'firlsbp200cn.mat')
nut_calltfcov('session.mat','450ms',39,48,'firlsbp200cn.mat')
nut_calltfcov('session.mat','450ms',52,75,'firlsbp200cn.mat')
nut_calltfcov('session.mat','450ms',75,98,'firlsbp200cn.mat')
%
for jj=1:size(freq,1);
nut_calltfrun('session.mat',[num2str(windur(jj)) 'ms'],freq(jj,1),freq(jj,2),'../firlsbp200cn.mat',covfile_usechar{jj});
end
%
nut_tfbf2timef('session_firlsbp200cn','SAM')
ELSE Running on computing grid using compiled code
Prerequisites
- You need access to a Linux cluster.
- UCSF users: you submit a request here. For large batch jobs, consider the QB3 cluster instead -- it has about 1000 CPUs available. Contact Joshua Baker-LePain <jlb -at- salilab.org> for an account. It requires a bit more fiddling to transfer files back and forth, though.
Time-Frequency Paradigm Setup
- In many instances, you can simply use the default settings.
- If you need to adjust the time-frequency settings, you only need to do it once and can then apply the settings to all subjects of your study.
- To change the settings, type on the Linux command line:
edit /data/research_meg/tfbf/bin/qTFBF.csh
and edit the file according to your frequency bands of interest and active/control window settings. In the near future, we will try to make this more intuitive. For now, ask one of the lab members if you need help. Save the modified file somewhere near your data. DO NOT OVERWRITE THE ORIGINAL FILE!
gedit /data/research_meg/tfbf/bin/qTFBF
change -t 1-8 to -t 1-number_of_frequencybands_in_your_study and qTFBF.csh to ./qTFBF.csh . Save the modified file in the same directory as the modified qTFBF.csh file.
chmod +x directory_containing_modifiedfiles/qTFBF
Apply Time-Window Parameters and Time-Frequency Settings to Current Subject
- On the Linux command line, type:
cd directory_containing_sessionfile ln -s directory_containing_timewindowparameterfiles/*ms.mat . ln -s directory_containing_yourtimefrequencysettings/qTFBF* . % (only if you have modified the qTFBF* files) ln -s /data/research_meg/tfbf/bin/MatlabSetup.csh .
Set up and run qsub jobs
- You will be generating hundreds of output files per session file, so it is recommended to place your nutmeg session files in separate directories. In each of these directories, create a subdirectory qlogs to hold the log files that will be generated. If anything weird happens, these log files will give you all sorts of clues.
- Make sure your paths are set up correctly, and that you have the necessary files in your data directory, which is the same directory where you placed your nutmeg session file.
- The following should be in your linux (.cshrc) path, which goes in /home/youraccount/.cshrc:
- /data/research_meg/tfbf/bin and /data/research_meg/tfbf/bin/i686
- (This is separate from the Matlab path). Ask for help if you don't know how to do this. When you type which tfcov you should get /data/research_meg/tfbf/bin/i686/tfcov.
- The following files should be in your data directory (where the mat session file is): parameter files (100ms.mat etc.), MatlabSetup.csh, optionally your modified qTFBF and qTFBF.csh.
- The following should be in your linux (.cshrc) path, which goes in /home/youraccount/.cshrc:
- Then, on a command line of a shell terminal, run:
qTFBF sessionfile % (using default settings of 4th order butterworth and SAM beamformer) or qTFBF sessionfile filterparamfile reconparamfile algo % for custom settings. For example, qTFBF sessionfile firlsbp200 bf SAM % this is one Sarang and Johanna like to use.
- You can type qstat -u yourusername to see how your jobs are doing. qw means your jobs are waiting in line, r means they're running, E usually means the job failed due to some random network problem. If your jobs are no longer listed, then they have finished running. (They may still have encountered an error though... if you don't see the output files you expect, check out the qlogs.)
- Once your jobs are done, you need to assemble the hundreds of output files into one conglomerate file. In Matlab:
nut_tfbf2timef sessionfile_firlsbp200cn SAM
- Alternatively, to batch with qsub from the linux command line:
qmaketf sessionfile_firlsbp200cn SAM
- This will generate s_beamtf_sessionfile_firlsbp200cn_SAM_all.mat -- if this file is successfully created, delete the original output files:
rm s_beamtf*SAM.mat
Remarks for CTF MEG systems
- The time-frequency beamformer can now read 3rd gradient corrections.
- Note that NUTMEG does not currently skip trials or channels marked as "bad" in CTF software -- however, if a new version of the dataset is created via DataEditor or newDs, these are removed by default
- Generate the multisphere head model for each dataset:
localSpheres -s /data/research_meg/mr/LastnameFirstname/LastnameFirstname_mri/LastnameFirstname.shape -d Dataset.ds
- If this is a brand new subject, .shape file may not exist. This needs to be created with MRIViewer... ask Anne or Susanne for assistance if you don't know how to do this. You will also need to generate an Analyze/SPM format MRI (.hdr/.img pair) from the raw scanner format for use with SPM and NUTMEG later... this can be done with MRIcro (type startmricro on the command line) using the Convert foreign to Analyze... option; usually, you will want to select "flip left/right" in the conversion box.
