Users Guide: (Hemodynamic Evoked Response)

Transcription

1 Users Guide: (Hemodynamic Evoked Response) Developed by T. Huppert and D. Boas A.A. Martinos Center for Neurological Imaging Massachusetts General Hospital. Charlestown, MA Copyright 2003 MGH Questions or Comments: contact T. Huppert (thuppert@nmr.mgh.harvard.edu) Introduction to program: HomER is a data analysis program written by the PMI lab at MGH for the purpose of quick, reliable, and user-friendly analysis of near-infrared spectroscopy. Currently, HOMer supports the continious wave measurements, but both frequency domain and time-domain data can also be made to display and analyze with HomER. The features of this program are organized into several tab-style display windows. This structure is easily expandable for future versions released by us, or custom writen by the user. For programming tips, see the accompanied Intro-to-programming script. Additionally, comments and suggestions are always welcome and should be sent to T. Huppert (thuppert@nmr.mgh.harvard.edu). Data Format: A sample data file (FakeData.mat) is included in the download of this program. The structure of each data file has a mimimum of 4 basic (required) fields. ml - The measurement list. This variable serves to map the data arrays onto the probe geometry. This variable has the structure: [source position, detector position, frequency, wavelength index] ie. [ ] would imply that the data referenced by this row is for the 2 nd source/optode position (not to be confused with laser #2- source positions refer to the probe geometry), the 3 rd detector position, the freq index of 1 indicates that this is a CW measurement, and the Lambda index of 1 indicates that this is the wavelength listed in the SD.lambda variable in the first position. The SD.lambda variable is specifed in the first line of the probe geometry (i.e. SD.Lambda = [ ]; ). The ML serves to map the d array (see below) onto the probe geometry. For example, when the probe geometry plot is highlighted between src #2 and det #3, then HOMer searches the ML for the row indexed as [2 3 <> <>] and plots that data. Each src-det pair must be represented for each wavelength. Additionally, the structure of ML should appear with all the lamdaindex=1 values listed first, followed by lambda=2, etc (more then 2 wavelengths are supported).

2 d - The actual data variable. This variable has dimensions of [number measurements by- number time pts]. Rows in d are mapped by the measurement list. For example, the 5 th row of the ML should describe the 5 th row of d (etc) t- The time variable. This maps the aquisition time to index of the measurment (i.e. the slop of this variable is the aquisition frequency). This will almost always be a straight line with slope equal to the acquisition frequency. s- The stimulus variable. This variable is used to determine the impulse train for averaging. aux10- (optional) This variable specifies the recorded auxillary data. This variable is optional. Although, SPM and other physiology features will not be allowed if this variable is not present Loading New Data: New data sets should be loaded by clicking on the pull-down menu under HOMER and clicking on Open SDG. This will bring up a pop-up menu prompting for subject number (leaving this field empty will save the subject as anoynomus ) For loading the sample data, click on the SampleProbe.m file. This will load the image of the probe into the figure on the top right of HOMER. The next step is to load the data sets. To do this, click on the Open Data File option on the same pull-down menu. This will again bring up the matlab uigetfile menu. Click on the file you wish to add. (For example, click on FakeData.mat to load the sample data set). To open more then one file simply repeat this step. An unlimited number of data files may be opened for each subject- however, too many files (or really large files) will be slow in matlab. Once the data file is opened, clicking around on the SD-geometry plot will change the display of the main plot. Loading Saved Data: To load previously saved data, click on the pull-down menu FILE then select Load Subject and Load Subject (again). This will load the SDG and any files that were previously saved (including any data anaylsis done).

3 Adding More Subjects: HomER allows the analysis of more then one subject. Subjects may have different file sizes, different stimulus type, and even different geometry files (probes). For example, you can load the data for a ipsolateral finger tapping experiment as one subject and a contralateral finger tapping as another. Multiple subjects can be averaged together (as a region of interest) to find group resonses. To add another subject or to remove a subject from the list, click on Load Subject>>Add or Remove Subject. This will prompt for the subject number/name and create a new subject field. To toggle between subjects, use the pop-up menu on the bottom left of the screen (upper right in multi-subject mode). Selecting a subject from this list will change all displays and fields to the specifics of that subject. NOTE: Adding files, updating, averaging, etc is always done to currently displayed subject only. To add data to an empty subject, first select that subject from the list and then proceed as described above. Selecting Load Subject will allow a previously saved data set to be loaded. This data set is added in addition to any existing loaded subjects. Close All: The close all feature will clear ALL loaded data. To close only a single subject- use the remove subject feature. Minimize Data Set: This removes all Non-nessacary fields from the data. This is done to speed-up display and calculations. Once the data set has been minimized, certain fields will no longer be available until the data is updated again. Saving Data: To save data (for future loading as described above), click on Save Data under the File pull-down. Here you will find the options to save ALL subjects or just the current subject. Save Flags gives the options to save only certain compentents of the data. Only the checked fields will be saved (for example MagGIE in the image to the left- this is the multi-subject data). Lisa and Bart are not yet

4 implemented but will be future expansions on the tab menu on the right side of the GUI. The option of Save Minimum under HoMER will save a reduced data set (same as Minimize data set described above). All data is saved as a *.mat file with the std. PMI data structure. Updating/Filtering: The first step in data analysis (after loading data) will be to update the fields. This action creates several variables that are nessacary for other features of the program such as averaging and imaging. Updating can be done per data file (#5) or for all files associated with the current subject all at once (on HOMER>>filtering pull-down option). The Filtering menu (demonstrated to the right) specifies the filtering parameters to be applied to the data upon updating. In addition, under the pull-down menu (HOMER>>FILTERS>>Adv Options) a number of additional features can be specified. These will also be applied upon updating 1) Low Pass Filter (LPF)- This field specifies the low pass filter value (in Hz) to apply to the raw data. This is the first step in the updating process. If this value is set to zero then the LPF step is skipped. This uses the matlab filtfilt command. NOTE: Both low and high pass filtering are done on the complex data. The log-normal data is then calculated from the absolute value of this data prior to the nsv filter. This allowed the I &Q compenenets of the data to remain separate as low as possible in the data processing. NOTE: HPF is now done prior to nsv filtering. 3) High Pass Filter (HPF): After the application of the first PCA filter, the data is then HPF d to remove any drifts (etc) in the data. Data must be at least 3 times the length of the HPF applied. If not, this filtering step is skipped. 2) nsv_pre: The next step in the updating process is the application of principle-compenent analysis filters. The first of such is a PCA filter that removes the first N eigen-vector components obtained from the entire data set. The effect of this filter is to remove strong coorelates between data traces (i.e. motion artifacts). The single-value spectrum can be displayed by selecting the pull-down menu (FIGURES>>Plot SV spectrum). The top plot in this figure is the SVD of the entire data set and the eigen-values of interest here. 4) NSV-dOD: This is the second PCA filter in the updating pathway. Unlike the first PCA filter, this filter uses baseline data and removes the first [N, M] eigen-vectors of the baseline data (at Lambda 1 and 2 respectively). This filter thus removes physiological noise from the data. The

5 SV spectrum can be displayed as above. The bottom two plots are the SV spectrums from lambda 1 and 2. (without baseline data, these plots are not available) Note: In order to use this filter, baseline data MUST be specified. Note: At this step, a custom filtering step can be added to the Update path. The DOT variable is passed to this user-defined filter and the (modified) DOT variable is expected to be returned by the function. Custom filters must have the structure: function {DOT,varargout} = <My_Filter>(DOT) After the data has passed through all filtering steps, delta-concentration is then calculated. Note: In the data structure, Conc data is referenced by the Lambda=1 compenent of the ML. The data structure stores HbO, HbR, and HbT in the [1,2,3] indexes of the 3 rd dimension of the data. Advanced Options: Here, the user has the option to specify custom filters (to be applied as described above) and/or partial volume and path-length corrections. These are all applied immediately after the last filtering step described above (the custom filter is applied first). Path-length corrections are multiplied against the linear distance between Src-Det pairs (specified in cm in the probe file). These options must be checked to be applied during updating. If Pathlength corrections are not applied, concentration data has units of Molar*cm (i.e. still has the L factor included as per Beer s Law). Pruning: Pruning provides a way to remove unwanted src-det pairs from being included in averaging and/or imaging (for example noisy or low signal channels). This can be done on the basis of Src-Det seperation distances, min/max AVERAGE intensities in the RAW data, or manually by clicking on the SD-geometry (dotted-lines are src-det pairs that have been removed from the ML).

6 Only active Src-Det pairs (those displayed with a solid line in the probe geometry) will be included in averaging, image reconstruction, and ROI averaging (if that option is chosen). Single Subject Averaging: NOTE: Data files MUST be updated prior to averaging. If Avgerging multiple data files together, all data files must be updated first. Stimulus: The stimulus train is calculated from the s variable. The features to the right side of the Averaging menu deal with this aspect of averaging. This process works by first normalizing the s variable. Next, the derivative of this trace is taken. After this, all points above the specified Threshold are found as potential stimulus time points. Finally, this list is compared against the Tsep value (for Time Seperation). This value (in seconds) specifies the minimum temperal distance between adjacent stimulus points. For example, if Tsep is 2 - then any point that is above the threshold but LESS then 2seconds following the last point that also met the threshold criteria is NOT included in the stimulus list. The Reset Stim button recalculates the stimulus train from the s variable. The Stim toggle button turns on/off the display of the calculated Stim train. The View Original Stim toggle button turns on/off the display of the original s varible used to calculate the stimulus points. User Stim allows the user to specify a set of stimulus points rather then calculating them from a s variable. This button must be down and the reset stim button pressed to apply the user defined stim points. Removing individual stimulus points. HOMER also allows for the selective removal of individual stimulus points (i.e. bad data points). By clicking on the green lines (active stim points), the stimulus lines can be turned off meaning that they will not be included in any averaging (or deconvolving). Red lines are inactive

7 stimulus points/green are active. Reset Stim restores all lines to active. Note: If the ZOOM or DISPLAY AVG ALL features are down, then clicking on the stimulus lines will have no effect. Turn off both of these features to toggle the stimulus lines. Averaging: Once the stimulus points have been defined, the data can now be averaged. The pre-time field specifies the time (in seconds) prior to each stimulus point to include in each epoch. (same with the post-time). Only epochs that FULLY fit into the data will be included in the average (for example typing a post-time of 60s if the total length of the experiment is only 30 seconds will result in an error and thus such epochs are not included in the averaging). Avg: Averages ONLY the current file Avg All: Computes the average from all files associated with the current subject. (Baseline data is ignored). Deconvolve: If this toggle button is down, then a Least-squares deconvolution method is used rather then a block average. Displaying data:

8 1) Main plot field. This displays the data trace for the entire exeriment. The data that is displayed is specified by the pop-up menu (#3). In the figure above, the raw data is being displayed. The wavelength to be displayed in specified by pop-menu #4 2) This figure displays the averaged data trace. Although this is also specified by menus #3 and 4, the only options for display here are dod_cov and dconc (both described below). If any other display option is selected, then dod_cov data will be displayed (such is the case in the figure above). 3) Display Menu. This specifes which data trace to display. Raw- Data loaded directly from data file. This data has not passed through any filters. Normalized- the Log of the normalized data- This data has been subjected to the LP and HP filters. Norm-Cov- This data is Normalized data from above with additional covariance (PCA) filtering HPF- The drift correction to be applied to the data set. This is NOT the high pass filtered Data itself, but instead is the correction that was applied to high-pass filter the data. I.e. this is the drift correction. dod- Delta Optical Density calculated from filtered data HPF,LPF,Cov-reduced} dod-cov- Applies Covarience reduction (against baseline) filter to dod data for each wavelength. Only avaliable if baseline data is specified. Conc- Displays concentration traces (specified by check concentrations off pull down menus from top of figure). This data has been calculated from the modified Beer-Lambert law. If partial-volume/pathlength corrections were specified, they have been applied here. Conc-Cov- Not yet implimented Aux10- Display Auxillary data (if any). 4) Wavelength selection. Choose which wavelegth to display. Note: Since wavelength doesn t make sense for concentration, the wavelength display must be the first index to display dconc (this has to do with the structure of the Conc variable). HOMER should automatically correct for this. 5) This allows the scale of the Average plot (#2) to be manually specified. Type 999 to autoscale 6) Display Even/Odd- Displays Averages on only the even and odd stimulus points seperately.

9 Display ErrorBars- Toggles on/off the display of error bars on the average plots. Advanced Averaging Options (on pull-down menu) allows the choice of Std Dev or Std Error Zoom- allows zooming on any of the three plots (main data, avg, and SD-geometry) Display All- Plots time traces (along x-axis) for the entire measurement list (along the y-axis). Magnitude is given in color scale Display Avg All: This toggles between displaying the average trace for ALL the data files (for current subject) or only the active one. This is only available when more then one data file is open (and averaged). 7) Probe- All displays will reflect the currently selected src-det pairs from this plot. Only active lines will be displayed. Additional Figures: FIGURES>NEW FIGURE: This will create a new figure displaying the plots from #1,2, and #3 from above FIGURES>>PLOT PSD This displays the power spectrum for the currently diplayed data (selected from #3 and #4) FIGURES>>PLOT ALL This displays the data reflecting its position in the SD-geometry. For dod, a black line is used for the Lambda Index #1 and the blue line is Lambda #2. (Red is used for #3 etc). For dconc, Black is HbO, Blue is HbR and Green is HbT.

10 Additionally, by left (mouse) clicking on any of the figures, the option to plot new plot can be selected. This plots that figure in a new window. Physiology: Currently not used in this version of HOMER To be implemented in the SPM add-on (coming soon) Imaging: NOTE: Averaging must be done before image reconstructions can be preformed. The basic fields in the imaging menu allow one to specify the Musp (scattering) and Mua (absorption) coefficients. These can be entered as a single value (i.e 10 cm-1) which then is taken to be the same for both wavelengths, or entered for each wavelength separately (i.e. [10 9] ) which is then applied to the two (or more) wavelengths independently. The units are in inverse cm. The X/Y/Z voxel fields are the range for the reconstruction (in cm). The optimal voxel size is automatically computed upon loading the geometry file. Make Matrix: This button forms the sensitivity matrix from the specified Musp and Mua coefficients. This is done using the PMI toolbox and assumes a semi-infinite slab geometry and Born approximation to generate the matrix. The matrix size is based upon the currently active ML (all the src-det currently active in the probe image). Note: Future versions will allow the control of the approximation type Invert Matrix: This button performs the regularized inversion of the sensitivity matrix. Trikonov regularization (λ=1). This inversion uses Note: Future versions will allow the regularzation parameter to be specified.

11 Make Image: This final button multiplies the sensitivity matrix against the dod_cov (active ML) variable to form an image. For reconstructing dconc images (see Adv Image options), the dod image is pixel-wise converted to a dconc matrix. Note: Partial-volume and pathlength corrections are NOT applied to the reconstructed dconc images Note: If the size of the ML is changed during image reconstruction, then the sensitivity matrix will need to be re-updated. Advance Options Imaging: This menu (found in the pull-down menu HOMER>>IMAGING) allows for several display options on the reconstructed image. dod vrs dconc: Which type of image to reconstruct. Show CNR Image: This option is only available if baseline data is specified AND a dod image is desired. To calculate noise, the image of the baseline is taken and then the standard error is calculated in the time dimension. This then becomes the image of noise, which is divided into the dod (contrast) image. Autoscale: Sets a change of zero to be green and autoscales the max/min of the image. Show Probe: Superimposes an image of the probe geometry onto the reconstructed image. Displaying the Image: The image is inheriently a 4D matrix (x/y/z/time). If reconstruction is done for multiple z-sections each of these slices will be displayed separately. In the time dimension, the image is reconstructed from a time average over the timewindow indicated in the average plot window (it is a red bar in the plot). The length/location of this bar can be moved around by clicking in the window above or below the bar. This will automatically update the displayed image to reflect the new time averaging. The display image button will recall the image reconstruction after the window has been closed. Note: While the Display Image button is down, the context menus (right-clicking features) of the Avg data plot are disabled.

12 Exporting Data: By right-clicking on any of the plot axes, the option will appear to export the data to file. This gives the option to export the currently displayed data type (i.e. dconc,dod etc) to either a *.mat or *.dat (ascii) file structure (only *.mat for the SD geometry). The structure of this exported variable is [ML x time pts]. For example, if the 3 rd row of the ML is [ ] then the 3 rd row of this data set is the data associated with the 1 st source to 2 nd detector at wavelength #2. Concentration data is stored as a three dimensional array in *.mat format (the third dimension is indexed by [HbO,HbR, and HbT] respectively). In *.dat (ascii), this data is stored as three separate varibles. MAGGIE (Multi-subject/ROI averaging) - Allows averaging across ROI for single and multiple subjects. Average All subjects: This button calculates the ROI average. The data to be included in this average is specified by the radio buttons to the right. Use all subjects vrs. Use current subject: If the current subject choice is selected, the ROI for only the currently displayed subject (shown in the pull-down menu on the right-side of the display) is displayed in the plot. For both choices, both the individual subject ROI averages AND the ROI average from ALL subjects is calculated. Toggling this radio-button between ALL and CURRENT changes the display (reflecting one or all subjects). The subject list controls which (individual) current subject to display. Use Act ML: If this option is selected, only currently active src-det s (for each subject) are used to specify the ROI. Otherwise, the entire ML is used as the ROI. Compare All: This button plots the ROI averages for all subjects as subplots on a single figure. Subjects are displayed on the same scale.

13 Show Statistics: This button brings up a pop-up window that allows the display of the zero-lag coorelation coefficients between all subjects for the specified variable. Subjects are denoted by there index on the list (i.e. the 3 rd subject on the list is the 3 rd row/column in the coorelation matrix). Programming new Features: This program was reworked to allow for easy expansion of future functions- you may have noticed that there are a few buttons on the right tab panel that don't do anything yet. This code will explain (as best I can) how to add your own functions to these tabs. HOW to add buttons to the GUI: In HOMer.fig file- after placing your button set callback to %automatic --this will make a call to this main program passing the name of the function and all GUI handles (see that code for details) The visibilty of buttons is controlled by the UserData field. "0" means that the button will be invisible; '1' means it will be visible. This is done so that visibility can be controled/referenced by the tabs and allow button access to be controlled by visibility and have that visibility state be recalled properly even when the tab is displaying a different field All default values for buttons should be: visible = false UserDate= [0 or 1] -- this sets the default state 'Tooltiptext'- "What does this button do?" Context menu- one of the ready made ones or add your own code The rest is up to you! Objects associated with the "Debug" context functions will be able to move around in Debug mode during execution (ie if the Deebug flag in HOMer.m is set to "1". This means that after you ste the position of the object You can look at it position during execution and fine-tune the size and positions. After getting it to where you want- click the display properties feature and it will tell you the size/position information. You then must go back to the main HOMer.fig file and make the appropriate changes in the property editor and save the fig file. This makes it easier to customize the fig file (expecially given it multi-layering nature). After creating a button in the HOMer.m program add the code: function your_button_name_callback(hobject, eventdata, handles) <Subprogram name>('<name of function in subprogram>',hobject, eventdata, handles, <any flags passed>); The reason to call all programs from this main program (rather then calling them directly from the callback itself is so I can allow users to change functions without giving access to the code itself and allow the program to (eventually) be compiled into a stand-alone cpp code.

14 ---- Asociating objects with a Tab button ---- Objects can be associated with a tab- i.e. their visibilty controled by a tab by simpily adding the name of the object handle to the list in the appropriate *_FUNs.m file (i.e. HOMer_FUNs.m) Whenever this tab is pressed, the main program will go through this list of objects- any objects on this list with a value of "1" for the UserData will be turned on and "0" will be left off. The current state, value, visibility, and any data associated with the object (i.e. strings/text) will be saved and recalled when switching between subjects provided the object is on one of these lists. Passing data into functions: All the data is stored on the main figure's UserData field and can be recalled using the command: data = get(handles.figure1,'userdata'); This data is stored in the Std DOT format used by this lab (same as PMI toolbox format). Data is a cell array indexed by the subect index. For currently displayed subject index type: subnum=get(handles.popupmenu_subjectlist,'value'); Data{subnum} -> data associated with subject subnum for more details- thuppert@nmr.mgh.harvard.edu