Wonkyconn

AUTHOR

Written by Clara El Khantour, Mathieu Dugré, Pierre Bergeret, Lea Waller, Hao-Ting Wang, Frank Hillary, Clara Moreau

Please address questions and comments to [email protected]. You can also join the HALFpipe Mattermost (similar to Slack) using this link.

Documentation

Wonkyconn evaluates the quality of functional connectivity matrices derived from HALFpipe atlas-based connectivity matrices. Given a set of pre-computed connectivity matrices, a phenotype file (age, gender), and atlas information, it computes a battery of benchmarking metrics and produces a summary report.

The project is based on the code of SIMEXP/fmriprep-denoise-benchmark and the publication by Wang et al. 2024.

This project is in alpha stage! This is not a stable project yet.

For more information, please refer to https://wonkyconn.readthedocs.io/en/latest/

Running WonkyConn

This page provides instructions for running WonkyConn on connectivity matrices generated by HALFpipe.

Installation

WonkyConn is distributed as a container image and can be run using Apptainer/Singularity or Docker

Download the latest container with:

apptainer build wonkyconn-26.2.0a0.simg docker://halfpipe/wonkyconn:26.2.0a0

docker pull halfpipe/wonkyconn:26.2.0a0

Source Code

The WonkyConn source code and documentation are available on GitHub:

https://github.com/HALFpipe/wonkyconn

Running WonkyConn

Example Setup

Define the required paths:

# HALFpipe derivatives directory
BIDS_DIR="/dataset/derivatives"

# Output directory
OUTPUT_DIR="/dataset/wonkyconn_no_QC"

# Phenotype file
PHENOTYPES="/dataset/participants.tsv"

# Atlas file
ATLAS_PATH="/atlas/atlas_enigma/atlas-Schaefer2018Combined_dseg.nii.gz"

# WonkyConn container
WONKYCONN="/containers/wonkyconn-26.2.0a0.simg"

Example Command

apptainer run \
  --contain \
  --cleanenv \
  --bind /path:/path \
  ${WONKYCONN} \
  ${BIDS_DIR} \
  ${OUTPUT_DIR} \
  group \
  --phenotypes ${PHENOTYPES} \
  --atlas atlas_name ${ATLAS_PATH}

The overall command structure is similar to the one used for HALFpipe. Adapt the file paths to match your environment.

Define the required paths:

# HALFpipe derivatives directory
BIDS_DIR="/dataset/derivatives"

# Output directory
OUTPUT_DIR="/dataset/wonkyconn_no_QC"

# Phenotype file
PHENOTYPES="/dataset/participants.tsv"

# Atlas file
ATLAS_PATH="/atlas/atlas_enigma/atlas-Schaefer2018Combined_dseg.nii.gz"

# WonkyConn container
WONKYCONN="/containers/wonkyconn-26.2.0a0.simg"

Example Command

docker run \
  --volume /path:/path \
  ${WONKYCONN} \
  ${BIDS_DIR} \
  ${OUTPUT_DIR} \
  group \
  --phenotypes ${PHENOTYPES} \
  --atlas atlas_name ${ATLAS_PATH}

Atlas Specification

Note

The atlas name (atlas_name) provided with --atlas must match the atlas name used during HALFpipe processing.

You can find the atlas name in your connectivity filenames. For example:

sub-001_task-rest_feature-correlation_atlas-schaeferCombined_desc-correlation.tsv

In this example, the atlas name is schaeferCombined

This name should be passed to the --atlas argument.

Mounting Directories

WonkyConn only has access to directories explicitly mounted with --bind (or --volume with docker).

You may include as many bind mounts as needed. For example:

--bind /path/to/derivatives:/derivatives \
--bind /path/to/atlas:/atlas \
--bind /path/to/phenotypes:/phenotypes

Note

Any file or directory that is not mounted into the container will not be accessible to WonkyConn.

Expected Directory Structure

Important

WonkyConn expects connectivity matrices to be located under a directory named derivatives/halfpipe

Ensure that your mounted directories preserve this structure. A typical layout may look like:

project/
└── derivatives/
    └── halfpipe/
        ├── sub-001/
        ├── sub-002/
        └── ...

Phenotype File Requirements

Note regarding multiple sites

At the moment, Wonkyconn does not account for site effects. You can therefore either run the pipeline separately for each site or combine data across sites into a single analysis. The current analyses only require age and sex as mandatory covariates. Support for site as a covariate may be added in a future release, but this is still under discussion.

The phenotype file must contain at least the following columns:

Column	Description
`participant_id`	Participant identifier
`age`	Participant age
`gender`	Participant sex/gender variable (binary variables)

Example:

participant_id    age    gender
sub-001           24     F
sub-002           19     M

Excluding Participants Based on Quality Control

For datasets containing a single session and a single run, participants with poor QC ratings can be excluded by removing them directly from the phenotype file before running WonkyConn.

Single Session / Single Run

Remove participants that should be excluded from your phenotype file.

WonkyConn will then process only the remaining participants.

Multiple Sessions or Runs

Warning

WonkyConn does not currently support automatic exclusion of individual runs or sessions based on QC ratings.

For datasets that include multiple sessions and/or runs, QC-based exclusion is more complex. In these cases, you can generate a separate script from a QC exclusion file to retain only the runs and sessions that pass quality control for each participant.

A dedicated QC-filtering script is currently under development and will allow WonkyConn to run only on participants and scans that pass QC criteria. If your dataset contains multiple sessions or runs, please contact the developers for the latest recommendations.