_____________________________________________________________
_ _ _ ____ __
/ / / /| / ) /
---/----__----------__---)__--_/__----/| /-|---/___ /-----/--
/ / ) / / /___) / ) / / |/ | / | /
_/___(___(_(___/_(___ _/_____/______/__/___|_/_____|__ _/_ __
/
__________(_ /_______________________________________________
(*) new commits will break the code very often
This is a bash/python/matlab/R toolbox to perform layer-fMRI VASO analyses using many software. Mostly a set of wrapper functions tailored for layer-fMRI analyses from start to bottom, there are examples of how to put things together but feel free to plug here and there your custom code for your custom analyses tailored to your specific project/data.
- Marco Barilari
- Renzo Huber
- Daniel Glen
- Paul Taylor
- Kenshu Koiso
- et al. ... if you think your name is missing, please do not hesitate to reach out
- layerfMRI-toolbox v0.1.0 - BETA*
The layerfMRI-toolbox helps with two main streams of data analyses:
- segmentation and layerification of anatomical data.
- vaso time series preprocessing. [WIP - available in the future]
- AFNI vXXX (in the path)
- LAYNII vXXX (in the path)
- Freesurfer v7+
- Matlab with SPM12 vXXX (in the path)
- ANTS vXXX
- Presurfer commit: (as submodule)
- Nordic commit:
- A good computer (better if it is a crunch computer or a cluster)
- Basic experience with Python/Bash scripting
- Lots of patience :) (tips: most of the time is just a path problem)
Tested on Linux (Ubuntu xxx) and Mac OSX xxx
Download this script and run it as follow (change project folder name and directory where you want to create it):
bash path/to/make_yoda_layerfMRI-toolbox.sh \
my_folder_project_name \
where/I/want/to/create/it# output structure
`analyses_layerfMRI_your-project-name`
.
├── code
│ ├── lib # where layerfMRI-toolbox lives
│ ├── src # where your code and the batch file to run layerfMRI-toolbox live
├── inputs
│ └── raw # your awesome raw dataset + other input to not touch, ideally bidslike format
└── outputs
└── derivates # where any processed file will be saved in separate subfolders named by `software-step` Automatic by cloning a template with ideal project folder structure (aka a YODA folder) and DATALAD:
Use the GitHub template template_layerfMRI-toolbox_yoda, it has already this toolbox installed
- Got to the link (up-right)
- Click on
Use this templategreen button (up-right) - Set your name
- Clone on your computer your new project repository via
# --recursive flag is very important!
git clone --recursive your/repo/url- Populate the repo with data a custom code
- Add this repo to your analysis project folder (see below for suggestions) via git operation.
git clone --recursive https://github.com/marcobarilari/layerfMRI-toolbox.git- Check you have all the prerequisites listed in this README file.
- Check the config file
config_layerfMRI_pipeline.shand modify it according to your software paths. - Check the demos for suggested pipelines in the
batch demos(and check paths there as well if you intend to use them).
-
Prepare (
presurfer) and segment (freesurfer) and anatomical using e.g.MP2RAGE -
Prepare a high-quality rim file (WM GM pial mask) for layeryfication (
SUMA) (manual editig might be needed though) -
Coregister the rim file to EPI distorde space (
ANTs) -
Create layers mask (
LAYNII) -
Apply thermal noise-cleaning on VASO data (
NORDIC) -
Preprocess VASO data (motion correction
AFNI; bold correctionLAYNII, T1w image fromnulledcontrast) -
Quality metrics (
LAYNII) as tSNR, noise distribution etc. -
For almost every process, it spits out a logfile
YYYYMMDDHHMMSS_process_name.txtwhich is what is printed in the command line. Useful for debugging and when multiple processes are running in the background in remote machines within separate sessions (e.g. usingscreen).
The demo has been run on a crunching computer (cpp-labMONSTER):
- Linux 6.2.0-36-generic #37~22.04.1-Ubuntu
- 24 CPUs (Intel(R) Xeon(R) Gold 5118 CPU @ 2.30GHz)
- 64GB ram + 200GB swap memory
RAM and CPU usage are sampled every ~30 seconds.
This section refers to the demo layerfMRI_pipeline_segment-layers.sh using a high-res anatomical MP2RAGE whole brain (0.75 mm iso) and T1w in EPI space derived from vaso functional data of a specific task experiment (0.75 mm iso, partial brain coverage).
CONCLUSION: It will hit hard on the memory (RAM or swap). To increase swap memory in Linux check here xxx. Windows and Mac should be already configured to steal memory to the HD increase the swap automatically if the RAM is full.
- Nifti files, what else
- It deals with
(nulled + not nulled).niiseriesnulled.niiandnot nulled.niiseparated series- time series with nordic noise volumes appended at the end
see WIP-folder_organization and provide feedbacks. Thinking about multiple options atm.
- Everyone is welcome to contribute.
- We don't believe this is the only way to analyze layer fMRI (VASO) data. It is one way of many, we just want to make it easier and faster.
- If you have a different and cool way to tackle a particular step, please make it available for everyone adding it to this repo.
- This pipeline is a transparent box. We keep it easy so that everyone can easily open the scripts and look at what is happening inside and contribute.
- Each called "function" has an input and an output and should do just one operation/step on the data.
- The pipeline is made of modules that can be ordered in a different way. The example demo is just an example that suits the dummy data. In your paradigm, you may have slightly different things that may benefit from eg a different steps order or custom code. Just get inspired.
- Python/jupiter notebook based batch
- Improvements in the current method
- Add alternative methods
- Add better documentation + educational material
- Write tests