[ENH, MRG] Clarify intracranial narrative for why individual coordina…

…tes are preferred (#975)

* clarify intracranial narrative for why individual coordinates are preferred

* [skip ci]

* update whatsnew

* fix sphinx ref

* alex changes

* fix bad overlooking data type mistake

doc/whats_new.rst

@@ -47,6 +47,8 @@ Enhancements
 
 - Add support for iEEG data in the coordinate frame ``Pixels``; although MNE-Python does not recognize this coordinate frame and so it will be set to ``unknown`` in the montage, MNE-Python can still be used to analyze this kind of data, by `Alex Rockhill`_ (:gh:`976`)
 
+- Add an explanation in :ref:`ieeg-example` of why it is better to have intracranial data in individual rather than template coordinates, by `Alex Rockhill`_ (:gh:`975`)
+
 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

examples/convert_ieeg_to_bids.py

@@ -1,4 +1,6 @@
 """
+.. _ieeg-example:
+
 .. currentmodule:: mne_bids
 
 ====================================
@@ -195,7 +197,7 @@
 #
 # `acpc_aligned=True` affirms that our MRI is aligned to ACPC
 # if this is not true, convert to `fsaverage` (see below)!
-write_raw_bids(raw, bids_path, anonymize=dict(daysback=30000),
+write_raw_bids(raw, bids_path, anonymize=dict(daysback=40000),
                montage=montage, acpc_aligned=True, overwrite=True)
 
 # check our output
@@ -270,8 +272,15 @@
 # Here we'll use the MNI Talairach transform to get to ``fsaverage`` space
 # from "mri" aka surface RAS space.
 # ``fsaverage`` is very useful for group analysis as shown in
-# `Working with SEEG
-# <https://mne.tools/stable/auto_tutorials/misc/plot_seeg.html>`_.
+# :ref:`tut-working-with-seeg`. Note, this is only a linear transform and so
+# one loses quite a bit of accuracy relative to the needs of intracranial
+# researchers so it is quite suboptimal. A better option is to use a
+# symmetric diffeomorphic transform to create a one-to-one mapping of brain
+# voxels from the individual's brain to the template as shown in
+# :ref:`tut-ieeg-localize`. Even so, it's better to provide the coordinates
+# in the individual's brain space, as was done above, so that the researcher
+# who uses the coordinates has the ability to tranform them to a template
+# of their choice.
 
 # ensure the output path doesn't contain any leftover files from previous
 # tests and example runs
@@ -293,7 +302,7 @@
 montage.apply_trans(mri_mni_t)
 
 # write to BIDS, this time with a template coordinate system
-write_raw_bids(raw, bids_path, anonymize=dict(daysback=30000),
+write_raw_bids(raw, bids_path, anonymize=dict(daysback=40000),
                montage=montage, overwrite=True)
 
 # read in the BIDS dataset