Tedana

tedana

tedana is a PYTHON BASED package used for preprocessing multi-echo (ME) fMRI data. Multi-echo data acquisitions involve collecting multiple measurements per radio-frequency (RF) pulse (hence the term - multi-echo). Most fMRI acquisitions involve only one 'snapshot' per RF pulse (hence single-echo)

There are two main benefits of ME acquisitions - both of which can be leveraged using tedana.

a) Data across echoes can be combined to create an 'optimum-combination' in which signal drop-out is minimised and signal is maximised

In tedana, a weighted average is applied to combine echoes such that echoes occurring around the 30-60ms post RF pulse are given greater importance over echoes outside this range (given that that that echo range is known to strike a better balance between signal strength/drop-out and tissue contrast)

b) One gains access to multi-echo independent component analysis based denoising

Different tissue types are known to decay at different rates after an RF pulse - and because multiple measurements are taken in ME acquisitions, we can track signal decay. Typically, this is not done on each voxel independently - instead, voxels are clustered together into independent components - groups of voxels which behave similarly across the timeseries. Based on known decay rates and the decay rates observed, we can then infer probabilistically whether the voxel groups we are looking at are BOLD-like ('signal') or nuisance and thus not relevant for analyses. tedana can estimate which components are likely BOLD-like, and strip non-BOLD like components from the optimally combined data.

tedana works pretty well with fMRIPrep.

As of 19/09/24, one should run fMRIPrep with the --me-output-echos argument such that all echos are preprocessed individually (however, some operations, such as head motion correction, will be estimated using the first echo only, and then applied to all subsequent echos) I tend to run my analyses by executing .py docs from the command line in bash. All one needs to do is run import argparse and from tedana import workflows in the .py doc - and import any other desired libraries (e.g. import os to make directories), and then run tedana like so:

parser = argparse.ArgumentParser()
parser.add_argument('--task', default=None, type=str, help="This is the task name (e.g. rest)")
parser.add_argument('--subj_id', default=None, type=int, help="Subj number")
parser.add_argument('--MY_OUT_DIR', default=None, type=str, help="out_dir for tedana")
parser.add_argument('--echotimes', default=None, type=str, help="echotimes")
parser.add_argument('--echofiles', default=None, type=str, help="echo files")
parser.add_argument('--FMRIPREP_MASK', default=None, type=str, help="prep mask")

echofiles=args.echofiles
echotimes=args.echotimes
task=args.task
subj_id=args.subj_id
MY_OUT_DIR = args.MY_OUT_DIR
FMRIPREP_MASK = args.FMRIPREP_MASK

os.makedirs(out_dir_tedana_mix, exist_ok=True)
workflows.tedana_workflow(
            echofiles,
            echotimes,
            out_dir=MY_OUT_DIR,
            prefix="sub-%s_task-%s-Native" % (subj_id, task),
            t2smap=t2star,
            fittype="curvefit",
            tedpca="kic",
            verbose=True,
            gscontrol=None,
            debug=True,
            mask=FMRIPREP_MASK
)

#!/bin/bash

# Define arguments
TASK="rest"
SUBJ_ID=01
MY_OUT_DIR="/path/to/output_dir"
ECHOTIMES="13.3,30.0,45.0"
ECHOFILES="/path/to/echo1,/path/to/echo2,/path/to/echo3"
FMRIPREP_MASK="/path/to/fmriprep_mask.nii.gz"

# Run the Python script with the arguments
python my_tedana_script.py \
  --task $TASK \
  --subj_id $SUBJ_ID \
  --MY_OUT_DIR $MY_OUT_DIR \
  --echotimes $ECHOTIMES \
  --echofiles $ECHOFILES \
  --FMRIPREP_MASK $FMRIPREP_MASK

SPECIAL NOTES ON USEAGE:

Unlike for other ICA based denoising methods, tedana does not recommend smoothing any data prior to analyses. This can cause issues with combining images. If you only have smoothed data, you can use the PAID method instead of the weighted average method described above - but this is not recommended.

I also prefer to provide my own mask to tedana - while a special mask (a 'good signal') mask will eventually be developed in the tedana workflow, an initial 'guess' mask is needed. The default behaviour is to implement Nilearn’s compute_epi_mask - but I have had some visual QC issues with this previously. fMRIPrep has done a lot of hard work estimating masks etc - why not leverage the work already done? I supply the mask made by fMRIPrep to tedana.

I turn off gscontrol because - at least for now - CSF + WM + GM signal regression tends to be preferred over global signal regression.

I also run with curvefit to estimate the decay rate - it is more computationally expensive, but is meant to be slightly better than performing a linear transform on the decay data before estimating the decay rate with a linear function.