Merge pull request #52 from yhuang43/master

support gifti time-series

Author: jnolan14

surfa/__init__.py

@@ -23,6 +23,7 @@
 from .mesh import Mesh
 from .mesh import Overlay
 from .mesh import sphere
+from .mesh import TimeSeries
 
 from .io import load_volume
 from .io import load_slice
@@ -31,6 +32,7 @@
 from .io import load_label_lookup
 from .io import load_mesh
 from .io import load_warp
+from .io import load_timeseries
 
 from . import vis
 from . import freesurfer

surfa/core/framed.py

@@ -15,6 +15,7 @@ class FramedArrayIntents:
     shape       = 2
     warpmap     = 3
     warpmap_inv = 4
+    timeseries  = 5
 
 
 class FramedArray:

surfa/io/__init__.py

@@ -6,3 +6,4 @@
 from .framed import load_warp
 from .labels import load_label_lookup
 from .mesh import load_mesh
+from .timeseries import load_timeseries

surfa/io/framed.py

@@ -7,6 +7,7 @@
 from surfa import Slice
 from surfa import Overlay
 from surfa import Warp
+from surfa import TimeSeries
 from surfa.core.array import pad_vector_length
 from surfa.core.framed import FramedArray
 from surfa.core.framed import FramedArrayIntents
@@ -185,7 +186,7 @@ def framed_array_from_4d(atype, data):
         Squeezed framed array.
     """
     # this code is a bit ugly - it does the job but should probably be cleaned up
-    if atype == Volume:
+    if atype == Volume or atype == TimeSeries:
         return atype(data)
     if atype == Warp:
         if data.ndim == 4 and data.shape[-1] == 2:

surfa/io/timeseries.py

@@ -0,0 +1,117 @@
+import os
+import numpy as np
+
+from surfa.io import protocol
+from surfa.io.utils import check_file_readability
+from surfa.io.framed import framed_array_from_4d
+
+from surfa import TimeSeries
+
+def load_timeseries(filename, fmt=None):
+    """
+    Generic loader for `FramedArray` objects.
+
+    Parameters
+    ----------
+    filename : str or Path
+        File path to read.
+    fmt : str, optional
+        Explicit file format. If None, we extrapolate from the file extension.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object loaded file.
+    """
+    check_file_readability(filename)
+
+    if fmt is None:
+        iop = find_timeseries_protocol_by_extension(filename)
+    else:
+        iop = protocol.find_protocol_by_name(timeseries_io_protocols, fmt)
+        if iop is None:
+            raise ValueError(f'unknown file format {fmt}')
+
+    return iop().load(filename)
+
+
+def find_timeseries_protocol_by_extension(filename):
+    """
+    Find timeseries IO protocol from file extension.
+
+    Parameters
+    ----------
+    filename : str
+        File path to read.
+
+    Returns
+    -------
+    protocol : IOProtocol
+        Matched timeseries IO protocol class.
+    """
+
+    # find matching protocol
+    iop = protocol.find_protocol_by_extension(timeseries_io_protocols, filename)
+    if iop is None:
+        basename = os.path.basename(filename).lower()
+        raise ValueError(f'timeseries file type {basename} is not supported.')
+    
+    return iop
+
+
+class GiftiIO(protocol.IOProtocol):
+    """
+    GIFTI IO protocol for time-series files.
+    """
+    name = 'time-series'
+    extensions = ('.gii')
+
+    def __init__(self):
+        try:
+            import nibabel as nib
+        except ImportError:
+            raise ImportError('the `nibabel` python package must be installed for gifti IO')
+        self.nib = nib
+
+    def load(self, filename):
+        """
+        Read time-series from a gifti file.
+
+        Parameters
+        ----------
+        filename : str or Path
+            File path read.
+
+        Returns
+        -------
+        TimeSeries
+            TimeSeries object loaded from file.
+        """
+
+        giftiImage = self.nib.load(filename)
+        data = np.expand_dims(giftiImage.agg_data(), axis=(1,2))
+        
+        arr = framed_array_from_4d(TimeSeries, data)
+
+        return arr
+
+
+    def save(self, arr, filename):
+        """
+        Write time-series to a gifti file.
+
+        Parameters
+        ----------
+        arr : array
+            Array to save as gifti time-series
+        filename : str or Path
+            Target file path.
+        """
+
+        raise ValueError(f'ERROR: surfa.io.timeseries.GiftiIO.save() not implemented!')
+
+    
+# enabled TimeSeries IO protocol classes
+timeseries_io_protocols = [
+    GiftiIO,                 # '.gii'
+]

surfa/mesh/__init__.py

@@ -2,3 +2,4 @@
 from .overlay import Overlay
 from .overlay import cast_overlay
 from .distance import surface_distance
+from .timeseries import TimeSeries

surfa/mesh/timeseries.py

@@ -0,0 +1,22 @@
+import surfa as sf
+from surfa.image.framed import FramedImage
+
+class TimeSeries(FramedImage):
+
+    def __init__(self, data):
+        """
+        Time-Series class defining an array with data frames.
+
+        Parameters
+        ----------
+        data : array_like
+            Image data array.
+        """
+
+        basedim = data.ndim - 1
+        super().__init__(basedim=basedim, data=data)
+
+
+    def save(self, filename, fmt=None):
+        super().save(filename, fmt=fmt, intent=sf.core.framed.FramedArrayIntents.timeseries)
+