SeeCAT 2.0 User Manual

SeeCAT is a MATLAB toolbox for brain functional connectivity analysis of resting-state functional MRI. It takes a study from DICOM files or a BIDS dataset through preprocessing, quality control, connectivity measures and multi-site harmonisation to group statistics and figures, in one window or from scripts. This manual describes version 2.0: what each part does, how it does it, every option, the files it reads and writes, and worked examples on real data.

1 Introduction

1.1 What SeeCAT does

SeeCAT covers the whole path of a resting-state study:

• DICOM to BIDS: converts DICOM folders in any common layout into a BIDS dataset with dcm2niix (bundled), finding subjects and sessions by itself.
• Data check: lists every BOLD run with its volumes, TR and head motion.
• Preprocessing: dummy-scan removal, slice timing, realignment, coregistration, unified segmentation, normalisation to MNI space, nuisance regression with band-pass filtering, handling of high-motion frames, smoothing; MRIQC image quality metrics, an HTML quality report per run and per study, and optional VBM maps.
• fMRIPrep denoising: the same denoising, censoring and smoothing applied to fMRIPrep outputs.
• Quality control: rules suggest which runs to exclude (motion, coverage, registration), image quality outliers are flagged per site, and a table lets you confirm each decision. Later steps leave excluded runs out.
• Seed FC: seed-based functional connectivity from spheres or masks.
• Degree: voxel-wise degree centrality and strength.
• Gradients: connectivity gradients by diffusion map embedding, aligned across runs.
• Harmonize: removes site and scanner effects from per-subject maps with ComBat and related models.
• Statistics: group GLM (one- and two-sample t tests, paired tests, one-way and repeated-measures ANOVA, regression, custom designs) with covariates, random field theory and FDR correction as in SPM, or TFCE with permutations.
• Viewer: slices, thresholds, cluster tables with atlas labels, mosaics, time series and surfaces.

Everything the window does is a configuration (a MATLAB struct, saved as JSON) passed to seecat.run, so every analysis can be repeated from a script.

1.2 What is new in 2.0

• A rewrite: SeeCAT needs only SPM, and works on BIDS data instead of the FunImgARW… folder layout of 1.x.
• Inputs are BIDS datasets and outputs follow BIDS-derivatives naming, so results can be read by other tools and other tools' results (fMRIPrep) can be read by SeeCAT.
• New: DICOM conversion, fMRIPrep input, MRIQC-style quality metrics, quality-control exclusions, connectivity gradients, multi-site harmonisation, TFCE, VBM maps, parallel processing that sizes itself to the computer's memory, and a new viewer.
• Steps resume after an interruption, and finished work with unchanged settings is skipped.

1.3 Licence and citation

SeeCAT is free software under the GNU General Public License, version 3 or later. It is developed by Mingrui Xia and colleagues at Beijing Normal University and distributed on GitHub and NITRC. When you publish results, please cite SeeCAT and the methods behind the steps you used (SPM, and the papers listed in References).

2 Installation and start

2.1 Requirements

2.2 Install

1. Download SeeCAT-2.0.0.zip from GitHub or NITRC and unzip it.
2. In MATLAB:

   addpath('path/to/spm');
   addpath('path/to/SeeCAT-2.0.0/SeeCAT');
   savepath   % optional: keep the paths for later sessions

3. Open the main window:

   SeeCAT

2.3 What is in the release

SeeCAT-2.0.0/
  SeeCAT/              the toolbox: add this folder to the path
    SeeCAT.m           opens the main window
    +seecat/           all functions (seecat.config, seecat.run, seecat.viewer, ...)
    templates/         brain, GM, WM, CSF masks and underlays (IXI549Space, MNI 2009c)
    resources/         icons and the window's web parts
  external/dcm2niix/   dcm2niix for win, mac, lnx
  Doc/manual/          this manual (HTML and PDF)
  README.md, LICENSE, CHANGELOG.md

2.4 Two ways to work

The window (SeeCAT) has a page per step. Each page builds a configuration; Run starts it in a separate MATLAB process so the window stays responsive, and Save writes the configuration as a JSON file.

Scripts use the same configurations:

cfg = seecat.config('prep');                 % every option at its default
cfg.bids_dir  = 'D:/study/bids';
cfg.subjects  = {'01', '02'};                 % empty = all
cfg.n_workers = 'auto';
seecat.run(cfg);                             % writes D:/study/bids/derivatives/seecat

seecat.run('my_prep.json');                  % a configuration saved from the window

Chapter 8 lists the batch functions and complete scripts.

3 Concepts

3.1 BIDS and BIDS-derivatives

SeeCAT reads raw data organised in the Brain Imaging Data Structure and writes its results as BIDS-derivatives. A raw dataset looks like this:

bids/
  dataset_description.json
  participants.tsv                  participant_id, and columns such as group, age, sex, site
  sub-01/
    anat/sub-01_T1w.nii.gz (+ .json)
    func/sub-01_task-rest_bold.nii.gz
         sub-01_task-rest_bold.json  RepetitionTime, SliceTiming, ...

File names are made of entities, key-value pairs separated by underscores, and end with a suffix (bold, T1w, mask, connectivity, ...). SeeCAT's outputs keep the entities of their source and add their own:

Every image comes with a JSON sidecar that records how it was made (sources, settings, frames used).

3.2 Spaces and templates

SeeCAT's own preprocessing normalises to SPM's template space, IXI549Space (the space of SPM's tissue probability maps, close to MNI152). Outputs are written at the chosen voxel size (3 mm by default) over SPM's bounding box [-90 -126 -72; 90 90 108]. fMRIPrep outputs stay in their space, usually MNI152NLin2009cAsym. The templates folder holds brain, GM, WM and CSF masks at 2 and 3 mm, made from SPM's TPMs, and underlays for the viewer (ch2, ch2better, ICBM152 2009c).

3.3 Units, resuming and skipping

Each pipeline splits its work into units: one BOLD run for Preprocessing, fMRIPrep denoising, Seed FC and Degree; one unit for a group step (Gradients, Harmonize, Statistics). When a unit finishes, SeeCAT records its settings. Running again:

• skips a unit that finished with the same settings (Overwrite runs it again);
• runs a unit again when its settings changed, after deleting the files it wrote before;
• resumes a unit that failed at the step where it stopped, from its work folder;
• never leaves a failed unit's partial outputs among the derivatives.

A failed unit does not stop the others; the summary table and the logs say what failed and why.

3.4 Logs, configurations and summaries

Every run writes, under <output>/logs: the configuration as JSON (<pipeline>_<time>_config.json), a main log, one log per unit, and a list of every file each unit wrote. <output>/reports/<pipeline>_<time>_summary.tsv has one row per unit: status, time, message and the unit's key results (frames kept, mean FD, ...).

3.5 Parallel processing and memory

The Parallel workers option of each page sets how many units run at the same time:

• auto (default): as many as fit in memory. SeeCAT estimates the memory one unit needs (from the size of the largest run, the brain mask, the node count of Gradients, the maps of Statistics), adds about 1 GB per worker, keeps what the main MATLAB needs, and uses at most 85 % of the free memory, one worker per core and one per unit. The log states the estimate and the choice. With only one unit (Harmonize, Statistics without TFCE), with too little memory for two workers, or without the Parallel Computing Toolbox, it runs one after another without a pool;
• 0: one after another, e.g. to leave the computer free for other work;
• a number: at most that many workers.

Each worker is given its share of the computer's cores as threads (e.g. 5 workers on 32 cores get 6 threads each), so matrix work keeps its speed. For Gradients and TFCE, which are one unit, the workers share the runs or the permutations of that unit. If a pool fails to start, SeeCAT tries once more with half the workers and only then runs one after another, and the log says why.

3.6 Quality-control exclusions

After Preprocessing or fMRIPrep denoising, the group report writes reports/qc_exclusions.tsv, a list of every run (and T1w image) with a decision: keep or exclude. Rules suggest exclusions; on the QC reports page you confirm or change them. Seed FC, Degree, Gradients, Harmonize and Statistics then leave excluded runs out (their option Leave out QC exclusions, on by default) and list them in the log. Chapter 6.5 describes the rules.

3.7 participants.tsv

Group information comes from participants.tsv of the BIDS dataset: the group of each subject, age, sex, site, scores. Statistics and Harmonize read it next to the derivatives, two folders up (bids/derivatives/seecat → bids), or from the dataset named in the derivatives' dataset_description.json; a different file can be chosen. Columns with numbers are used as numbers, text columns as categories. Tissue volumes from Preprocessing (gm_ml, wm_ml, csf_ml, tiv_ml, in reports/anat_volumes.tsv) can be used as if they were columns of participants.tsv.

4 The main window

4.1 Layout

• Pages (left) in three groups: PREPARE (DICOM to BIDS, Preprocessing, fMRIPrep denoising), ANALYSE (Seed FC, Degree, Gradients, Harmonize, Statistics) and RESULTS (Viewer, Data check, QC reports). Manual opens this document, About shows the version.
• Options (centre), in cards such as Input, Preprocessing, Denoising. The tabs above jump to a card. Show advanced options adds the options most studies keep at their defaults.
• Description (right): click the i icon of an option, or edit it, to read what it does, with examples, its default and its batch field name. Hovering over an option shows a short tooltip.
• Run panel (right, bottom): Run, Stop, the progress of the units, and the state (Ready, Running, Finished, Failed).
• Drawer (bottom): the Log and the Summary table of the last run; the arrow opens and closes it.
• Load and Save (top right): read or write the page's configuration as JSON. A configuration saved here runs unchanged with seecat.run.

4.2 Running

Run checks every option first and lists all problems at once (an empty required folder, a value out of range). The pipeline then runs in a separate MATLAB process: the window stays usable, the log streams into the drawer, and Stop ends the process (units that finished keep their outputs; the unit that was interrupted resumes next time). When the run ends, the Summary tab of the drawer shows the run's table (one row per unit, as in reports/<pipeline>_<time>_summary.tsv); each unit's own log is in logs/<pipeline>_<time>/.

4.3 Kinds of fields

5 Workflow

fMRIPrep users start at fMRIPrep denoising instead of Preprocessing; everything after it is the same. The table shows what each step reads and writes:

By default every step writes into the same derivatives/seecat folder, so each next step finds its input there: set the derivatives folder once and leave Output folder empty.

6 The modules

Each section below describes one page: what it is for, how it works, every option (the tables are generated from the software, so they show exactly what the window offers), what it reads and writes, and how to run it from a script. Options marked advanced appear after ticking Show advanced options. Options shared by several pages (denoising, censoring, quality control, output, selection, run) are described once, in sections 6.12 to 6.15.

6.1 DICOM to BIDS

Converts DICOM files into a BIDS dataset with dcm2niix. It reads the DICOM headers to find subjects, visits and series, names each series by rules, and writes the images with their JSON sidecars into the BIDS layout.

How subjects, sessions and series are found

1. Reading headers. SeeCAT reads the first and last file of every folder that holds DICOM files (a fast reader of the header up to the series fields; other files, such as .txt or .nii, are ignored). A folder whose first and last files belong to different people is reported as an error.
2. Subjects. Folders with the same PatientID belong to one subject. The subject is named after the folder that holds all of that person's folders and no one else's, keeping letters and digits (S_001 → sub-S001). When IDs are missing or anonymised (e.g. anonymous, xxxx, 0000), the folder tree decides. Layouts that work include one folder per subject (S001/…), modality folders with subject folders inside (T1/S001, REST/S001) and deeper trees (S001/visit1/T1). Find subjects shows the layout it recognised and the subjects before anything is converted.
3. Sessions. A subject scanned in one visit (one DICOM study) gets no session folder. Several visits become ses-1, ses-2, … by scan date; the assignment is kept in code/seecat/from_dicom_sessions.tsv so a later visit gets the next number.
4. Series. dcm2niix converts each subject; every series is named by the first rule that matches its sidecar. The default rules take a 3D T1-weighted image (MPRAGE, SPGR, BRAVO, …) as anat/…_T1w and resting-state BOLD (series names containing rest, rsfMRI, or RS as a word) as func/…_task-rest_bold. A resting run must also be a 2D EPI with at least 20 volumes. Series that match no rule are listed, not copied.
5. Writing. Images go to sub-<label>/[ses-<label>/]anat|func as .nii.gz with their sidecars; dataset_description.json is written if missing and participants.tsv gets the new subjects. Images already present are kept, so converting again only adds what is missing. A table of every series and what happened to it is written to code/seecat/.

Options

A rules file that also keeps a task run and a field map:

[{"match": {"SeriesDescription": "rest"}, "datatype": "func", "suffix": "bold", "entities": {"task": "rest"}},
 {"match": {"SeriesDescription": "nback"}, "datatype": "func", "suffix": "bold", "entities": {"task": "nback"}},
 {"match": {"SeriesDescription": "mprage|t1"}, "datatype": "anat", "suffix": "T1w"}]

Script

seecat.bids.scan_dicom('D:/study/dicom')                   % what would be converted
S = seecat.bids.from_dicom('D:/study/dicom', 'D:/study/bids');   % convert every subject
S = seecat.bids.from_dicom('D:/study/dicom/S_001', 'D:/study/bids', 'sub', '01', 'ses', 'pre');

6.2 Data check

Before preprocessing, look at what the dataset holds. Data check lists every BOLD run of a BIDS dataset (or of a derivatives folder) with its number of volumes and TR; where a confounds table exists (after preprocessing or fMRIPrep), also the mean and largest framewise displacement and the frames flagged for motion. Runs with mean FD above 0.25 mm or more than 20 % of frames flagged are highlighted. Open in viewer steps through the volumes of the selected run with its motion trace; QC report opens its report.

The Series menu chooses which images are listed: preprocessed (desc-preproc), denoised, raw (the BIDS dataset) or all BOLD images. Script: R = seecat.qc.runs('D:/study/bids', 'raw').

6.3 Preprocessing

Preprocesses every BOLD run of a BIDS dataset with SPM and writes analysis-ready data to derivatives/seecat. Each run is a unit; its T1w (from the same session if there is one) is used for registration and segmentation.

Steps

1. Input. The run and its T1w are copied into the work folder. Leading non-steady-state volumes are removed: with dummy_scans = auto, leading volumes whose mean brain intensity is a robust outlier (z > 3.5 against the median and MAD of the run, within the first 20) are dropped; volumes the scanner already discarded are not counted again.
2. Slice timing (SPM). The slice acquisition times come from SliceTiming in the sidecar (seconds), so sequential, interleaved and multiband orders are all handled; the reference is the middle of the TR unless set. The times are read along SliceEncodingDirection (k when absent; k- is reversed to voxel order). Slices along the first or second voxel axis (i, j) are not supported and stop the run with an error; reorient such images, or turn slice timing off.
3. Realignment (SPM). Two passes, to the first volume and then to the mean. The six motion parameters go to the confounds table; the data are not resampled here.
4. Coregistration. The T1w is registered to the mean EPI by normalised mutual information (only its header changes).
5. Segmentation. SPM unified segmentation of the T1w with SPM's tissue probability maps gives native GM, WM and CSF maps, a bias-corrected T1w and the deformation to IXI549Space. Without a T1w (normalise.method = epi) the mean EPI is segmented instead.
6. Nuisance masks. WM (p > 0.99) and CSF (p > 0.95) masks in the subject's own space, eroded by a 2 mm ball, so they keep away from grey matter; they are resampled to the output grid.
7. Normalisation. The deformation is applied once to the BOLD data (4th-degree B-spline; the only resampling of the data) and to the tissue maps, at the chosen voxel size over SPM's bounding box.
8. Masks in output space: brain = GM + WM + CSF > 0.5, inside the field of view in every frame.
9. Confounds. A table with fMRIPrep's column names: 24 motion regressors (6 parameters, their derivatives and squares; Friston 1996), framewise displacement (Power 2012), the mean signals of brain (global_signal), WM and CSF, aCompCor components of WM and CSF (computed on good frames), one motion_outlier_XX column per flagged frame and a censor column.
10. IQMs (optional, on by default): MRIQC image quality metrics of the raw BOLD and T1w; see 6.5.
11. Denoising. One linear model per voxel: polynomial trend (order 1) + the chosen regressors, with data and regressors band-passed by the same filter, fitted on the good frames. High-motion frames are first filled in from the good frames (spectral interpolation) so that filtering does not spread them, then left out of the fit and marked for later steps. The voxel mean is added back. Output: desc-denoised.
12. Smoothing (optional): Gaussian kernel of the chosen FWHM; output desc-denoisedSm6. The unsmoothed series is kept.
13. Outputs and a QC report per run; when all runs have finished, the group report and the exclusion list.

Input options

Preprocessing options

VBM options

Nuisance mask options

Denoising, censoring, smoothing and quality-control options are in sections 6.12 and 6.13; output, selection and run options in 6.15.

Outputs

derivatives/seecat/
  dataset_description.json
  sub-01/
    anat/  sub-01_desc-preproc_T1w.nii             bias-corrected T1w (coregistered to the EPI)
           sub-01_label-GM|WM|CSF_probseg.nii       native tissue maps (sidecar: volumes in mL, TIV)
           sub-01_from-T1w_to-IXI549Space_mode-image_xfm.nii   deformation field
           sub-01_space-IXI549Space_res-1p5_label-GM_desc-modulated_probseg.nii      VBM (vbm.enable)
           sub-01_space-IXI549Space_res-1p5_label-GM_desc-modulatedSm8_probseg.nii   VBM, smoothed
    func/  sub-01_task-rest_space-IXI549Space_res-3_desc-preproc_bold.nii      normalised, not denoised
           sub-01_task-rest_space-IXI549Space_res-3_desc-denoised_bold.nii     input of Seed FC, Degree, Gradients
           sub-01_task-rest_space-IXI549Space_res-3_desc-denoisedSm6_bold.nii  smoothed copy
           sub-01_task-rest_space-IXI549Space_res-3_desc-brain_mask.nii
           sub-01_task-rest_desc-confounds_timeseries.tsv (+ .json)
    sub-01_task-rest_desc-qc_report.html, sub-01_task-rest_desc-qc_metrics.json, figures/
  reports/  prep_qc.html, prep_qc.tsv, qc_exclusions.tsv, anat_volumes.tsv, prep_<time>_summary.tsv
  logs/

Images are written compressed (.nii.gz) when the input is compressed, otherwise as .nii. Work files are in seecat_work next to the output folder and are deleted after a unit succeeds (unless Keep work files).

6.4 fMRIPrep denoising

For data already preprocessed by fMRIPrep. For each BOLD run in the chosen space it reads *_desc-preproc_bold, its brain mask and confounds table, removes fMRIPrep's non-steady-state volumes, replaces fMRIPrep's motion outlier columns by SeeCAT's own (the same FD rule for every input), and then denoises, censors and smooths exactly as Preprocessing. Outputs have the same names, so Seed FC, Degree, Gradients and Statistics work unchanged. IQMs are not computed (fMRIPrep's outputs hold no raw data); the motion, coverage and registration checks are (registration uses fMRIPrep's tissue maps in the output space when present).

aCompCor takes the first n c_comp_cor/w_comp_cor columns of fMRIPrep's table; older fMRIPrep versions write only a_comp_cor_*, which must then be listed by name in a config file (denoise.regressors).

6.5 Quality control

Quality control runs inside Preprocessing and fMRIPrep denoising; the QC reports page is where you review it and decide which runs are used.

The run report

Each run gets sub-*/…_desc-qc_report.html with:

• a summary: frames, dummy scans, mean and largest FD, flagged frames, minutes kept, tSNR, the correlation of FD with DVARS before and after denoising (a good denoising brings it close to 0), largest translation and rotation, coverage;
• head motion: FD over time with the threshold and flagged frames shaded, translations and rotations;
• DVARS before and after denoising;
• carpet plots (Power 2017) before and after denoising, voxels ordered GM, WM, CSF;
• registration and coverage: the mean normalised EPI with the template GM outline and the brain mask, and the registration measures;
• the WM and CSF masks used for the nuisance signals;
• the image quality metrics (MRIQC).

Image quality metrics (IQMs)

With qc.iqm (on by default) Preprocessing computes the metrics of MRIQC (Esteban et al. 2017) on the raw data, reusing its own segmentation, realignment and coregistration: the BOLD run after dummy-scan removal, head-motion corrected, without slice timing; the T1w with its bias-corrected image and native tissue maps. The formula-based metrics give the same values as MRIQC's own functions on the same inputs; the head, air and brain masks are SeeCAT's own, so absolute values can differ from an MRIQC run. Compare runs within a dataset and within a site.

Registration measures

Coverage

The share of the template brain inside the field of view in every frame, in total and separately for its top (z > 50 mm) and bottom (z < −30 mm: cerebellum and temporal poles). Low coverage means part of the brain was not scanned.

Exclusion rules and warnings

When every run has finished, the group report (reports/prep_qc.html) writes reports/qc_exclusions.tsv. A run is suggested for exclusion when it breaks a rule:

Warnings, which do not exclude: mean FD above 0.25 mm; bottom coverage below 80 %; an IQM or registration measure whose robust z (distance from the median in MADs) within the run's site is beyond 3 in the bad direction. Sites come from the site column of participants.tsv; without it, or with fewer than 5 runs in a site, the whole dataset is the reference. T1w images get a row of their own, with warnings only.

The QC reports page

Choose the derivatives folder: the table lists every run and T1w image with its site, mean FD, largest translation and rotation, coverage, brain Dice, GM correlation with the TPM, minutes kept, tSNR, T1w CNR, the reasons and the warnings. Tick or untick Exclude, add a Note, and Save decisions. Rows you change are marked as your decision and keep it when Preprocessing is run again. Group report and Run report open the HTML pages.

The list is a plain table:

id                        kind  exclude  reasons            warnings              decision  note
sub-PKUHC0001_task-rest   bold  1        mean FD > 0.5 mm                         auto
sub-SCUMDD0003_task-rest  bold  0                           mean FD > 0.25 mm     user      checked carpet plot
sub-CSUHC0002_T1w         T1w   0                           cnr outlier           auto

Later steps match files to this list by the entities that identify an acquisition (sub, ses, task, acq, ce, rec, dir, run, echo), so every map derived from an excluded run, and the VBM maps of an excluded T1w, are left out. Editing the list does not make finished units run again.

6.6 Seed FC

Seed-based functional connectivity. For each run and seed, the mean signal of the seed's voxels (inside the brain mask, on the frames kept after censoring) is correlated with every voxel; the result is written as a Pearson r map and a Fisher z map (z = atanh r). Use the z maps in Harmonize and Statistics.

Seeds

• Sphere: a centre in MNI millimetres (x y z) and a radius; voxels within the radius of the centre. Examples: PCC 0 -53 26, mPFC 0 52 -6, left motor cortex -38 -22 56.
• Mask: a NIfTI image in MNI space (any voxel size; voxels above 0 are the seed), resampled to the data by nearest neighbour. Add mask files adds one row per chosen file, named after it.

Names are letters and digits; they become the desc of the output maps.

Outputs

sub-01/func/sub-01_task-rest_space-IXI549Space_res-3_desc-PCC_stat-r_connectivity.nii.gz (+ .json)
sub-01/func/sub-01_task-rest_space-IXI549Space_res-3_desc-PCC_stat-z_connectivity.nii.gz (+ .json)

The sidecar records the seed (centre and radius, or file), the input series and the frames used.

cfg = seecat.config('fc');
cfg.input_dir = 'D:/study/bids/derivatives/seecat';
cfg.seeds = struct('name', {'PCC', 'Amygdala'}, 'center', {[0 -53 26], []}, ...
                   'radius', {6, []}, 'file', {'', 'D:/masks/amygdala_L.nii'});
seecat.run(cfg);

6.7 Degree

Voxel-wise degree centrality. Every voxel of the mask is a node of the correlation network of a run (frames kept after censoring). The binary degree of a voxel counts its connections whose correlation reaches the threshold; the weighted degree (strength) sums their r values. As in SeeCAT 1.0: correlations from z-scored series, the sign rule applied (absolute: |r|; negative: −r), values below the threshold set to 0. Optionally connections shorter than a distance are ignored, or split into distance bins (short- and long-range degree). Maps are written raw and z-scored within the mask, and smoothed afterwards if asked (the network is built from unsmoothed data).

Outputs

…_desc-degPosBinR0p2_stat-raw_connectivity.nii.gz      binary degree, positive r ≥ 0.2
…_desc-degPosBinR0p2_stat-z_connectivity.nii.gz        the same, z-scored within the mask
…_desc-degPosWeiR0p2Sm6_stat-z_connectivity.nii.gz     strength, z-scored, smoothed 6 mm
…_desc-degPosBinR0p2D0to75_stat-raw_connectivity.nii.gz  with distance bins [0 75 Inf]

Time and memory grow with the square of the number of voxels: about 50 000 grey-matter voxels at 3 mm take seconds to a minute per run; at 2 mm there are 3.4 times as many voxels and over ten times the work.

6.8 Gradients

Connectivity gradients (Margulies et al. 2016): the main axes along which connectivity profiles change across the cortex, the first usually running from sensory and motor cortex to the default-mode network. For each run:

1. the node series: the mean of the run's brain-mask voxels in each node (voxels of a coarser MNI grid, or parcels of an atlas), frames kept after censoring;
2. the connectivity matrix: Pearson r between nodes;
3. each row keeps its strongest 10 % (sparsity 0.9) and the rest is set to 0;
4. the affinity between rows: normalised angle (1 − angle/π of their cosine similarity) or cosine;
5. diffusion map embedding with α = 0.5 (Coifman & Lafon 2006) and multiscale eigenvalues λ/(1−λ), as BrainSpace (Vos de Wael et al. 2020);

then the runs are aligned (generalized Procrustes: rotations and sign flips onto a reference, the reference updated to the mean, up to 10 rounds), starting from the gradients of the group-mean connectivity matrix (default) or from the first run. SeeCAT's embedding equals the exact diffusion map; it solves the symmetric form of the problem.

Choosing the nodes

Times are for a 32-core desktop and 200-volume runs. SeeCAT checks the free memory first and stops with advice when it is not enough. An atlas (e.g. Schaefer 400) is fast and gives a value per parcel, also written as a table.

Outputs

sub-01/func/…_desc-grad1Vox4_connectivity.nii.gz   gradient 1 of the run, aligned (2, 3 … up to Maps written)
group/gradientsVox4/gradientsVox4_desc-grad1_reference.nii    final reference (mean of the aligned runs)
group/gradientsVox4/gradientsVox4_desc-grad1_groupmatrix.nii  gradients of the group-mean matrix
group/gradientsVox4/gradientsVox4_lambdas.tsv     eigenvalues of every run, variance explained, r with the reference

6.9 Harmonize

Multi-site studies carry site and scanner differences in every map. Harmonize removes them from per-subject maps, between the measures (Seed FC, Degree, Gradients, VBM) and Statistics, while keeping the effects you will test. It writes the harmonised maps next to the originals with the desc label extended (desc-PCC → desc-PCCComBat).

Methods

The ComBat variants give the same results as neuroCombat. A reference site can be kept unchanged with the others mapped onto it. Every effect you will test later must be among the kept covariates; otherwise, where it differs between sites, it is partly removed with the site effect. The log and group/harmonize<label>_<maps>_<hash>/…_report.json (the hash tells map selections apart) give the share of voxels with a site effect (F test, p < 0.05, adjusted for the kept effects) before and after.

6.10 Statistics

Group statistics on per-subject maps: a general linear model at every voxel, contrasts, and correction for multiple comparisons. The model, smoothness estimate and random field theory follow SPM, so the numbers match SPM's results table for the same model.

Designs

Covariates are mean-centred; text covariates become centred dummy columns. With Variance unequal (default for anova1_rm), non-sphericity is estimated with ReML as in SPM.

Corrections

• cluster_fwe (default): clusters of voxels above the cluster-forming p (0.001), kept when their extent has a family-wise error p < alpha by random field theory.
• voxel_fwe: voxels with FWE p < alpha (random field theory).
• voxel_fdr: voxels with false discovery rate < alpha (Benjamini–Hochberg).
• tfce_fwe: threshold-free cluster enhancement (Smith & Nichols 2009; E = 0.5, H = 2, 26-connectivity) with voxel FWE p from permutations (Freedman–Lane: sign flips for one-sample, swaps within subjects for paired designs, row permutations otherwise), as FSL randomise. Parallel workers share the permutations.

With Two-tailed (default), each T contrast of a pair is tested at alpha/2. Maps excluded by QC are left out, and every map that is dropped (no participants.tsv row, a missing value) is listed in the log.

Outputs

group/<name>/
  <name>_design.tsv                                    maps and design columns
  <name>_desc-mask_mask.nii.gz                         voxels tested
  <name>_contrast-<c>_stat-t_statmap.nii.gz          T (or F) map, with df and smoothness in the sidecar
  <name>_contrast-<c>_stat-z_statmap.nii.gz          Z of the same p
  <name>_contrast-<c>_stat-p_statmap.nii.gz          −log10 p
  <name>_contrast-<c>_stat-effect_statmap.nii.gz     contrast estimate
  <name>_contrast-<c>_desc-clusterFWE_stat-t_statmap.nii.gz   thresholded map
  <name>_contrast-<c>_desc-clusterFWE_dseg.nii.gz             surviving clusters, numbered
  <name>_contrast-<c>_desc-clusterFWE_clusters.tsv            cluster table (SPM style)
  <name>_contrast-<c>_desc-tfce_stat-tfce_statmap.nii.gz     TFCE values (tfce_fwe)
  <name>_contrast-<c>_desc-tfceFWE_stat-p_statmap.nii.gz     −log10 FWE p (tfce_fwe)
  <name>_report.json

The cluster table has, per cluster, its size, FWE and uncorrected cluster p, and up to three peaks more than 8 mm apart with statistic, Z, peak p and MNI coordinates.

6.11 Viewer

The viewer shows any NIfTI image on an MNI brain: SeeCAT's statistic maps, seed and degree maps, gradients, VBM maps, or a 4D BOLD series.

• Layouts: Orthogonal (three views and the cursor read-out), Single (one large view and three thumbnails), Mosaic (slices of one orientation).
• Underlay: chosen by the map's space (ch2 for IXI549Space, ICBM152 2009c for MNI152NLin2009cAsym), or picked from the menu.
• Threshold by value or by p. For SeeCAT statistic maps (and SPM-style maps with df in the header) p thresholds can be corrected (cluster FWE, voxel FWE, voxel FDR) with the same code as Statistics, so the viewer and the pipeline agree. Sign (+, −, ±), minimum cluster size, colour map and opacity.
• Clusters: the table of clusters with their peaks and atlas labels (Neuromorphometrics from SPM; AAL and Brodmann when BrainNet Viewer is installed); clicking a row moves the cursor. Export TSV saves it.
• Time series: for a 4D series, the cursor voxel's signal with FD and flagged frames; a slider and Play step through the volumes.
• Save image writes the current view as PNG; Save map writes the thresholded map as NIfTI; Surface shows the map on the cortex in BrainNet Viewer.
• Neuro / Radio: left on the left, or on the right.

seecat.viewer('group/PCConeSampleHC/PCConeSampleHC_contrast-pos_stat-t_statmap.nii.gz')

6.12 Shared: denoising, censoring and smoothing

These options are the same on Preprocessing and fMRIPrep denoising.

6.13 Shared: quality control

6.14 Shared: selection of runs

The pages that process runs choose them by subject, session, task and run. Seed FC, Degree, Gradients, Harmonize and Statistics also leave out what quality control excluded:

6.15 Shared: output and run

7 Worked examples

This chapter runs a complete study and reports what SeeCAT produced, with the real numbers. Every figure in this manual comes from these runs. The script that ran them is in section 8.2; the configurations can also be loaded into the window with Load.

7.1 The example dataset

A public test subset of a multi-site depression study: 30 subjects from three sites (CSU, PKU, SCU), five healthy controls (HC) and five patients with major depression (MDD) at each site. Every subject has one T1-weighted image and one resting-state run (TR 2 s). The three per-site folders were merged into one BIDS dataset with a participants.tsv:

participant_id   site   group   age   sex
sub-CSUHC0001    CSU    HC      28    M
sub-CSUHC0002    CSU    HC      34    M
…

All runs used n_workers = 'auto' on a 32-core workstation with about 200 GB of free memory. The outputs go to manual_run/derivatives/seecat.

7.2 Example A: seed connectivity of the default-mode network

From BIDS to a group map of posterior cingulate (PCC) connectivity, and a comparison of the two groups.

A1. Check the data

On Data check, choose the BIDS folder and press Scan. The table lists 30 runs, one per subject, with their volumes and TR (section 6.2). Nothing is missing, so preprocessing can start.

A2. Preprocess

On Preprocessing: BIDS folder bids2, Output folder manual_run/derivatives/seecat, tick VBM maps (for Example B), Parallel workers auto; all other options at their defaults. Press Run.

Parallel workers (auto): about 5.5 GB per worker (4.5 GB task + 1 GB worker), 0.5 GB kept by the main MATLAB,
    206.4 GB free: 30 worker(s) (32 cores, 30 task(s))
Parallel pool: A pool of 30 workers did not start (…). Started 15 workers instead.
QC: …/derivatives/seecat/reports/prep_qc.html
Tissue volumes: …/derivatives/seecat/reports/anat_volumes.tsv
Done: 30 ok, 0 skipped, 0 failed.

The memory estimate allowed 30 workers. Windows could not start that many at once, so SeeCAT retried with half and noted it in the log. The 30 runs took about 19 minutes.

A3. Review quality

The group report reports/prep_qc.html (figure in section 6.5) suggests excluding four runs:

Other runs have warnings but are kept. Examples:

• sub-PKUHC0001: DVARS and AQI outliers, and a low grey-matter correlation with the TPM (0.637, the lowest of the study). Open its run report and look at the carpet plot and registration before deciding.
• sub-PKUMDD0005: mean FD 0.281 mm, above the 0.25 mm warning level, but enough clean data remain.
• sub-SCUHC0001: an FBER outlier. Its run report (figure in section 6.5) shows one movement about 2.5 minutes into the run; the six censored frames around it are shaded.

The brain mask Dice with the template is 0.956 to 0.984 for all runs, so no registration failed. We keep the suggestions as they are. The QC reports page shows the same list and can change any decision before the next step.

Every later step reads the exclusion list and logs what it leaves out:

Left out by QC (reports/qc_exclusions.tsv): sub-CSUHC0004_task-rest, sub-CSUHC0005_task-rest,
    sub-CSUMDD0004_task-rest, sub-PKUMDD0002_task-rest

This leaves 26 runs: 13 HC (CSU 3, PKU 5, SCU 5) and 13 MDD (CSU 4, PKU 4, SCU 5).

A4. Seed FC

On Seed FC, add two spheres of 6 mm radius: PCC at (0, −53, 26) and mPFC at (0, 52, −6). The 26 runs took 7 seconds. Each run gets r and Fisher z maps:

sub-SCUHC0001_task-rest_space-IXI549Space_res-3_desc-PCC_stat-z_connectivity.nii.gz
sub-SCUHC0001_task-rest_space-IXI549Space_res-3_desc-mPFC_stat-z_connectivity.nii.gz

A5. Harmonize

On Harmonize: Map PCC, Statistic z, Site column site, Method combat, Covariates kept group, sex, age.

[harmonizeComBat_PCCz_3821b739] 26 maps, 45150 voxels, 3 sites (CSU: 7, PKU: 9, SCU: 10)
[harmonizeComBat_PCCz_3821b739] kept effects: group_MDD, sex_M, age
[harmonizeComBat_PCCz_3821b739] voxels with a site effect (p < 0.05): 9.9% before, 0.1% after

Before harmonisation, 9.9% of grey-matter voxels had a site effect, about twice the 5% expected by chance. After ComBat, 0.1% did. The new maps are named desc-PCCComBat. With sites this small, SeeCAT also logs the small-site warning of section 6.9. Here we keep ComBat for the FC maps; Example B shows when this matters.

A6. One-sample test in the healthy controls

Is PCC connectivity positive in the 13 controls? On Statistics: Name PCConeSampleHC, Map PCCComBat, Statistic z, Design one_sample, Subjects: the 13 HC labels, Correction cluster_fwe and tfce_fwe.

[PCConeSampleHC] 13 maps, 45150 voxels in the analysis mask
[PCConeSampleHC] df 12.00; FWHM [6.31 6.48 7.38] mm; resels 2812.9
[PCConeSampleHC] TFCE: 5000 permutations (flip), 2 contrast(s), 16 worker(s), 93 s
[PCConeSampleHC] pos, cluster_fwe: height 3.930, 12 cluster(s) / 1705 voxel(s) survive
[PCConeSampleHC] pos, tfce_fwe: height 2.780, 33 cluster(s) / 3867 voxel(s) survive
[PCConeSampleHC] neg, cluster_fwe: height 3.930, 6 cluster(s) / 140 voxel(s) survive
[PCConeSampleHC] neg, tfce_fwe: height 6.340, 4 cluster(s) / 7 voxel(s) survive

The cluster-forming threshold p < 0.001 is t ≥ 3.93 at 12 degrees of freedom. The largest positive clusters are those of the default-mode network:

TFCE finds the same network and extends it (3867 voxels). Its height is the smallest t that survives (2.78), so lower than the cluster-forming threshold. In the cluster file, a row with n/a voxels is a further peak of the cluster above it (e.g. −9, −69, 27 and 3, −63, 39 in the PCC cluster). Open the result in the viewer (figures in section 6.11): at p 0.001 with cluster FWE and both signs, the viewer shows the same 18 clusters (12 positive, 6 negative; 1845 voxels).

A7. Two-sample test, HC versus MDD

Name PCCtwoSample, Design two_sample, Factor group, Levels HC, MDD, Covariates age, sex.

[PCCtwoSample] 26 maps, 45150 voxels in the analysis mask
[PCCtwoSample] df 22.00; FWHM [6.09 6.23 7.18] mm; resels 3115.0
[PCCtwoSample] HCgtMDD, cluster_fwe: height 3.505, 0 cluster(s) / 0 voxel(s) survive
[PCCtwoSample] MDDgtHC, cluster_fwe: height 3.505, 0 cluster(s) / 0 voxel(s) survive

No cluster survives in either direction. With 13 subjects per group this is expected and is not evidence that the groups have the same connectivity. The unthresholded t map (…_contrast-HCgtMDD_stat-t_statmap) can still be shown in the viewer, or used to plan a larger study.

7.3 Example B: grey-matter volume and age (VBM)

Because VBM maps was ticked in A2, every T1w already has modulated grey-matter maps in MNI space (1.5 mm), smoothed with 8 mm:

sub-SCUHC0001_space-IXI549Space_res-1p5_label-GM_desc-modulatedSm8_probseg.nii

Total intracranial volume per subject is in reports/anat_volumes.tsv. Statistics and Harmonize read it automatically as the column tiv_ml. The QC exclusions are for fMRI runs, so all 30 T1w images are used here.

B1. Regression on age

On Statistics: Name VBMage, Map modulatedSm8, Label GM, Suffix probseg, Design regression, Regressors age, Covariates sex, tiv_ml, site, Mask gm.

[VBMage] 30 maps, 414177 voxels in the analysis mask
[VBMage] df 24.00; FWHM [11.43 11.81 11.25] mm; resels 797.0
[VBMage] agepos, cluster_fwe: height 3.467, 0 cluster(s) / 0 voxel(s) survive
[VBMage] ageneg, cluster_fwe: height 3.467, 0 cluster(s) / 0 voxel(s) survive

The site column is text, so it enters the model as two indicator columns. With intercept, age, sex, TIV and site, that leaves 30 − 6 = 24 degrees of freedom. Since the ages are random, no effect is the correct result.

B2. Why not ComBat here

Site differences in VBM are large: in 49.8% of grey-matter voxels before harmonisation (0.2% after ComBat with group, sex, age and TIV kept). It seems natural to harmonise first. We ran the same regression after each choice:

The age effect is not real, so the ComBat clusters are false positives. ComBat rescales each site's residual variance using only ten subjects per site. That makes the harmonised data look less variable than they are, and tests of the kept covariates become too liberal (Nygaard et al. 2016). Methods that only remove site means do not have this problem. With fewer than about 20 subjects per site:

• use combat_mean or lm, or keep the maps unharmonised with site as a covariate;
• compare any ComBat result with the unharmonised one before reporting it.

SeeCAT writes this warning in the Harmonize log and report.

7.4 Example C: degree centrality and gradients

C1. Degree

Degree with its defaults: grey-matter mask, positive correlations above r = 0.2, binary and weighted degree, also as z-scored maps, smoothed with 6 mm.

Parallel workers (auto): about 3.9 GB per worker (2.9 GB task + 1 GB worker), …: 26 worker(s)
Done: 26 ok, 0 skipped, 0 failed.

The 26 runs took about 2 minutes. Each run gets four maps, each as raw values and as z:

…_desc-degPosBinR0p2_stat-z_connectivity.nii.gz        binary, unsmoothed
…_desc-degPosWeiR0p2Sm6_stat-z_connectivity.nii.gz     weighted, smoothed: the usual choice for statistics

Harmonising degPosWeiR0p2Sm6 z (with group, sex and age kept) reduced voxels with a site effect from 17.2% to 0.0%. Degree is more site-dependent than seed FC here, probably because it summarises the whole connectivity distribution, which depends on noise and smoothness.

C2. Gradients

Gradients with the defaults: Nodes voxels with Node size 4 mm (the unit is named gradientsVox4), 10 components with 3 maps written, Alignment group.

Parallel workers (auto): about 8.2 GB per worker (7.2 GB task + 1 GB worker), 7.7 GB kept by the main MATLAB,
    187.4 GB free: 18 worker(s) (32 cores, 26 task(s))
[gradientsVox4] 26 run(s), 21972 nodes (Vox4); about 7.2 GB of memory per run being computed
[gradientsVox4] node series done; 19564 of 21972 nodes have data in every run
[gradientsVox4] gradients of 26 run(s) in 413 s (15 worker(s))
[gradientsVox4] finished (472.0 s)

Each run needs a 21972 × 21972 connectivity matrix, so memory, not cores, set the number of workers (18). The reference is the gradient of the group-mean matrix. Each run is aligned to it, a new reference is formed from the mean of the aligned runs, and this repeats until the reference no longer changes.

group/gradientsVox4/gradientsVox4_lambdas.tsv gives, per run:

• the eigenvalues;
• the variance explained by gradient 1: 0.18 to 0.31, median 0.24;
• the correlation of the run's aligned gradient 1 with the reference: 0.43 to 0.69, median 0.58.

A run with a much lower correlation than the others deserves a look at its QC report. The per-run maps (desc-grad1Vox4 … grad3Vox4) can be harmonised and tested like any other map.

7.5 Time for the whole study

8 Batch scripting

Everything in the window is available from MATLAB code. A pipeline is configured by a struct and run by seecat.run; the window's Save button writes the same struct as JSON.

8.1 Functions

8.2 A complete study

The scripts of chapter 7, in one file. Each seecat.run call can be run on its own; finished units are skipped when run again.

bids = 'D:/data/test_seecat/DIDA/bids2';
out  = 'D:/data/test_seecat/DIDA/manual_run/derivatives/seecat';

% 1. Preprocessing with image quality metrics and VBM maps
cfg = seecat.config('prep');
cfg.bids_dir   = bids;
cfg.output_dir = out;
cfg.vbm.enable = true;
cfg.n_workers  = 'auto';
seecat.run(cfg);
% ... review reports/prep_qc.html and the QC reports page ...

% 2. Seed FC
cfg = seecat.config('fc');
cfg.input_dir = out;
cfg.seeds = struct('name', {'PCC', 'mPFC'}, 'center', {[0 -53 26], [0 52 -6]}, ...
                   'radius', {6, 6}, 'file', {'', ''});
cfg.n_workers = 'auto';
seecat.run(cfg);

% 3. Degree and gradients
cfg = seecat.config('degree');   cfg.input_dir = out;   cfg.n_workers = 'auto';   seecat.run(cfg);
cfg = seecat.config('gradient'); cfg.input_dir = out;   cfg.n_workers = 'auto';   seecat.run(cfg);

% 4. Harmonize the PCC maps across the three sites
cfg = seecat.config('harmonize');
cfg.input_dir  = out;
cfg.maps       = struct('desc', 'PCC', 'stat', 'z');
cfg.site       = 'site';
cfg.covariates = {'group', 'sex', 'age'};
seecat.run(cfg);                                  % writes desc-PCCComBat maps

% 5. One-sample t test in the HC group, with TFCE
P  = seecat.io.read_tsv(fullfile(bids, 'participants.tsv'));
hc = erase(P.participant_id(strcmp(P.group, 'HC')), 'sub-')';
cfg = seecat.config('stat');
cfg.name      = 'PCConeSampleHC';
cfg.input_dir = out;
cfg.maps      = struct('desc', 'PCCComBat', 'stat', 'z');
cfg.design    = 'one_sample';
cfg.subjects  = hc;
cfg.inference = {'cluster_fwe', 'tfce_fwe'};
cfg.n_workers = 'auto';
seecat.run(cfg);

% 6. VBM: grey matter and age, unharmonised maps with site as a covariate
cfg = seecat.config('stat');
cfg.name       = 'VBMage';
cfg.input_dir  = out;
cfg.maps       = struct('desc', 'modulatedSm8', 'label', 'GM', 'suffix', 'probseg');
cfg.design     = 'regression';
cfg.regressors = {'age'};
cfg.covariates = {'sex', 'tiv_ml', 'site'};
cfg.mask       = 'gm';
seecat.run(cfg);

seecat.viewer(fullfile(out, 'group', 'PCConeSampleHC', 'PCConeSampleHC_contrast-pos_stat-t_statmap.nii.gz'));

8.3 Configuration files

A configuration file is the struct as JSON. Only the options you change need to be in it; the others take their defaults. Numbers with Inf are written as text ("[0 75 Inf]") and read back as numbers.

{
  "pipeline": "stat",
  "name": "PCCtwoSample",
  "input_dir": "D:/data/test_seecat/DIDA/manual_run/derivatives/seecat",
  "maps": {"desc": "PCCComBat", "stat": "z"},
  "design": "two_sample",
  "factor": "group",
  "levels": ["HC", "MDD"],
  "covariates": ["age", "sex"]
}

Run several configurations in sequence:

for f = {'prep.json', 'fc.json', 'harmonize.json', 'stat.json'}
    seecat.run(fullfile('D:/study/configs', f{1}));
end

8.4 Running on a server

Without a display, start MATLAB with -batch:

matlab -batch "addpath('/opt/spm'); addpath('/opt/SeeCAT/SeeCAT'); seecat.run('/data/configs/prep.json')"

Logs are written as the run goes (<output>/logs), so progress can be followed with tail -f.

9 Output reference

9.1 The derivatives folder

derivatives/seecat/
  dataset_description.json                 names the source dataset (SourceDatasets)
  sub-<label>/[ses-<label>/]
    anat/                                  T1w outputs (Preprocessing)
    func/                                  run outputs and per-run maps (all pipelines)
    sub-<label>_…_desc-qc_report.html      run reports, qc_metrics.json, figures/
  group/
    <name>/                                Statistics
    harmonize<label>_<maps>/                      Harmonize: maps.tsv, report.json
    gradients<nodes>/                      Gradients: reference maps, lambdas.tsv
  reports/
    prep_qc.html, prep_qc.tsv              group QC (or fmriprep_qc.*)
    qc_exclusions.tsv                      the exclusion list
    anat_volumes.tsv                       GM, WM, CSF, TIV per T1w
    <pipeline>_<time>_summary.tsv          one per run of a pipeline
  logs/
    <pipeline>_<time>.log, _config.json    main log and the configuration used
    <pipeline>_<time>/<unit>.log           one log per unit
    done/                                  finished units and their settings (for skipping)
    outputs/                               files written by each unit
seecat_work/                               work files (next to the output folder)

9.2 File names

9.3 Confounds table

9.4 JSON sidecars

Each image's sidecar describes how it was made. Common fields: Sources (the files it came from: BIDS URIs such as bids:raw:sub-01/func/… for the per-run outputs; Harmonize and Statistics list the paths of their input maps), Software, and step-specific fields, for example FramesUsed, FramesTotal and Seed (Seed FC); Threshold, Sign, Measure (Degree); Lambdas, VarianceExplained, Alignment (Gradients); Harmonization, Site, KeptEffects (Harmonize); DegreesOfFreedom, FWHMmm, Resels, Contrast, Inference (Statistics).

10 Performance and common questions

10.1 Time and memory

With n_workers = auto, SeeCAT chooses the number of workers from these estimates and the free memory; the log shows the choice.

10.2 Common questions

A subject failed. Do I have to run everything again?

No. Run the same configuration again: finished subjects are skipped and the failed one resumes at the step where it stopped. The unit's log (logs/<pipeline>_<time>/<unit>.log) gives the reason.

I changed an option. What is recomputed?

Every unit whose result depends on it. Changing only Parallel workers or Keep work files recomputes nothing; ticking Overwrite recomputes every unit and clears its work folder. A finished unit is also run again when its inputs changed, when SeeCAT itself changed, or when one of its outputs was deleted; the log says why. Inputs are every file the unit reads, including the files named in the options (seed and ROI images, masks, atlases, image covariates, the participants table), the set of maps selected, the participant values and the runs excluded or restored by QC. A file up to 64 MB is compared by its contents, a larger one (a BOLD series) by its size and date. SeeCAT itself is the code that computes the results and the bundled templates: after an update, finished units are computed again with the new code. Files outside these, for example an SPM installed elsewhere, are not followed; tick Overwrite after changing them.

Can I write the results into the input folder, or run SeeCAT twice at once?

The output folder may not be the BIDS folder or the fMRIPrep folder; SeeCAT refuses it before writing anything. In every other case a unit that would write over one of its own input files stops with an error and leaves the file as it is. Two SeeCAT sessions may work in the same output folder at the same time on different units (for example different subjects); a unit that another session is computing fails with a message naming that session, and is computed when you run the configuration again. If MATLAB was closed while a unit ran, its lock (logs/locks/) is removed by the next run on the same computer.

Seed FC says "no desc-denoised bold" or finds no runs.

Check that the derivatives folder is the output of Preprocessing or fMRIPrep denoising and that Denoise was on. If the folder holds runs in more than one space, set Space; with several tasks, set Task. If every run is excluded by QC, check the QC reports page.

Statistics finds several maps per subject.

The map fields must pick exactly one map per subject (two for paired designs). Add Space, Task or Other (e.g. run=1) until the line below the fields counts one map per subject.

Where are age, sex and group taken from?

From participants.tsv of the BIDS dataset (see 3.7). Values that are empty or n/a drop that subject from the analysis that uses the column, and the log lists it.

Should I smooth before Seed FC?

The default input is the unsmoothed desc-denoised; use denoisedSm6 to follow studies that correlate smoothed data. Degree and Gradients should use unsmoothed data; Degree smooths its maps afterwards.

Why harmonize, and when not?

Harmonize when maps from several sites or scanners enter one analysis and the sites have enough subjects (ComBat works best with 10 or more per site). Keep every effect you will test among the covariates. With a single site, skip it.

How do I report the quality control?

The group report gives the rules, the runs excluded and why; reports/qc_exclusions.tsv and prep_qc.tsv hold the numbers. Report the exclusion rules, how many runs were excluded per group and site, and mean FD per group.

The window does not respond during a run.

It should: runs happen in a separate MATLAB process. If MATLAB itself is busy (e.g. a long command in the command window), the window waits for it.

11 References

• Ashburner J, Friston KJ (2005). Unified segmentation. NeuroImage 26:839–851.
• Behzadi Y, Restom K, Liau J, Liu TT (2007). A component based noise correction method (CompCor) for BOLD and perfusion based fMRI. NeuroImage 37:90–101.
• Buckner RL et al. (2009). Cortical hubs revealed by intrinsic functional connectivity. J Neurosci 29:1860–1873.
• Chen AA et al. (2022). Mitigating site effects in covariance for machine learning in neuroimaging data (CovBat). Hum Brain Mapp 43:1179–1195.
• Coifman RR, Lafon S (2006). Diffusion maps. Appl Comput Harmon Anal 21:5–30.
• Eklund A, Nichols TE, Knutsson H (2016). Cluster failure. PNAS 113:7900–7905.
• Esteban O et al. (2017). MRIQC: advancing the automatic prediction of image quality in MRI from unseen sites. PLoS ONE 12:e0184661.
• Esteban O et al. (2019). fMRIPrep: a robust preprocessing pipeline for functional MRI. Nat Methods 16:111–116.
• Fortin JP et al. (2017). Harmonization of multi-site diffusion tensor imaging data. NeuroImage 161:149–170.
• Fortin JP et al. (2018). Harmonization of cortical thickness measurements across scanners and sites. NeuroImage 167:104–120.
• Freedman D, Lane D (1983). A nonstochastic interpretation of reported significance levels. J Bus Econ Stat 1:292–298.
• Friston KJ et al. (1996). Movement-related effects in fMRI time-series. Magn Reson Med 35:346–355.
• Gorgolewski KJ et al. (2016). The brain imaging data structure. Sci Data 3:160044.
• Hallquist MN, Hwang K, Luna B (2013). The nuisance of nuisance regression. NeuroImage 82:208–225.
• Johnson WE, Li C, Rabinovic A (2007). Adjusting batch effects in microarray expression data using empirical Bayes methods. Biostatistics 8:118–127.
• Li X, Morgan PS, Ashburner J, Smith J, Rorden C (2016). The first step for neuroimaging data analysis: DICOM to NIfTI conversion (dcm2niix). J Neurosci Methods 264:47–56.
• Lindquist MA, Geuter S, Wager TD, Caffo BS (2019). Modular preprocessing pipelines can reintroduce artifacts into fMRI data. Hum Brain Mapp 40:2358–2376.
• Margulies DS et al. (2016). Situating the default-mode network along a principal gradient of macroscale cortical organization. PNAS 113:12574–12579.
• Nichols TE (2013). Notes on creating a standardized version of DVARS. arXiv:1704.01469.
• Nygaard V, Rødland EA, Hovig E (2016). Methods that remove batch effects while retaining group differences may lead to exaggerated confidence in downstream analyses. Biostatistics 17:29–39.
• Parkes L, Fulcher B, Yücel M, Fornito A (2018). An evaluation of the efficacy, reliability, and sensitivity of motion correction strategies for resting-state functional MRI. NeuroImage 171:415–436.
• Pomponio R et al. (2020). Harmonization of large MRI datasets for the analysis of brain imaging patterns throughout the lifespan (ComBat-GAM). NeuroImage 208:116450.
• Power JD et al. (2012). Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion. NeuroImage 59:2142–2154.
• Power JD et al. (2014). Methods to detect, characterize, and remove motion artifact in resting state fMRI. NeuroImage 84:320–341.
• Power JD (2017). A simple but useful way to assess fMRI scan qualities. NeuroImage 154:150–158.
• Smith SM, Nichols TE (2009). Threshold-free cluster enhancement. NeuroImage 44:83–98.
• Vos de Wael R et al. (2020). BrainSpace: a toolbox for the analysis of macroscale gradients in neuroimaging and connectomics datasets. Commun Biol 3:103.
• Worsley KJ et al. (1996). A unified statistical approach for determining significant signals in images of cerebral activation. Hum Brain Mapp 4:58–73.
• Xia M, Wang J, He Y (2013). BrainNet Viewer: a network visualization tool for human brain connectomics. PLoS ONE 8:e68910.
• Zuo XN et al. (2012). Network centrality in the human functional connectome. Cereb Cortex 22:1862–1875.

12 Appendix

12.1 Index of options

Every option of every pipeline, by batch field. The tables in chapter 6 explain each one.

12.2 Coming from SeeCAT 1.x