README.md

VBIndex

Vogt-Bailey index [1-4] toolbox in Python

Installation as a Python package

Clone the repository:

git clone https://github.com/VBIndex/py_vb_toolbox.git
cd py_vb_toolbox

Proceed to install the toolbox via pip from the main project directory:

pip install .

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:

vb_tool --help

If you see output similar to the following (specifically showing vb_tool usage and the volumetric subcommand), the prerequisites have been properly installed.

usage: vb_tool [-h] {volumetric} ...

Calculate the Vogt-Bailey Index of a dataset. For more information, refer to
[https://github.com/VBIndex/py_vb_toolbox](https://github.com/VBIndex/py_vb_toolbox).

options:
  -h, --help      show this help message and exit

VB method:
  {volumetric}  Different methods for computing the VB Index
    volumetric    Computes the VB Index on volumetric data using a searchlight
                  approach

Usage

Volumetric VB Index

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:

vb_tool volumetric --data input_data/data.nii.gz --output volumetric_output

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).

• The *.vbi-vol.nii.gz file stores the calculated VB Index (or ReHo value) for each voxel.
• The *.vbi-neigh.nii.gz file stores the number of neighbours included in the searchlight calculation for each voxel.

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:

vb_tool volumetric --data input_data/data.nii.gz --volmask input_data/volumetric_mask.nii.gz --output volumetric_output

Volumetric approach with ReHo

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:

vb_tool volumetric --data input_data/data.nii.gz --volmask input_data/volumetric_mask.nii.gz --reho --output volumetric_reho_output

(Note: Output filenames will reflect the ReHo analysis, e.g., volumetric_reho_output.unnorm.vbi-vol.nii.gz)

General Notes

Note on the data file

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.

Notes on parallelism

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:

vb_tool volumetric --data ... --output ... --jobs 4

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.

References

[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.

[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

[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.

[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.

[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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Aitor-Alberdi 💻 🚧	Keith George Ciantar 💻	NicoleEic 💻	claudebajada 🐛 🤔 📆 💻	Lucas Campos 💻 🐛 🤔 🚧	paola-g 💻	ChristineFarrugia 💻
jschewts 💻	Kenneth Scerri 📆