nilearn · man-shu · Jun 4, 2024 · Apr 24, 2024 · Apr 24, 2024 · Apr 24, 2024
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -72,7 +72,6 @@ repos:
                 | examples/01_plotting/plot_surface_projection_strategies.py
                 | examples/04_glm_first_level/plot_localizer_surface_analysis.py
                 | examples/07_advanced/plot_surface_bids_analysis.py
-                | nilearn/_utils/helpers.py
                 | nilearn/plotting/html_surface.py
                 | nilearn/plotting/js_plotting_utils.py
                 | nilearn/plotting/surf_plotting.py

diff --git a/doc/changes/latest.rst b/doc/changes/latest.rst
@@ -32,3 +32,5 @@ Changes
 - :bdg-dark:`Code` Throw error in :func:`nilearn.glm.first_level.first_level_from_bids` if unknown ``kwargs`` are passed (:gh:`4414` by `Michelle Wang`_).
 
 - :bdg-primary:`Doc` Refactor design matrix and contrast formula for the two-sample T-test example in :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_two_sample_test.py` (:gh:`4407` by `Yichun Huang`_).
+
+- :bdg-success:`API` Allow users to control copying header to the output in :func:`nilearn.image` functions and add future warning to copy headers by default in release 0.13.0 onwards (:gh:`4397` by `Himanshu Aggarwal`_).
diff --git a/doc/visual_testing/reporter_visual_inspection_suite.py b/doc/visual_testing/reporter_visual_inspection_suite.py
@@ -197,7 +197,7 @@ def report_flm_fiac():
     data = datasets.func.fetch_fiac_first_level()
     fmri_img = [data["func1"], data["func2"]]
 
-    mean_img_ = mean_img(fmri_img[0])
+    mean_img_ = mean_img(fmri_img[0], copy_header=True)
 
     design_files = [data["design_matrix1"], data["design_matrix2"]]
     design_matrices = [pd.DataFrame(np.load(df)["X"]) for df in design_files]
@@ -249,6 +249,7 @@ def report_slm_oasis():
         datasets.fetch_icbm152_brain_gm_mask(),
         oasis_dataset.gray_matter_maps[0],
         interpolation="nearest",
+        copy_header=True,
     )
 
     design_matrix = _make_design_matrix_slm_oasis(oasis_dataset, n_subjects)

diff --git a/examples/00_tutorials/plot_decoding_tutorial.py b/examples/00_tutorials/plot_decoding_tutorial.py
@@ -52,7 +52,7 @@
 from nilearn import plotting
 from nilearn.image import mean_img
 
-plotting.view_img(mean_img(fmri_filename), threshold=None)
+plotting.view_img(mean_img(fmri_filename, copy_header=True), threshold=None)
 
 # %%
 # Feature extraction: from :term:`fMRI` volumes to a data matrix

diff --git a/examples/00_tutorials/plot_single_subject_single_run.py b/examples/00_tutorials/plot_single_subject_single_run.py
@@ -64,7 +64,7 @@
 from nilearn.image import concat_imgs, mean_img
 
 fmri_img = concat_imgs(subject_data.func)
-mean_img = mean_img(fmri_img)
+mean_img = mean_img(fmri_img, copy_header=True)
 
 # %%
 # Specifying the experimental paradigm

diff --git a/examples/01_plotting/plot_demo_more_plotting.py b/examples/01_plotting/plot_demo_more_plotting.py
@@ -276,7 +276,7 @@
 
 # Compute voxel-wise mean functional image across time dimension. Now we have
 # functional image in 3D assigned in mean_haxby_img
-mean_haxby_img = image.mean_img(haxby_func_filename)
+mean_haxby_img = image.mean_img(haxby_func_filename, copy_header=True)
 
 # %%
 # Showing how to use `add_edges`

diff --git a/examples/01_plotting/plot_demo_plotting.py b/examples/01_plotting/plot_demo_plotting.py
@@ -114,7 +114,7 @@
 
 # Compute the voxel_wise mean of functional images across time.
 # Basically reducing the functional image from 4D to 3D
-mean_haxby_img = image.mean_img(haxby_func_filename)
+mean_haxby_img = image.mean_img(haxby_func_filename, copy_header=True)
 
 # Visualizing mean image (3D)
 plotting.plot_epi(mean_haxby_img, title="plot_epi")

diff --git a/examples/01_plotting/plot_haxby_masks.py b/examples/01_plotting/plot_haxby_masks.py
@@ -25,7 +25,7 @@
 from nilearn import image
 
 func_filename = haxby_dataset.func[0]
-mean_img = image.mean_img(func_filename)
+mean_img = image.mean_img(func_filename, copy_header=True)
 
 z_slice = -14
 

diff --git a/examples/01_plotting/plot_visualization.py b/examples/01_plotting/plot_visualization.py
@@ -28,7 +28,7 @@
 
 # Compute the mean EPI: we do the mean along the axis 3, which is time
 func_filename = haxby_dataset.func[0]
-mean_haxby = mean_img(func_filename)
+mean_haxby = mean_img(func_filename, copy_header=True)
 
 from nilearn.plotting import plot_epi, show
 

diff --git a/examples/02_decoding/plot_haxby_different_estimators.py b/examples/02_decoding/plot_haxby_different_estimators.py
@@ -186,7 +186,7 @@
 # Use the average :term:`EPI` as a background
 from nilearn.image import mean_img
 
-mean_epi_img = mean_img(func_filename)
+mean_epi_img = mean_img(func_filename, copy_header=True)
 
 for classifier_name in sorted(classifiers):
     coef_img = classifiers_data[classifier_name]["map"]

diff --git a/examples/02_decoding/plot_haxby_frem.py b/examples/02_decoding/plot_haxby_frem.py
@@ -49,7 +49,7 @@
 # Compute the mean EPI to be used for the background of the plotting
 from nilearn.image import mean_img
 
-background_img = mean_img(func_filenames)
+background_img = mean_img(func_filenames, copy_header=True)
 
 # %%
 # Fit FREM

diff --git a/examples/02_decoding/plot_haxby_glm_decoding.py b/examples/02_decoding/plot_haxby_glm_decoding.py
@@ -123,7 +123,7 @@
 from nilearn.image import mean_img
 from nilearn.reporting import make_glm_report
 
-mean_img_ = mean_img(func_filename)
+mean_img_ = mean_img(func_filename, copy_header=True)
 report = make_glm_report(
     glm,
     contrasts=conditions,

diff --git a/examples/02_decoding/plot_haxby_searchlight.py b/examples/02_decoding/plot_haxby_searchlight.py
@@ -118,7 +118,7 @@
 # Use the :term:`fMRI` mean image as a surrogate of anatomical data
 from nilearn import image
 
-mean_fmri = image.mean_img(fmri_img)
+mean_fmri = image.mean_img(fmri_img, copy_header=True)
 
 from nilearn.plotting import plot_img, plot_stat_map, show
 

diff --git a/examples/02_decoding/plot_miyawaki_encoding.py b/examples/02_decoding/plot_miyawaki_encoding.py
@@ -162,7 +162,7 @@
 score_map_img = masker.inverse_transform(cut_score)
 
 thresholded_score_map_img = threshold_img(
-    score_map_img, threshold=1e-6, copy=False
+    score_map_img, threshold=1e-6, copy=False, copy_header=True
 )
 
 

diff --git a/examples/03_connectivity/plot_data_driven_parcellations.py b/examples/03_connectivity/plot_data_driven_parcellations.py
@@ -132,7 +132,7 @@
 
 # Compute mean over time on the functional image to use the mean
 # image for compressed representation comparisons
-mean_func_img = mean_img(dataset.func[0])
+mean_func_img = mean_img(dataset.func[0], copy_header=True)
 
 # Compute common vmin and vmax
 vmin = np.min(get_data(mean_func_img))

diff --git a/examples/04_glm_first_level/plot_first_level_details.py b/examples/04_glm_first_level/plot_first_level_details.py
@@ -560,7 +560,7 @@ def plot_contrast(first_level_model):
 from nilearn.image import resample_to_img
 
 resampled_icbm_mask = resample_to_img(
-    icbm_mask, data_mask, interpolation="nearest"
+    icbm_mask, data_mask, interpolation="nearest", copy_header=True
 )
 
 # %%

diff --git a/examples/04_glm_first_level/plot_predictions_residuals.py b/examples/04_glm_first_level/plot_predictions_residuals.py
@@ -26,7 +26,7 @@
 fmri_img = image.concat_imgs(subject_data.func)
 
 # Make an average
-mean_img = image.mean_img(fmri_img)
+mean_img = image.mean_img(fmri_img, copy_header=True)
 mask = masking.compute_epi_mask(mean_img)
 
 # Clean and smooth data

diff --git a/examples/04_glm_first_level/plot_spm_multimodal_faces.py b/examples/04_glm_first_level/plot_spm_multimodal_faces.py
@@ -55,11 +55,11 @@
     ]
 affine, shape = fmri_img[0].affine, fmri_img[0].shape
 print("Resampling the second image (this takes time)...")
-fmri_img[1] = resample_img(fmri_img[1], affine, shape[:3])
+fmri_img[1] = resample_img(fmri_img[1], affine, shape[:3], copy_header=True)
 
 # %%
 # Let's create mean image for display purposes.
-mean_image = mean_img(fmri_img)
+mean_image = mean_img(fmri_img, copy_header=True)
 
 # %%
 # Make the design matrices.

diff --git a/examples/04_glm_first_level/plot_two_runs_model.py b/examples/04_glm_first_level/plot_two_runs_model.py
@@ -45,7 +45,7 @@
 # Create a mean image for plotting purpose.
 from nilearn.image import mean_img
 
-mean_img_ = mean_img(fmri_imgs[0])
+mean_img_ = mean_img(fmri_imgs[0], copy_header=True)
 
 # %%
 # The design matrices were pre-computed,

diff --git a/examples/05_glm_second_level/plot_oasis.py b/examples/05_glm_second_level/plot_oasis.py
@@ -74,6 +74,7 @@
     gm_mask,
     gray_matter_map_filenames[0],
     interpolation="nearest",
+    copy_header=True,
 )
 
 # %%

diff --git a/examples/05_glm_second_level/plot_thresholding.py b/examples/05_glm_second_level/plot_thresholding.py
@@ -59,6 +59,7 @@
     threshold=3.29,
     cluster_threshold=10,
     two_sided=True,
+    copy_header=True,
 )
 
 # %%

diff --git a/examples/06_manipulating_images/plot_affine_transformation.py b/examples/06_manipulating_images/plot_affine_transformation.py
@@ -98,21 +98,26 @@
 from nilearn.image import resample_img
 
 img_in_mm_space = resample_img(
-    img, target_affine=np.eye(4), target_shape=(512, 512, 1)
+    img, target_affine=np.eye(4), target_shape=(512, 512, 1), copy_header=True
 )
 
 target_affine_3x3 = np.eye(3) * 2
 target_affine_4x4 = np.eye(4) * 2
 target_affine_4x4[3, 3] = 1.0
-img_3d_affine = resample_img(img, target_affine=target_affine_3x3)
-img_4d_affine = resample_img(img, target_affine=target_affine_4x4)
+img_3d_affine = resample_img(
+    img, target_affine=target_affine_3x3, copy_header=True
+)
+img_4d_affine = resample_img(
+    img, target_affine=target_affine_4x4, copy_header=True
+)
 target_affine_mm_space_offset_changed = np.eye(4)
 target_affine_mm_space_offset_changed[:3, 3] = img_3d_affine.affine[:3, 3]
 
 img_3d_affine_in_mm_space = resample_img(
     img_3d_affine,
     target_affine=target_affine_mm_space_offset_changed,
     target_shape=(np.array(img_3d_affine.shape) * 2).astype(int),
+    copy_header=True,
 )
 
 img_4d_affine_in_mm_space = resample_img(

diff --git a/examples/06_manipulating_images/plot_extract_rois_statistical_maps.py b/examples/06_manipulating_images/plot_extract_rois_statistical_maps.py
@@ -30,13 +30,15 @@
 # Two types of strategies can be used from this threshold function
 # Type 1: strategy used will be based on scoreatpercentile
 threshold_percentile_img = threshold_img(
-    tmap_filename, threshold="97%", copy=False
+    tmap_filename, threshold="97%", copy=False, copy_header=True
 )
 
 
 # Type 2: threshold strategy used will be based on image intensity
 # Here, threshold value should be within the limits i.e. less than max value.
-threshold_value_img = threshold_img(tmap_filename, threshold=3.0, copy=False)
+threshold_value_img = threshold_img(
+    tmap_filename, threshold=3.0, copy=False, copy_header=True
+)
 
 # %%
 # Visualization

diff --git a/examples/06_manipulating_images/plot_mask_computation.py b/examples/06_manipulating_images/plot_mask_computation.py
@@ -42,7 +42,7 @@
 )
 
 miyawaki_filename = miyawaki_dataset.func[0]
-miyawaki_mean_img = image.mean_img(miyawaki_filename)
+miyawaki_mean_img = image.mean_img(miyawaki_filename, copy_header=True)
 plot_epi(miyawaki_mean_img, title="Mean EPI image")
 # %%
 # A NiftiMasker with the default strategy
@@ -77,7 +77,7 @@
 epi_img = index_img(epi_filename, slice(0, 100))
 
 # To display the background
-mean_img = image.mean_img(epi_img)
+mean_img = image.mean_img(epi_img, copy_header=True)
 plot_epi(mean_img, title="Mean EPI image")
 
 # %%

diff --git a/examples/06_manipulating_images/plot_nifti_simple.py b/examples/06_manipulating_images/plot_nifti_simple.py
@@ -43,7 +43,7 @@
 from nilearn.plotting import plot_roi
 
 # calculate mean image for the background
-mean_func_img = mean_img(func_filename)
+mean_func_img = mean_img(func_filename, copy_header=True)
 
 plot_roi(mask_img, mean_func_img, display_mode="y", cut_coords=4, title="Mask")
 
@@ -80,7 +80,7 @@
 from nilearn.plotting import plot_stat_map, show
 
 # calculate mean image for the background
-mean_func_img = mean_img(func_filename)
+mean_func_img = mean_img(func_filename, copy_header=True)
 
 plot_stat_map(
     index_img(components, 0),

diff --git a/examples/06_manipulating_images/plot_resample_to_template.py b/examples/06_manipulating_images/plot_resample_to_template.py
@@ -24,7 +24,7 @@
 # to the :term:`MNI` template image.
 from nilearn.image import resample_to_img
 
-resampled_stat_img = resample_to_img(stat_img, template)
+resampled_stat_img = resample_to_img(stat_img, template, copy_header=True)
 
 # %%
 # Let's check the shape and affine have been correctly updated.

diff --git a/examples/06_manipulating_images/plot_roi_extraction.py b/examples/06_manipulating_images/plot_roi_extraction.py
@@ -109,7 +109,7 @@
 
 # First, compute the voxel-wise mean of smooth EPI image
 # (first argument) using image processing module `image`
-mean_img = image.mean_img(fmri_img)
+mean_img = image.mean_img(fmri_img, copy_header=True)
 # Second, we visualize the mean image with coordinates positioned manually
 plot_epi(mean_img, title="Smoothed mean EPI", cut_coords=cut_coords)
 

diff --git a/examples/06_manipulating_images/plot_smooth_mean_image.py b/examples/06_manipulating_images/plot_smooth_mean_image.py
@@ -24,7 +24,7 @@
 first_epi_file = data.func[0]
 
 # First compute the mean image, from the 4D series of image
-mean_func = image.mean_img(first_epi_file)
+mean_func = image.mean_img(first_epi_file, copy_header=True)
 
 # %%
 # Then we smooth, with a varying amount of smoothing, from none to 20mm

diff --git a/examples/07_advanced/plot_haxby_mass_univariate.py b/examples/07_advanced/plot_haxby_mass_univariate.py
@@ -139,7 +139,7 @@
 from nilearn.image import get_data
 
 # Use the fMRI mean image as a surrogate of anatomical data
-mean_fmri_img = image.mean_img(func_filename)
+mean_fmri_img = image.mean_img(func_filename, copy_header=True)
 
 threshold = -np.log10(0.1)  # 10% corrected
 

diff --git a/examples/07_advanced/plot_ica_resting_state.py b/examples/07_advanced/plot_ica_resting_state.py
@@ -78,7 +78,7 @@
 # Show some interesting components
 
 # Use the mean as a background
-mean_img = image.mean_img(func_filename)
+mean_img = image.mean_img(func_filename, copy_header=True)
 
 plot_stat_map(image.index_img(component_img, 0), mean_img)