Description of ensemble_fmri

0001 function outdata = ensemble_fmri_ica(indata,defs)
0002 
0003 % performs individual independent component analyses on given 4D volumes
0004 %
0005 % CURRENTLY only uses FSL's Melodic
0006 % CURRENTLY expects 4D nifti volumes
0007 % CURRENTLY runs separate ICA on each 4D volume provided ...
0008 % CURRENTLY looks for hires data, otherwise uses MNI 152 as background img
0009 %
0010 % REQUIRES
0011 %   epi data - 4D nifti files - it will iterate over each 4D nifti file
0012 %       given, and perform ICA analyses on each file
0013 %   path data
0014 %
0015 %   defs.filt - filter criteria applied to epi data
0016 %   defs.ica.NDIMS - number of IC dimensions to retain, 0 = default melodic
0017 %       estimation
0018 %   defs.ica.BGTHRESH
0019 %   defs.ica.MMTHRESH
0020 %   defs.ica.TR
0021 %   defs.ica.melodic_params - extra parameters t pass to melodic
0022 %       default: --nobet --Ostats
0023 %
0024 % output directories:
0025 %   if a given 4D volume has
0026 %
0027 % 2009.03.05 FB
0028 
0029 global defaults r
0030 VERBOSE = 1;
0031 
0032 outdata = ensemble_init_data_struct();
0033 outdata.type = 'ica';
0034 
0035 r = init_results_struct;
0036 
0037 r.type = 'fmri_ica';  % Identify the type of this reporting instance
0038 r.report_on_fly = 1;
0039 
0040 dstr = datestr(now(),30);
0041 
0042 % Parse out the input data
0043 for idata = 1:length(indata)
0044   if isfield(indata{idata},'type')
0045     switch indata{idata}.type
0046       case {'epi','realign_epi'}
0047         epidata = indata{idata};
0048         epicol = set_var_col_const(epidata.vars);
0049       case {'paths'}
0050         pathdata = indata{idata};
0051         pcol = set_var_col_const(pathdata.vars);
0052       case 'hires'
0053         hires = indata{idata};
0054         hicol = set_var_col_const(hires.vars);
0055       case 'coplanar'
0056         coplanar = indata{idata};
0057         cocol = set_var_col_const(coplanar.vars);
0058     end
0059   end
0060 end
0061 
0062 % check for required vars
0063 check_vars = {'pathdata','epidata'};
0064 check_required_vars;
0065 
0066 % return an output directory for ensemble_jobman_parallel
0067 % for this function, it should be the analysis output directory
0068 if (iscell(indata) && ~isempty(indata) && isfield(indata{1},'task') && ...
0069         ~isempty(strmatch('return_outdir',indata{1}.task))) || ...
0070         (isstruct(indata) && isfield(indata,'task') && ...
0071         ~isempty(strmatch('return_outdir',indata.task)))
0072   if isfield(defs,'paths') && isfield(defs.paths,'analpath')
0073     outdata = defs.paths.analpath;
0074   end
0075   if ~exist('outdata','var') || ~exist(outdata,'dir'), outdata = ''; end
0076   return
0077 end
0078 
0079 % outdata
0080 outdata.vars = [outdata.vars 'ica_reports'];
0081 ica_idx = length(outdata.vars);
0082 outdata.data{ica_idx} = ensemble_init_data_struct();
0083 outdata.data{ica_idx}.type = 'ica_report';
0084 outdata.data{ica_idx}.vars = {'subject_id','session','ensemble_id',...
0085     'run','path'};
0086 outdata.data{ica_idx}.data{1} = {};
0087 outdata.data{ica_idx}.data{2} = [];
0088 outdata.data{ica_idx}.data{3} = [];
0089 outdata.data{ica_idx}.data{4} = [];
0090 outdata.data{ica_idx}.data{5} = {};
0091 
0092 % get flags
0093 try USE_SPM = defs.ica.USE_SPM; catch USE_SPM = 0; end
0094 try USE_FSL = defs.ica.USE_FSL; catch USE_FSL = 1; end
0095 try MMTHRESH = defs.ica.MMTHRESH; catch MMTHRESH = 1; end
0096 try NDIMS = defs.ica.NDIMS; catch NDIMS = 0; end
0097 try TR = defs.ica.TR; end
0098 if ~exist('TR','var')
0099   try TR = defs.fmri.protocol.epi.tr; catch error('must specify a TR'); end
0100 end
0101 try BGTHRESH = defs.ica.BGTHRESH; catch BGTHRESH = 1; end
0102 try melodic_params = defs.ica.melodic_params;
0103     catch melodic_params = '--nobet --Ostats';
0104 end
0105 
0106 if exist('hires','var')
0107   bgimage = hires.data{hicol.path}{1};
0108 elseif exist('coplanar','var')
0109   bgimage = coplanar.data{cocol.path}{1};
0110 end
0111 
0112 if exist('bgimage','var') && exist(bgimage,'file')
0113   msg = sprintf('using background image %s\n',bgimage);
0114   r = update_report(r,msg);
0115 else
0116   avgimage = fullfile(defs.fmri.spm.paths.canonical_dir,'avg152T1.nii');
0117   if ~exist(avgimage,'file')
0118     msg = sprintf(['background images %s and %s not found, no '...
0119         'background image is being used\n'],bgimage,avgimage);
0120     r = update_report(r,msg);
0121     bgimage = '';
0122   else
0123     bgimage = avgimage;
0124   end
0125 end
0126 
0127 if USE_SPM && ~USE_FSL
0128   error('SPM not supported yet ...\n');
0129 elseif ~USE_FSL && ~USE_SPM
0130   error(['\t\tyou must specify either SPM or FSL to carry out '...
0131       'the analyses\n']);
0132 end
0133 
0134 %
0135 % apply filtering criteria
0136 %
0137 
0138 if isfield(defs,'filt')
0139   epidata = ensemble_filter(epidata,defs.filt);
0140 end
0141 
0142 %
0143 % LOOP OVER IMAGES, estimate
0144 %
0145 
0146 nimg = length(epidata.data{epicol.path});
0147 opfilt.include.all.path_type = {'anal_outdir'};
0148 
0149 for ii=1:nimg
0150 
0151   % get path to image for estimation
0152   imgpath = epidata.data{epicol.path}{ii};
0153   [fp,fn,fx] = fileparts(imgpath);
0154   
0155   % get output path - try anal_outdir for subject/session from pathdata
0156   opfilt.include.all.subject_id = epidata.data{epicol.subject_id}(ii);
0157   opfilt.include.all.session    = epidata.data{epicol.session}(ii);
0158   opdata = ensemble_filter(pathdata,opfilt);
0159   
0160   if ~isempty(opdata.data{pcol.path}) && exist(opdata.data{pcol.path}{1},'dir')
0161     % 'anal_outdir/ica' for subject/session
0162     opath = fullfile(opdata.data{pcol.path}{1},'ica');
0163     check_dir(opath);
0164     opath = fullfile(opath,fn);
0165     check_dir(opath);
0166     opath = fullfile(opath,dstr);
0167     check_dir(opath);
0168   else
0169     % construct from defs.paths.outroot
0170     opath = defs.paths.outroot;
0171     check_dir(opath);
0172     if ~isempty(epidata.data{epicol.subject_id}{ii})
0173       % outroot/subject_id
0174       opath = fullfile(opath,epidata.data{epicol.subject_id}{ii});
0175       check_dir(opath);
0176       if ~isempty(epidata.data{epicol.session}(ii))
0177         % outroot/subject_id/sessionN
0178         opath = fullfile(opath,...
0179             sprintf('session%d',epidata.data{epicol.session}(ii)));
0180         check_dir(opath);
0181       end
0182       % add 'analyses'
0183       opath = fullfile('analyses');
0184       check_dir(opath);
0185     else
0186       % outroot/analyses
0187       opath = defs.paths.analpath;
0188       check_dir(opath);
0189     end
0190     % add 'ica/dstr'
0191     opath = fullfile(opath,'ica',dstr);
0192     check_dir(opath);
0193   end
0194   
0195   % run ICA analysis
0196   if exist(imgpath,'file') || exist([imgpath '.nii'],'file') || ...
0197           exist([imgpath '.nii.gz'],'file')
0198     mstr = sprintf(['melodic -i %s -o %s --bgthreshold=%d --tr=%1.1f '...
0199         '-d %d --mmthresh=%1.1f --report -v %s'],...
0200         imgpath,opath,BGTHRESH,TR,NDIMS,MMTHRESH,melodic_params);
0201     if ~isempty(bgimage)
0202       mstr = [mstr sprintf(' --bgimage %s',bgimage)];
0203     end
0204     msg = sprintf('executing: %s',mstr);
0205     r = update_report(r,msg);
0206     status = unix(mstr);
0207     if status
0208       warning('melodic failed to analyze %s:\n\t(%s)\n',imgpath,mstr);
0209     end
0210   else
0211     warning('%s not found, no ICA estimated\n',imgpath);
0212   end
0213   
0214 end
ensemble_fmri_ica

PURPOSE

SYNOPSIS

DESCRIPTION

CROSS-REFERENCE INFORMATION

SOURCE CODE
