cpp-lln-lab/cpp_roi

Set of Octave and Matlab functions, demos and scripts to help manage ROIs and to play nice with BIDS datasets. Mostly volume-based and SPM centric.

CPP ROI

Set of Octave and Matlab functions, demos and scripts to help manage ROIs and to play nice with BIDS datasets.

Mostly volume-based and SPM centric.

For surface based and freesurfer ROIs see for example:

• https://github.com/noahbenson/neuropythy

Installation

Download this repository and unzip the content where you want to install it.

Or clone the repo.

git clone https://github.com/cpp-lln-lab/CPP_ROI.git

Fire up Octave or Matlab and type

cd CPP_ROI

% The following adds the relevant folders to your path.
% This needs to be done once per session (your path will not be saved)

initCppRoi

If you are using CPP_SPM, you got nothing to do as CPP_ROI is already installed as a submodule, and initialized when running initCppSpm.

Dependencies

Dependencies	Used version
Matlab	20???
or octave	4.?
SPM12	v7487
bids-matlab	>=0.1.0

• Other dependencies (MarsBar) are shipped with CPP_ROI in the lib folder.

Features

• create ROI from probability maps
• create ROI from atlas (see below)
• create ROI filenames that are "BIDS-ish"
• extract ROI with a given numerical label
• extract ROI from one hemisphere
• breaks a cluster image into several ROIs with each their own label

Atlas

• Can help generate ROI based on:
  • the SPM Anatomy toolbox (INSERT URL)
  • the SPM neuromorphometric atlas
  • neurosynth probability maps
  • A multi-modal parcellation of human cerebral cortex [@glasser2016]
  • the probabilistic maps of visual topography in human cortex [@wang2014]
    • https://scholar.princeton.edu/napl/resources
  • the probabilistic functional atlas of human occipito-temporal visual cortex [@rosenke2020]
  • extended Human Connectome Project multimodal parcellation atlas of the human cortex and subcortical areas [@huang2022]

Also includes:

• Yeo's 7 networks "atlas"

Marco Barilari 💻 📖 🤔	Remi Gau 💻 📖 🚇 🎨 👀 🐛 ⚠️	Jeanne Caron-Guyon 🤔 📓	Iqra Shahzad 📓	Federica Falagiarda 🐛 📓	Ceren Battal 💻 👀 📓	Jacek Matuszewski 🐛 📓
Ying Yang 🐛 📓

cpp_roi's Issues

[ENH] : include Glasser Atlas for ROI creation

Is there an existing issue for this?

• I have searched the existing issues

New feature

It would be nice to create regions of interest using labels from glasses atlas. For example, a roi with label x or a roi that includes both label x and y.

Unclear documentation

No response

bump anatomical toolbox version version

https://github.com/inm7/jubrain-anatomy-toolbox

this may require reverse engineering the content of the Macro and JuBrain variables contained in this zip file

https://github.com/inm7/jubrain-anatomy-toolbox/blob/master/JuBrain_Data_v30.mat.zip

[BUG] Typo in line 7 (visfAtlas instead of visfatlas)

Is there an existing issue for this?

• I have searched the existing issues

Expected Behavior

visfatlas specified in atlas folders should be loaded and ROIs of choice should be extracted

Current Behavior

opt.roi.atlas = 'visfAtlas';

getLookUpTable(opt.roi.atlas) % to get the list of possible run

results in error of unknown file format during atlas loading.

Error message

Error using spm_load (line 84)
Unknown file format.

Error in getLookUpTable (line 16)
roiLabelLUT = spm_load(atlasName);

Environment

- OS: mac OS 13.1
- Matlab:2019b
- SPM: 12

Branch

- branch:
- version:

Anything else?

All it takes to work is to change the atlas name in

opt.roi.atlas = 'visfAtlas';

to 'visfatlas'

[REFACTOR] replace the renameFile function with the bids.File.rename method

To do laundry list

Drafting here some basic things to help us create ROIs (in MNI space from atlases and inverse normalize) and potentially run ROI based analysis.

• use imageCalc to threshold images
• add possibility to intersect 2 masks
• have option to save created ROIs
• create roi filenaming function
• create standard output data structure
• batch to inverse normalize ROI
• add function to keep only one hemisphere
• add functions to break clusters in several smaller ROIs
• add function and example to run ROI based univariate analysis with MarsBar implemented in CPP_SPM
  • add possibility to get time course of specific contrasts, events and their PSC
• add proba Visual atlas in git LFS?
• add Yeo2011_7Networks_MNI152_FreeSurferConformed1mm_LiberalMask from spmup?
• add tests

[ENH] Add HCPex atlas from Huang et al. 2022 (MT vs MST)

Is there an existing issue for this?

• I have searched the existing issues

New feature

Add the HCPex atlas from Huang et al. 2022

• Paper : https://www.oxcns.org/papers/645%20Huang%20Rolls%20et%20al%202022%20An%20Extended%20Human%20Connectome%20Project%20Atlas.pdf
• Atlas on Github : https://github.com/wayalan/HCPex

Especially interesting as it divides MT and MST !

nb: they already implemented the use of aal3 within SPM to label activation clusters with this atlas. Might be interesting for further dev of automatic labelling.

Unclear documentation

No response

add CI to run tests in CI with windows and macos

More than one `*_mask.nii` makes `MoAE_create_roi_extract_data` demo crash

Describe your problem in detail

Opening this issue here cause it is related to CPP_ROI even though it is part of a CPP_SPM demo.

If I have more than 1 *_mask.nii file in the ffx folder the demo crashes (eg. an already existing ROI file or another contrast image). To me, it is that:

maskImage = spm_select('FPList', ffxDir, '^.*_mask.nii$');

with eg output two images and the line after can't handle more than 1 entry in the array as input

% we get the con image to extract data
% we can do this by using the "label-XXXX" from the mask
p = bids.internal.parse_filename(spm_file(maskImage, 'filename'));

Describe what outcome you expected

I don;t know actually if this is the case in other examples with more than 1 mask in the ffx folder and I just need to tweak bids.internal.parse_filename(spm_file(maskImage, 'filename'))

Describe what you got instead

Error message

If possible paste below the error message you encountered.

Error using regexp
The 'STRING' input must be either a char row vector, a cell array of char row vectors, or a string array.

Error in bids.internal.parse_filename (line 30)
  [parts, dummy] = regexp(filename, '(?:_)+', 'split', 'match'); %#ok<ASGLU>

Error in MoAE_create_roi_extract_data (line 24)
p = bids.internal.parse_filename(spm_file(maskImage, 'filename'));

[BUG] expand roi fails

Is there an existing issue for this?

• I have searched the existing issues

Expected Behavior

reported by @iqrashahzad14

Using a 4D beta image as data for defining space and a map from neurosynth, createRoi fails to give a ROI.

Minimal code to reproducde

opt.save.roi = true; 
opt.outputDir = pwd;

dataImage = fullfile(pwd, '4D_beta_0.nii');
zMap = fullfile('hMT.nii');

% X Y Z coordinates of right V5 in millimeters
location = [44 -67 0];

sphere.location = location;
sphere.radius = 1; % starting radius
sphere.maxNbVoxels = 200;

specification  = struct('mask1', zMap, ...
                        'mask2', sphere);

mask = createRoi('expand', specification, dataImage, opt.outputDir, opt.save.roi);

Current Behavior

No response

Error message

 Expansion:
 radius: 1.00 mm; roi size: 2 voxels
 radius: 3.00 mm; roi size: 20 voxels
 radius: 5.00 mm; roi size: 70 voxels
 radius: 7.00 mm; roi size: 192 voxels
 radius: 9.00 mm; roi size: 395 voxels
Error using maroi_pointlist (line 61)
Non integer points in voxel space - are points really of type 'real'?

Error in createRoi>saveRoi (line 296)
  roiObject = maroi_pointlist(struct('XYZ', mask.roi.XYZmm, ...

Error in createRoi (line 212)
    outputFile = saveRoi(mask, volumeDefiningImage, outputDir);

Error in MNE (line 26)
mask = createRoi('expand', specification, dataImage, opt.outputDir, opt.save.roi);

Environment

- OS: ?
- Matlab: ?
- SPM: ?

Branch

- branch: master ?
- version CPP ROI: v0.1.0

Anything else?

No response

[BUG] (solution provided!) HCPex atlas does not produce Left V1 ROI due to wrong LUT reading in `getLookUpTable.m`

Is there an existing issue for this?

• I have searched the existing issues

Expected Behavior

I expected to build a V1 ROI from hcpex with

opt.roi.hemi = {'L', 'R'};
opt.roi.atlas = 'HCPex';
opt.roi.name = 'V1';

bidsCreateROI(opt);

Current Behavior

L_V1 is not listed as an available ROI even though it exists in the look-up table
(CPP_ROI/atlas/HCpex/HCPex_v1.0/HCPex.nii.txt) line 1: 1 L_V1 1

Error message

No response

Environment

- OS:
- Matlab:
- SPM:

Branch

- branch:
- version: v0.3.1

Anything else?

ERROR REASON:
getLookUpTable.m with 'hcpex' atlas skips first row of the text file when looking up ROI labels and names

case 'hcpex'

      roiLabelLUT = fullfile(atlasDir, 'HCPex.nii.txt');

      fid = fopen(roiLabelLUT);
      pattern = '%f%s%s%f';
      C = textscan(fid, pattern, 'Headerlines', 1);
     ```

SOLUTION: 
Change 
`C = textscan(fid, pattern, 'Headerlines', 1);` to 0 to avoid skipping first line

So this will work with V1 ROI: 
`C = textscan(fid, pattern, 'Headerlines', 0;`

Expand ROI creation should stop when spheres get beyond a certain radius

Unless we are dealing with whale brain, there is no point in continuing to include voxels when the sphere radius goes beyond 30 cm...

Simplify saving ROI as .nii in createRoi

Is there an existing issue for this?

• I have searched the existing issues

New feature

createROI : From line 301, to save ROI
use the more simple function "save_as_image" from mars bar

saveroi(roiObject, ...
          fullfile(outputDir,  [roiName '.mat'])); % in .mat format
save_as_image(roiObject, ...
          fullfile(outputDir, [roiName '.nii'])); % in .nii format

Unclear documentation

No response

createRoi: ensure that image defining space and mask have the same resolution

add marsbar as a submodule

https://github.com/marsbar-toolbox/marsbar

change copyright format and update miss hit version

miss hit now allows to be specified with a blank line after the help section

this should prevent from the copyright to appear in all the doc

  %
  % USAGE::
  %
  %    allRunsHaveSameNbRegressors(spmMatFile)

  % (C) Copyright 2022 bidspm developers

`createRoi>createRoiName` is not happy if the name of `volumeDefiningImage` is not a BIDS format

Describe your problem in detail

using createRoi and reslicing and save the ROI image

Describe what outcome you expected

the sphere ROI.nii

Describe what you got instead

Error message

Index exceeds matrix dimensions.

Error in bids.internal.parse_filename (line 40)
    p.(d{1}) = d{2};

Error in createRoi>createRoiName (line 304)
      tmp = bids.internal.parse_filename(volumeDefiningImage);

Error in createRoi>saveRoi (line 270)
  roiName = createRoiName(mask, volumeDefiningImage);

Error in createRoi (line 189)
    saveRoi(mask, volumeDefiningImage, outputDir);

if I understand correctly if I set

volumeDefiningImage = 'path/to/spmT-001_0049_auditory_p-0001_k-0_MC-none.nii

the code will use bids.internal.parse_filename which is looking for parts of the name that have two subparts eg sub-002 where dash is the delimiter. Being that our ffx results have no bids format, it complains:

Error in bids.internal.parse_filename (line 40)
    p.(d{1}) = d{2};

make createROI more verbose

Especially when expanding, it should display the current radius size and number of voxels included

[BUG] Parallel toolbox + `bidspm` initialization messing up

Is there an existing issue for this?

• I have searched the existing issues

Expected Behavior

No response

Current Behavior

Copied from cpp-lln-lab/bidspm#1225:

Hi there, yes this indeed fixed the problem. However, a similar one happens when CPP-ROI copies the atlases.

Here though is quite strange, it only happens if I run the script from terminal matlab call, while if I run the code (copy pasted) in the same terminal matlab session it work perfectly.

in the file attached what is printed in the terminal/matlab command window

I see that this is a specifc problem that I might be the only one having so no need to rush or find a solution if you think it might requires too much debugging.

A workaround could be to let CPP ROI checking if the atlases are already there and skip copying in case.

Error message

20240419_error_command_window_parallelpool_atalases_installation.txt

Environment

- OS: Linux
- Matlab: 
- SPM:

Branch

- branch: main
- commit: 06727ee

Anything else?

No response

renameNeuroSynth: make sure that the input image as a neurosynth name

something like: _association-test_z_FDR_0.01.nii

atlas from Anatomy toolbox v3.0 doesn't work well with cpp_roi

Hi, I try to use atlas from Anatomy toolbox v3.0--->ROI tool and cpp-roi to create individual rois.

After prepareDataAndROI step when using createRoi('expand) to create a roi, an error occurs said that
the image:../src/inputs/JuBrain_ROIs/space-MNI_label-leftAG_desc-p00pt00_mask.nii must be a binary image. It seems to more than ones and zeros. Error in createRoi (line 174) isBinaryMask(roiImage);

But this mask should be a binary mask because it has already been binarised using thresholdToMask. After checking with isBinaryMask.m, I found that the mask is binarised as [0, 1.000] instead of [0, 1]. As isBinaryMask.m only considers a mask contain [0,1] as a binary mask, an error occurs.

It might related to the data type of atlas from Anatomy toolbox? checked atlas with spm_vol found that it was in int16 format. If rewrite it with float64, above mentioned error disappeared.

demo create ROI with expansion case gives me 3 ROIs as result of the expansion

Hey, just running the demo roi_script, in the case of getDataFromExpansion(opt, dataImage, roiName); I get this

where this is the last result with 57 voxels, you can see that in the brain there are 3 masked spots, two in I guess MT, and 1 in some inferior part of the brain.

So two questions,

(1) is it intended to start expanding in only 1 ROI and continuing in the second one?

(2) I guess that the 3rd spot in the inferior part is there by mistake.

Also, Have you tried to save each ROI across the expansion iteration? It seems that at some point in the process it stops expanding and starts again towards the end.

createROI: ensure that the mask image is binary mask

Add support for neuroparc

https://github.com/neurodata/neuroparc

[ENH] Merge ROIs

You think / need this code to do merge 2 or more ROIs.

It can be put as a case in createRoi

Use spm batch imcalc to create rois

add marsbar citation

We presented an abstract to the Human Brain Mapping conference for 2002; this may be useful as a reference: MarsBaR HBM abstract. It should apparently be cited as:

Matthew Brett, Jean-Luc Anton, Romain Valabregue, Jean-Baptiste Poline. Region of interest analysis using an SPM toolbox [abstract] Presented at the 8th International Conference on Functional Mapping of the Human Brain, June 2-6, 2002, Sendai, Japan. Available on CD-ROM in NeuroImage, Vol 16, No 2.

Freesurfer ROIs

https://github.com/CerenB/rhythmBlock_mvpa/blob/main/parcel2mask.m

[INFRA] make sure tests can run in CI

`sphere` case in `createRoi`, error in `createRoiName` with `volumeDefiningImage = con_0001.nii`

Describe your problem in detail

using createRoi as:

conImage = '.../derivatives/cpp_spm/sub-pilot001/stats/task-rdkMohBimodalMotion_space-individual_FWHM-6_desc-BimodalMotionRdkALaMoh/con_0049.nii'

[~, roiFile] = createRoi('sphere', sphere, conImage, pwd, saveROI);

Describe what outcome you expected

the actual sphere

Describe what you got instead

I guess that the subfun createRoiName is looking for the brain space in which we are working on to create a label, to parse the filename it assumes that it is BIDS like with parte1-parte2 divided by dash which is not the case for our contrast image.

Therefore it fails.

If I am not wrong, this happens only with the sphere case

Error message

If possible paste below the error message you encountered.

Index exceeds matrix dimensions.

Error in bids.internal.parse_filename (line 40)
    p.(d{1}) = d{2};

Error in createRoi>createRoiName (line 333)
      tmp = bids.internal.parse_filename(volumeDefiningImage);

Error in createRoi>saveRoi (line 296)
  roiName = createRoiName(mask, volumeDefiningImage);

Error in createRoi (line 215)
    outputFile = saveRoi(mask, volumeDefiningImage, outputDir);