👋 @man-shu Thanks for creating a PR!

Until this PR is ready for review, you can include the [WIP] tag in its title, or leave it as a github draft.

Please make sure it is compliant with our contributing guidelines. In particular, be sure it checks the boxes listed below.

• PR has an interpretable title.
• PR links to Github issue with mention Closes #XXXX (see our documentation on PR structure)
• Code is PEP8-compliant (see our documentation on coding style)
• Changelog or what's new entry in doc/changes/latest.rst (see our documentation on PR structure)

For new features:

• There is at least one unit test per new function / class (see our documentation on testing)
• The new feature is demoed in at least one relevant example.

For bug fixes:

• There is at least one test that would fail under the original bug conditions.

We will review it as quick as possible, feel free to ping us with questions if needed.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.94%. Comparing base (abb80ff) to head (cbba0af).
Report is 70 commits behind head on main.

@@            Coverage Diff             @@
##             main    #4392      +/-   ##
==========================================
+ Coverage   91.85%   91.94%   +0.08%     
==========================================
  Files         144      143       -1     
  Lines       16419    16639     +220     
  Branches     3434     3529      +95     
==========================================
+ Hits        15082    15299     +217     
+ Misses        792      769      -23     
- Partials      545      571      +26     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

The same MSDL dataset download fails during building the docs.

So maybe first merging #4390 would be better.

I'm still not 100% sure that this deserves a full example, but I find it quite pedagogical, so I'm +0 for this addition.

Yes, maybe it doesn't make much sense to have it for just one function.

But as explained in #4393, I identified the same issue in several others under the image module. So maybe a more general example would be worthwhile to have across all of them (once I have fixed them).

Can you propose an enhanced example ?

Yes, but I should fix #4393 first.

So, all the other nilearn.image functions with the same issue do not need further explanation (see #4397, they can now simply copy the header by default).

math_img remains the most peculiar, with several use cases where the default behavior could be confusing/problematic and could use this explanation. But I don't think I can change much in the current example.

We should decide on this at a forthcoming coredev meeting.