3.05 with documenation

doc/index.html

@@ -4,16 +4,15 @@ MELODIC v3.0
 Multivariate Exploratory Linear Optimized Decomposition into Independent Components
 <TD ALIGN=RIGHT><a href="../index.html"><IMG BORDER=0 SRC="../images/fsl-logo.jpg"></a></TR></TABLE><HR>
 
+<IMG ALIGN=RIGHT hspace=20 vspace=20 width=90% SRC="tica_diag.png"
+ALT="Example GUI view">
+
 <H2>INTRODUCTION</H2>
  
-<P>MELODIC (Multivariate Exploratory Linear Optimized Decomposition
-into Independent Components) uses ICA (Independent Component Analysis)
-to decompose 4D data (for example FMRI data) into different
-interesting spatial and temporal components. It can pick out different
-activation and artefactual components without any model being
-specified. Thus the output is a new 4D data set (each volume being a
-separate spatial component) and a text file of separate time courses
-(temporal components).
+<P>MELODIC 3.0 uses Independent Component Analysis
+to decompose a single or multiple 4D data sets into different spatial and temporal components. For multiple input data sets, MELODIC uses either Tensorial Independent Component Analysis (TICA), where data is decomposed into 
+spatial maps, time courses and subject/session modes or a simpler temporal concatenation approach. MELODIC can pick out different
+activation and artefactual components without any explicit time series model being specified. 
 
 <P>For more detail on MELODIC and an updated journal reference, see
 the <A
@@ -23,35 +22,104 @@ quote the journal reference listed there.
 
 <p>The different MELODIC programs are:
 <UL>
-<LI><a href="#Melodic">Melodic</a> - MELODIC GUI<br>
+<LI><a href="#MelodicGUI">Melodic</a> - MELODIC GUI<br>
 <LI><a href="#melodic">melodic</a> - command-line MELODIC program<br>
+<LI><a href="#regfilt">fsl_regfilt</a> - command-line tool for removing regressors from data (melodic denoising)<br>
 </UL>
 
-<A NAME="Melodic"></A><hr><H2>Melodic GUI</H2>
+<A NAME="MelodicGUI"></A><hr><H2>Melodic GUI</H2>
+
+<IMG ALIGN=RIGHT hspace=20 vspace=20 SRC="gui.png"
+ALT="Example GUI view">
+
+<p>To call the MELODIC GUI, either type <b>Melodic</b> in a terminal
+  (type <b>Melodic_gui</b> on Mac or Windows), or
+  run <b>fsl</b> and press the <b>MELODIC</b> button.
+
+<p>Before calling the GUI, you need to prepare each session's
+data as a 4D NIFTI or Analyze format image; there are utilities in
+fsl/bin called <a href="../avwutils/index.html" target="_top">fslmerge
+and fslsplit</a> to convert between multiple 3D images and a single 4D
+(3D+time) image. 
+
+<p>Structural images for use as "highres" images in registration
+should normally be brain-extracted using <a href="../bet2/index.html"
+target="_top">BET</a>.
+
+<H2>GUI details</H2>
+Contents<br>
+<a href="#misc">Misc</a><br>
+<a href="#data">Data</a><br>
+<a href="#prestats">Pre-Stats</a><br>
+<a href="#reg">Registration</a><br>
+<a href="#stats">Stats</a><br>
+<a href="#poststats">Post-Stats</a><br>
+<a href="#buttons">Bottom Row of Buttons</a><br>
+
+<a name="misc"></a>
+<hr><H3>Misc</H3>
+
+<p><b>Balloon help</b> (the popup help messages in the MELODIC GUI) can
+be turned off once you are familiar with the GUI.
+
+<p>The <b>Progress watcher</b> button allows you to tell Melodic not to
+start a web browser to watch the analysis progress. If you are
+running lots of analyses you probably want to turn this off; you can
+view the same logging information by looking at the report_log.html or log.txt
+files in any MELODIC directories instead.
 
-<center><IMG SRC="./mel1.png" ALIGN=CENTER></center>
+<a name="data"></a>
+<hr><H3>Data</H3>
 
-<p>Press <code>Select 4D data</code> and select the input data.
+<p>First, set the filename of the 4D input image
+(e.g. <b>/users/sibelius/origfunc.nii.gz</b>) by pressing <b>Select 4D
+data</b>. You can select multiple files if you want MELODIC to perform a group analysis or if you want to run separate ICAs.
+Results for each input file will be saved in separate .ica directories, the name of which is based on the input data's filename (unless you enter an <b>Output directory</b> name). 
 
-<p><center><IMG SRC="./mel2.png" ALIGN=CENTER></center>
+<p><b>Delete volumes</b> controls the number of initial FMRI volumes
+to delete before any further processing. 
+
+<p><b>TR</b> controls the time (in seconds) between scanning
+successive FMRI volumes. Changes here will not affect the analysis and only change the x-axis units of the final time series plots.
+
+<p>The <b>High pass filter cutoff</b> controls the longest temporal
+period that you will allow. 
+
+<a name="prestats"></a>
+<hr><H3>Pre-Stats</H3>
 
 <p>Low-frequency drifts and motion in the data can adversely affect
 the decomposition. In most cases, you would want to motion-correct the
-data and remove these drifts first. This can be done from within the
+data, remove these drifts first or perform other types of typical data pre-processing before running the analysis. This can be done from within the
 Melodic GUI <code>Pre-stats</code> section.
 
-<center><IMG SRC="./mel3.png" ALIGN=CENTER></center>
+<a name="reg"></a>
+<hr><H3>Registration</H3>
+
+<p>Before any multi-session or multi-subject analyses can be carried
+out, the different sessions need to be registered to each other. This
+is made easy within MELODIC which performs registration on input data as part of an analysis using FEAT functionality. Unlike registration step in FEAT this here needs to be performed before the statistical analysis so that the filtered functional data is transformed into the standard space. For information on using multi-stage registration please consult the <a href="../feat5/detail.html#reg" target="_top">FEAT</a> manual.
 
-The MELODIC section finally lets you control some of the options for
-          the decomposition.
-The default setting will most probably already be set to what you
-          would want most of the time.
+<p><b>Standard space</b> refers to the standard (reference) image; it
+should be an image already in standard space, ideally with the
+non-brain structures already removed.
+
+<p><b>Resampling resolution (mm)</b> refers to the desired isotropic voxel dimension of the resampled data. In order to save on disk space and on required memory during the analysis it is advisable to resample the filtered data into standard space but keeping the resampled resolution at the FMRI resolution (typically 4mm or 5mm).
+
+<a name="stats"></a>
+<hr><H3>Stats</H3>
+
+<p>The Stats section lets you control some of the options for the decomposition. The default setting will most probably already be set to what you would want most of the time.
 
 <p> By default, Melodic will automatically estimate the number of
-          components from the data - you can switch this
-          option off and then can specify the number of
-          components explicitly.<p>
-Melodic will also by default carry out inference on the estimated maps
+ components from the data - you can switch this option off and then can specify the number of components explicitly.<p>
+
+<p> You can select the type of analysis. If only a single input name was specified MELODIC will perform a single session ICA analysis. 
+	
+<a name="poststats"></a>
+<hr><H3>Post-Stats</H3>
+
+<p> Melodic will also by default carry out inference on the estimated maps
           using the mixture model approach. A threshold level of 0.5
           in the case of alternative hypothesis testing means that a
           voxel 'survives' thresholding as soon as the probability
@@ -61,29 +129,77 @@ Melodic will also by default carry out inference on the estimated maps
           you are placing an equal loss on false-positives and
           false-negatives. If, however, you consider e.g. false-positives as
           being twice as bad as false-negatives you should change this value
-          to 0.66...<p>
-Now simply press &nbsp;<code>Go</code><p>
+          to 0.66...
+
+<p> You can select the image used for the generation of the spatial maps.
+	
+<p> If you select the <b>Output full stats folder</b> option, MELODIC will save thresholded maps and probability maps in a <code>/stats</code> subdirectory within its output folder.
+	
+	<p>You can specify a temporal design matrix and in the case of a group analysis also a session/subject design matrix as well as corresponding contrast matrices. If these matrices are set in the GUI, MELODIC will perform a post-hoc regression analysis on estimated time courses and session/subject modes. This can be a helpful tool in order to identify whether or not a given component is task related. The matrices themselves can be created easily using the <a href=../feat5/programs.html><b>Glm</b></a> GUI.
+
+	<a name="buttons"></a>
+	<hr><H3>Bottom Row of Buttons</H3>
+
+	<p>When you have finished setting up MELODIC, press <b>Go</b> to run the
+	analysis. Once MELODIC is running, you can either <b>Exit</b> the GUI, or
+	setup further analyses.
+
+	<p>The <b>Save</b> and <b>Load</b> buttons enable you to save and load
+	the complete MELODIC setup to and from file. 
+
+<a name="output"></a>
+<hr><H3>MELODIC output</H3>
 
 Melodic will then generate the results and 
 your terminal window will tell you where to find the web report. 
 
+Each IC_XX.html webpage shows one spatial map thresholded and rendered on top of a background image
+followed by the relevant time-course of the ICA decomposition and the power-spectrum of the time-course. 
+
+<p> If you click on the thresholded map, you can inspect the raw IC output together with probability maps and the Mixture Model fit. 
+
 
+<p>In the case of TICA or simple time series concatenation the time course plotted is the rank-1 approximation to all the different time courses that correspond to the given spatial map within the population. 
 
-Each webpage shows one spatial map thresholded and rendered on top of an example functional scan
-followed by the relevant time-course of the ICA decomposition and the
-            power-spectrum of the time-course. If you click on the
-            thresholded map, you can inspect the raw IC output
-            together with probability maps and the Mixture Model
-            fit. Use <code>previous</code> and <code>next</code> to
-            view another component map.<p>
+<p>If a temporal design was specified in the <a href="#poststats" target="_top">Post-Stats</a> section then the time series plot will also contain a plot of the total model fit. In addition, a simple GLM table will describe the fit in detail, providing information of the regression parameter estimates (PEs). Furthermore, MELODIC will perform a simple F-test on the estimated time course and the total model fit. For task related components the model fit will explain large amounts of the variaiton contained in the estimated time couse. In addition, if a contrast matrix was specified, the table will also contain Z-statistics and p-values for all the contrasts.
+
+If a group analysis was carried out then the report page will also include information on the distribution of the effect size across the population. A simple plot and a boxplot show the relative effect size across the different sessions/subjects. If a designmatrix was specified in the GUI setup then MELODIC will also include a GLM regression fit table.
 
 <A NAME="melodic"></A><HR><H2>melodic COMMAND-LINE PROGRAM</H2>
 
 <p>Type <b>melodic --help</b> to get usage.
   
+<A name="regfilt"></A><HR><H2>fsl_regfilt COMMAND-LINE PROGRAM</H2>
+
+<p>Running MELODIC can be a useful tool for gaining insight into unexpected artefacts or activation in your data.
+
+<p>As well as being a good way to find structured noise (or unexpected
+  activation) in your data, ICA can also be used to remove chosen
+  components (normally obvious scanner-related or physiological
+  artefacts) from your data in order, for example, in order to improve
+  the FEAT results. In order to do this:
+
+	<UL>
+
+	<LI> Run MELODIC single-session ICA on a 4D image file
+
+	<LI> Open the MELODIC report
+	  (<code>melodic_output_directory.ica/filtered_func_data.ica/report/00index.html</code>)
+	  in a web browser and look through the components to identify those
+	  that you wish to remove; record the list of component numbers to
+	  remove.
+
+	<LI> In a terminal, run the MELODIC denoising, using the
+	  commands:<pre>cd melodic_output_directory.ica
+	fsl_regfilt -i filtered_func_data -o denoised_data -d filtered_func_data.ica/melodic_mix --filter="2,5,9"</pre>
+	where you should replace the comma-separated list of component numbers with the list that you previously recorded when viewing the MELODIC report.<br>
+	</UL>
+	The output file <code> denoised_data.nii.gz</code> then contains the filtered and denoised data set which can be used e.g. within FEAT. When running FEAT on this data make sure that the analysis is set to <code>Stats + Post-stats </code> as you do not want to run the other filtering steps (smoothing etc.) again on this data.
+
 
-<p><HR><FONT SIZE=1>Copyright &copy; 2001-2002, University of
-Oxford. Written by C. Beckmann and <A
+<p><HR><FONT SIZE=1>Copyright &copy; 2001-2007, University of
+Oxford. Written by 	<A
+	HREF="http://www.fmrib.ox.ac.uk/~beckmann/">C.F. Beckmann </A> and <A
 HREF="http://www.fmrib.ox.ac.uk/~steve/index.html">S. Smith</A>.</FONT>
 
 <br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br>

melodic.h

@@ -40,7 +40,7 @@
 
 namespace Melodic{
 
-const string version = "3.04";  
+const string version = "3.05";  
 
 // The two strings below specify the title and example usage that is	
 // printed out as the help or usage message

melreport.cc

@@ -158,11 +158,11 @@ namespace Melodic{
 			 IChtml << "<img BORDER=0 SRC=\"" 
 	  	  +string("t")+num2str(cnum)+".png\"></A><p>" << endl;	
 	
-			if(melodat.get_numfiles()>1 && melodat.explained_var.Storage()>0 
-				&& melodat.explained_var.Ncols()>=cnum)
-				IChtml << "Rank-1 approximation of individual time courses explains " 
-				<< melodat.explained_var(cnum) << "% of variance.<p>" << endl;
-			}//time series plot
+	//		if(melodat.get_numfiles()>1 && melodat.explained_var.Storage()>0 
+	//			&& melodat.explained_var.Ncols()>=cnum)
+	//			IChtml << "Rank-1 approximation of individual time courses explains " 
+	//			<< melodat.explained_var(cnum) << "% of variance.<p>" << endl;
+	//		}//time series plot
 
 	 		if(!opts.pspec.value())
 	   	{//plot frequency