Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.image.threshold_img¶

nilearn.image.threshold_img(img, threshold, cluster_threshold=0, two_sided=True, mask_img=None, copy=True, copy_header=False)[source]¶

Threshold the given input image, mostly statistical or atlas images.

Thresholding can be done based on direct image intensities or selection threshold with given percentile.

If threshold is a float:

we threshold the image based on image intensities.
- When two_sided is True:
  
  The given value should be within the range of minimum and maximum intensity of the input image. All instensities in the interval [-threshold, threshold] will be set to zero.
- When two_sided is False:
  - If the threshold is negative:
    
    It should be greater than the minimum intensity of the input data. All intensities greater than or equal to the specified threshold will be set to zero. All other instensities keep their original values.
  - If the threshold is positive:
    
    then it should be less than the maximum intensity of the input data. All intensities less than or equal to the specified threshold will be set to zero. All other instensities keep their original values.
If threshold is str:

The number part should be in interval [0, 100]. We threshold the image based on the score obtained using this percentile on the image data. The percentile rank is computed using scipy.stats.scoreatpercentile.
- When two_sided is True:
  
  The score is calculated on the absolute values of data.
- When two_sided is False:
  
  The score is calculated only on the non-negative values of data.

Changed in version 0.9.0: New cluster_threshold and two_sided parameters added.

Added in version 0.2.

Parameters:

imga 3D/4D Niimg-like object

Image containing statistical or atlas maps which should be thresholded.

thresholdfloat or str

Threshold that is used to set certain voxel intensities to zero. If threshold is float, it should be within the range of minimum and the maximum intensity of the data. If two_sided is True, threshold cannot be negative. If threshold is str, the given string should be within the range of “0%” to “100%”.

cluster_thresholdfloat, default=0

Cluster size threshold, in voxels. In the returned thresholded map, sets of connected voxels (clusters) with size smaller than this number will be removed.

Added in version 0.9.0.

two_sidedbool, default=True

Whether the thresholding should yield both positive and negative part of the maps.

Added in version 0.9.0.

mask_imgNiimg-like object, default=None

Mask image applied to mask the input data. If None, no masking will be applied.

copybool, default=True

If True, input array is not modified. True by default: the filtering is not performed in-place.

copy_headerbool, default=False

Whether to copy the header of the input image to the output.

Added in version 0.11.0.

This parameter will be set to True by default in 0.13.0.

Returns:

Nifti1Image: Thresholded image of the given input image.

Raises:

ValueError: If threshold is of type str but is not a non-negative number followed by the percent sign. If threshold is a negative float and two_sided is True.
TypeError: If threshold is neither float nor a string in correct percentile format.

Examples using `nilearn.image.threshold_img`¶

Encoding models for visual stimuli from Miyawaki et al. 2008

Statistical testing of a second-level analysis

Region Extraction using a t-statistical map (3D)

nilearn.image.threshold_img¶

Examples using nilearn.image.threshold_img¶

Examples using `nilearn.image.threshold_img`¶