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.math_img

nilearn.image.math_img(formula, copy_header_from=None, **imgs)[source]

Interpret a numpy based string formula using niimg in named parameters.

Added in version 0.2.3.

Parameters:
formulastr

The mathematical formula to apply to image internal data. It can use numpy imported as ‘np’.

copy_header_fromstr, default=None

Takes the variable name of one of the images in the formula. The header of this image will be copied to the result of the formula. Note that the result image and the image to copy the header from, should have the same number of dimensions. If None, the default Nifti1Header is used.

Added in version 0.10.4.

imgsimages (Nifti1Image or file names)

Keyword arguments corresponding to the variables in the formula as Nifti images. All input images should have the same geometry (shape, affine).

Returns:
Nifti1Image

Result of the formula as a Nifti image. Note that the dimension of the result image can be smaller than the input image. The affine is the same as the input image.

See also

nilearn.image.mean_img

To simply compute the mean of multiple images

Notes

This function is the Python equivalent of ImCal in SPM or fslmaths in FSL.

Examples

Let’s load an image using nilearn datasets module:

>>> from nilearn import datasets
>>> anatomical_image = datasets.load_mni152_template()

Now we can use any numpy function on this image:

>>> from nilearn.image import math_img
>>> log_img = math_img("np.log(img)", img=anatomical_image)

We can also apply mathematical operations on several images:

>>> result_img = math_img("img1 + img2",
...                       img1=anatomical_image, img2=log_img)

The result image will have the same shape and affine as the input images; but might have different header information, specifically the TR value, see #2645.

Added in version 0.10.4.

We can also copy the header from one of the input images using copy_header_from:

>>> result_img_with_header = math_img("img1 + img2",
...                                   img1=anatomical_image, img2=log_img,
...                                   copy_header_from="img1")

Examples using nilearn.image.math_img

Second-level fMRI model: one sample test

Second-level fMRI model: one sample test

Example of generic design in second-level models

Example of generic design in second-level models

Negating an image with math_img

Negating an image with math_img

Comparing the means of 2 images

Comparing the means of 2 images

Copying headers from input images with math_img

Copying headers from input images with math_img

NeuroVault meta-analysis of stop-go paradigm studies

NeuroVault meta-analysis of stop-go paradigm studies