[MRG][ENH]: Add Ability to export STC files as GIFTI

doc/changes/devel.rst

@@ -41,6 +41,7 @@ Enhancements
 - Add ``method="polyphase"`` to :meth:`mne.io.Raw.resample` and related functions to allow resampling using :func:`scipy.signal.upfirdn` (:gh:`12268` by `Eric Larson`_)
 - The package build backend was switched from ``setuptools`` to ``hatchling``. This will only affect users who build and install MNE-Python from source. (:gh:`12269`, :gh:`12281` by `Richard Höchenberger`_)
 - :meth:`mne.Annotations.to_data_frame` can now output different formats for the ``onset`` column: seconds, milliseconds, datetime objects, and timedelta objects. (:gh:`12289` by `Daniel McCloy`_)
+- Add ``save_as_surface`` method to allow saving GIFTI files from STC SourceEstimates in :class:`~mne._BaseSurfaceSourceEstimate` (:gh:`12309` by `Peter Molfese`_)
 
 Bugs
 ~~~~

mne/source_estimate.py

@@ -1583,6 +1583,98 @@ def in_label(self, label):
             subject=self.subject,
         )
         return label_stc
+
+    def save_as_surface(self, fname, src, scale=1, scale_rr=1e3):
+        """Save a surface source estimate (stc) as a GIFTI file.
+
+        Parameters
+        ----------
+        fname : path-like
+            filename basename to save files as
+            Will write anatomical gifti plus time series gifti for both lh/rh
+            ex: 
+                "basename" --> "basename.lh.gii" and "basename.lh.time.gii"
+                           --> "basename.rh.gii" and "basename.rh.time.gii"
+        src : source solution (surface) object
+            the source space of the forward solution
+        scale : int
+            scale of functional values
+        scale_rr : float
+            Value to scale source solution
+
+        Notes
+        ----------
+        Creates gifti files for source solution and time courses of STC
+        .. versionadded:: 1.7
+        """
+        nib = _import_nibabel()
+        from .source_space import get_decimated_surfaces
+
+        ss = get_decimated_surfaces(src)
+        stc = self
+
+        # Create lists to put DataArrays into
+        lh = []
+        rh = []
+
+        # Coerce rr to be in mm (MNE uses meters)
+        ss[0]['rr'] *= scale_rr
+        ss[1]['rr'] *= scale_rr
+
+        lh.append(nib.gifti.gifti.GiftiDataArray(
+            data=ss[0]['rr'], 
+            intent='NIFTI_INTENT_POINTSET', 
+            datatype='NIFTI_TYPE_FLOAT32'))
+        rh.append(nib.gifti.gifti.GiftiDataArray(
+            data=ss[1]['rr'], 
+            intent='NIFTI_INTENT_POINTSET', 
+            datatype='NIFTI_TYPE_FLOAT32'))
+
+        # Make the topology DataArray
+        lh.append(nib.gifti.gifti.GiftiDataArray(
+            data=ss[0]['tris'], 
+            intent='NIFTI_INTENT_TRIANGLE', 
+            datatype='NIFTI_TYPE_INT32'))
+        rh.append(nib.gifti.gifti.GiftiDataArray(
+            data=ss[1]['tris'], 
+            intent='NIFTI_INTENT_TRIANGLE', 
+            datatype='NIFTI_TYPE_INT32'))
+
+        # Make the output GIFTI for anatomicals
+        topo_gi_lh = nib.gifti.gifti.GiftiImage(darrays=lh)
+        topo_gi_rh = nib.gifti.gifti.GiftiImage(darrays=rh)
+
+        #actually save the files
+        nib.save(topo_gi_lh, f"{fname}-lh.gii")
+        nib.save(topo_gi_rh, f"{fname}-rh.gii")
+
+        # Make the Time Series data arrays
+        lh_ts = []
+        rh_ts = []
+
+        for t in range(stc.shape[1]):
+            lh_ts.append(
+                nib.gifti.gifti.GiftiDataArray(
+                    data=stc.lh_data[:, t] * scale,
+                    intent='NIFTI_INTENT_POINTSET',
+                    datatype='NIFTI_TYPE_FLOAT32'
+                )
+            )
+
+            rh_ts.append(
+                nib.gifti.gifti.GiftiDataArray(
+                    data=stc.rh_data[:, t] * scale,
+                    intent='NIFTI_INTENT_POINTSET',
+                    datatype='NIFTI_TYPE_FLOAT32'
+                )
+            )
+
+        #save the time series
+        ts_gi_lh = nib.gifti.gifti.GiftiImage(darrays=lh_ts)
+        ts_gi_rh = nib.gifti.gifti.GiftiImage(darrays=rh_ts)
+        nib.save(ts_gi_lh, f"{fname}-lh.time.gii")
+        nib.save(ts_gi_rh, f"{fname}-rh.time.gii")
+
 
     def expand(self, vertices):
         """Expand SourceEstimate to include more vertices.

mne/tests/test_source_estimate.py

@@ -247,6 +247,34 @@ def test_volume_stc(tmp_path):
             assert_array_equal(stc.vertices[0], stc_new.vertices[0])
             assert_array_almost_equal(stc.data, stc_new.data)
 
+@testing.requires_testing_data
+def test_save_stc_as_gifti(tmp_path):
+    """Save the stc as a gifti file and export."""
+    nib = pytest.importorskip("nibabel")
+    surfpath_src = bem_path / "sample-oct-6-src.fif"
+    surfpath_stc = data_path / "MEG" / "sample" / "sample_audvis_trunc-meg"
+    src = read_source_spaces(surfpath_src) #need source space
+    stc = read_source_estimate(surfpath_stc) #need stc
+    assert isinstance(src, SourceSpaces)
+    assert isinstance(stc, SourceEstimate)
+
+    surf_fname = tmp_path / "stc_write"
+
+    stc.save_as_surface(surf_fname, src)
+
+    #did structural get written?
+    img_lh = nib.load(f'{surf_fname}-lh.gii')
+    img_rh = nib.load(f'{surf_fname}-rh.gii')
+    assert isinstance(img_lh, nib.gifti.gifti.GiftiImage)
+    assert isinstance(img_rh, nib.gifti.gifti.GiftiImage)
+
+    #did time series get written? 
+    img_timelh = nib.load(f'{surf_fname}-lh.time.gii')
+    img_timerh = nib.load(f'{surf_fname}-rh.time.gii')
+    assert isinstance(img_timelh, nib.gifti.gifti.GiftiImage)
+    assert isinstance(img_timerh, nib.gifti.gifti.GiftiImage)
+
+
 
 @testing.requires_testing_data
 def test_stc_as_volume():