NITRC CONN : functional connectivity toolbox Forum: help

Multi-dataset pipeline

shiinsaad — Thu, 05 Mar 2026 15:13:37 GMT

Hi Alfonso,

I’m building a resting-state functional connectivity mega-analysis that combines multiple independent rs-fMRI datasets, and I’m now starting the preprocessing stage. I would really appreciate your guidance as I move forward.

Across datasets, there is substantial heterogeneity in both (i) study-level variables (number of subjects; number of visits per subject [1–4]; condition availability; demographics; study design [parallel vs crossover]; and stimulation parameters including active vs sham, stimulation site, intensity, duration, electrode shape/size, and potentially a “number of prior sessions” variable to capture consolidation/time effects for studies with repeated active visits) and (ii) acquisition-level variables (TR, slice timing information/slice order, and native voxel size).

I’m preprocessing using CONN in MATLAB (batch mode), aiming to follow CONN’s default MNI preprocessing pipeline as closely as possible.

Data organization

I keep a consistent structure across datasets, e.g.:
Study (01_Name) / Subject (S01) / Visit (V1) / anat and func (PRE, DURING, POST)

Each subject can have 1–4 visits (V1…V4). Each visit typically has one T1 and one 4D resting-state NIfTI per condition: PRE and POST, and in some datasets also DURING.

What I am doing in my batch script (so far tested on one dataset)

1. loop subjects within a dataset
I run the batch one dataset at a time, looping over all subjects in that dataset.

2. auto-detect available visits for the subject
For each subject, the script scans the subject metadata and automatically identifies available visit labels (V1…V4), then sorts them in visit order.

3. Build CONN sessions as visit × condition
For each detected visit, look for functional runs corresponding to each condition in a fixed order:
PRE -> DURING (if available) -> POST
Each available run becomes one CONN “session”, so the final session list is:
V1_PRE, V1_DURING, V1_POST, V2_PRE, … (depending on availability).

My intent was to keep a transparent mapping between acquisition blocks and CONN sessions. In your opinion, for a multi-visit setup, is it better to:

keep conditions identical across visits (PRE/DURING/POST),

or define visit-specific conditions (V1_PRE, V2_PRE, etc.)?

4. one CONN project per subject (multi-session)

For each subject, I create one CONN project containing all that subject’s sessions (sessions = visit × condition).

This was mainly to simplify handling variable session counts and reduce failures when subjects are “incomplete” relative to others. However, I’m unsure if this is a good design for later group-level analyses and contrasts. Would you recommend instead:

one project per dataset (all subjects in that dataset), or

a single project for the full mega-analysis?

5. Structural assignment

At the moment, I provide one T1 per subject (selected from available visits, usually the earliest valid T1).

I initially tried using one T1 per visit/session, but it produced repeated segmentation outputs across visits (multiple c0/c1/c2 generations), and in the CONN GUI the structural preview looked distorted/tilted compared to the original T1.
From a best-practice perspective for multi-visit data: should I insist on using the visit-matched T1 (one per visit), or is one T1 per subject acceptable/preferable in CONN?

6. TR handling
The script reads TR from the JSON (RepetitionTime) when available; otherwise it falls back to a TR value from an external table. It also checks within-subject consistency across sessions.

In one case, a single session had a different TR in JSON (e.g., 2.5 s vs 3.0 s in other sessions). The JSONs were generated from DICOM headers and slice timing info was missing for that Philips scanner.
I’m not sure if this reflects conversion/metadata issues or true acquisition differences that should be modeled explicitly.

7. STC strategy
If SliceTiming is available in JSON, STC is run using the BIDS SliceTiming
If SliceTiming is missing, the script falls back to a user-defined slice order (from an excel)
If neither is available, STC is skipped for that subject (and recorded in the log)

8. preprocessing
I run an explicit steps list that matches CONN’s default MNI pipeline order, with functional_removescans explicitly placed first.

In practice:

If STC is available: removescans -> functional centering -> realign/unwarp -> slice-timing -> ART -> direct functional segmentation+normalization -> smoothing -> structural centering -> structural segmentation+normalization

If STC is not available: same order, but without the slice-timing step.

------------------------------

A) Main issue I’m currently debugging: intermittent “mean functional file not found”

When running this multi-session setup through the default-MNI-style pipeline with mean-based coregistration enabled, I intermittently get:
“Mean functional file not found (associated with functional data … au*.nii)”

It generates a mean image for the first session (V1_PRE), but then fails to find/generate the expected mean for later sessions (e.g., V1_DURING/POST, V2 sessions).
Have you seen this behavior before, and do you have any idea what in the multi-session setup could trigger it (e.g., project structure, session ordering, conditions, or something else)?

I would like to keep mean-based coregistration (i.e., not switch to coregtomean=0). As a temporary workaround, I handle this specific failure in the script as follows:

I run conn_batch in a try/catch.

If the error message contains “Mean functional file not found (associated with functional data … au*.nii)”, I parse the missing au*.nii path from the message.

generate mean directly from that 4D file using SPM (mean across volumes, saved in the same folder).

retry conn_batch once

This resolves the failure. From the output files, it seems like CONN (with direct normalization) is using V1_PRE “reference mean functional” to estimate the normalization, and then it applies that transform to all sessions. In that case, those later sessions do not have session-specific ART-related outputs (e.g., y_art_mean_au… and related files), I am not sure if this is correct.

The first 10 volumes

meikei leung — Thu, 05 Mar 2026 3:14:48 GMT

Hi Alfonso,

In the default preprocessing pipeline, is the step of removing the first 10 volumes of resting-state data automatically included (but not seen in the list of the pipeline)? Or, is this removal step not needed for the preprocessing and ART methods in CONN?

Thanks for your comment on this,

meikei

Should I re-run motion/WM/CSF regression in CONN if already done in FSL?

Gabby Guadalupe — Wed, 04 Mar 2026 16:37:25 GMT

Hi,
I am trying to import preprocessed BOLD data (already in MNI space) into CONN. The data have been slice-time, motion, and distortion corrected. In my preprocessing pipeline (using FSL commands), I also regressed out motion parameters and nuisance signals (CSF and WM), producing residualized BOLD time series.
My question is: When importing into CONN (Setup step), should I input the data before nuisance regression and allow CONN to handle denoising, or is it appropriate to input the already residualized data?
I want to avoid double regression or otherwise interfering with CONN’s denoising pipeline.
Thank you for the hep!
Best, Gabby

RE: Multiple Conn remote connection issues

Joshua Neal — Mon, 02 Mar 2026 15:29:56 GMT

HI Alfonso,
In regards to the Ubuntu Cluster, In was able to talk to my PI about the configuration. For the cluster, there is a first password for the cluster itself, which is the one I enter for the Conn and Matlab interface. His explanation is that the second password is needed for a Kerberos system to connect to the accompanying NAS storage. This is the process that requires a second, department-level password. I am able to enter that second password in a terminal SSH session, but cannot through the Matlab and Conn interfaces to date. Regarding the Windows PC connection, I tested utilizing the scp prompt you gave me, and recieved the following: 
(base) ➜  ~ scp jnnea@100.74.53.80: ~/connserverinfo.json
jnnea@100.74.53.80's password: 
scp: download ./: not a regular file Let me know what thoughts you might have to troubleshoot these connections further.
Thanks again,
Josh
 Originally posted by Alfonso Nieto-Castanon:
<blockquote>
Hi Josh,
Regarding the Ubuntu cluster connection, from your description it seems likely that the system is getting stucked in that "second password" procedure. Can you please provide more details (or point me to your cluster documentation) about how this double-password system works? (e.g. in BU, for example, we have a two-factor authentication procedure in place, but that seems to work fine when using CONN to connect remotely -you would simply get that same prompt requesting to choose a 2FA method in the Matlab command-window when connecting remotely and after answering that prompt everything continuous normally). 
And regarding connecting to your Windows PC, the "reading configuration information" step is trying (and failing) to use scp to download that configuration file from your Windows machine. Can you check from a terminal window on your Mac computer the command:
scp jnnea@100.74.53.80:~/connserverinfo.json .
and see whether that works fine? (one possibility would be that the Windows PC might have a ssh but not scp server active?)
Hope this helps
Alfonso
 
Originally posted by Joshua Neal:
<blockquote>
Hello,
I'm reaching out because I have a M1 Macbook Air running Matlab R2024b and CONN toolbox 22.v2407. I have been attempting to use it as the client computer for either of two different computers - an Ubuntu Cluster, and a personal Windows PC. 
For the Ubuntu cluster, the remote connection works up to the "This may take a few minutes, please be patient as your job currently sits in a queue. CONN will resume automatically when the new Matlab session becomes available" prompt. When I manually ssh into this cluster, I have to enter two separate passwords - first a general password, then a university account specific password. For the Conn remote connection I have been entering the first password, but am not given a prompt to enter a second. Is there a configuration option on my end that I could utilize to get both passwords entered and fulfill the connection?
For the Windows PC, I simply get the following error when attempting the remote login:  "Reading configuration information from jnnea@100.74.53.80:~/connserverinfo.json to /Users/joshneal/.conn_cache/conncache_27de0c9542e2f7f30a24833d879248a1
Unable to find CONN distribution in jnnea@100.74.53.80.
If this is your first time connecting to 100.74.53.80, please use the following steps to confirm that CONN is available there and then try connecting again:
   1. Log in to 100.74.53.80 as user jnnea
   2. Launch Matlab
   3. From Matlab command-window type "conn remotely setup" (without quotes) and confirm that the file ~/connserverinfo.json is created
   4. Log out from 100.74.53.80
(see "in the server computer" section at https://web.conn-toolbox.org/resources/remote-configuration for details)
 
Try connecting again to jnnea@100.74.53.80? (yes|no) :"
This has occurred multiple times, in spite of generating the connserverinfo.json file repeatedly, inlcuding through ssh connection from the Mac to PC. Is there a compatability issue with Windows as the CONN server, or is there another troubleshooting process I can try here? Appreciate any help with either or both connections.
Thanks,
Josh
</blockquote>
 
</blockquote>

Deleting imported files

Mara Britt Neumann — Mon, 02 Mar 2026 14:30:45 GMT

Hello,
I imported data for all subjects with four sessions each. For one subject, however, I need to exclude two sessions from the analysis. I initially tried removing the corresponding files from the file paths, but this now causes errors in CONN.
Is there a proper way to remove specific sessions from a subject within the project so that these two sessions are no longer included in the analysis?
Thank you.

RE: degrees of freedom

Amy Wang — Sun, 01 Mar 2026 21:47:02 GMT

Hi Alfonso, 
If there an easy way to output the residual DOF after denosing at the subject-level? Or get the average DOF across subject after denosing? I used the 2019b version of CONN. Thank you!
Best,
Amy

RE: Session specific re-alignment

Alfonso Nieto-Castanon — Sat, 28 Feb 2026 12:48:21 GMT

Hi Jeff,
In some of the latest releases we added to the default pipeline a "session-specific centering" step before realignment (which applies a simple translation to all functional runs before running realignment) which in our experience helped make realignment more robust avoiding or minimizing this sort of issues. Have you tried if that helps in your case as well? (alternatively, of course, you can run preprocessing separately for each session, as Herberto was doing and similarly to what one would do in the context of longitudinal data, but often that is reserved to cases where the anatomy itself may be expected to have changed between sessions, like in long developmental datasets, in pre/post surgery designs, etc.; and btw the way in batch to run preprocessing only within a single session is to set BATCH.Setup.preprocessing.sessions=session_number)
Hope this helps
Alfonso
Originally posted by Jeff Browndyke:
<blockquote>
Hi,
Did you ever find a solution to this problem and how did you import the separately realigned and processed files back into CONN?
I've been running into this problem for quite a few people in our pipeline.
Thanks, Jeff
</blockquote>

RE: Session specific re-alignment

Jeff Browndyke — Fri, 27 Feb 2026 18:29:09 GMT

Hi,
Did you ever find a solution to this problem and how did you import the separately realigned and processed files back into CONN?
I've been running into this problem for quite a few people in our pipeline.
Thanks, Jeff

RE: Error with conn_jobmanager / parallel processing fails

johnsojp13 — Thu, 26 Feb 2026 16:38:20 GMT

Thanks again, Alfonso. I updated my CONN with the patch and tried running in parallel again and it worked perfectly without any errors. To answer your question: I didn't use a batch script to run the parallel process -- I simply selected "distributed processing (run on Background process (Windows))" in the GUI, specified the number of parallel processes (I tried it several times with the number ranging from 2-10 and got the error every time), and which outlier detection thresholds to use (I always chose default intermediate). That was it. I hope this is helpful.
 Thanks again for your help!
 
Jeff
 
Originally posted by Alfonso Nieto-Castanon:
<blockquote>
for some reason I am not able to attach the patch here, in any case the current development version of CONN in github (github.com/alfnie/conn) now includes this fix (and this specific patch is in the file conn.m)
Best
Alfonso
 
 
Originally posted by Alfonso Nieto-Castanon:
<blockquote>
Hi Jeff,
Thanks for the additional info, this was indeed quite a strange error to debug! if I am interpreting correctly the issue was that in your project info (somehow, I am not sure yet how this happened) the project filename is stored as conn_n21_parallel (the folder) instead of conn_n21_parallel.mat (the file) and that is creating some problems down the stream when running things in parallel. The attached patch should be able to fix this issue, but to make sure I am not missing anything (and to avoid others from running into the same issue) if you could please let me know some specific details on how the parallel process was run (e.g. did you use a batch script) that would be very helpful. 
(note: this patch is for release 25b, to install it simply copy the attached file to your CONN distribution folder overwriting the file with the same name there)
Best
Alfonso
 
Originally posted by johnsojp13:
<blockquote>
Hi Alfonso, 
Thanks for your response. To keep things moving forward, I ran outlier detection overnight using the standard, non-parallelized method. But I also tried running a version in parallel just now and the logs are still showing the same errors, so I'm attaching the qlog subdirectory you requested. 
Thank you,
Jeff
</blockquote>
 
</blockquote>
 
</blockquote>

RE: Importing custom ROIs in MNI space

Isabelle Faillenot — Thu, 26 Feb 2026 13:39:37 GMT

Hi Fabian,
yes you can import your ROI in MNIspace in the setup of CONN. 
If you plan a group analysis, you need to normalize you subject images in the MNI space (with fmriprep before import in CONN or with the 'preprocessing' step inside CONN). Then your images will be in MNI space and so in the same space as your ROI. 
if you plan to make only 1st level analysis (meaning at the individual level) you don't need to normalize subject images. but your ROI should be import in the subject space. I don't know if you can do it inside conn.
hope it helps,
Isabelle