FAQ

THIS SITE IS OLD AND NOT MAINTAINED. Go to openfnirs.org/software/homer for the latest on Homer and AtlasViewer.

NIRS File Format

General

HOMER

AtlasViewer

Format for .nirs file and sample .nirs files

To create a proper .nirs file please look at the Homer2 Users Guide on the Documentation page.

It is the first page of the documentation after the Table of Contents that describes how to make the .nirs file. It is on page 4.

On that same web page, next line down, you can find a link to download sample data. Please download that zip file. In the directory Example1_Simple_Probe, you will find Simple_Probe.nirs that will provide an example of this .nirs file.

There is a possible issue with the formatting of the measurement list, i.e. the variable ml which is the same as SD.MeasList. It is advisable that measurements be ordered by wavelength. ml is a Nx4 matrix where N is the number of measurements and each column describes the source index, detector index, data type index, and wavelength index for each measurement. While in theory the measurements can be ordered in any way, in practice it seems that some functions only work properly if all measurements for the first wavelength are ordered first, and then the second wavelength, and so on.

Converting Hitachi files to .nirs files

A Matlab script to convert the raw .csv Hitachi ETG4000 output file into a .nirs file for use with Homer2 can be obtained at http://www.nitrc.org/projects/hitachi2nirs. Created by Rebecca Dewey.

Converting NIRx files to .nirs files

NIRx2nirs is a Matlab script which takes near-infrared spectroscopy data recorded by NIRx system(s) and converts it to a .nirs file format for use with the HOMER2 NIRS processing package. It can be obtained at http://www.nitrc.org/projects/nirx2nirs/ . Created by Rob Cooper.

Converting Shimadzu files to .nirs files

Shimadzu2nirs is a Matlab script which takes near-infrared spectroscopy data recorded by Shimadzu system(s) and converts it to a .nirs file format for use with the HOMER2 processing package. It can be obtained at https://www.nitrc.org/projects/shimadzu2nirs/ . Created by Sahar Jahani.

Converting Artinis files to .nirs files

Anyone interested in converting Artinis NIRS files to the .nirs file format should contact Jörn M. Horschig at Artinis.

Subscribing to the email list

Subscribe to Homer-users by filling out the form on the URL below:

https://mail.nmr.mgh.harvard.edu/mailman/listinfo/homer-users

https://mail.nmr.mgh.harvard.edu/mailman/listinfo/homer-users

Unsubscribing is quite simple. Just go to the URL below (note: this is indicated at the bottom of every post to the homer list server so you don’t need to remember it).

https://mail.nmr.mgh.harvard.edu/mailman/listinfo/homer-users

On this Web page there is a box to enter your email address in order to unsubscribe. The email address must match the email address that you originally used to subscribe.

Homer – Export Processing Script

All Homer processing functions can be accessed from the Matlab command line. You can export a matlab script for your current processing stream using the ‘File -> Export Processing Script’ menu item.

Homer – How to add auxiliary measurements in the nirs files Script

You can add hmrCreateAuxRegressor function before the hmrDeconvHRF_DriftSS function in your processing stream in Homer. You need to put the auxiliary measurements in the nirs files as aux variable beforehand to be able to use the function (sampling rate should match).

Each row of aux is a different aux input.

1)   Down/upsample aux to match nirs sampling rate (you can use one of the Matlab functions eg resample)

2)   Load .nirs file in Matlab

3)   Load aux

4)   Over-save .nirs file

 hmrCreateAuxRegressor has 3 parameters that user needs to input. The first one is which row of aux you want to use as a regressor.  The second two are hpf and lpf parameters. Eg if you want to use the first row of aux as regressor and no filter you can input [1 0 5]. Then GLM function (hmrDeconvHRF_DriftSS) will add this row to the design matrix.

AtlasViewerGUI – Preparing Subject Digitized Points for Registering the Atlas

If you have digitized optode positions on your subject and the key 10-20 reference points Nz, Cz, Iz, Ar, and Al, then you can easily register the head atlas to your subject and visualize the optode positions on the registered atlas. To do so, create a text file called ‘digits.txt’ and place it in the subject directory. This text file should look like the example below. Each row gives the coordinate of the indicated 10-20 reference point or source s# or detector d#. This example has 3 sources and 4 detectors, but you can have as many sources or detectors as you like. Make sure the units of the coordinates are in millimeters.

nz: 101.5 -16.2 -0.3
ar: -8.9 -60.2 90.8
al: -4.8 -59.6 -89.2
cz: -12.1 102.9 0.2
iz: -104.8 -15.0 -0.3
s1: 10.2 55.7 -95.7
s2: -9.9 68.0 -87.4
s3: -32.9 83.2 -62.2
d1: 12.7 75.7 -78.1
d2: -4.8 90.3 -61.8
d3: -14.3 106.7 -31.1
d4: 6.4 15.3 -110.6

Note that presently the number of sources and detectors in this digits.txt file must match the number of sources and detectors in your SD structure. Usually this is not problem. But it is possible that your SD has, for example, 8 detectors labeled 1 2 3 4 17 18 19 20. For some reason, 5-16 have been skipped. In this case, your SD.DetPos would indicate 20 detectors. As a result, you must also define d5, d6… d16 in the digits.txt file and can give them arbitrary locations.

AtlasViewerGUI – Registering Atlas to Subject Head Size

If the user doesn’t have digitized points from the subject, they can instead measure the head size of the subject including the head circumference, the distance from Nz to Iz, and the distance from Ar to Al, all along the surface of the head. Using the menu ‘Tools->Register Atlas to Head Size’ tool, the user is asked for these coordinates in centimeters. The atlas is then scaled to match this head size.

Presently this function determines the axes of an ellipsoid that has the given lengths. It would be better to use the lengths along the surface of the atlas head rather than the length along the surface of an ellipsoid.

AtlasViewerGUI – probe placement variation

This tool was developed to visualize the optode positions obtained with a 3D digitizer and the variability of those optode positions for a group of subjects. While it has not been tested, it likely also works for visualizing the variability of optode positions registered to the head using the spring relaxation method. This tool is selected using the ‘Tools -> Probe Placement Variation’ menu option. It will ask you to select the root directory of a group of subjects. Each sub-folder in this directory represents a subject and should contain an atlasViewer.mat file saved using the ‘File -> Save Viewer State’ menu option for each subject. This tool will create two figures. The first displays the each optode on the atlas head color coded for subject. The second figure displays the mean position of each optode and is color coded to show the standard deviation of the position across subjects with the scale given in mm units.

A demo group folder containing several subject sub-folders with the necessary information can be downloaded here to help you test the functionality of this tool.

AtlasViewerGUI – subject specific anatomy

AtlasViewer has GUI menu functions that can convert subject-specific MRI, processed in Freesurfer to it’s own format. Then it can be loaded in AtlasViewer. After that, you can use the “Find Ref Pts” menu option to select the head reference points Nz, Iz, LPA, RPA and Cz. Lastly, you can generate the 10-20 reference point from these initial reference point using the “Calc 10-20 Ref Pts” menu option.

To do this follow these steps:

1. Open AtlasViewerGUI in the subject folder where the Freesurfer MRI and surf folders are. AtlasViewerGUI should open with the Colin atlas.

2. Go to the “File” menu and select

“Convert FS files to Viewer”

That should create the files in AtlasViewer format. It should also automatically reload the subject folder with the new files.

3. Select initial reference points Nz, Iz, LPA, RPA, Cz. To to this, go to the “Tools” menu and select

“Find Ref Pts”.

NOTE ON LEFT/RIGHT ORIENTATION: You have to be careful to select LPA and RPA correctly or else you will mis-label the left side RPA and right side LPA. To label correctly you have to know the orientation of the Freesurfer processed MRI volume you’re using such as T1. To find out, use the Freesurfer utility mri_info to look up the 3-letter code that tells how the volume is oriented by specifying how the 3 volume dimensions, column, row, and slice are ordered.

To simplify things, the general rule is that any volume whose code has an L rather than R in it (for example “PLI”), will appear left/right flipped when viewed in MATLAB (and “Find Ref Pts” utility) and conversely any volume whose orientation code has an R in it (for example RSA) will not appear flipped. That is the side that appears to be the subject’s right side is actually the right side and the left side the left. L and R will never both appear in an orientation code.

So for example, when you run recon-all, all the final stage volumes such as T1, brain, aseg, wm, etc will have the orientation code “LIA”. This means that when these volumes’ headers are converted to AtlasViewer format, the left and right sides will appear flipped when viewed in “Find Ref Pts” display. Therefore what appears to be the right side is really the subject’s left side and should be labeled LPA and the side that appears as the left side is really the subject’s right and should be RPA.

4. Once those two steps are completed, you can generate 10-20 or 10-10 EEG reference points by going to the “Tools” menu and selecting

“Calc Ref Points”.

AtlasViewer – HbO/HbR concentration changes overlay on the Atlas

This function is a useful tool to visualize the average of HbO/HbR concentration in a specific time duration on the Atlas. To use this function the groupResults.mat and probe.SD files are necessary. Follow the below instruction to create the overlay of HbO/HbR concentration changes on the Atlas where the registered probe is located.

Instruction:

  1. Add Homer folders and subfolders to your Matlab path,
  2. Change your Matlab path to the folder where your groupResults.mat is available,
  3. Open AtlasViewerGUI,
  4. Go to tools menu and import your probe.SD file,
  5. Register probe to the surface,
  6. From the Tools menu, select Hb Conc Overlay,
  7. Select an appropriate time range: [tRangeMin tRangeMax]. (The time range which you want to see the averaged Hbo/HbR changes on the Atlas),
  8. From the drop down box in the Image Display section, you can select HbO Conc, HbR Conc and so on. Also, under the drop down box, you are able to specify the colormap range (specifying an appropriate colormap range will result in a complete probe HbO/ HbR overlay on the Atlas), channel numbers (default is displaying all channels), and Condition (put the number of your intended condition) and then press the Enter key.