Digitization progress

This issue is to keep track of the remaining Digitization PRs. It reflects a conversation with @larsoner.

TODO (each item will be a separate PR):

• Add move all montage use to Raw and Epochs readers that have montage argument to call only the following at the end of their __init__, not used anywhere else (#6462):

  if montage is not None:
      self.set_montage(montage)
  

• Deprecate montage argument in all readers that support montage arguments (#6534)

  • Make we have a test like sure https://github.com/mne-tools/mne-python/issues/6461#issuecomment-503584614

    def test_montage():
    	raw_montage = read_raw_*(fname, montage=my_montage)
        raw_none = read_raw_*(fname, montage=None)
        raw_none.set_montage(montage)
        assert object_diff(raw_none.info['chs'], raw_montage.info['chs'])
    	assert object_diff(raw_none.info['dig'], raw_montage.info['dig'])
    

• ~Replicate montage and digmontage usecases with Digitization~ This no longer applies. We kept DigMontage, remove Montage and make digitization private.

  • Refactor DigMontage to use Digitization + ch_names as representation (+ deprecate things that we no longer want to support) (#6639)
  • Make digitization module private _digitization (#6700)
  • Fix DigMontage.save (saves dig but not ch_names)
  • Fix DigMontage() without parmeters.
  • Refactor DigMontage tests. All that we did not change in #6639 because we only wanted to touch code logic not test logic.
  • set_montage takes only DigMontage not Montage
  • Some refactor of mne/_digitization. We have all _make_dig_{kit, artemist, bti} that overlap with DigMontage.
  • deprecate read_dig_montage in favor of read_dig_montage_FOO or make_dig_montage(np.arrays..). No transforms allowed.
  • deprecate DigMontage.dev_head_t in favor of:
    • Storing the 2 versionsof the HPI points in the DigMontage.dig: one in FIFFV_COORD_HEAD and the other in FIFFV_COORD_MEG. When you want dev_head_t, call DigMontage.get_dev_head_t() and it will compute it from these directly.
    • a free function returning a proper transformation: def compute_dev_head_t(dig: Digitization) -> Transform:
  • rename elp, hpi in favor of the new names (hpi, hpi_dev) in the internal calls. (I’m not sure this will be needed. We’ll see)
  • DigMontage.transform_to_head() (not fully clear but it will get more clear when addressing the others). Things that could require:
    • a free function like: def get_fiducials(dig: Digitization) -> Fiducials: (Fiducials is a Bunch with nasion, lpa, rpa or similar, named tuple whatever.)
    • do all points need to be in ‘head’ or only some of them?
    • does it need to be a method? (probably yes)

• remove fit_match_points outside of coreg.

• move read_dig_XXXX to mne/io/

• ~Add plot() to Digitization class #6412. 3D plot with each dig point, maybe symbol based on coordinate frame (sphere=head, cube=meg, … ?) and color based on type (eeg, extra, hpi, we have colors for these in defaults.py or plot_alignment somewhere)~ Fix the DigMontage-Montage mess we had in the existing plot with point_names and custom transforms. (#6649, maybe different PR)

• Make a none smoke test for applied transforms https://github.com/massich/mne-python/pull/31 (I’ve close it by error, it still applies)

---

Log of past PRs:

• Add example showing all the eeg helmets (#6158)
• MRG: Prepare BTI to refactor for Digitization (#6228)
• MAINT: Refactor digitation for KIT, artemis123, bti (#6368)
• ENH: Add digitization class (#6369)
• MNT: Change DigMontage representation to use Digitization (#6639)
• Make mne/digitization private mne/_digitization (#6700)

Cross-reference issues:

• https://github.com/mne-tools/mne-python/issues/3893#issuecomment-271925975
• #6698

---

Here is a summary of the readers with respect to how they are tested. Main focus: does the reader go through _test_raw_reader? has the reader been tested with digitization or None? Does the reader have digitization or a montage?

                       | _test_raw_reader | None | Digitization | other   |
-----------------------+------------------+------+--------------+---------+
RawArray               |     x            |  x   |              |         |
read_raw_artemis123    |     x            |      |     x        |         |   
read_raw_bdf           |                  |      |              | montage |
read_raw_brainvision   |     x            |  x   |     x        |         |    
read_raw_bti           |     x            |  x   |     x        |         |
read_raw_cnt           |     x            |  x   |              | montage |
read_raw_ctf           |     x            |      |     x        |         |
read_raw_edf           |     x            |  x   |     x        |         |
read_raw_eeglab        |     x            |      |     x        |         |
read_raw_egi           |     x            |  x   |              | montage |
read_raw_eximia        |     x            |  x   |              | ------- |
read_raw_fieldtrip     |                  |      |              | ------- |
read_raw_fif           |     x            |      |     x        |         |
read_raw_gdf           |     x            |  x   |              | montage |
read_raw_kit           |     x            |  x   |     x        |         |
read_raw_nicolet       |     x            |  x   |              | montage |

---

other notes:

1. duplicated montages

import os.path as op
import mne
fname = op.join(op.dirname(mne.io.edf.__file__), 'tests', 'data', 'biosemi.hpts')

default_biosemi64 = mne.channels.read_montage('biosemi64')
edf_testing_biosemi64 = mne.channels.read_montage(fname)

[larsoner]

@massich updated top description with my suggested order / description based on extrapolating what I discussed with @agramfort

[agramfort]

yes then we need to change the read_dig_xxx so they don’t use unknown but the proper source of the data. We would need to add a constant for captrack though