mriqc.qc package — mriqc 0.8 documentation

# mriqc.qc package

## Module contents

This module contains the actual computation of IQMs included within MRIQC.

Note

Most of the IQMs in this module are adapted, derived or reproduced from the QAP project [QAP]. We particularly thank Steve Giavasis (@sgiavasis) and Krishna Somandepali for their original implementations of the code in this module that we took from the [QAP].

## Submodules

## mriqc.qc.anatomical module

Computation of the quality assessment measures on structural MRI

`mriqc.qc.anatomical.` `art_qi1`(airmask, artmask)

  Detect artifacts in the image using the method described in [Mortamet2009]. Caculates q1, as the proportion of voxels with intensity corrupted by artifacts normalized by the number of voxels in the background. Lower values are better.

  Parameters: | airmask (numpy.ndarray) – input air mask, without artifacts artmask (numpy.ndarray) – input artifacts mask

`mriqc.qc.anatomical.` `art_qi2`(img, airmask, ncoils=12, erodemask=True)

  Calculates qi2, the distance between the distribution of noise voxel (non-artifact background voxels) intensities, and a centered Chi distribution.

  Parameters: | img (numpy.ndarray) – input data airmask (numpy.ndarray) – input air mask without artifacts

`mriqc.qc.anatomical.` `cjv`(img, seg=None, wmmask=None, gmmask=None, wmlabel=u'wm', gmlabel=u'gm')

  Calculate the CJV, a measure related to SNR and CNR that is presented as a proxy for the INU artifact [Ganzetti2016]. Lower is better.

  \[\text{CJV} = \frac{\sigma_\text{WM} + \sigma_\text{GM}}{\mu_\text{WM} - \mu_\text{GM}}.\]

  Parameters: | img (numpy.ndarray) – the input data wmmask (numpy.ndarray) – the white matter mask gmmask (numpy.ndarray) – the gray matter mask
  Returns: | the computed CJV

`mriqc.qc.anatomical.` `cnr`(img, seg, lbl=None)

  Calculate the CNR [Magnota2006]. Higher values are better.

  \[\text{CNR} = \frac{|\mu_\text{GM} - \mu_\text{WM} |}{\sigma_B},\]

  where \(\sigma_B\) is the standard deviation of the noise distribution within the air (background) mask.

  Parameters: | img (numpy.ndarray) – input data seg (numpy.ndarray) – input segmentation
  Returns: | the computed CNR

`mriqc.qc.anatomical.` `efc`(img)

  Calculate the EFC [Atkinson1997]. Uses the Shannon entropy of voxel intensities as an indication of ghosting and blurring induced by head motion. Lower values are better.

  The original equation is normalized by the maximum entropy, so that the EFC can be compared across images with different dimensions.

  Parameters: | img (numpy.ndarray) – input data

`mriqc.qc.anatomical.` `fber`(img, seg, air=None)

  Calculate the FBER, defined as the mean energy of image values within the head relative to outside the head. Higher values are better.

  \[\text{FBER} = \frac{E[|F|^2]}{E[|B|^2]}\]

  Parameters: | img (numpy.ndarray) – input data seg (numpy.ndarray) – input segmentation

`mriqc.qc.anatomical.` `rpve`(pvms, seg)

  Computes the rPVe of each tissue class.

`mriqc.qc.anatomical.` `snr`(img, smask, nmask=None, erode=True, fglabel=1)

  Calculate the SNR. The estimation may be provided with only one foreground region in which the noise is computed as follows:

  \[\text{SNR} = \frac{\mu_F}{\sigma_F},\]

  where \(\mu_F\) is the mean intensity of the foreground and \(\sigma_F\) is the standard deviation of the same region. Alternatively, a background mask containing only noise can be provided. This must be an air mask around the head, and it should not contain artifacts. The computation is done following the eq. A.12 of [Dietrich2007], which includes a correction factor in the estimation of the standard deviation of air and its Rayleigh distribution:

  \[\text{SNR} = \frac{\mu_F}{\sqrt{\frac{2}{4-\pi}}\,\sigma_\text{air}}.\]

  Parameters: | img (numpy.ndarray) – input data fgmask (numpy.ndarray) – input foreground mask or segmentation bgmask (numpy.ndarray) – input background mask or segmentation erode (bool) – erode masks before computations. fglabel (str) – foreground label in the segmentation data. bglabel (str) – background label in the segmentation data.
  Returns: | the computed SNR for the foreground segmentation

`mriqc.qc.anatomical.` `summary_stats`(img, pvms)

  Estimates the mean, the standard deviation, the 95% and the 5% percentiles of each tissue distribution.

`mriqc.qc.anatomical.` `volume_fraction`(pvms)

  Computes the ICV fractions corresponding to the (partial volume maps).

  Parameters: | pvms (list) – list of `numpy.ndarray` of partial volume maps.

`mriqc.qc.anatomical.` `wm2max`(img, seg)

  Calculate the WM2MAX, defined as the maximum intensity found in the volume w.r.t. the mean value of the white matter tissue. Values close to 1.0 are better.

## mriqc.qc.functional module

Computation of the quality assessment measures on functional MRI

`mriqc.qc.functional.` `compute_dvars`(in_file, in_mask, output_all=False, out_file=None)

  Compute the mean DVARS [Power2012].

  Particularly, the standardized DVARS [Nichols2013] are computed.

  Note

  Implementation details

  Uses the implementation of the Yule-Walker equations from nitime for the AR filtering of the fMRI signal.

  Parameters: | func (numpy.ndarray) – functional data, after head-motion-correction. mask (numpy.ndarray) – a 3D mask of the brain output_all (bool) – write out all dvars out_file (str) – a path to which the standardized dvars should be saved.
  Returns: | the standardized DVARS

`mriqc.qc.functional.` `gcor`(func, mask)

  Compute the GCOR.

  Parameters: | func (numpy.ndarray) – input fMRI dataset, after motion correction mask (numpy.ndarray) – 3D brain mask
  Returns: | the computed GCOR value

`mriqc.qc.functional.` `gsr`(epi_data, mask, direction='y', ref_file=None, out_file=None)

  Computes the GSR [Giannelli2010]. The procedure is as follows:

  > 1. Create a Nyquist ghost mask by circle-shifting the original mask by \(N/2\).
  > 2. Rotate by \(N/2\)
  > 3. Remove the intersection with the original mask
  > 4. Generate a non-ghost background
  > 5. Calculate the GSR

  Warning

  This should be used with EPI images for which the phase encoding direction is known.

  Parameters: | epi_file (str) – path to epi file mask_file (str) – path to brain mask direction (str) – the direction of phase encoding (x, y, all)
  Returns: | the computed gsr

`mriqc.qc.functional.` `summary_fd`(fd_movpar, fd_thres=1.0)

  Generates a dictionary with the mean FD, the number of FD timepoints above fd_thres, and the percentage of FD timepoints above the fd_thres

`mriqc.qc.functional.` `zero_variance`(func, mask)

  Mask out voxels with zero variance across t-axis

  Parameters: | func (numpy.ndarray) – input fMRI dataset, after motion correction mask (numpy.ndarray) – 3D brain mask
  Returns: | the 3D mask of voxels with nonzero variance across \(t\).
  Return type: | numpy.ndarray