tedana.utils.make_adaptive_mask

make_adaptive_mask(data, mask, threshold=1, methods=['dropout'])[source]

Make map of data specifying longest echo a voxel can be sampled with.

Parameters:

  • data ((S x E x T) array_like) – Multi-echo data array, where S is samples, E is echos, and T is time.

  • mask (str or img_like) – Binary mask for voxels to consider in TE Dependent ANAlysis. This must be provided, as the mask is used to identify exemplar voxels. Without a mask limiting the voxels to consider, the adaptive mask will generally select voxels outside the brain as exemplars.

  • threshold (int, optional) – Minimum echo count to retain in the mask. Default is 1, which is equivalent to not thresholding.

  • methods (list, optional) – List of methods to use for adaptive mask generation. Default is [“dropout”]. Valid methods are “decay”, “dropout”, and “none”.

Returns:

  • mask ((S,) numpy.ndarray) – Boolean array of voxels that have sufficient signal in at least threshold echos.

  • adaptive_mask ((S,) numpy.ndarray) – Valued array indicating the number of echos with sufficient signal in a given voxel.

Notes

The adaptive mask can flag “bad” echoes via two methods: dropout and decay. Either or both methods are applied to the mean magnitude across time for each voxel and echo.

Dropout

Remove voxels with relatively low mean magnitudes from the mask.

This method uses distributions of values across the mask. Therefore, it is sensitive to the quality of the mask. A bad mask may result in a bad adaptive mask.

This method is implemented as follows:

  1. Calculate the 33rd percentile of values in the first echo, based on voxel-wise mean over time.

  2. Identify the voxel where the first echo’s mean value is equal to the 33rd percentile. Basically, this identifies “exemplar” voxel reflecting the 33rd percentile.

    • The 33rd percentile is arbitrary.

    • If more than one voxel has a value exactly equal to the 33rd percentile, keep all of them.

  3. For the exemplar voxel from the first echo, calculate 1/3 of the mean value for each echo.

    • This is the threshold for “good” data.

    • The 1/3 value is arbitrary.

    • If there was more than one exemplar voxel, retain the the highest value for each echo.

  4. For each voxel, identify the last echo with a mean value greater than the corresponding echo’s threshold.

    • Preceding echoes (including ones with mean values less than the threshold) are considered “good” data. That means, if echoes 1-3 in a voxel are [good, good, bad] the adaptive mask will assign a 2, and if they are [good, bad, good], the adaptive mask will assign a 3.

Decay

Determine the echo at which the signal stops decreasing for each voxel. If a voxel’s signal stops decreasing as echo time increases, then we can infer that the voxel has either fully dephased (i.e., “bottomed out”) or been contaminated by noise. This essentially identifies the last echo with “good” data. For a scan that collects many echoes for T2* estimation or has a relatively short echo spacing, it is possible that a later echo will have a higher value, but the overall trend still shows a decay. This method should not be used in those situations.

The element-wise minimum value between any selected methods is used to construct the adaptive mask.