Loading data, probe registration

Loading Data, probe registraton

Loading Data, probe registraton

1.1 Loading Data

This toolbox can load almost all existing NIRS files. If you have a new NIRS system or a file that cannot be loaded by the toolbox, please reach out to us.
Downloading ‘demo_data’ from the server
clear all
clc
 
if(ismac | isunix)
root_dir = [‘/Users/’ getenv(‘USER’) ‘/Desktop/tmp’];
else
root_dir = [getenv(‘UserProfile’) ‘\Desktop\tmp’];
end
 
if(~exist(root_dir,‘dir’) || ~exist(fullfile(root_dir,‘demo_data’),‘dir’))
mkdir(root_dir);
disp(‘downloading sample data from bitbucket.org site’);
%% download the dataset
urlwrite(‘http://huppertlab.net/wp-content/uploads/2024/05/demo_data.zip’, …
[root_dir filesep ‘demo_data.zip’])
% This command will download the demo_data.zip file from the server. This
% step can be skipped if you already downloaded this. This could take a few minutes if your internet conenction is slow
% The file is about 90Mb in size.
% unzip the data
unzip([root_dir filesep ‘demo_data.zip’],[root_dir filesep]);
% This will unpack a folder called “data” containing two groups (G1 & G2).
% A script “simulation.m” is included which was used to generate the data
% (but is not intended to be run). The data was simulated from a set of
% experimental resting state NIRS data with simulated evoked responses
% added to it to demostrate this analysis pipeline.
else
disp([‘Data found in: ‘ root_dir ‘: skipping download’]);
end
Data found in: /Users/hendriksantosa/Desktop/tmp: skipping download
This example will download one dataset (68 NIRS files) from the toolbox to your local computer (‘Desktop/tmp’)
Screenshot 2024-06-24 at 10.32.32 AM.png
Inside this ‘demo_data’, there are two subfolders ‘G1’ and ‘G2’, each containing several subjects. These subfolders contain individual single *.nirs file.
There are two option to load the NIRS data:
Option 1: Loading a single NIRS data
Please set your current folder to one NIRS file, for example: ‘/Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S68’
raw1 = nirs.io.loadDotNirs(‘scan.nirs’)
Loading scan.nirs Empty file found (skipping): scan.nirs raw1 = 0×0 Data array with properties: description data probe time Fm auxillary stimulus demographics Fs
 
% Here is another option for different NIRS datasets
% nirs.io.loadNIRx
% nirs.io.loadBiopacNIR
% etc
Option 2: Loading all files in a specific directory (Recommended)
This function loads a whole directory of *.nirs files. The second argument tells the function to use the first level of folder names to specify group id (‘group’) and the seond level to specify subject id (‘subject’). The ‘nirs.io.loadDirectory’ module will automatically read any type of NIRS file (do not specify *.nirs or *wl, etc)
raw = nirs.io.loadDirectory([root_dir filesep ‘demo_data’ filesep ‘data’], {‘group’, ‘subject’});
Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S11/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S12/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S13/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S15/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S17/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S19/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S22/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S23/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S27/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S28/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S29/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S30/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S32/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S36/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S37/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S38/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S4/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S40/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S43/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S44/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S46/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S47/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S48/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S49/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S50/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S55/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S57/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S58/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S62/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S63/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S65/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S66/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S68/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S8/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S1/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S10/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S14/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S16/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S18/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S2/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S20/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S21/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S24/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S25/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S26/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S3/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S31/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S33/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S34/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S35/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S39/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S41/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S42/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S45/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S5/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S51/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S52/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S53/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S54/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S56/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S59/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S6/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S60/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S61/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S64/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S67/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S7/scan.nirs Loading /Users/hendriksantosa/Desktop/tmp/demo_data/data/G2/S9/scan.nirs
 
% To see demographics (created from ‘nirs.io.loadDirectory’)
nirs.createDemographicsTable(raw)
ans = 68×2 table
 groupsubject
1‘G1’‘S11’
2‘G1’‘S12’
3‘G1’‘S13’
4‘G1’‘S15’
5‘G1’‘S17’
6‘G1’‘S19’
7‘G1’‘S22’
8‘G1’‘S23’
9‘G1’‘S27’
10‘G1’‘S28’
11‘G1’‘S29’
12‘G1’‘S30’
13‘G1’‘S32’
14‘G1’‘S36’
â‹®
 
% This raw file contain all the information which will be used in the next
% data processing: data, probe, time, Fs, stimulus, demographics, etc
raw(1)
ans =
Data with properties: description: ‘/Users/hendriksantosa/Desktop/tmp/demo_data/data/G1/S11/scan.nirs’ data: [3505×70 double] probe: [1×1 nirs.core.Probe] time: [3505×1 double] Fm: 0 auxillary: [1×1 Dictionary] stimulus: [1×1 Dictionary] demographics: [1×1 Dictionary] Fs: 10
 
To see the raw data
figure; raw(1).draw
 
To see the probe information
raw(1).probe.link
ans = 70×3 table
 sourcedetectortype
111690
211830
312690
412830
516690
616830
721690
821830
922690
1022830
1123690
1223830
1326690
1426830
â‹®
 
To plot the raw(1) data and stimulus info
raw(1).draw
 
To plot hbo and hbr first channel of 690nm data (S1-D1) and 830nm data (S1-D1)
figure; raw(1).draw([1 2])
 
To plot probe configuration
figure; raw(1).probe.draw
 
GUI for visualization
nirs.viz.TimeSeriesViewer(raw)
ans =
TimeSeriesViewer with no properties.

1.2 Remove Data

This example shows how to remove files from the dataset. For example, we want to remove subjects S11, S12, S61, and S64
lst = find(ismember(nirs.createDemographicsTable(raw).subject, {‘S11’, ‘S12’, ‘S61’, ‘S64’}))
lst = 4×1
1 2 64 65
 
raw2 = raw
raw2 = 68×1 Data
 1
11×1 Data
21×1 Data
31×1 Data
41×1 Data
51×1 Data
61×1 Data
71×1 Data
81×1 Data
91×1 Data
101×1 Data
111×1 Data
121×1 Data
131×1 Data
141×1 Data
â‹®
raw2(lst) = [] %This raw2 will contain all previous file except S11, S12, S61, and S64
raw2 = 64×1 Data
 1
11×1 Data
21×1 Data
31×1 Data
41×1 Data
51×1 Data
61×1 Data
71×1 Data
81×1 Data
91×1 Data
101×1 Data
111×1 Data
121×1 Data
131×1 Data
141×1 Data
â‹®

1.3 Quality Report

1.3.1 Scalp Coupling Index

This module computes “scalp coupling index (SCI)” over all channels. This SCI is based on the cross correlation of the two wavelengths of optical data for each channel around the cardiac frequency. In the best data, the cardiac signals at two wavelengths are correlated, thus yielding an SCI close to 1. In contrast, noisy cardiac signals led to a lower SCI value (close to 0). For details, see this paper: Pollonini et. al., 2016 (https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5175555/)
% This module will show the sci from every channel in raw(1)
tblSCI = nirs.util.scalp_coupling_index(raw(1))
tblSCI = 35×5 table
 sourcedetectorscipowerfpower
1110.149601.3568
2120.02120.00011.0030
3160.458800.7961
421-0.00750.00020.8118
5220.045601.0030
6230.03100.00011.1171
7260.305700.7890
8310.05970.00141.5580
933-0.011801.2298
10420.34890.00031.0044
1143-0.015701.4296
12530.052101.0044
13540.03230.00011.3497
1463-0.02720.00010.9802
â‹®

1.4 Export results

We can export all the tables to an Excel file:
writetable(tblSCI, ‘tblSCI.xlsx’) %This will create the excel file of tblSCI in your current folder

1.5 Probe registration

This example show how to register 2D probe into Colin27
clear all
clc
 
raw = nirs.testing.simData;
figure; raw.probe.draw
 
% let’s just center this on the forehead
Name{1}=‘FpZ’;
xyz(1,:)=[0 0 0];
Type{1}=‘FID-anchor’; % This is an anchor point
Units{1}=‘mm’;
 
Name{2}=‘Cz’;
xyz(2,:)=[0 100 0];
Type{2}=‘FID-attractor’; % This is an attractor
Units{2}=‘mm’;
 
Name{3}=‘T7’;
xyz(3,:)=[-200 0 0];
Type{3}=‘FID-attractor’; % This is an attractor
Units{3}=‘mm’;
 
Name{4}=‘T8’;
xyz(4,:)=[200 0 0];
Type{4}=‘FID-attractor’; % This is an attractor
Units{4}=‘mm’;
 
% Create table from that position information
fid=table(Name’,xyz(:,1),xyz(:,2),xyz(:,3),Type’,Units’,…
‘VariableNames’,{‘Name’,‘X’,‘Y’,‘Z’,‘Type’,‘Units’});
% and concatinate it to the probe
raw.probe.optodes=[raw.probe.optodes; fid];
 
% We can change the headsize
headsize=Dictionary();
headsize(‘circumference’)=430; %mm
 
% Register probe to the head
raw.probe=nirs.util.registerprobe1020(raw.probe,headsize);
 
% To visualize
figure; raw.probe.draw1020
 
% Load Colin27 atlas mesh
mesh=nirs.registration.Colin27.mesh;
 
mesh(1).fiducials.Draw(:)=false;
% the mesh is also nested (4-layers), so let’s turn off the display of the
% skin, skull, and dura
mesh(1).transparency=0;
mesh(2).transparency=0;
mesh(3).transparency=0;
 
% Register it to the probe
raw.probe=raw.probe.register_mesh2probe(mesh);
 
% This is all the option:
raw.probe.defaultdrawfcn = ‘?’
Here are the options for drawing configurations {’10-20′ } {’10-20 mercator projection map’ } {’10-20 zoom’ } {’10-20 mercator with restricted view’ } {’10-20 map’ } {’10-20 mercator with underlain image’ } {’10-20 map zoom’ } {’10-20 mercator with underlain image’ } {’10-20 label’ } {’10-20 mercator projection map’ } {’10-20 map zoom label’ } {’10-20 mercator with underlain image’ } {’10-20 ball’ } {’10-20 with underlying circles for heat maps’ } {’10-20 ball zoom’ } {’10-20 with underlying circles for heat maps with restricted view’} {‘3D’ } {‘3D line drawing ‘ } {‘3D mesh’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (frontal)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (left)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (right)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (superior)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (top)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (posterior)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (occipital)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (back)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (inferior)’ } {‘3D line drawing overlain on mesh’ } {‘3D mesh (bottom)’ } {‘3D line drawing overlain on mesh’ } {‘3D ball’ } {‘3D ball and stick drawing overlain on mesh’ } {‘3D label’ } {‘3D line drawing ‘ } {‘3D label mesh’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (frontal)’ } {‘3D line drawing overlain on mesh’ } {‘3D labelmesh (left)’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (right)’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (superior)’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (top)’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (posterior)’} {‘3D line drawing overlain on mesh’ } {‘3D label mesh (occipital)’} {‘3D line drawing overlain on mesh’ } {‘3D label mesh (back)’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (inferior)’ } {‘3D line drawing overlain on mesh’ } {‘3D label mesh (bottom)’ } {‘3D line drawing overlain on mesh’ } {‘3D label ball’ } {‘3D ball and stick drawing overlain on mesh’ } {‘2D’ } {‘2D probe layout’ }
raw =
Data with properties: description: [] data: [3001×32 double] probe: [1×1 nirs.core.Probe1020] time: [3001×1 double] Fm: 0 auxillary: [1×1 Dictionary] stimulus: [1×1 Dictionary] demographics: [1×1 Dictionary] Fs: 10
 
% change the default draw behavior and show the results
raw.probe.defaultdrawfcn=‘3D mesh (frontal)’;
figure; raw.probe.draw;

1.6 Probe sensitivity

We can show how your probe cofiguration relative to Broadman area, see this paper: https://pubmed.ncbi.nlm.nih.gov/28948192, Fig. 9
lstName = {‘ba-9_l’, ‘ba-9_r’, ‘ba-10_l’, ‘ba-10_r’}
lstName = 1×4 cell
‘ba-9_l’ ‘ba-9_r’ ‘ba-10_l’ ‘ba-10_r’
nirs.util.regionmap(lstName, raw(1).probe)
Warning: Limiting legend entries to 50. Specify a vector of graphics objects to display more than 50 entries.