FAQ

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.

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.


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 supports using subject specific anatomies. To do so, you must provide a bunch of necessary files in the directory “SUBJ_DIR/anatomical”. We have a script here called create_HeadVox.m that you can use to create all of these files. In order to begin, you need a mesh of the head surface and the brain surface. These meshes need to be in the same coordinate system. You’d be surprised how easy it is to create these two surfaces in two different coordinate systems. Make sure they are in the same coordinate system otherwise the script will not work for you. The meshes need to be saved in FreeSurfer format. Homer includes a script write_surf(fname, vertex_coords, faces) that will create a mesh file in FreeSurfer format.

fname – is the file name for the mesh. This should either be headsurf.mesh or pialsurf.mesh

vertex_coords – this is a matrix with nv x 3 elements containing the X,Y,Z coordinates of the nv vertices on the mesh.

faces – this is a matrix with nf x 3 elements pointing to the 3 vertices that define the nf faces on the mesh. Note that faces points to the first vertex as element 0! Please check this. Matlab wants the first vertex to be referred to as element 1, but the FreeSurfer convention is a C convention which starts with index 0. There are different versions of write_surf.m out there that either subtract one from faces or doesn’t. I am cleaning this up in Homer so that what you must pass to write_surf.m is faces pointing to the first vertex with index 0. There is the companion function read_surf.m. To use the returned faces in Matlab, you must add 1 to faces returned by read_surf.m.

Once you have run the script create_HeadVox.m, you can then launch AtlasViewerGUI and view your subject specific head anatomy.

You now need to find the landmark 10-20 reference points Nz, Iz, Ar, Al, and Cz. Use the menu item ‘Tools->Find Ref Pts’ to do this. To use this tool, you need to use the matlab Data Cursor tool to select the reference point and then click the corresponding pushbutton to save that reference point. Repeat this for the 5 reference points and then  push the ‘save reference points’ pushbutton. You can now go back to the AtlasViewer window and view your defined 10-20 points. You should also go to ‘Tools->Recalculate 10-20 Pts’ to calculate the rest of the 10-20 points.

Please note that this is still a works in progress. Please provide feedback so that we can make this work more robustly.

I am grateful to Vince Magnotta, Soba Wijeakumar, and John Spencer for debugging several issues with these steps.