QPPLab: A generally applicable MATLAB package for detecting, analysing, and visualizing quasiperiodic spatiotemporal patterns (QPPs) of whole brain activity
The quasi-periodic spatiotemporal pattern of signal changes is one prominent feature of the infraslow BOLD signal that is known to tie to the infraslow neural activity involved in attention and arousal fluctuations, and it has been widely detected in resting and task-evoked brains across species. Existing QPP detection and analyzing tools were developed with study-specified parameter settings and analysing methods. This MATLAB package provides a parameter-simplified, user-friendly, and generally applicable toolbox for detecting, analyzing, and visualizing QPPs and other related results from functional neuroimaging timeseries of the brain. It has been succesfully demonstrated on fMRI datasets of mice, rats and human brains.
- 1 - Prerequisite
- 2 - Main Pipeline
- 3 - Output Files
- 4 - References
This is a Matlab (The Mathworks Inc., Natick, MA, USA, R2018a or a later version) toolbox. Any operational system with Matlab (R2018) installed will be sufficient to run this toolbox. All supporting Matlab functions to be called in the main pipeline are included in ./QPPv0922/ folder.
The input file data.mat is included in ./input/ folder whereas data is the input filename. Two distinct input samples are enclosed in the current ./input/, which includes a visually stimulated brain dataset, and a resting human brain dataset.
The input data.mat must include the following four variables.
| Variable name | Description | Note |
|---|---|---|
D0 |
a (nsbj X nscn) cell matrix | Each cell has a (nroi X ntimepoints) matrix of EPI timeseries. |
MotionInf |
a (nsbj X nscn) cell matrix | Each cell includes >=1 segment(s) of timepoints without significant motions. |
ROI2Net |
a (nroi X 1) vector | Each entry is the network index corresponding to each ROI. |
NetLB |
a (nnet X 1) cell vector | Each cell includes the (shorthand) label of each network. |
Note: nsbj= number of subjects, nscn=number of EPI scans, nroi=number of ROIs, ntimepoints=number of timepoints, nnet= number of networks.
The ROI2Net and NetLB variables can be generated by running 'st0_ROIreOrg.m'. In this case, the EPI data cell matrix should at least be included in your original input file; if you did not prepare the MotionInf parameter, the entire timepoints of each scan will be included in MotionInf when running 'st0_ROIreOrg.m'. You can ignore the warning message of ''Variable 'MotionInf' not found.'' in this case.
In addition, you will also need to prepare an atlas-network file. This file should be a spreadsheet including at least two columns, one column including the numerical label of ROIs/Parcels corresponding to your atlas, and the other column including the network name each ROI belongs to. In ./resources/ folder, an examplary atlas-network file is included.
The main pipeline consists of 3 steps. The 1st step (st1_ParamSt.m) sets up the initial parameters. The 2nd step (st2_QPPanalysis.m) detects and analyzes QPPs. The 3rd step (st3_QPPFCvisual.m) visualizes QPP and related results based on the outputs of step 2.
The following parameters need to be prespecified before running the script. A parameter file Params_data_ext.mat will be generated after running this script.
| Category | Variable name | Description | Note |
|---|---|---|---|
| Filepath | data |
the input filename | The input should has the filename data.mat |
ext |
the parameter filename extension | The parameter filename will be Params_data_ext.mat |
|
| QPP global parameters | nP |
total # of QPPs to detect (nP<=5) | If nP=1, only detect the primary QPP (QPP1); if nP=2, detect both QPP1 & QPP2; etc. |
PL |
a (nP X 1) vector of QPP window length | The QPP wavelength is ~20s for humans, as indicated by PL(ip)=20/TR, (Yousefi et al., 2018), ~10s in adult mice (Belloy, Naeyaert, et al., 2018) and ~16s in adult rats (Majeed et al., 2011). | |
| QPP detection parameters | cth13 & cth45 |
a 2D vector of correlation threshold for QPP1-QPP3 (cth13) & for QPP4-QPP5 (cth45) |
If you do not need to detect QPP4-QPP5, please assign cth45 a random number (e.g., cth45=[0, 0]). |
| QPP phase adjustment parameters | cthph |
similarity threshold when phase-adjusting (phadj) a QPP | Default value: cthph=0.88 |
s |
control for strict phase adjustment (s=1) or relaxed phase adjustment (s=0) |
||
sdph |
a (nP X 1) cell array of reference parcels | Each cell may include >=1 parcel IDs. The phase-adjusted QPP waveform will start from rising positive values for the selected parcels. | |
| Functional connectivity (FC) analysis parameters | fz |
control for the output matrix FCr to be the Pearson correlation (fz=1) or to be the Fisher Z-Transformation of the Pearson correlation (fz=1). |
The following three parameters need to be prespecified at the beginning of this script.
| Category | Variable name | Description | Note |
|---|---|---|---|
| Filepath | dataext |
parameter filename | The parameter .mat file generated from step 1, which has the filename Param_dataext.mat |
| Data concatenation method | runM |
control the way to concatenate the data | If runM=1, concatenate all D0{i,j} as a whole group and detect group QPP; if runM=2, concatenate all D0{i,:} and detect QPP from all scans of each subject; if runM=3, concatenate all D0{:,:} and detect QPP from all subjects of each scan. |
| QPP detection method | rbstScrn |
control for fast QPP detection (rbstScrn=0) or robust QPP detection (rbstScrn=1) |
The fast QPP detection randomly selects a limited number of starting points which was used in (Abbas, Bassil, et al., 2019; Abbas, Belloy, et al., 2019; Belloy et al., 2018; Majeed et al., 2011; Maltbie et al., 2022; Raut et al., 2021; Yousefi et al., 2018), whereas the robust detection selects all possible starting points which was used in (Xu et al., 2023; Yousefi & Keilholz, 2021). |
For the QPP analysis, the following analytical procedures will be executed: 1) QPP1 detection, 2) phase adjustment, 3) detection of additional QPPs from the residuals of QPP1, 4) reverse phase QPP detection, and 5) Functional connectivity computation after QPP regression. The key output variables are:
| Output variable | Format | Note |
|---|---|---|
QPPs |
a (nP X 2) cell matrix | The 1st column includes the 2D template of QPP1-QPPnP, and the 2nd column includes the corresponding reverse phase QPPs. |
Cs |
a (nP X 1) cell vector | Each cell includes the QPP sliding correlation timecourse. |
TMXs |
a (nP X 2) cell matrix | The occurring time of the QPP (1st column) and the reverse phase QPP (2nd column). |
METs |
a (nP X 2) cell matrix | The metadata of maxima and minima of the QPP sliding timecourse. |
Ds |
a (nP X 1) cell vector | Each cell includes original EPI timeseries. |
Drs |
a (nP X 1) cell vector | Each cell includes the EPI timeseries after QPP regression. |
Crs |
a (nP X 1) cell vector | Each cell includes the QPP sliding correlation timecourses after QPP regression. |
FCrs |
a (nP X 1) cell vector | Each cell includes the functional connectivity map after the QPP regression. |
iROI2Net |
a (nroi X 1) vector | Sorted ROI network based on each network. E.g., QPPs{1}(iROI2Net,:) will return ROIs sorted QPP along functional networks. |
Note: Similar to detected QPPs, the phase-adjusted QPP and related variables are saved in the following cell matrices, QPPas, TMXas, METas, Cas. All these parameters are saved in the dataext_*_QPPs.mat file, where * depends on the prespecified parameters.
In addition to the 3 parameters described in Section 2.2.1, three additional parameters can be prespecified at the beginning of this script.
| Variable name | Description | Purpose |
|---|---|---|
Pselect |
a vector of integers | to specify the QPP #s to be visualized |
Gselect |
a vector of integers | to specify the group# (e.g. which scans/subjects) to be compared; if runM=1, by default Gselect=1. |
bin |
a decimal | to specify bin size of the histogram of sliding correlation timecouses |
| Index | Figure Description |
|---|---|
| 1 | specified QPPs of each group |
| 2 | phase reversed QPPs of each group |
| 3 | sliding correlation timecourses with maxima and minima labeled |
| 4 | sliding correlation timecourses before and after QPP regression |
| 5 | histograms of sliding correlation timecourses before and after QPP regression |
| 6 | functional connectivity (FC) matrix before (upper triangular) and after (lower triangular) QPP regression |
In figures 1, 2, and 6, ROIs are reorganized based on networks.
Examples of output files are listed.
./Output
├── GrpQPP # Concatenated all EPI scans of all subjects as a whole group (`runM`=1)
│ ├── interm # Intermediate output files
│ │ ├── `dataext`_Grp1_rbst1_qpp1.mat # QPP1 detected with robust detection
| │ ├── `dataext`_Grp1_rbst1_qpp2.mat # QPP2 detected with robust detection
| │ ├── `dataext`_Grp1_rbst1_qpp3.mat # QPP3 detected with robust detection
| │ ├── `dataext`_Grp1_rbst0_qpp1.mat # QPP1 detected with fast detection
| │ ├── `dataext`_Grp1_rbst0_qpp2.mat # QPP2 detected with fast detection
| │ ├── `dataext`_Grp1_rbst0_qpp3.mat # QPP3 detected with fast detection
| │ ├── `dataext`_Grp1_rbst0_qpp4.mat # QPP4 detected with fast detection
| │ ├── `dataext`_Grp1_rbst0_qpp5.mat # QPP5 detected with fast detection
│ │ └── ...
│ ├── `dataext`_Grp1_rbst1_QPPs.mat # Key output variables for QPP1-QPP3 with robust detection (`rbstScrn`=1)
│ ├── `dataext`_Grp1_rbst0_QPPs.mat # Key output variables for QPP1-QPP5 with fast detection (`rbstScrn`=0)
│ └── ...
│
├── SbjQPP # Concatenated all EPI scans of each subject as a whole group (`runM`=2)
│ ├── interm # Intermediate output files
│ │ ├── `dataext`_Sbj1_rbst1_qpp1.mat # QPP1 detected with robust detection for subject 1
| │ ├── `dataext`_Sbj1_rbst1_qpp2.mat # QPP2 detected with robust detection for subject 1
| │ ├── `dataext`_Sbj1_rbst1_qpp3.mat # QPP3 detected with robust detection for subject 2
| │ ├── `dataext`_Sbj2_rbst1_qpp1.mat # QPP1 detected with robust detection for subject 2
| │ ├── `dataext`_Sbj2_rbst1_qpp2.mat # QPP2 detected with robust detection for subject 2
| │ ├── `dataext`_Sbj2_rbst1_qpp3.mat # QPP3 detected with robust detection for subject 2
│ │ └── ...
│ ├── `dataext`_Sbj1_rbst1_QPPs.mat # Key output variables for QPP1-QPP3 of subject 1 with robust detection (`rbstScrn`=1)
│ ├── `dataext`_Sbj2_rbst1_QPPs.mat # Key output variables for QPP1-QPP3 of subject 2 with robust detection (`rbstScrn`=1)
│ └── ...
│
└── ScnQPP # Concatenated all subjects' EPI data of each scan as a whole group (`runM`=3)
├── interm # Intermediate output files
│ ├── `dataext`_Scn1_rbst0_qpp1.mat # QPP1 detected with fast detection for the 1st scan
│ ├── `dataext`_Scn1_rbst0_qpp2.mat # QPP2 detected with fast detection for the 1st scan
│ ├── `dataext`_Scn2_rbst0_qpp1.mat # QPP1 detected with fast detection for the 2nd scan
│ ├── `dataext`_Scn2_rbst0_qpp2.mat # QPP2 detected with fast detection for the 2nd scan
│ └── ...
├── `dataext`_Scn1_rbst0_QPPs.mat # Key output variables for QPP1-QPP2 of the 1s scan with fast detection (`rbstScrn`=0)
├── `dataext`_Scn2_rbst0_QPPs.mat # Key output variables for QPP1-QPP2 of the 2nd scan with fast detection (`rbstScrn`=0)
└── ...
Abbas, A., Bassil, Y., & Keilholz, S. (2019). Quasi-periodic patterns of brain activity in individuals with attention-deficit/hyperactivity disorder. NeuroImage: Clinical, 21, 101653. https://doi.org/10.1016/j.nicl.2019.101653
Abbas, A., Belloy, M., Kashyap, A., Billings, J., Nezafati, M., Schumacher, E. H., & Keilholz, S. (2019). Quasi-periodic patterns contribute to functional connectivity in the brain. NeuroImage, 191, 193–204. https://doi.org/10.1016/J.NEUROIMAGE.2019.01.076
Belloy, M. E., Naeyaert, M., Abbas, A., Shah, D., Vanreusel, V., van Audekerke, J., Keilholz, S. D., Keliris, G. A., van der Linden, A., & Verhoye, M. (2018). Dynamic resting state fMRI analysis in mice reveals a set of Quasi-Periodic Patterns and illustrates their relationship with the global signal. In NeuroImage (Vol. 180, pp. 463–484). Academic Press Inc. https://doi.org/10.1016/j.neuroimage.2018.01.075
Majeed, W., Magnuson, M., Hasenkamp, W., Schwarb, H., Schumacher, E. H., Barsalou, L., & Keilholz, S. D. (2011). Spatiotemporal dynamics of low frequency BOLD fluctuations in rats and humans. Neuroimage, 54(2), 1140–1150. https://doi.org/10.1016/j.neuroimage.2010.08.030
Maltbie, E., Yousefi, B., Zhang, X., Kashyap, A., & Keilholz, S. (2022). Comparison of Resting-State Functional MRI Methods for Characterizing Brain Dynamics. Frontiers in Neural Circuits, 16. https://doi.org/10.3389/FNCIR.2022.681544/FULL
Raut, R. v., Snyder, A. Z., Mitra, A., Yellin, D., Fujii, N., Malach, R., & Raichle, M. E. (2021). Global waves synchronize the brain’s functional systems with fluctuating arousal. Science Advances, 7(30). https://doi.org/10.1126/SCIADV.ABF2709/SUPPL_FILE/SCIADV.ABF2709_SM.PDF
Xu, N., Smith, D. M., Jeno, G., Seeburger, D. T., Schumacher, E. H., & Keilholz, S. D. (2023). The interaction between random and systematic visual stimulation and infraslow quasiperiodic spatiotemporal patterns of whole brain activity. BioRxiv, 2022.12.06.519337. https://doi.org/10.1101/2022.12.06.519337
Yousefi, B., & Keilholz, S. (2021). Propagating patterns of intrinsic activity along macroscale gradients coordinate functional connections across the whole brain. NeuroImage, 231, 117827. https://doi.org/10.1016/j.neuroimage.2021.117827
Yousefi, B., Shin, J., Schumacher, E. H., & Keilholz, S. D. (2018). Quasi-periodic patterns of intrinsic brain activity in individuals and their relationship to global signal. NeuroImage, 167, 297–308. https://doi.org/10.1016/j.neuroimage.2017.11.043