= Tutorial 11: Time-frequency =
This tutorial introduces how to compute the time-frequency decomposition of MEG recordings and cortical currents using Morlet wavelets. There are several ways to reachthe same result, please read all the sections carefully and then chose the method that is best suited for your own data.

<<TableOfContents(2)>>

== Introduction to Morlet wavelets ==
Dimitrios: Write your text here.

Can you also describe the two parameters, and the following screen capture ?

{{attachment:waveletOptions.gif}}

== Compute from recordings ==
 * We are going first to compute the time-frequency decomposition for the two averaged recordings we have in the protocol.
 * Drag'n'drop the two ERP files from !StimRightThumb and !StimLeftThumb in the "Processes" list, as explained in tutorial 9 (Processes). Select the "Recordings" button.<<BR>><<BR>> {{attachment:fileSelection.gif}}
 * Click on Run. Then select the process: Spectral analysis > Time-frequency decomposition.<<BR>><<BR>> {{attachment:processSelection.gif}}
 * You do not have anything else to configure here: we want to get the time-frequency decomposition for all the time points, and we do not want to save the output file in a specific condition. The only thing that you may do is add a comment to the file (text field in the top of the figure). Click on Run.<<BR>><<BR>> {{attachment:timeFreqOptionsBasic.gif}}
 * This option window allows you to configure the time and the frequency resolutions, the wavelets themselves, the sensors to process, and the type of output.

== Description of the options ==
 * '''Comment''': This is the string that will be displayed in the database explorer to represent the output file.
 * '''Time definition''':
  * This panel describes the time points for which you will get a value at the end of the computation.
  * '''Same as input file''': If you select this option, you would get the time-frequency decomposition (TF) for each of the time samples in the input file (here: 375 samples between -50ms to 250ms)
  * '''Group in time bands''': This option adds another step of computation:
   * 1) It first computes the TF for each of the time points in the initial file, excactly like with the "same as input file" option
   * 2) For each time band: it groups the corresponding time points by averaging the power of theire TF values.
  * Definition of the time bands: two methods
   * Enter your own time bands in the text area, one line per time band, with following forma: "name : start_time, stop_time"
   * Click on the "Generate" button to create automatically a list of time bands with the same length. You will be asked the maximal length of each time band.
 * '''Frequency definition''':
  * This panel describes the frequencies for which the power will be estimated at each time instant.
  * '''Linear''': You can specify the frequencies with any Matlab syntax start:step:stop. The default is "1:1:30", which produces 60 values [1, 2, 3, 4, ..., 59, 60]
  * '''Group in frequency bands''': As for the time definition, this option leads to a two-step process:
   * 1) It computes the TF for 4 frequencies for each frequency band. For example, the first default frequency band "delta: 2,4" would estimate the TF for the frequencies [2, 2.66, 3.33, 4]
   * 2) Then for each frequency band: it averages the power of the 4 frequencies, so that you get only one value for each frequency band (and for each time point and each sensor).
  * Definition of the frequency bands:
   * One line per frequency band, with the format "name : start_freq, stop_freq"
   * Click on the "Reset" button to go back to the default settings.
 * '''Morlet wavelet options''':
  * Describes one wavelet for a given frequency ("Central frequency" parameter).
  * This wavelet is then scaled for all the other frequencies requested in the "frquency definition" panel.
  * See the first section of this tutorial for a description of those parameters.
 * '''Processing options''':
  * '''Sensors to process''':
   * This is the list of the sensors for which the TF is going to be computed.
   * You can provide either sensor types (eg. EEG, MEG, MEG GRAD), or sensor names (eg. MLC15, MEG0121, EEG23)
  * '''Compute the following measure''':
   * The TF returns basically the wavelet coefficients for each frequency/time/sensor, which are complex values. Typically, what you want to display is the power of the coefficients, which is the square of the amplitude: abs(TF).^2. You can choose if you want to apply this transformation or not.
   * '''Power''': Applies the "power" transformation right after the computation. This induces a loss of the phase information.
   * '''None''': Save the TF coefficients as they are computed. This can be useful if you plan to use those decompositions for other purposes that requires the phase.
   * If you select "None" here, the power will be computed on the fly for the various displays.
   * Some combinations of options may disable this choice. Example: if you ask for time bands or frequency bands, the program will have to compute the power before averaging the values; so in those cases the "None" option is diabled.
  * '''Output''':
   * '''Save individual TF maps''': This option stops the computation here, and saves in the database one time-frequency file for each input file.
    * Be very careful using this option because if you have hundreds of trials, it will fill your hard drive very quickly.
    * One full TF file in this case contains [nSensors x nTime x nFreq] = 3.397.500 values = 25 Mb.
    * You can however limit the amount of data produced by using time and/or frequency bands. For 15 time bands and 6 frequency bands, the size of each file drops to: 110 Kb.
   * '''Save average TF maps''': This option is available only when there are more than one input files (number of files you dorpped in the Processes tab).
    * Instead of saving the TF for each file separately, it automatically computes the average of the power of all the TF.
    * This is a good choice if you do not plan to use independently all the TF files, because it saves a lot of time and disk space.

== Display of the time-frequency maps ==
 * Back to our evoked fields. Let's first keep all the default options for time, frequency and wavelet defintions.
 * Just change the '''Output '''option to '''Save individual TF maps'''.''' '''What we want is to compute two TF decompositions, one for the Left condition and one for the Right, not the average of the two.
 * Click on "Ok". After a while, two new files will appear in the tree, representing the TF for the two averaged recordings of the two conditions.
 * Right-click on the TF file of the !StimLeftThumb condition to see what are the possible display mode.<<BR>><<BR>> {{attachment:treePopupRecordings.gif}}

=== Time-frequency maps ===
 * This is the default view for the TF dcompositions of full recordings value, ie. what would be displayed if you double-click on this file. It represents shows for one sensors (or one cluster/scout/source) the power of each frequency at each time.
 * When you load some time-frequency information, the "Time-freq" tab automatically appears in the main Brainstorm window, to offer some options for the displays.<<BR>><<BR>> {{attachment:panelTimefreq.gif}} - {{attachment:timeFreqInit.gif}}

=== Time-frequency maps: "Time-freq" tab ===
 * '''Current frequency''': Slider that shows the current frequency selected in ALL the figures. <<BR>>Exactly as the time is Brainstorm, the frequency selection/display is centralized and managed by one control only for all the figures. As a consequence, it is impossible to display TF files with different frequency definitions at the same time. This can be perceived as an annoying limitation, but it allows all the simultaneous displays to be consistent at anytime, and make the interface much more intuitive to manipulate, with lower risks of mistakes in the interpretation of the different figures.
 * '''List of sensors''': This controls shows what is displayed in the selected figure. Try to change it, it will update the display of the figure, showing the frequency powers for another sensor.<<BR>>Warning: this selection is relative only to the selected figure, and gets updated when you selected another TF figure. <<BR>><<BR>> {{attachment:timeFreqSensor2.gif}} - {{attachment:timeFreqSensor3.gif}}
 * '''Display square root of power''': This is a global setting that is applied to all the figures when selected, and saved from one session to another.<<BR>>When unchecked (left fig): displays the power for each time/frequency, as described previously.<<BR>>When checked (right fig): displays the square root of the power; it produces displays with much less contrast between the high and low values, allowing to see better what is happening in the high frequencies.<<BR>><<BR>> {{attachment:timeFreqPower.gif}} -  {{attachment:timeFreqSqrt.gif}}

=== Time-frequency maps: Mouse and keyboard ===
 * '''Left-click''': Selection of current time and frequency.
  * If you click anywhere on a TF figure, it will move the current time/frequency cursor to the clicked point, update the Time and the Frequency sliders in the Brainstorm window, and also update all the other visualization figures.
  * If you change the current time or the current frequency with the sliders or with another figure, you would observe that the time/frequency cursor position is updated.
 * '''Left-click + move''': Select a time/frequency range.
  * Hold the left mouse button and move the mouse to mark a selection in both time and frequency. The legends of the X and Y axis are updated to display the selected time and frequency ranges selected.<<BR>><<BR>> {{attachment:timefreqSelection.gif}}
  * This selection is used by some functions accessible in the figure's popup menu.
 * '''Zoom''':
  * '''Mouse wheel''': Zoom/unzoom in time, centered on the current time cursor.
  * '''Control + mouse wheel''': Zoom/unzoom in frequencies, centered on the current frequency cursor.
  * '''Right-click + move''', or Control + left-click + move: Move in the zoomed image.
  * '''Double-click''': Restore initial view.<<BR>><<BR>> {{attachment:timeFreqZoom.gif}}
 * '''Colormap''':
  * As explained in the previous tutorials, you can change the colormap by left-clicking on the colorbar on the right of the figure, holding the button, and then by moving the mouse.
  * Up/down: Changes the brightness of the colormap.
  * Left/Right: Changes the contrast.
  * This has the same effect than changing the brightness/contrast using the popup menu.<<BR>><<BR>> {{attachment:timeFreqColormap1.gif}} - {{attachment:timeFreqColormap2.gif}}
 * '''Popup menu''': Right-click on the figure.<<BR>><<BR>> {{attachment:figurePopup.gif}}
  * All the menus have been described in the [[Tutorials/TutExploreRecodings|tutorial  #4 "Exploring the recordings"]], except the "Time-frequency selection  menu":
  * '''Set selection  manually''': Does the same thing as  drawing a time/freq selection square on a figure, but by typing the  values for time and frequency manually.
  * '''Export to  database''': Save the selection for the displayed sensor in a new  TF file in the database. However, it is  necessary to keep the same time definition for this new file because as  it has to stay compatible with the other files it is linked with (here:  the recordings file). So in this case, only the selected frequencies are  saved, but the time selection is ignored, all the time points are  saved. <<BR>>Remember that only one sensor is exported using  this menu, all the others are ignored.
  * '''Export to file''':  Same as "Export to database", but the saved file is not registered in  the database. The user has to select where to save the file.  <<BR>>The database time constrains do not apply here, so the  ONLY the selected time points are exported.
  * '''Export to Matlab''':  Same as "Export to file", but the output structure is sent to a  variable in the Matlab base workspace instead of being saved to a file.
 * '''Keyboard shortcuts''':
  * '''Left and right arrows''': Change the current time
  * '''Page-up and page-down''': Also change the current time, but faster (10 time samples instead of one)
  * '''Up and down arrows''': Change the the sensor displayed in this figure (same as using the drop-list in the Time-freq tab)
  * '''Control + up and down arrows''': Change the current frequency
  * '''Control + R''': View the original MEG recordings (this shortcut and the following are visible in the popup menu)
  * '''Control + T''': View the time-frequency 2D topography (explained in the next sections)
  * '''Control + I''': Save as image
  * '''Control + D''': Dock figure in the Matlab environment.

=== Time-frequency maps (all the sensors) ===
 * Right-click on the TF file in condition  !StimLeftThumb and select: "Time-frequency maps (all  sensors)". This is a spatial view of the TF maps  for all  the sensors. This is not a very interactive display: all what you can do  is making it bigger and changing the  colormap.<<BR>><<BR>> {{attachment:timeFreqAllSensors.gif}}

=== Time-frequency 2D topography ===
 * Right-click on the TF file in condition  !StimLeftThumb and select successively the first three menus in "MEG":  3D Sensor cap, 2D Sensor  cap, 2D Disc.<<BR>><<BR>> {{attachment:topo3DSensorCap.gif}} {{attachment:topo2DSensorCap.gif}} {{attachment:topo2DDisc.gif}}

 * All  those three windows represent the same information, in a  slightly different way: a spatial map of the power of the current  frequency, for all the sensors at the current time.
 * Try to  move the time and frequency sliders and see what happens.
 * '''Keyboard shortcuts''':
  * '''Left  and right arrows''': Change the current time
  * '''Page-up and page-down''': Also change the current time, but  faster  (10 time samples instead of one)
  * '''Up and down arrows''':  Change the current frequency
  * '''Control  + E''': Display the  sensors markers
  * '''Control  + E again''': Display  the sensors names
  * All the other shortcuts and the popup  menu are already described  in [[Tutorials/TutExploreRecodings|tutorial   #4 "Exploring the recordings"]].
 * Display the sensors  (Control + E)
 * '''Shift  + Click on a sensor''':  Displays the time-frequency decomposition for that specific  sensors.<<BR>><<BR>> {{attachment:topoSelectSensor.gif}} {{attachment:topoSelectSensorTf.gif}}

=== Time-frequency 2D Layout ===
 * The last display mode available for those TF decomposition of recordings is this "2D Layout" menu. Right-click on the TF file for the Left condition and select MEG > 2D Layout.
 * This represents spatially the power of the current frequency for all the sensors and all the time points. Try to move the current frequency slider to see how the display changes when increasing the frequency. It is a good example to show that the time resolution increase with the frequency. Below: the "2D Layout" displays for f=8Hz and f=60Hz.<<BR>><<BR>> {{attachment:topo2DLayout1.gif}} {{attachment:topo2DLayout2.gif}}
 * Useful operations for this window:
  * '''Mouse wheel''': Zoom / unzoom
  * '''Left+right click + move''': Move into the window
  * '''Control + E''': Display the channels names
  * All the other shortcuts and the popup  menu are already described  in [[Tutorials/TutExploreRecodings|tutorial   #4  "Exploring the recordings"]].

== What's in those "timefreq" files ==
 * Right click one of the TF files, and select the menu File > View .mat file, to have a look to what is the actual contents of those structures.<<BR>><<BR>> {{attachment:viewMatFile.gif}}
 * '''TF''': [nSensors x nTime x nFrequency] matrix containing all the values of the time-frequency decomposition (complex wavelet coefficients, or power of amplitudes)
  * nSensors: Number of sensors for which the TF has been estimated
  * nTime:
   * If there are time bands defined, nTime = size(!TimeBands,1) = number of time bands
   * If there are no time bands (linear time sampling): nTime = length(Time)
  * nFrequency:
   * If there are frequency bands defined, nFrequency = size(Freqs,1) = number of frequency bands
   * If there are no frequency bands (linear frequency sampling): nFrequency = length(Freqs
 * '''Comment''': String displayed in the database explorer to represent the file.
 * '''!DataType''': Explains from what kind of data this file was computed. Possible values are: 'data', 'results', 'cluster', 'scout'
 * '''Time''': Time vector used to estimate this file.
 * '''!TimeBands''': Description of the time bands. Cell array {nTimeBands x 3}, where each line represents a time band {'band_name', time_start, time_stop}
 * '''Freqs''':
  * If frequecy bands: Cell array {nFreqBands x 3}, where each line represents a frequency band  {'band_name', freq_start, freq_stop}
  * In linear frequency sampling: vector containing all the frequencies
 * '''!RowNames''': Cell array of strings that describes each line of the TF matrix. In this specific case, it would be the list of all the MEG sensor names. But it could also be a list of names of scouts or clusters.
 * '''Measure''': Contains the name of the function that was applied right after the computation of the wavelet coefficients. So it represents the type of data contained in the TF matrix. Possible values:
  * Empty matrix: No measure applied, TF contains the complex wavelet coefficients.
  * 'Power': TF contains the power for each frequency, ie. the square of the amplitude: abs(coefficients).^2
 * '''!DataFile''': Initial file from which this file was computed. In the database explorer, the TF file will be shown as a child of this !DataFile file.
 * '''!ChannelFlag''': Good/bad channel vector of the recordings file at the time the TF file was computed
 * '''nAvg''': Number of trials that were averaged to obtain this file (copied from the recordings file at computation)

== Time and frequency bands ==
== Time-frequency on  clusters time series ==
== Time-frequency on sources ==
== Time-frequency  on scouts time series ==
== Shortcut using the database explorer ==
== Processing time-frequency files with the Processes panel ==
== Next ==
This is the last tutorial for Brainstorm  introduction. You had an overview of most of the software features.

Now you can go back to the main [[Tutorials]] page, and read tutorials that are closer to your centers of interest.