Documentation

Table of contents:
Installation Instructions, Release v2.3
Installation Instructions, Release v2.1 and earlier
Documentation on using Homer2_UI
Documentation on using AtlasViewerGUI
Tutorials

This page contains documentation for the HOMER2 release v2.2 and earlier.

NOTE: For earlier releases v2.1, v2.0, and earlier, standalone executables Homer2_UI.exe and AtlasViewerGUI.exe had to be downloaded and installed separately. Also Colin atlas data and the Monte Carlo software tMCimg  (used by AtlasViewGUI) had to be downloaded and installed separately. Lastly, the executables for earlier releases were only available for Windows.

Starting with release v2.2, executables are available for MAC as well as Windows. They are available as installation packages, that is a single zip file the contains both  Homer2_UI andAtlasViewerGUI and their data, instead of just the executables.

 

Installation Instructions, Release v2.3

If you have a Matlab license:

1) First step is to make sure you have the following Matlab toolboxes, used by each application:

– Homer2_UI

  • Signal Processing Toolbox
  • Symbolic Math Toolbox
  • Image Processing Toolbox
  • Statistics Toolbox
  • Wavelet Toolbox
  • Curve Fitting Toolbox

– AtlasViewerGUI

  • Image Processing Toolbox
  • Simulink
  • Control System Toolbox

2) Download homer2 source code release file, homer2_src_v2_3_10172017.zip from the Homer2 web page. Then unzip the installation file.

3) Open Matlab and in the command window, change the current folder to
the homer2 root folder that you just downloaded and unzipped.

4) In Matlab command window, type

>> setpaths

This will set all the required matlab search paths for Homer2 and AtlasViewer.

Note: this step should be done every time a new Matlab session is started.

5) At this point you should be ready to start Homer2_UI or AtlasViewerGUI from the Matlab command window.

To test that they work properly, do the following:

a) To test that Homer2_UI works properly, start  Homer2_UI in the Matlab command window. When it comes up it will ask the user to select a subject folder. Navigate to the Test-Homer2 folder in PACKAGES / Test / Test-Homer2 and select it. Homer2_UI will then ask for the Process Options file – choose the test_process.cfg file.

b) To test that AtlasViewerGUI works properly, start  AtlasViewerGUI in the Matlab command window. When it comes up it will ask the user to select a subject folder. Navigate to the Test-AtlasViewer folder in PACKAGES / Test / Test-AtlasViewer and select it. AtlasViewerGUI should come up with an image of the atlas and a probe registered to it.

 

If you do NOT have a Matlab license:

Before you can run Homer2_UI and AtlasViewerGUI standalone, you have to install the executable files for these applications.

In addition to that installation you have to download and install the MATLAB Runtime. The MATLAB Runtime is a standalone set of shared libraries that enables the execution of compiled MATLAB applications on computers that do not have MATLAB installed. Without this installation, the Homer2_UI and AtlasViewerGUI executables will NOT work.

The following is installation instructions for Homer2_UI and AtlasViewerGUI                             executables and MATLAB Runtime:

On Windows:

1) Install MATLAB Runtime in order to be able run Matlab applications. To do this, download MATLAB Runtime R2016a (9.0.1) 64-bit for Windows at the Mathworks website.

2) When it finishes downloading, install it on your PC by double-clicking on the downloaded file. NOTE: You will need administrator rights to run MCRInstaller.

3) Download the homer2_install_v2_3_win_10182017.zip file from the Homer2 web page.

4) Unzip homer2_install_v2_3_win_10182017.zip

a) Open Windows Explorer ( XP / 7 ) or File Explorer ( 8 / 10 ) and go into the Downloads folder.
b) Double click on the homer2_install_v2_3_win_10182017.zip to unzip it.

5) To run the installation

a) In Windows Explorer ( XP / 7 ) or File Explorer ( 8 / 10 ) go to the just unzipped homer2_install folder.

b) Double-click on the setup.bat file.

6) Once installation finishes, you should have 2 new icons on your
desktop:

Homer2_UI.exe
AtlasViewerGUI.exe

Double click on either one to run it.

6) Once installation finishes, you should have 2 new icons on your
desktop:

Homer2_UI.exe
AtlasViewerGUI.exe

Double click on either one to run it.

7) To test that Homer2_UI or AtlasViewerGUI work properly, do the following:

a) To test that Homer2_UI works properly, start  Homer2_UI by clicking on the Desktop shortcut Homer2_UI. When Homer2_UI starts it will ask the user to select a subject folder. Click on the Test folder in the Desktop folder and select Test-Homer2. Homer2_UI will then ask for the Process Options file – choose the test_process.cfg file in the Test-Homer2 folder.

b) To test that AtlasViewerGUI works properly, start  it by clicking on the Desktop shortcut AtlasViewerGUI. When AtlasViewerGUI comes up it will ask the user to select a subject folder. Click on the Test folder in the Desktop folder and select Test-AtlasViewer. AtlasViewerGUI should come up with an image of the atlas and a probe registered to it.

 

On MAC OS:

1) Install Matlab Libraries to run any matlab application. To do this download MATLAB Runtime R2016a (9.0.1) 64-bit for Mac at the Mathworks website.

2) When it finishes downloading, unzip the file.

3) Install the MATLAB Runtime on your Mac by double-clicking on the install file in the unzipped folder. When asked for the installation folder, keep the default

/ Applications / MATLAB / MATLAB_Runtime.

and click the next button. This will lead you to the installation button.

4) Download the homer2_install_v2_3_mac_10182017.zip file to the Downloads folder on your MAC.

5) IMPORTANT: Open the MAC application Finder and go into the Downloads folder (or which ever folder contains the homer2 zip file) and make sure there is no folder there named homer2_install (for example, from previous homer2 installations). If there is, rename or delete it. The point is to have no folders named homer2_install in the folder with the zip file, before going to the next step.

6) Unzip homer2_install_v2_3_mac_10182017.zip.

a) Again in Finder, go in the Downloads folder (or which ever folder
contains the homer2 zip file).
b) Double click on the homer2_install_v2_3_mac_10182017.zip to
unzip it.

7) To run the installation

a) In Finder go to the just unzipped homer2_install folder.
b) Double-click on the setup.command file.

8) Once installation finishes, you should have 2 new icons on your desktop:

Homer2_UI.command
AtlasViewerGUI.command

Double click on either one to run it.

9) To test that Homer2_UI or AtlasViewerGUI work properly, do the following:

a) To test that Homer2_UI works properly, start it by clicking on the Desktop shortcut Homer2_UI.command. When Homer2_UI starts it will ask the user to select a subject folder. Click on the Test folder on your Desktop and select Test-Homer2. Homer2_UI will then ask for the Process Options file – choose the test_process.cfg file in the Test-Homer2 folder.

b) To test that AtlasViewerGUI works properly, start  it by clicking on the Desktop shortcut AtlasViewerGUI.command. When AtlasViewerGUI comes up it will ask the user to select a subject folder. Click on the Test folder in the Desktop folder and select Test-AtlasViewer. AtlasViewerGUI should come up with an image of the atlas and a probe registered to it.

 

Installation Instructions, Release v2.2

If you have a Matlab license:

1) Matlab toolboxes used by each application:

Homer2_UI

Signal Processing Toolbox
Symbolic Math Toolbox
Image Processing Toolbox
Statistics Toolbox
Wavelet Toolbox
Curve Fitting Toolbox

AtlasViewerGUI

Image Processing Toolbox
Simulink
Control System Toolbox

2) Download homer2 source code release file, homer2_src_v2_2_03132017.zip‘ from the Homer2 web page. Them unzip the installation file.

3) Open Matlab and in the command window, change the current folder to
the homer2 root folder that you just downloaded and unzipped.

4) In Matlab command window, type

>> setpaths

This will set all the required matlab search paths for Homer2 and AtlasViewer.

Note: this step should be done every time a new Matlab session is started.

If you do NOT have a Matlab license:

Before you can run Homer2_UI and AtlasViewerGUI standalone, you have to install the executable files for these applications.

In addition to that installation you have to download and install the MATLAB Runtime. The MATLAB Runtime is a standalone set of shared libraries that enables the execution of compiled MATLAB applications on computers that do not have MATLAB installed. Without this installation, the Homer2_UI and AtlasViewerGUI executables will NOT work.

The following is installation instructions for Homer2_UI and AtlasViewerGUI                             executables and MATLAB Runtime:

 On Windows:

1) Install MATLAB Runtime in order to be able run Matlab applications. To do this, download MATLAB Runtime R2016a (9.0.1) 64-bit for Windows at the Mathworks website.

2) When it finishes downloading, install it on your PC by double-clicking on the downloaded file. NOTE: You will need administrator rights to run MCRInstaller.

3) Download the ‘homer2_install_v2_2_win_03132017.zip’ file from the Homer2 web page.

4) Unzip ‘homer2_install_v2_2_win_03132017.zip’

a) Open Finder and go into the Downloads folder.
b) Double click on the ‘homer2_install_v2_2_win_03132017.zip’ to unzip it.

5) To run the installation

a) In Windows Explorer ( XP / 7 ) or File Explorer ( 8 / 10 ) go to the just unzipped homer2_install folder.

b) Double-click on the setup.bat file.

6) Once installation finishes, you should have 2 new icons on your
desktop:

Homer2_UI.exe
AtlasViewerGUI.exe

Double click on either one to run it.

On MAC OS:

1) Install Matlab Libraries to run any matlab application. To do this download MATLAB Runtime R2016a (9.0.1) 64-bit for Mac at the Mathworks website.

2) When it finishes downloading, unzip the file.

3) Install the MATLAB Runtime on your Mac by double-clicking on the install file in the unzipped folder. When asked for the installation folder, keep the default

/ Applications / MATLAB / MATLAB_Runtime.

and click the next button. This will lead you to the installation button.

4) Download the ‘homer2_install_v2_2_mac_03132017.zip’ file to the Downloads folder on your MAC.

5) IMPORTANT: Open the MAC application Finder and go into the Downloads folder (or which ever folder contains the homer2 zip file) and make sure there is no folder there named homer2_install (for example, from previous homer2 installations). If there is, rename or delete it. The point is to have no folders named homer2_install in the folder with the zip file, before going to the next step.

6) Unzip ‘homer2_install_v2_2_mac_03132017.zip’.

a) Again in Finder, go in the Downloads folder (or which ever folder
contains the homer2 zip file).
b) Double click on the ‘homer2_install_v2_2_mac_03132017.zip’ to
unzip it.

7) To run the installation

a) In Finder go to the just unzipped homer2_install folder.
b) Double-click on the setup.command file.

8) Once installation finishes, you should have 2 new icons on your desktop:

Homer2_UI.command
AtlasViewerGUI.command

Double click on either one to run it.

 

Installation Instructions, Release v2.1 and earlier

 Homer2_UI

This section is in the process of being updated.

 

Installation Instructions for AtlasViewerGUI

If you have a matlab license:

1. Download homer2_*.zip file from the Homer2 web page and unzip. This package contains all the matlab scripts for Homer2_UI and AtlasViewerGUI.

2. In matlab, cd to the root homer2 folder in your file system and add paths for all folder under the homer2 root folder.

For example

>> cd C:\…\homer2

>> p = genpath(pwd); addpath(p,’-end’);

3. Start AtlasViewerGUI – it should automatically find the default Colin atlas folder and the Monte Carlo executable, tMCimg.exe.

If you do not have a matlab license:

1. Download the latest AtlasViewerGUI_*.exe file from the Homer2 web page.

On Windows:

2. Download and install the 64-bit MATLAB Runtime installer, R2014b,  for the latest Homer2 release v2.1. ( For release v2.0, download and install the 32-bit MATLAB Runtime installer, R2012b from the Mathworks website. )

3. Create Desktop shortcut to AtlasViewerGUI.exe or drag the AtlasViewerGUI.exe file directly to the Desktop.

4. Download the zip files, Colin.zip and tMCimg.zip (see links below), unzip and move the unzipped Colin and tMCimg folders to C:\Users\Public.

** NOTE : When extracting these zip files, check to make sure the Colin and tMCimg root folders are C:\Users\Public\Colin and C:\Users\Public\tMCimg respectivly and not a layer below that in C:\Users\Public\Colin\Colin and C:\Users\Public\tMCimg\tMCimg. Otherwise AtlasViewerGUI will not find them in the default location and will prompt the user to locate them at startup.

( For release v2.0, move the unzipped Colin and tMCimg folders to the desktop. )

5. Start AtlasViewerGUI.exe by double-clicking on the AtlasViewerGUI shortcut. It should automatically find the default Colin atlas folder and the Monte Carlo executable, tMCimg.exe.

On Linux and MacOS:

2. Follow the instructions in the section above, “If you have a matlab license”, since currently we do not provide the AtlasViewerGUI executable for Linux or MAC.

Download sample data sets here:

 

Documentation on using Homer2_UI

The documentation on usage can be found in the HOMER2 User’s Guide. Please note that this documentation was written in 2012. We are now working to keep the documentation live and up-to-date at a wiki.

The documentation wiki is at NITRC.org.

Documentation on using AtlasViewerGUI

This paper in Neurophotonics provides a tutorial on using AtlasViewer.

 

Tutorials

Training Session 1

Basic training on using HOMER2 from the online training session from March 4, 2013. The training session is 60 min long.

Training Session 2

Recording of the training session from April 16, 2014. This session covered several questions including:

  • excluding channels based on signal level, SNR, and source-detector separation
  • Exporting HRF results
  • Looking at channel cross-correlations
  • Correction motion artifacts on OD rather than intensity
  • A review of the GLM capabilities of Homer
  • Some discussions about AtlasViewer

Displaying Different Channels Of Data in Homer2

This 4-min tutorial demonstrates how to select different channels of data to display. It shows how to select channels from individual sources or detectors, how to display data from multiple sources and detectors, and how to individually hide or deactivate specific channels of data.

Simple Probe

This is the basic introduction to the screen layout of HOMER2, how to view data from different sources and detectors, how to execute a simple processing script to convert from intensity to optical density to concentration, how to bandpass filter the data, and how to block average the response to a stimulus.

Waterfall Plot an Fixed Plot Range

A short tutorial showing the waterfall plot feature, selecting multiple channels of data to display, and fixing the plot range.

Exporting a Data Trace

This tutorial shows how to export data traces from the plot window by right clicking on the line within the plot window. You have the option of saving the single trace, or all traces visible in the plot window. They are saved to a text file where the first column is the time vector and each subsequent channel is the data for one of the channels. The top of each column is labeled to identify the data type and source and detector.

AtlasViewer Digitized Points File

This tutorial shows the basic format of the digits.txt file used by AtlasViewer to register an atlas to the subject. Download this sample data to follow along.

Register Atlas to Subject Digitized Points

This is a tutorial on using AtlasViewer to register the atlas to the 10-20 points (Nz,Iz,A1,A2,Cz) digitized on a subject. If the source and detector positions are digitized and the SD structure is available either from a .SD file or a .nirs file, this tutorial shows that you can also display the measurement list on the registered atlas. Download this sample data to follow along. Note that it is a good idea to save the the viewer state (under the File Menu) before closing AtlasViewer so that when you return, it comes back to the same state. Otherwise you may have to repeat the registration steps.

Register Atlas to Subject Digitized Points and run Monte Carlo Forward Model

This is a tutorial on using AtlasViewer to register the atlas to the 10-20 points (Nz,Iz,A1,A2,Cz) digitized on a subject. If the source and detector positions are also digitized, this tutorial shows you how to run the Monte Carlo photon migration forward model to calculate the sensitivity profile on the cortical surface. Download this sample data to follow along. Note that it is a good idea to save the the viewer state (under the File Menu) before closing AtlasViewer so that when you return, it comes back to the same state. Otherwise you may have to repeat the registration and Monte Carlo steps.

CORRECTION: As shown in this tutorial, you can have only the .SD file and not the .nirs file to provide the SD structure. Also, this tutorial describes the structure of the digpts.txt file.

Basic Introduction to Homer2 Website (by Jonathan Perry)

The Homer2 website contains 6 sections: Home, Documentation, Download, Forum, Developers/Citation, and FAQ. This tutorial is about the content of each section.

How to find conversion script on Homer2 Website (by Jonathan Perry)

This tutorial explains where to find the conversion codes. To know more about the data format you can check the documentation section.

Introduction to Homer2 GUI (by Jonathan Perry)

This tutorial shows how to use the user interface for Homer2. In the documentation section, you can find the sample datasets to work with Homer2GUI. Download this sample data to follow along.

Intensity to optical density conversion function (by Jonathan Perry)

This tutorial explains the Intensity2OD.m function in Homer2. This function converts the intensity data to optical density.

enPCAFilter function (by Jonathan Perry)

This tutorial is about the enPCAFilter.m function in Homer2. This function performs a PCA filter on the data.