You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Proceed to install the toolbox via pip from the main project directory:
17
+
21
18
```bash
22
-
pip install py_vb_toolbox/
19
+
pip install .
23
20
```
24
21
25
-
The installation will automatically install the dependancies specified in the `requirements.txt` file. In your terminal, check to see whether the VB toolbox has been properly installed by running:
22
+
The installation will automatically install the dependencies specified in the requirements.txt file. In your terminal, check to see whether the VB toolbox has been properly installed by running:
26
23
27
24
```bash
28
-
vb_tool
25
+
vb_tool --help
29
26
```
30
27
31
-
If you see the following output, the pre-requisites have been properly installed.
28
+
If you see output similar to the following (specifically showing vb_tool usage and the volumetric subcommand), the prerequisites have been properly installed.
32
29
33
-
```
34
-
usage: app.py [-h] {volumetric} ...
30
+
```bash
31
+
usage: vb_tool [-h] {volumetric} ...
35
32
36
-
Calculate the Vogt-Bailey index of a dataset. For more information, refer to
37
-
https://github.com/VBIndex/py_vb_toolbox.
33
+
Calculate the Vogt-Bailey Index of a dataset. For more information, refer to
{volumetric} Different methods for computing the VB Index
44
-
volumetric Computes the VB Index on volumetric data using a searchlight approach
45
-
46
-
authors:
47
-
48
-
The VB Index Team (See Contributors Section in the main README)
49
-
50
-
references:
51
-
52
-
Bajada, C. J., Campos, L. Q. C., Caspers, S., Muscat, R., Parker, G. J., Ralph, M. A. L., ... & Trujillo-
53
-
Barreto, N. J. (2020). A tutorial and tool for exploring feature similarity gradients with MRI data.
54
-
NeuroImage, 221, 117140.
55
-
56
-
Ciantar, K. G., Farrugia, C., Galdi, P., Scerri, K., Xu, T., & Bajada, C. J. (2022). Geometric effects of
57
-
volume-to-surface mapping of fMRI data. Brain Structure and Function, 227(7), 2457-2464.
58
-
59
-
Farrugia, C., Galdi, P., Irazu, I. A., Scerri, K., & Bajada, C. J. (2024). Local gradient analysis of human
60
-
brain function using the Vogt-Bailey Index. Brain Structure and Function, 229(2), 497-512.
40
+
{volumetric} Different methods for computing the VB Index
41
+
volumetric Computes the VB Index on volumetric data using a searchlight
42
+
approach
61
43
62
-
Galea, K., Escudero, A. A., Montalto, N. A., Vella, N., Smith, R. E., Farrugia, C., ... & Bajada, C. J. (2025).
63
-
Testing the Vogt-Bailey Index using task-based fMRI across pulse sequence protocols. bioRxiv, 2025-02.
64
-
65
-
copyright:
66
-
67
-
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General
68
-
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
69
-
option) any later version.
70
-
71
-
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
72
-
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
73
-
for more details.
74
-
75
-
You should have received a copy of the GNU General Public License along with this program. If not, see
76
-
<https://www.gnu.org/licenses>.
77
44
```
78
45
79
46
## Usage
80
47
81
-
### 1.1 Volumetric VB Index
48
+
### Volumetric VB Index
82
49
83
-
The VB Index has been tested using a searchlight analysis with no surface mapping. This method for running the VB Index
84
-
is referred to as "Volumetric analysis" and can be carried out with the following command:
50
+
This toolbox calculates the VB Index using a searchlight approach directly on volumetric data (NIfTI format). This method is referred to as "Volumetric analysis" and can be carried out with the following command:
This is the simplest way to run this analysis. It will output two files, ```-vol.nii.gz``` and ```-neigh.nii.gz```. The first file is going to store the information from the analysis. On the other hand, the second file is going to store the neighbourhood used for every voxel, so the output should be a cube.
56
+
This is the simplest way to run this analysis. It will output two files using the base name provided with --output and the normalization method used (e.g., volumetric_output.unnorm.vbi-vol.nii.gz and volumetric_output.unnorm.vbi-neigh.nii.gz).
57
+
58
+
* The *.vbi-vol.nii.gz file stores the calculated VB Index (or ReHo value) for each voxel.
59
+
* The *.vbi-neigh.nii.gz file stores the number of neighbours included in the searchlight calculation for each voxel.
91
60
92
-
This may take a while since the tool will try to compute the VB index for every voxel and for every voxel both inside and outside of the brain. In order to speed this up, a volumetric mask can be specified:
61
+
The analysis computes the index for every voxel within the NIfTI file's dimensions. This can take time. To speed this up and restrict the analysis to brain voxels, provide a volumetric brain mask:
The VB Toolbox also supports analysing data with the Regional Homogeneity (ReHo) index [5]. The ReHo index measures the similarity between the Blood Oxygen Level Dependent (BOLD) signal of a voxel with respect to its immediate neighbors. To run ReHo for volumetric analysis:
*(Note: Output filenames will reflect the ReHo analysis, e.g., volumetric_reho_output.unnorm.vbi-vol.nii.gz)*
76
+
106
77
## General Notes
107
78
108
79
### Note on the data file
109
80
110
-
`vb_tool` can handle two separate cases. If there is a single structure in the
111
-
file, `vb_tool` will read it as a matrix in which each row relates to a specific
112
-
vertex. If there are two or more structures, it will read them as a series of
113
-
column vectors in which each entry relates to a vertex. It will then coalesce
114
-
them into a single matrix, and run the analysis of all quantities concurrently.
81
+
The volumetric analysis mode expects input data (--data) as a 4D NIfTI file (e.g., fMRI time series data in .nii or .nii.gz format). The optional mask (--volmask) should be a 3D NIfTI file coregistered with the data file, containing non-zero values for voxels to be included in the analysis.
115
82
116
83
### Notes on parallelism
117
84
118
-
`vb_tool` uses a high level of parallelism. The number of threads spawned by
119
-
`vb_tool` itself can be controlled using the `-j/--jobs` flag. By default, the software
120
-
will try to use all the CPUs in your computer at the same time to perform the
121
-
analysis. Depending on the BLAS installation on your computer, this might not
122
-
be the fastest approach, but will rarely be the slowest. If you are
123
-
unsure, keep the default number of jobs.
124
-
125
-
Due to the job structure of the `vb_tool`, the level of parallelism it can achieve
126
-
on its own depends on the specific analysis being carried out.
85
+
vb_tool uses multiprocessing to speed up computations. The number of parallel processes (threads) can be controlled using the -j or --jobs flag when running the volumetric command. For example:
127
86
128
-
1. Full brain analysis: Low level of parallelism. Will only spawn one job
129
-
2. Region of Interest (ROI) analysis: Medium level of parallelism. Will spawn as many
130
-
jobs as there are ROIs, or number of CPUS, whichever is the lowest.
131
-
3. Any other analysis: High level of parallelism. Will spawn as many jobs as
Especially for the whole brain analysis, having a well-optimized BLAS
135
-
installation will greatly accelerate the process, and allow for further
136
-
parallelism. Both MKL and OpenBLAS have been shown to support fast analysis. If
137
-
you are using the Anaconda distribution, you will have a good BLAS
138
-
pre-configured.
91
+
By default, the software will try to use all available CPU cores. Depending on your system and BLAS installation, adjusting the number of jobs might yield better performance. If unsure, keeping the default is usually a safe starting point.
139
92
140
93
## References
141
-
[1] C. J. Bajada et al., “A tutorial and tool for exploring feature similarity gradients with MRI data,” NeuroImage, vol. 221, pp. 117140–117140, Jul. 2020, doi: https://doi.org/10.1016/j.neuroimage.2020.117140.
94
+
95
+
[1] C. J. Bajada, L. Q. C. Campos, S. Caspers, R. Muscat, G. J. Parker, M. A. Lambon Ralph, ... and N. J. Trujillo-Barreto, (2020). “A tutorial and tool for exploring feature similarity gradients with MRI data,” NeuroImage, vol. 221, pp. 117140–117140, Jul. 2020, doi: https://doi.org/10.1016/j.neuroimage.2020.117140.
142
96
143
97
[2] C. Farrugia, P. Galdi, Irati Arenzana Irazu, K. Scerri, and C. J. Bajada, “Local gradient analysis of human brain function using the Vogt-Bailey Index,” Brain structure & function, vol. 229, no. 2, pp. 497–512, Jan. 2024, doi: https://doi.org/10.1007/s00429-023-02751-7
144
98
145
99
[3] K. G. Ciantar, C. Farrugia, P. Galdi, K. Scerri, T. Xu, and C. J. Bajada, “Geometric effects of volume-to-surface mapping of fMRI data,” Brain Structure and Function, vol. 227, no. 7, pp. 2457–2464, Jul. 2022, doi: https://doi.org/10.1007/s00429-022-02536-4.
146
100
147
-
[4] K. Galea. A. A. Escudero, N. A. Montalto, N. Vella, R. E. Smith, C. Farrugia, P. Galdi, K. Scerri, L. Butler, and C. J. Bajada, “Testing the Vogt-Bailey Index using task-based fMRI across pulse sequence protocols,” bioRxiv, pp. 2025-02, 2025.
101
+
[4] K. Galea. A. A. Escudero, N. A. Montalto, N. Vella, R. E. Smith, C. Farrugia, P. Galdi, K. Scerri, L. Butler, and C. J. Bajada, “Testing the Vogt-Bailey Index using task-based fMRI across pulse sequence protocols,” bioRxiv, pp. 2025-02, 2025.
148
102
149
103
[5] Y. Zang, T. Jiang, Y. Lu, Y. He, and L. Tian, “Regional homogeneity approach to fMRI data analysis,” NeuroImage, vol. 22, no. 1, pp. 394–400, May 2004, doi: https://doi.org/10.1016/j.neuroimage.2003.12.030.
150
104
151
-
152
105
## Contributors ✨
153
-
154
106
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
155
107
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
156
108
<!-- prettier-ignore-start -->
@@ -159,30 +111,15 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
0 commit comments