.nSD files

Important Update: starting from 2021, ninjaGUI is fully compatible with regular SD files created with AtlasViewer. This means nSD files are no longer necessary for most applications. However, the nSD format compatibility is retained in case future fNIRS systems are implemented that require functions not specified in the original SD format (for example, frequency selection for each individual source).

The .nSD files (new Source-Detector files) are configuration files used in ninjaGUI to determine important parameters about the fNIRS experiment to be performed. It is based on the .SD file format used for our acquisition software used with the TechEn CW systems, but both formats are incompatible (though it is relatively easy to make the nSD file format backwards compatible).

The .nSD file is a binary file stored in Matlab (.mat) format. And thus they can be easily loaded on Matlab with the load command by adding the -mat flag. The file specification is for it to contain a structure called nSD. This structure contains the following fields:

• device: this field is a string containing the name of the target hardware device for the experiment. For example, 'ninjaNIRS'
• lambda: this is a 1 by nLambdas sized numeric array, with each element representing each of the wavelengths (in nanometers) used in the device (for example [690 830]). It is expected for the wavelengths to be ordered from shorter to longer.
• nLambdas: this is an integer that specifies how many different wavelengths the device uses. It should be consistent with the 'lambda' field
• nSrcs: an integer specifying how many sources are in the probe. Right now, it is expected for nSrcs and nDets to be identical, but not necessarily so for other types of devices. This number is independent of the field in the .cfg file. The .cfg file should specify how many sources are connected/available in the device, while this field should specify how many sources are necessary for the particular probe. Thus, nSrcs in the .nSD file needs to be equal or lesser than the number of sources available in the device.
• nDets: similar to nSrcs, but for detectors.
• spatialUnit: string indicating the measurement units used for distances specified on the file (for example 'mm')
• measList: This is a N by 4 integer numeric array. It indicates the source detector pairs, as well as the state and wavelength associated with each fNIRS channel. The first column is the number of the source of the channel, the second is the number of the detector of the channel. The third is the state at which the channel will be active, and the fourth column is the wavelength ID associated to the channel. For example, if the fifth column is [2,6,2,2], it means that the fifth channel is source 2 to detector 6, that this channel will be measured during state 2, and that it used wavelength 2 (second element of the lambda array).
• srcPos: this is a nSrcs by 3 double array. Specifies the (x,y,z) location of each source on the probe. Generally, z=0 is defined as being coincident with the scalp. The units are specified by the spatialUnit string. This information (along with measList) is used for drawing the probe diagram on the GUI. Right now the drawing is 2D and assumes z is always 0. There are plans to make it 3D at some point.
• detPos: similar to srcPos but for detectors.
• nStates: specifies how many states are in the probe design. This feature has not been implemented yet, but the idea is that we will be able to perform time multiplexing to increase the number of available channels. A channel will be active only for the state specified in the measList array.
• srcFreqMap: this field is unused right now, so it is generally empty
• freqMap: this is a nSrcs by nStates by nLambdas numeric array. It specifies the ID of the modulation frequency for each source and wavelength combination at a given state. For example, if freqMap(3,2,1) is 4, it means that the first wavelength of source 3 needs to be modulated at the frequency with an ID of 4 during state 2. freqMap also indicates the intensity level of a light source for certain devices (like ninjaGUI). If the frequency is stored as positive, it means the source needs to be modulated at the given frequency and the light level should be set to "high". If the frequency is negative, the modulation frequency is the same but the light level is set to "low". If the frequency is indicated as zero, then the light source should be off for that given state. Low light levels are used for short separation light sources, to avoid saturating the nearby detector.

There is currently no editor for .nSD files, so they need to be generated manually. This requires the user to figure out the best assignment of frequencies and states for each source detector pair for devices in which those need to be specified (for example, ninjaNIRS).

Important note: at this point, HOMER is not compatible with nSD files. HOMER expects SD files, which contains a structure called SD. Said structure contains most of the fields of the nSD file (and some others not used in the nSD file format) but some of the fields have a different capitalization. A way to make them compatible is by adding a copy of the nSD structure to the nSD file called simply "SD", and renaming the fields in order to be consistent with the capitalization.