NeuroDOT Code

From OICWiki

Jump to: navigation, search

This is page is an overview/outline of all the neuroDOT code.


User Guide

Acquring Data

The first step in using the NeuroDOT system is obviously to acquire some data. This is done using a stand-alone (i.e., non-MATLAB) program called Acqdecode. This program will control both the LEDs (encoding) and the data acquisition (decoding).

When you open Acqdecode, it will prompt you for a subject code (a HIPAA-compliant string to de-identify the data) and the pad (optode array) you are using. Using this information, it will choose the appropriate LED flashing pattern (encoding pattern). Then, to acquire data, you simply have to press the START and STOP buttons. When you stop recording, Acqdecode will prompt you for a "tag" and "comment". The "tag" is appended to the filename and allows MATLAB to identify files corresponding to different stimuli. The "comment" is included the an output text file and allows you to later remember key facts about the run (e.g., you stopped part-way through due to subject motion).

If you wish to use Acqdecode in a more detailed way (e.g., you want to use a different encoding pattern), follow the links to the Acqdecode page to learn detailed instructions. Additionally, the Acqdecode page will tell you how to interpret the graphs, which the program plots--these are useful for real-time checks of noise in the data.


Two standard stimuli programs are included with NeuroDOT. These are dostimretinotopy() and dostimAC(). dostimretinotopy() performs phase-encoded retinotopy experiments (as in White et al, NeuroImage 2009. It will do all four types: clockwise and counter-clockwise rotating wedges and expanding and contracting rings. dostimAC() will perform left and right flickering checkerboards in the lower visual quadrants (the AC terminology is a reference to the definitions in Zeff et al., PNAS 2007).

Checking Data Integrity

After you have acquired data, Acqdecode will output files containing decoded data. Four of these files are important for each run and can be read in by loaddata(). The .mag contains the decoded data. The -info.txt file contains information about the run (e.g., the encoding pattern and optode pad used)--this file can be viewed using any word processor. Additionally, you will need the .raw file corresponding to your stimulus synchronization channel (usually this will be the second-to-last MOTU channel). In order to align the stimulus information with the decoded data you will need the .fs file, which contains the time-points at which each acquisition frame occurred. Acqdecode will also output a .iq, but this file is not used by current decoding or data-processing programs, and you can ignore it.

A good first step is now to check the quality of the recorded data. To do this, you can load in the data with loaddata() and then view it with viewrawdata() (Note: this program also requires variables from the accessory radius file corresponding to your pad). These graphs will allow you to check multiple things:

  1. Are your recorded light levels well above the noise floor?
  2. Was there any movement during the run?
  3. What does the noise in the data look like? Are the enough non-noisy channels to expect a good reconstruction?

After the data has been further processed, you can look at later stages of the processing with similar programs. Filtered source-detector (un-imaged) data can be analyzed with viewnlrdata() ("nlr" standing for Noise-reduced Log-Ratio). Imaged data can be viewed with viewcortex().

Processing Known Experimental Designs

If you don't want to go in-depth into creating your own data-processing stream, there are three built-in programs that can handle everything about specific experimental designs. (Note that before using any of these programs, you need to make sure that the directory files correspond to your file storing structure.)

  • pbd(): This program processes block-design data.
  • sig(): This program processes phase-encoded retinotopy data.

Some of these also have further processing steps:

  • spg(): This program crates retinotopic phase maps from the output of sig().

Rather than using the pre-made set-ups or processing streams, you can design your own code (either to process in a different manner or to handle your own experimental design). The programs for that level of control are described below.

Creating Figures

If you want to view the figures output at the end of the experimental design programs, you don't have re-run the entire processing stream. You can use sigplots() and spgplots() to recreate the appropriate figures.

Looking at Data Files

You might not remember exactly which options you chose for every set of data. Thus, every processed data file has three variables that can help you figure out how your data got where it is.

  • info contains factual information about the data set (i.e., these are values that can't easily be changed through reprocessing). First, this includes information from AcqDecode about how the run was originally acquired (e.g., the pad used, the encoding pattern, the scan time, the frame rate, and any comments) is included in the variable info. Second, info also contains the dimensions of the A-matrix used for imaging (these are numbers that originally came from the variable dim exported by dotimage()).
  • The settings used by all the programs to process the data are listed in the variable flags. These could be changed if you wanted to reprocess the data: see Using flags.
  • how tells you which version of the NeuroDOT code processed your data. It tells you both the controlling program name and the date that program was saved (not the date the data was saved). Since changes are made to the NeuroDOT code, this allows to track down which code iteration resulted in your data.

Developer Guide

Forward Modeling and Optode Grids

In order to perform a scan, you first must know your arrangement of sources and detectors (collectively: optodes) and use that information to make a forward model of light propagation through the head. Information about the cap arrangement is stored in a variety of files by the NeuroDOT code

The first is a grid file which contains source and detector positions in 2D and 3D as well as the number of sources and detectors. You can either make your own such file, or if your pad has the same interleaved source and detector arrangement as our standard pads, you can use the program gridstandard() to make a grid file.

Once you have a grid file you need to additionally make a radius file (which contains nearest neighbor definitions and source-detector separations) and a pad configuration file which contains this same information in a format that is read by Acqdecode. Both of these files are output by grid2radiuscfg().

Now that your optode array is defined, you are ready to model light flow. This can either be done analytically on a semi-infinite geometry (using makeAanalytic()) or using a finite-element model of the head (using makeAnirfast()). In order to use makeAnirfast(), you will also need a copy of NIRFAST (available on the web), a mesh in NIRFAST format, a regions file (stored with the mesh), and an optical properties file defining the properties of each mesh region.


If you wish to create your own stimulus paradigm, the revisions to the NeuroDOT code in spring 2010. All stimuli are controlled by a central program called dostim(). In order to call dostim() you will need a steps variable. This variable is a struct that contains everything about how the stimulus is to processed (e.g., what stimuli and for how long). Additionally, you will need a stim variable that contains the actual graphics to be presented on the screen.


The NeuroDOT system comes with multiple encoding patterns included, but you may want to create your own. Reasons for doing do include changing the frame rate and changing the number of sources per spatial encoding region. You can generate new encoding patterns with the program EncodeStandard(). This program is, however, not capable of changing the basic encoding structure. For example, it is unable to generate a pattern consisting solely of frequency encoding. Also, note that, while the hardware is flexible, there is one chip which requires the encoding pattern to have a frame rate of about 10 Hz.

High-Level Data Processing

If you wish to process data yourself without relying on the built in experimental design programs or if your data falls outside of their stimulus structure, there are other programs within the NeuroDOT code that can handle your needs. It is possible to process your data without having to resort to understanding every individual step and small program.

The first step is take the decoded data saved by Acqdecode and load it into MATLAB for processing. This is accomplished with loaddata().

Now you can fully filter and image your data with dotbasic(). This will return to you both the filtered data (nlrdata) and the imaged data (cortexhb). If you have your own stimulus information, you can crop your data with cropdata(). dotbasic() contains three steps, which you can perform independently, if you'd like.

dotfilter() takes decoded data and prepares it for imaging. This includes high-pass and low-pass filters, as well as regressions of noise signals. In addition, it searches for noisy channels, which can then be excluded from further processing and use in the image reconstruction. resampledata() changes the sampling rate of your data--this is useful for switching from the default frame rate of 10.79 Hz to a more manageable 10 Hz or 1 Hz frame rate. Finally, dotimage() images your data, going from source-detector data to voxel data.

In all of these programs, there are multiple ways to control the steps involved. This is generally accomplished using either a flags file or by inputting flags directly. Further details can be found on the programs' individual pages.

Personal tools