doc: point to read_dipole

[sappelhoff]

This PR also comes with a question: Why do we support saving Dipoles in dip and bdip, but FixedDipoles in FIF? would it not be possible to support all formats for all objects?

https://mne.tools/stable/generated/mne.DipoleFixed.html#mne.DipoleFixed.save

https://mne.tools/stable/generated/mne.Dipole.html#mne.Dipole.save

[larsoner]

For formats we inherited those from Elekta/Neuromag/MEGIN. The .dip is meant for sequential dipole fits which vary in location and orientation for every time point (potentially). The DipoleFixed has at least a fixed position. See notes in https://mne.tools/1.8/generated/mne.DipoleFixed.html

[larsoner]

Committed that change and marking for merge-when-green, thanks @sappelhoff !

[sappelhoff]

For formats we inherited those from Elekta/Neuromag/MEGIN. The .dip is meant for sequential dipole fits which vary in location and orientation for every time point (potentially). The DipoleFixed has at least a fixed position.

Okay -- thanks for the pointer :)

I am still not very sure why (1) there are three formats, (2) what advantages they have over each other, (3) which non-mne softwares produce them, and (4) whether some dipoles (fixed, non-fixed) can only be saved in some but not other formats 🤔

For (4) I think you say that any dipole can be saved and loaded from any format (fif, dip, bdip)

for (3) I know have heard of "xfit", which seems to be Neuromag/Elekta/MEGIN proprietary software (?)

for (2) dip and bdip are the same except that one is binary and therefore saves disk space? ... but why is there also FIF then? -- this is related to (1)

[larsoner]

I am still not very sure why (1) there are three formats, (2) what advantages they have over each other, (3) which non-mne softwares produce them, and (4) whether some dipoles (fixed, non-fixed) can only be saved in some but not other formats 🤔

Maybe it's easier to think of in terms of the type of fit you do:

1. Non-fixed-position (sequential) dipole fits. These are Dipole and cannot be saved to FIF, only to dip/bdip.
2. Fixed-position dipole fits. These are DipoleFixed and can be saved to FIF, and are really a lot more like an Evoked instance than anything else. The amplitude and maybe ori vary as a function of time, but not the position. You could in principle maybe save these to dip/bdip but I'm not sure we support it (or want to).

I think Xfit (Neuromag dipole fitting software) can write both formats.

[drammock]

I am still not very sure why (1) there are three formats, (2) what advantages they have over each other, (3) which non-mne softwares produce them, and (4) whether some dipoles (fixed, non-fixed) can only be saved in some but not other formats

Sounds like we should add a Notes section with some version of what @larsoner just posted:

Maybe it's easier to think of in terms of the type of fit you do:

1. Non-fixed-position (sequential) dipole fits. These are Dipole and cannot be saved to FIF, only to dip/bdip.
2. Fixed-position dipole fits. These are DipoleFixed and can be saved to FIF, and are really a lot more like an Evoked instance than anything else. The amplitude and maybe ori vary as a function of time, but not the position. You could in principle maybe save these to dip/bdip but I'm not sure we support it (or want to).

I think Xfit (Neuromag dipole fitting software) can write both formats.

[sappelhoff]

Thanks Eric, and agreed Dan. I can look into this as part of my #13153 or in a separate PR.