Fix apply_function docstring for Epochs #13118

[Imama-Kainat]

The current documentation for apply_function in mne.Epochs is misleading, as it does not accurately describe the shape of the epochs data (3D arrays). This can cause confusion about how the function processes the data across different dimensions.

This PR updates the relevant docstrings in mne/utils/docs.py to clearly state how apply_function operates on the epochs data, ensuring users understand the function's behavior when applied to multi-dimensional data structures. The updated documentation improves clarity and consistency with other MNE functions.

[welcome]

Hello! 👋 Thanks for opening your first pull request here! ❤️ We will try to get back to you soon. 🚴

[Imama-Kainat]

I've made the necessary changes, built the documentation successfully, and verified that the updates are rendering correctly. I've now submitted the pull request for review. Let me know if any further modifications are needed. Thanks!

[scott-huberty]

This isn't quite right, because this change will be reflected in the documentation for raw.apply_function and evoked.apply_function, but we don't want it to, since those data will never be 3D!

e.g. see https://output.circle-artifacts.com/output/job/118b9184-1aa0-461c-a3a6-7f831deca1ee/artifacts/0/html/generated/mne.io.Raw.html#mne.io.Raw.apply_function

[scott-huberty]

Thanks @Imama-Kainat for brining this to attention!

Can you help me to better understand the issue, by providing a minimally working example (MWE) of a user-defined function that works with epochs.apply_function(channel_wise=True) but fails with epochs.apply_function(channel_wise=False)?

You can start with this:

import mne

sample_fpath = mne.datasets.sample.data_path()
fpath = sample_fpath / "MEG" / "sample" / "sample_audvis_raw.fif"
raw = mne.io.read_raw(sample_fpath, preload=True).pick("eeg")

epochs = mne.make_fixed_length_epochs(raw, duration=1, preload=True)

def my_fun(x):
    """My function that works with epoch.apply_function(channel_wise=True)"""
   return

If epoch.apply_function(channel_wise=False) requires the user to pass a 3D array, then I think we'll likely want to add another doc_dict entry like the one below, here

docdict["fun_applyfun_epochs"] = applyfun_fun_base.format(
    " if ``channel_wise=True`` and ``(n_epochs, n_channels, n_times)`` otherwise"
)

And then use %fun_applyfun_epochs here