/
README.html
492 lines (335 loc) · 36 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
h1,h2,h3,h4,p,div,li,td { font-family: Calibri, Geneva, sans-serif; }
p { font-size: 12pt; text-align: justify; }
p.ph1 { margin-top: 0px; margin-bottom: 0px; padding-top: 0px; padding-bottom: 0px; padding-left: 28px; font-size: 14pt; }
p.ph2 { margin-top: 0px; margin-bottom: 0px; padding-top: 0px; padding-bottom: 0px; padding-left: 58px; font-weight: bold; }
p.ph3 { margin-top: 0px; margin-bottom: 0px; padding-top: 0px; padding-bottom: 0px; padding-left: 88px; }
p.ph4 { margin-top: 0px; margin-bottom: 0px; padding-top: 0px; padding-bottom: 0px; padding-left: 118px; font-size: 10pt; }
p.titlepage { font-size: 36pt; font-weight: bold; text-align: left; }
div.footnote { font-size: 9pt; }
div.matlabcode { font-family: "Courier New", Courier, monospace; font-size: 11pt; border: 1px solid #cccccc; background-color: #e8e8e8; }
span.nefile { font-family: "Courier New", Courier, monospace; font-size: 11pt; font-weight: bold; }
span.nefunction { font-weight: bold; color: #cc0000; }
@media print {
h1 { page-break-before: always; }
a.pageref::after { content: leader('.') target-counter(attr(href), page); }
}
@page { size: 7in 9.25in; margin: 25mm 25mm 25mm 25mm; }
</style>
</head>
<body>
<p class="titlepage">NeuroElf v1.1</p>
<h2>User manual</h2>
<h3>Jochen Weber, Columbia University</h3>
<p><br /><br /><img src="_files/manual/NE_gui_empty.png" width=1000 height=740 alt="NeuroElf GUI without datasets" /><br />
<div class="footnote">NeuroElf GUI, without datasets</div></p>
<h1>Index</h1>
<p class="ph1"><a class="pageref" href="#preface">Preface</a></p>
<p class="ph2"><a class="pageref" href="#whatisneuroelf">What NeuroElf is and what it's not</a></p>
<p class="ph2"><a class="pageref" href="#acknowledgments">Acknowledgments</a></p>
<p class="ph1"><a class="pageref" href="#overview">Overview</a></p>
<a name="preface"><h1>Preface</h1></a>
<a name="whatisneuroelf"><h2>What NeuroElf is and what it's not</h2></a>
<p>NeuroElf is a MATLAB toolbox supposed to facilitate a sub-set of
neuro-functional imaging applications (preprocessing, regressions,
visualization, post-hoc data extraction and analyses, etc.). The GUI
(graphical user interface) that comes with NeuroElf is able to visualize
and work on typically used voxel-based (and selected surface) file
formats. The best analogy that comes to mind is that of a Swiss Army
knife of neuro-functional imaging tools. That being said, it's important
to understand what NeuroElf is not...</p>
<p>NeuroElf is, in itself, not a toolbox or program with which all
aspects of imaging applications can be done. Most importantly, it does
not come with a full set of preprocessing routines, mainly spatial
normalization to a template space, and it thus requires at least one
other major neuro-imaging application, such as SPM, FSL, or BrainVoyager
QX to bring raw scanner data into a format and representation that
allows group-based analyses. As a method of choice, SPM-based
preprocessing can be easily configured and executed using a separate
graphical interface in NeuroElf.</p>
<p>Generally speaking, the functionality implemented in NeuroElf can be
understood as a set of tools that will facilitate and complement the
(pre-) processing, as it is implemented in SPM5 or SPM8 (SPM12 support
will be added shortly) as well as provide the user with relatively easy
to script functions to access and visualize the resulting data. On its
own, it allows to run either ordinary-least-squares or robust
regressions on preprocessed data files, with a variety of options for
nuisance regressors, parametric regression, (non-deconvolved and
re-convolved) PPI, seed-correlations, and a relatively simple to use
contrast manager together with beta extraction and time course plotting
capabilities.</p>
<p>Most of the focus and effort in developing and implementing NeuroElf
has been placed on making these processes as accessible and hassle-free
as possible for the non-Computer-Science user, i.e. for
psychologists.</p>
<p>Another large portion of features in NeuroElf relates to the
visualization and ease of extracting data after an analysis has been
run. To that end, NeuroElf features high-resolution slice-based
montages--i.e. overlaying statistical information as colored heat-maps
on anatomical data--, surface-based representation of data, and a 3D
rendering engine. Additional features also include a beta plotter (more
on that later), and a graphical interface visualizing stimulus
onset-locked region-averaged time courses (event-related averaging).</p>
<p>In short, some of the main reasons to use NeuroElf are to simplify
SPM-based preprocessing, to perform regression analyses, and to
visualize and dig into the results of those.</p>
<p>Some additional tools, such as (single-level) mediation analyses,
meta analyses, single-run ICA, linear classification, etc. are
available, but not all of these have yet been fully implemented in the
GUI, and as such may only be fully utilized by a more experienced MATLAB
user. If you find a tool that you believe is suitable for inclusion in
NeuroElf, please feel free to contact me with a request at
info@neuroelf.net.</p>
<a name="acknowledgments"><h2>Acknowledgments</h2></a>
<p>While most of the coding has been done by the main author, the
following people deserve special mention for their countless
contributions to the process of making and improving on NeuroElf:</p>
<p>Hedy Kober, who is now an Assistant Professor of Psychiatry and
Psychology at Yale University, New Haven, CT. Hedy has, over the years,
been extremely helpful by suggesting countless improvements in the user interface and in pointing out several bugs and issues. In addition, she has been a good friend and her very enthusiastic approach to NeuroElf and advocacy outside of Columbia University certainly kept it from ever becoming a "dead-end project".</p>
<p>Kevin Ochsner, who is a Professor of Psychology at Columbia University, New York, NY, has provided the means and, also funded by his research grants, most of the datasets on which NeuroElf's features were tested initially.</p>
<p>Additionally, thanks go to Cameron DeLeone, Federico DeMartino, Bryan Denny, Fabrizio Esposito, Andrew Gerber, Rainer Goebel, Armin Heinecke, Katie Insel, Zoran Josipovic, Jenna Reinen, Ajay Satpute, Jen Silvers, Jared van Snellenberg, and Noam Zerubavel, for being heavy users and contributors to the process of making NeuroElf a better version of itself over time, by finding bugs and sharing their preferences for working with functional imaging data, which makes the foundation of a user-friendly UI.</p>
<p>Some code has been loaned from other authors:</p>
<ul>
<li>Chih-Chung Chang and Chih-Jen Lin, the authors of LIBSVM</li>
<li>Aapo Hyvärinen, the author of the FastICA algorithm</li>
<li>Dirk-Jan Kroon, the author of the shear-warp rendering algorithm</li>
</ul>
<p>And last but not least, I thank my partner, Changyu Zhu, who supports me at times when things seem a bit pointless, so I keep moving on anyway.</p>
<a name="overview"><h1>Overview</h1></a>
<p>The NeuroElf toolbox has three main components, a graphical user interface (<span class="nefunction">neuroelf_gui</span>), a file handling class (<span class="nefile">@xff</span>) and a library of functions for general data processing (<span class="nefile">@neuroelf</span>).</p>
<p>This readme (manual) uses the following notation: two greater-than symbols at the beginning of a paragraph (>>) in a "code box" indicate a single line of code to be entered at the MATLAB prompt (please enter without the >> symbols!). For a longer paragraph of code, an initial line (and possibly one or several subsequent lines) will begin with a per-cent symbol (%) indicating a MATLAB comment.</p>
<h2>Installation</h2>
<p>Depending on whether you downloaded the installation M-file+MAT-file version or the flat folder version, instructions slightly differ.</p>
<p>The archive containing NeuroElf is about 20 Megabytes in length. Once unpacked and installed, NeuroElf requires at least 100 Megabyte and, if all additional files are created, can require as much as 2.5 Gigabyte of disk space. So please make sure that the folder you choose as installation folder is on a medium that offers enough free space (i.e. does not come with a hard limitation or quota).</p>
<p>Please be aware that as a user of NeuroElf, you should have write-access to a few critical folders located in the <span class="nefile">_files</span> folder, and also the files located in the <span class="nefile">_core/config</span> folder. Without write access in these folders some functions may not work properly!</p>
<h3>M-file version installation</h3>
<p>To install NeuroElf, unzip the content (three files: <span class="nefile">NeuroElf_v10.m</span>, <span class="nefile">NeuroElf_v10.mat</span>, and <span class="nefile">ne_eo.m</span>), then open MATLAB and change the current folder into the folder containing those three files. Then enter</p>
<div class="matlabcode">>> NeuroElf_v10 -i</div>
<p>to start the installation process. You will be asked where to install the toolbox, with the default being the toolbox folder of your MATLAB installation. If you do not have write permissions in that folder, please choose "n" when being asked whether this is a good location and then enter a more suitable folder path. If in doubt, enter a path within your home folder (unless there is a quota restriction in place, at which point you should talk to your system administrator to determine a good location).</p>
<h3>Flat folder version installation</h3>
<p>Simply unzip the archive and move the unpacked files into a folder where you would like to install the toolbox. This should be a folder without spaces or other non alphanumeric characters in its full path and name.</p>
<h3>NeuroElf setup function</h3>
<p>After the files are successfully unpacked, the function <span class="nefunction">neuroelf_setup</span> must be called. If you installed using the M-file version, this will be done automatically. Otherwise, please enter</p>
<div class="matlabcode">>> neuroelf_setup</div>
<p>at the MATLAB prompt manually. This function ensures that the toolbox has been correctly installed and is functional. At the end of this procedure, you will be asked whether <span class="nefunction">neuroelf_makefiles</span> (from the <span class="nefile">@neuroelf</span> library) should be called as well. If you have also downloaded the auxiliary files (Colin brain, etc.; see below) and unpacked those into the <span class="nefile">_files/colin</span> subfolder of the installation, you can safely say no. Otherwise, it is recommended that you let NeuroElf generate these additional files (which will take somewhere between 20 and 50 minutes, depending on your computer's speed and available free memory).</p>
<h2>Folder structure</h2>
<p>The installation folder has the following folder structure:</p>
<ul>
<li><span class="nefile">@neuroelf/ </span> - class containing the function library within its private subfolder</li>
<li><span class="nefile">@transimg/ </span> - class used to blend 2D (RGB) images together</li>
<li><span class="nefile">@transio/ </span> - class allowing transparent IO file access (for large datasets)</li>
<li><span class="nefile">@xff/ </span> - class giving access to a variety of file formats (including functions/methods)</li>
<li><span class="nefile">@xfigure/ </span> - class providing object-oriented design patterns for to MATLAB's graphics handles</li>
<li><span class="nefile">@xini/ </span> - class providing an interface to *.ini configuration files</li>
<li><span class="nefile">@xprogress/</span> - simplified class for progress bars</li>
<li><span class="nefile">_core/ </span> - control, text, and image files required for NeuroElf's core functionality</li>
<li><span class="nefile">_files/ </span> - auxiliary files required for additional functions</li>
</ul>
<h2>Files coming with NeuroElf</h2>
<p>NeuroElf comes with a 1-mm resolution version of Colin Holmes' 27-scan average brain image, and a set of derived images and surface reconstructions is generated during the <span class="nefunction">neuroelf_makefiles</span> call, including 0.5-mm resolution versions for improved visualizations, sub-cortical surfaces, as well as flattened meshes and a head mesh for more complex surface scenes. These files must be located in the <span class="nefile">_files/colin</span> subfolder of the installation. Some preliminary masks have also been derived from this dataset, and those are stored in the <span class="nefile">_files/masks</span> subfolder.</p>
<p>In addition, NeuroElf contains a copy of the original Talairach labeled brain atlas, together with transformation files that relate this atlas approximately to ICBM/MNI space (derived using SPM8's segmentation on a ternary labeled version of the atlas). Files related to the Talairach atlas are located in the <span class="nefile">_files/tal</span> subfolder.</p>
<p>Lastly, the <span class="nefunction">neuroelf_makefiles</span> function optionally downloads and installs a 1-mm resolution full-brain, anatomical-T1 DARTEL template from NeuroElf's website to allow using SPM8's DARTEL tools to warp any subject's brain (anatomical and functional data, if aligned) to a slightly better matching ICBM/MNI space. This template was derived from 305 anatomical scans collected at Columbia University over the course of 11 studies, and also included Colin Holmes' 27-scan average brain. These files will be stored in the <span class="nefile">_files/spm/dartel/Template1mm</span> subfolder.</p>
<p>Further subfolders in the <span class="nefile">_files</span> folder contain the cached information of the <span class="nefile">@xff</span> class (which speeds up initializing NeuroElf considerably across MATLAB sessions); additional M-files in the <span class="nefile">_files/contrib</span> folder that may be of interest for users who want to script NeuroElf; files downloaded from NeuroSynth (via the File -> NeuroSynth maps menu entry in the GUI) will be stored in <span class="nefile">_files/neurosynth/terms</span>; SPM processing job specification files are stored in <span class="nefile">_files/spm</span>; and a small set of predefined surface files (sphere, cylinder, cube) are located in <span class="nefile">_files/srf</span>.</p>
<h1>The NeuroElf GUI</h1>
<p>The GUI component can be started up by entering</p>
<div class="matlabcode">>> neuroelf_gui</div>
<p>on the MATLAB prompt. Below is a screenshot of the GUI with some areas highlighted that will be explained in greater detail in this chapter.</p>
<p><img src="_files/manual/NE_gui_areas.png" width=1000 height=740 alt="NeuroElf GUI with highlighted areas" />
<div class="footnote">NeuroElf GUI with highlighted areas: 1. Menu; 2. Object selector; 3a. Statistical map selector; 3b. Statistical map configuration; 4. Cluster/VOI tools; 5. Drawing tools; 6. Slice-based dataset view and browsing controls</div>
<h2>GUI outline</h2>
<p>The highlighted areas are:</p>
<p><b>1. </b>Menu: used to configure NeuroElf (mostly under the File -> Options menu entry) and call functions or open additional UIs (e.g. for the GLM contrast manager or montage configuration).</p>
<p><b>2. </b>File selector: used to switch between loaded objects, to set the orientation (translation, rotation, size) for objects, and to close (unload) the currently selected object--both for anatomical and statistical datasets.</p>
<p><b>3a. </b>Statistical map selector: used to select one or multiple maps (in the same dataset); the button functions are</p>
<table border=0 cellpadding=0><tr><td rowspan=9 height=196><img src="_files/manual/NE_stats_buttons.png" height=196 width=25 alt="NeuroElf GUI statistical map tool buttons" /></td>
<td height=22>move selected map(s) up the list</td></tr>
<tr><td height=20>move selected map(s) down the list</td></tr>
<tr><td height=20>inspect and/or change map properties (name, stats type, DF)</td></tr>
<tr><td height=20>delete selected map(s) from the container object </td></tr>
<tr><td height=16></td>
<tr><td height=20>compute a formula (expression) on map values</td></tr>
<tr><td height=20>sample selected maps into surface space (with selected surfaces)</td></tr>
<tr><td height=20>open GLM beta plotter (if GLM selected or referenced)</td></tr>
<tr><td height=20>select maps with same name across subjects (for GLMs)</td></tr>
</table>
<p><b>3b. </b>Statistical map configuration: used to configure a single statistical map (thresholds, visible tails, cluster size thresholding, coloring).</p>
<table border=0><tr><td height=144><img src="_files/manual/NE_stats_buttons2.png" height=144 width=280 alt="NeuroElf GUI statistical map configuration" /></td>
<td>The two edit boxes with values represent the lower and upper threshold for the currently selected (single) map. All statistical values (absolutely) below the lower boundary will not be shown (transparent). For LUT configuration, values will be scaled between 1 and the number of lookup-colors defined in the LUT and then be shown in that color. For RGB configuration, all values above the upper boundary will be shown in the colors configured with the "++" and "--" buttons (depending on the sign of the statistic and enabled tails). Values inbetween the boundaries will be shown in a color between the "+" and "++" color for the positive tail or between the "-" and "--" colors for the negative tail. The p-value dropdown can be used to set a specific p-value as the lower boundary. The p-value will be converted into the appropriate statistical threshold by NeuroElf. In addition to a "height threshold", a cluster size (extent) threshold can be set in the edit box following the "k-thresh:" label and enable with the checkbox right before.</td></table>
<p><b>4. </b>Cluster/VOI tools: used to select a cluster and update the cursor position to its peak coordinate, also possibly auto-extracting data from clusters. The buttons can be used to:</p>
<table border=0 cellpadding=0><tr><td rowspan=10 height=224><img src="_files/manual/NE_VOI_buttons.png" height=224 width=25 alt="NeuroElf GUI VOI tool buttons" /></td>
<td height=22>highlight selected clusters in VMR</td></tr>
<tr><td height=20>restrict selected clusters to a sphere around the peak (or create spherical ROI)</td></tr>
<tr><td height=20>add VOI from Talairach atlas labels</td></tr>
<tr><td height=20>goto cluster peak closest to current browsing location</td></tr>
<tr><td height=20>zoom in on currently selected cluster</td></tr>
<tr><td height=20>cluster properties (not yet implemented)</td></tr>
<tr><td height=20>remove selected clusters</td></tr>
<tr><td height=20>open (or add) VOI file from disk to list of clusters</td></tr>
<tr><td height=20>save list of clusters into VOI file</td></tr>
<tr><td height=20>manually trigger data extraction from selected clusters (from GLM)</td></tr>
</table>
<p><b>5. </b>Drawing tools: used to configure the drawing pen and perform image operations.</p>
<table border=0 cellpadding=0><tr><td rowspan=3 height=68><img src="_files/manual/NE_draw_buttons1.png" height=68 width=24 alt="NeuroElf GUI drawing tool buttons (1)" /></td>
<td height=22>disable drawing mode (set to simple browsing mode)</td></tr>
<tr><td height=20>configure and enable 2D (within-slice) drawing mode</td></tr>
<tr><td height=20>configure and enable 3D (volumetric) drawing mode</td></tr>
<tr><td rowspan=5 height=110><img src="_files/manual/NE_draw_buttons2.png" height=110 width=24 alt="NeuroElf GUI drawing tool buttons (2)" /></td>
<td height=22>perform flood-fill operation within value range from current position</td></tr>
<tr><td height=20>perform grow-region operation (extend marked voxels by 1 within range)</td></tr>
<tr><td height=20>smooth voxels within selected value range (and bounding box)</td></tr>
<tr><td height=20>smooth marking (incl. threshold and bounding box)</td></tr>
<tr><td height=20>smooth within detected borders (not yet implemented)</td></tr>
<tr><td height=20><img src="_files/manual/NE_draw_buttonsu.png" height=22 width=24 alt="NeuroElf GUI drawing tool buttons (undo)" /></td>
<td height=20>toggle between regular and "undo-" painting modes</td></tr>
<tr><td rowspan=5 height=110><img src="_files/manual/NE_draw_buttons3.png" height=110 width=24 alt="NeuroElf GUI drawing tool buttons (3)" /></td>
<td height=22>accept changes (to buffer)</td></tr>
<tr><td height=20>revert changes (from buffer)</td></tr>
<tr><td height=20>reload entire dataset from disk</td></tr>
<tr><td height=20>reload marked voxels (from buffer)</td></tr>
<tr><td height=20>reload all but marked voxels (from buffer)</td></tr>
<tr><td rowspan=3 height=66><img src="_files/manual/NE_draw_buttons4.png" height=66 width=24 alt="NeuroElf GUI drawing tool buttons (4)" /></td>
<td height=22>define ROI/VOI from marked voxels</td></tr>
<tr><td height=20>set underlay object (for enhanced drawing or registration check)</td></tr>
<tr><td height=20>toggle between regular and V16 data for VMR objects</td></tr>
</table>
<p>Most functions that are invoked by the GUI (e.g. updating the slicing position, particularly when statistical maps are overlaid on voxel-based object) can be scripted by adding the sub-function and required options as arguments to the call to <span class="nefunction">neuroelf_gui</span>, such as in</p>
<div class="matlabcode">>> neuroelf_gui('setslicepos', [-16, -24, -16]);</div>
<p>or</p>
<div class="matlabcode">
% set the surface viewpoint of satellite BS1a2b3c to 135-mark-45 degrees,<br />
% [0, 0, 0] translation, and a 1.25 zoom factor at virtual time index 0<br />
neuroelf_gui('setsurfpos', 'BS1a2b3c', {135, 45, [0, 0, 0], 1.25, 0});<br /><br />
% save a screenshot of that satellite into "surface_135_45_zoom125.png"<br />
% using the high-quality settings<br />
neuroelf_gui('screenshot', 'BS1a2b3c', 'surface_135_45_zoom125.png', 'high-q');
</div>
<p>This allows to script functions ranging from data processing to visualization, also making it possible to create animation movies! The sections describing the main functionality of the GUI below contain the name and prototypical use of the underlying function and, where applicable, a brief example. If a function is, for example, implemented in the file @neuroelf/private/ne_screenshot.m, the function can be called with <b>neuroelf_gui('screenshot', ARGUMENTS{:});</b>.</p>
<p>To get help about a specific function, such as "screenshot", use:</p>
<div class="matlabcode">>>neuroelf_gui('help', 'screenshot')</div>
<h2>GUI functions overview</h2>
<p>Some of the main functions of the GUI (above and beyond the library of functions discussed in a later chapter) are</p>
<ul>
<li>loading most supported file formats into the viewer (Analyze/NIFTI files representing anatomical, time-course, and statistical data; as well as BrainVoyager QX file formats and AFNI's HEAD/BRIK format)</li>
<li>loading BrainVoyager surfaces (SRF) into the surface view</li>
<li>overlaying multiple statistical maps on anatomical data (as long as they are in the same object container, such as a multi-volume NIFTI or VMP)</li>
<li>displaying RGB-coded data (multi-colored anatomical datasets, NIFTI)</li>
<li>drawing on/into anatomical and RGB data</li>
<li>create surface reconstructions from binary (foreground/background) images</li>
<li>blending two anatomical datasets (to check registration or to allow painting in specific areas)</li>
<li>displaying multiple surfaces together</li>
<li>undocking a view into satellites (which are live and can be linked to the main viewer)</li>
<li>morphing surfaces to a target intensity in a voxel-based image</li>
<li>smoothing surfaces (inflation, to-sphere morphs)</li>
<li>morphing surfaces using a "virtual time axis"</li>
<li>sampling statistical maps into surface space</li>
<li>displaying time-courses at cursor for 4D objects (NIFTI, VTC)</li>
<li>configuring multi-study (random- and fixed-effects) GLMs (MDM)</li>
<li>computing contrasts/correlations for random- and fixed-effects GLMs</li>
<li>computing instantaneous seed-correlation maps (VTC only)</li>
<li>computing arbitrary formulas on existing maps (VMP only)</li>
<li>running mediation analyses on RFX-GLMs (single-level)</li>
<li>performing meta-analyses (using PLP format)</li>
<li>loading fMRI quality check and motion parameters for visual inspection</li>
<li>creating high-quality slice-, render-, and surface-based visualizations</li>
<li>averaging anatomical files for a group-based dataset for stats overlay</li>
</ul>
<h3>Loading datasets</h3>
<p>Use the File -> Open... menu entry (COMMAND/CTRL + o) to select any of the following formats to be loaded into the viewer:</p>
<ul>
<li>VMR (BrainVoyager's voxel-based MR datasets)</li>
<li>HDR/NII (Analyze/NIftI datasets) --to load statistical data, please use File -> Open file as stats..., *.nii.gz supported</li>
<li>HEAD (AFNI's HEAD+BRIK datasets)</li>
<li>SRF (BrainVoyager's surface datasets) --also used for fiber-trackings</li>
<li>VMP (BrainVoyager's voxel-based map datasets; extended content in .Map.RunTimeVars)</li>
<li>SMP (BrainVoyager's surface-based map datasets; extended content in .Map.RunTimeVars)</li>
<li>GLM (BrainVoyager's General Linear Model datasets; extended content in .RunTimeVars)</li>
<li>VTC (BrainVoyager's voxel-based 4D time course datasets; extended content in .RunTimeVars)</li>
<li>MSK (BrainVoyager's mask datasets)</li>
<li>FMR (BrainVoyager's slice-based functional MR datasets; STC loaded automatically)</li>
<li>AMR (BrainVoyager's anatomical-information MR datasets)</li>
<li>MAP (BrainVoyager's slice-based map datasets; obsolete)</li>
<li>DMR (BrainVoyager's diffusion MR datasets; DWI loaded automatically)</li>
</ul>
<p>NIftI files that are gzip-compressed (*.nii.gz) will be decompressed in a temporary folder prior to being rendered.</p>
<p>Currently, only NIftI files can be used to store RGB data in a (X, Y, Z, 1, 3)-sized dataset. To convert a VMR into an RGB dataset use the VMR -> Export as RGB Nifti menu entry.</p>
<p>Loading datasets is coded in functions @neuroelf/private/ne_openfile.m and @neuroelf/private/ne_openstatsfile.m. To call this function in a script, use neuroelf_gui('openfile', FILENAME) or neuroelf_gui('openstatsfile', FILENAME) for HDR/NII files.</p>
<h3>General browsing</h3>
<p>To change the slicing position, simply click into the displayed (voxel-based) dataset at a new position. Alternatively, coordinates can be entered either as real-world (MNI or TAL, depending on dataset) coordinates or as (1-based) voxel indices into the current dataset. For datasets that contain 4D time series, the volume can be selected by either entering the number into the respecting edit box or by clicking into the displayed time course.</p>
<h3>Overlaying maps</h3>
<p>To overlay statistical data on an anatomical dataset, load both a VMR/HDR/NII/HEAD object (or use the packaged Colin dataset) as well as a statistical map object (VMP or HDR/NII with File -> Open file as stats...).</p>
<p>Once the statistical maps are loaded, the first list box in the left column of controls can be used to select one or multiple maps (if the format supports those).</p>
<p>If a single map is selected, the controls that configure the map (lower and upper threshold, positive/negative tail of a distribution, cluster size thresholding, and coloration settings) can be used.</p>
<p>The p-value dropdown control will not be updated when a map is changed and only functions as a way to set the thresholds (no read-out of currently set thresholds). If the cluster size thresholding is enabled and cluster size thresholds have been determined--either via alphasim for regular maps or as part of the simulation for meta-analysis maps--the p-value dropdown will also update the cluster size threshold accordingly.</p>
<p>Further thresholding options for VMP-based maps are available via the VMP -> Thresholding sub menu.</p>
<p>Slicing and overlaying data is coded in function @neuroelf/private/ne_setslicepos.m and for satellites in @neuroelf/private/ne_setsatslicepos.m. Scripting of this function (e.g. for screenshots) is possible via neuroelf_gui('setslicepos', [X, Y, Z]) or neuroelf_gui('setsatslicepos', 'BS1a2b3c', [X, Y, Z]).</p>
<h3>Drawing tools</h3>
<p>The drawing tools can be invoked using either the regular pen icon (second from the top on the left side of the brain slicing) to paint only into the selected slice or by using the 3D pen icon (below), to paint in all three dimensions.</p>
<p>When the drawing is enabled for the first time (or another operation is performed that alters the dataset), an undo-buffer will be stored in the associated object's .RunTimeVars.UndoBuffer field, from which voxels that are to be recovered will be read.</p>
<p>The configuration dialog that pops up allows to set a radius size and shape (circle/sphere or square/cube) as well as a color code.</p>
<p>For VMR datasets (which store voxel values as unsigned 8-bit integers), the color codes 226 through 245 represent the 10 main positive-tail colors (226 through 235, from red to yellow) and the 10 main negative-tail colors (236 through 245, from blue to cyan) with a default color of 240, mimicking BrainVoyager's behavior. The color codes 246 through 255 are all plain white but can be used to differentiate different labels. If a VMR dataset has an associated (and automatically loaded) V16-file, drawing can also be made into this dataset by switching to V16-mode using the respective button (bottom-most buton in the drawing tools).</p>
<p>For non-VMR datasets, the color range is only restricted by the datatype of the underlying file/object.</p>
<p>For RGB datasets, three values can be entered to represent the three components (e.g. 255 0 255 for deep purple voxels).</p>
<p>In addition to regular, positive color codes (which will simply be written into the dataset), three special value ranges exist with extended functionality:</p>
<ul>
<li>values in the range of -Infinity and -4 (not including) will be used as a "subtraction" from the original values in the .RunTimeVars.UndoBuffer field, allowing to reduce the intensity of voxels by a specific value</li>
<li>values in the range of -4 (including) and -2 (not including) will be used as a "multiplication" factor for the original values in the .RunTimeVars.UndoBuffer, such that -3.5 leads to a 1.5-factor multiplication and -2.3 leads to a 0.3-factor multiplication, a.s.f.</li>
<li>values in the range of -2 (including) and 0 (not including) will be used as a multiplication factor for the current values in the voxels, with the same logic such that -1.5 leads to a 1.5-factor and -0.3 leads to a 0.3 factor multiplication</li>
</ul>
<p>Drawing can be restricted to affect only voxels within a specific range (useful to draw, for instance, only over white matter or gray matter voxels).</p>
<p>And lastly, a smoothness operator can be applied to the pen, such that values will be a mix between the current and the new values according to a Gaussian kernel function.</p>
<p>Additional functions that are part of the drawing tools are (from the forth button downwards)</p>
<ul>
<li>flood filling a dataset, for which all voxels, beginning with the currently selected coordinate, are being filled so long as they are within the specified value range and are connected to the already "filled" voxels</li>
<li>extending the marked voxels into a specified value range by at most 1 voxel in each direction (grow-region alrogithm)</li>
<li>smoothing (which can be restricted to a cuboid-shaped subportion of the dataset as well as to a value range)</li>
<li>smoothing of the marked voxels (by retrieving non-marked voxels from the .RunTimeVars.UndoBuffer)</li>
<li>smoothing within detected borders (not yet fully implemented, and non-functional in the GUI for now)</li>
<li>switching between drawing and undo modes</li>
<li>accepting changes (thus re-copying voxels to .RunTimeVars.UndoBuffer)</li>
<li>revering all changes (copying the full .RunTimeVars.UndoBuffer back)</li>
<li>reloading the dataset from disk</li>
<li>reloading only the voxels that are marked (setting all others to 0)</li>
<li>reloading all by the marked voxels (setting the marked voxels to 0)</li>
<li>create a ROI (in the currently held VOI object) from the voxels marked in one value</li>
<li>setting an underlay object (see below)</li>
<li>switching between VMR and V16 datasets (for VMRs only)</li>
</ul>
<p>The drawing function itself is implemented in @neuroelf/private/ne_draw.m. Scripting of this function (e.g. to draw a specific shape or remove a specific area from a dataset) can be done with neuroelf_gui('draw', [X, Y, Z] [, SLICINGDIRECTION]). The function that controls the drawing mode is implemented in @neuroelf/private/ne_setdrawmode.m, and before using this via script, it is recommended to read the help from neuroelf_gui('help', 'setdrawmode').</p>
<h3>Surface reconstruction</h3>
<p>This function allows binary VMR datasets (where voxels are either 0 or have a unique, common foreground value, usually 240) to be represented as a surface mesh. A marching-cubes algorithm is applied and the resulting surface (SRF object) is added to the viewer and shown.</p>
<p>The algorithms are implemented in @neuroelf/private/ne_vmr_dbreco, which uses @xff/private/vmr_DBReco.m and @neuroelf/private/mesh_reconstruct.c. To invoke this function use neuroelf_gui('vmr_dbreco');</p>
<h3>Blending two anatomical datasets</h3>
<p>For the purpose of registration checking and secure paiting (such that voxels in an original dataset will not be touched), NeuroElf has the feature to display a mixing of two anatomical objects (that need not be of the same type or in the same space). To enable this feature, click the cyan-colored brain button above the "V16" button on the left side of the brain slices. Next, select a dataset (other than the currently displayed one).</p>
<p>To configure the type of blending, use the options in File -> Options -> Underlay blending mode.</p>
<p>The blending function itself is implemented in @neuroelf/private/montagemix.m.</p>
<h3>Undocking view into satellites</h3>
<p>To undock a current view into a satellite figure (UI without dataset selection and map configuration controls), click the "pop-out" button in the top right corner. The newly created figure remains browsable, and can be position/viewpoint linked to the main viewer by enabling the "linked-browsing mode" either with the button below or by selecting File -> Options -> Linked browsing with satellites from the menu.</p>
<p>The undocking itself is implemented in @neuroelf/private/ne_undock.m and can be invoked with neuroelf_gui('undock'). Importantly, make sure to retrieve the outputs of that function call to further access the undocked figure and use its identifier for calls to, say, the screenshot function:</p>
<div class="matlabcode">
% switch to surface view (of the main UI)<br />
neuroelf_gui('showpage', 3);<br /><br />
% undock the main viewer (surface now) into a satellite, store info<br />
[sat_handle, sat_tags, sat_id] = neuroelf_gui('undock');<br /><br />
% create a screenshot with high-quality settings<br />
neuroelf_gui('screenshot', sat_id, FILENAME, 'high-q');<br /><br />
% then close the window to clean up<br />
neuroelf_gui('closesatwindow', sat_id);
</div>
<h2>GLM computation (MDM configuration)</h2>
<h2>GLM contrast manager</h2>
<p>After performing the first-level regression of beta estimates (how much signal variation is due to the independent variables given in the design matrices, at best measured in a normalized way, e.g. after percent-signal-change transformation), a typical way to procede is to compute random-effects summary statistic maps. For this purpose the NeuroElf GUI comes with a contrast manager:</p>
<h2>GLM beta plotter</h2>
<h2>Time course averaging</h2>
<h1>Function library</h1>
<p>The second main component is a library of underlying functions which can, in themselves, be used for other, non-functional-imaging related, more general purposes.</p>
<p>To get access to these functions, create a variable from the @neuroelf class constructor:</p>
<div class="matlabcode">>> netools = neuroelf;</div>
<p>After this, the functions are accessible via the fields of this object variable:</p>
<div class="matlabcode">>> list_of_files = netools.findfiles(startfolder, pattern);</div>
<h1>Version history</h1>
</body>
</html>