Skip to main content

Combine multi-echoes from a multi-echo fMRI acquisition.

Project description

Multi-echo combinations

PyPI version PyPI - Python Version

MRI data acquisitions can involve multiple volumes acquired at different echo times. Typically, subsequent processing pipelines assume data to be acquired at a single echo time. This repository provides a command line tool to combine multiple echoes from a multi-echo (BOLD f)MRI acquisition. It currently provides three different echo avering algorithms:

algorithm description
1. average Echoes are weighted equally
2. PAID Echoes are weighted by their CNR, i.e. by their TE*tSNR contributions (BOLD fMRI data only)
3. TE Echoes are weighted by their TEs

For more information on multiecho acquisition and combination schemes, please refer to (for example):

  • Poser et al. (2006). BOLD Contrast Sensitivity Enhancement and Artifact Reduction with Multiecho EPI: Parallel-Acquired Inhomogeneity- Desensitized fMRI. Magn. Reson. Med. 55:6, pp. 1227–35.
  • Posse, Stefan (2012). Multi-Echo Acquisition. NeuroImage 62:2, pp. 665–671.

Multiecho has been developed at the Donders Institute of the Radboud University.

Installation

To install, simply run:

pip install multiecho

This will give you the latest stable release of the software. To get the very latest (possibly unreleased) version of the software you can install the package directly from the Github source code repository:

pip install git+https://github.com/Donders-Institute/multiecho

Alternatively, clone this repository and run the following on the root folder of the repository:

pip install .

The tool supports Python 3.6+.

Usage

Once installed, a command line tool called mecombine should be available in your PATH. Detailed usage information can be found by running mecombine -h:

usage: mecombine [-h] [-o OUTPUTNAME] [-a {PAID,TE,average}]
                      [-w [WEIGHTS [WEIGHTS ...]]] [-s] [-v VOLUMES]
                      pattern

Combine multi-echo echoes.

Tools to combine multiple echoes from an fMRI acquisition.
It expects input files saved as NIfTIs, preferably organised
according to the BIDS standard.

Currently three different combination algorithms are supported, implementing
the following weighting schemes:

1. PAID => TE * SNR
2. TE => TE
3. Simple Average => 1

positional arguments:
  pattern               Globlike search pattern with path to select the echo
                        images that need to be combined. Because of the
                        search, be sure to check that not too many files are
                        being read

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUTNAME, --outputname OUTPUTNAME
                        File output name. If not a fullpath name, then the
                        output will be stored in the same folder as the input.
                        If empty, the output filename will be the filename of
                        the first echo appended with a '_combined' suffix
                        (default: )
  -a {PAID,TE,average}, --algorithm {PAID,TE,average}
                        Combination algorithm. Default: TE (default: TE)
  -w [WEIGHTS [WEIGHTS ...]], --weights [WEIGHTS [WEIGHTS ...]]
                        Weights (e.g. = echo times) for all echoes (default:
                        None)
  -s, --saveweights     If passed and algorithm is PAID, save weights
                        (default: False)
  -v VOLUMES, --volumes VOLUMES
                        Number of volumes that is used to compute the weights
                        if algorithm is PAID (default: 100)

examples:
  mecombine '/project/number/bids/sub-001/func/*_task-motor_*echo-*.nii.gz'
  mecombine '/project/number/bids/sub-001/func/*_task-rest_*echo-*.nii.gz' -a PAID
  mecombine '/project/number/bids/sub-001/func/*_acq-MBME_*run-01*.nii.gz' -w 11 22 33 -o sub-001_task-stroop_acq-mecombined_run-01_bold.nii.gz

Caveats

Currently, the echo combination is resource hungry as we load all datasets into memory at once. We could iterate through the volumes and only keep the final combined series in memory at any given time.

You may receive a runtime warning (invalid value encountered in true_divide) when combining echoes with PAID. If your datasets have voxels with zeros, e.g., if they were masked, a division by 0 will lead to infinite weights. You may safely ignore the warning, but do check your data after the combination.

By default, PAID will compute the weights based on the last 100 volumes of the acquisition. Whether this is optimal or not is up to discussion. If you are testing out the combination on a small subset of volumes, say 5 or so, then the weights won't be stable and your image may look noisy.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

multiecho-0.30.tar.gz (12.3 kB view details)

Uploaded Source

Built Distribution

multiecho-0.30-py3-none-any.whl (9.1 kB view details)

Uploaded Python 3

File details

Details for the file multiecho-0.30.tar.gz.

File metadata

  • Download URL: multiecho-0.30.tar.gz
  • Upload date:
  • Size: 12.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.8

File hashes

Hashes for multiecho-0.30.tar.gz
Algorithm Hash digest
SHA256 9156923b4c5967606ac8fcaa33e4f4b6bf003cd8bd2c89aba58a1d5069a9aa7e
MD5 9750afdcbcc5bc79586060cf917379d7
BLAKE2b-256 5f069082dff109b8529b726a357e6d60825890d84d4b150480dd9f02219a91b4

See more details on using hashes here.

File details

Details for the file multiecho-0.30-py3-none-any.whl.

File metadata

  • Download URL: multiecho-0.30-py3-none-any.whl
  • Upload date:
  • Size: 9.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.8

File hashes

Hashes for multiecho-0.30-py3-none-any.whl
Algorithm Hash digest
SHA256 fd751e331206b5ac9f520f1e6efd5a01c282d12f0feed10f04bede5473eef288
MD5 2d91663ac8f489de41c1be9a75dd6574
BLAKE2b-256 74d03805af67b4883ba0d51924ef311f1737151b499e03aaab1616ead9e062f4

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page