NUTMEG's Time-frequency Beamformer

From NUTMEGwiki

Jump to: navigation, search

Contents

Preprocessing (CTF Software)

  • 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
  • Try to remove any intermediate datasets you create in this process to save disk space.
  • 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.

Generating NUTMEG session file

This is done once for every set of data you are putting together. That could mean per dataset, or could mean per stimulus type within a dataset.

See Getting started and lead field computation sections for more info. Be sure to run nut_liposession (described in lead field section).

Time Window Setup (in Matlab)

  • 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.
  • Remember 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.
  • EITHER call nut_tfbf_gui, and create the time windows within the portion near the top of the GUI
  • OR
    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

Filtering and other parameters

  • May use example filter and parameter setup files in */nutmeg/tfbf/params, or create new via the nut_tfbf_GUI

Prerequisites for UCSF users

  • Account for BIL linux workstations
  • Permission to run HPC grid (qsub) jobs. Submit request here.
  • For large batch jobs, consider the QB3 cluster instead -- it has about 1000 CPUs available. Contact Jeff Block (jeff.block -at- radiology.ucsf.edu) for an account. It requires a bit more fiddling to transfer files back and forth, though.
  • Fresh copy of NUTMEG and SPM2 (or soon SPM8 ok too)


IF Running on computing grid using compiled code

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.
  • 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

ELSE if running in Matlab using non-compiled code

  • Have created session.mat, timewindow files (i.e. 200ms.mat), and params file (i.e. firlsbp200cn.mat), and session_Lp.mat

IF you wish to go straight from session.mat to output files per TF window

  • then call tfcov, followed by nut_tfbf2timef
  • the following are examples only! you should use the appropriate time-frequency windows for your study 
tfcov('session.mat','300ms.mat',8,12,'firlsbp200cn.mat',{'SAM'});
tfcov('session.mat','200ms.mat',12,30,'firlsbp200cn.mat',{'SAM'});
tfcov('session.mat','150ms.mat',30,45,'firlsbp200cn.mat',{'SAM'});
tfcov('session.mat','100ms.mat',55,95,'firlsbp200cn.mat',{'SAM'});
tfcov('session.mat','100ms.mat',105,145,'firlsbp200cn.mat',{'SAM'});
tfcov('session.mat','100ms.mat',155,195,'firlsbp200cn.mat',{'SAM'});
%
nut_tfbf2timef session_firlsbp200cn SAM

ELSE if you wish to save intermediate outputs

  • such as saving the frequency filtered data, or 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')
Retrieved from "http://nutmeg.berkeley.edu/index.php?title=NUTMEG%27s_Time-frequency_Beamformer"