Merge pull request #855 from apdavison/issue799

Fix for #799

Author: apdavison

neo/core/basesignal.py

@@ -139,8 +139,10 @@ def _get_required_attributes(self, signal, units):
         '''
         required_attributes = {}
         for attr in self._necessary_attrs:
-            if 'signal' == attr[0]:
-                required_attributes[str(attr[0])] = signal
+            if attr[0] == "signal":
+                required_attributes["signal"] = signal
+            elif attr[0] == "t_start":
+                required_attributes["t_start"] = getattr(self, "t_start", 0.0 * pq.ms)
             else:
                 required_attributes[str(attr[0])] = getattr(self, attr[0], None)
         required_attributes['units'] = units
@@ -176,7 +178,9 @@ def _copy_data_complement(self, other):
         all_attr = {self._recommended_attrs, self._necessary_attrs}
         for sub_at in all_attr:
             for attr in sub_at:
-                if attr[0] != 'signal':
+                if attr[0] == "t_start":
+                    setattr(self, attr[0], deepcopy(getattr(other, attr[0], 0.0 * pq.ms)))
+                elif attr[0] != 'signal':
                     setattr(self, attr[0], deepcopy(getattr(other, attr[0], None)))
         setattr(self, 'annotations', deepcopy(getattr(other, 'annotations', None)))
 

neo/core/imagesequence.py

@@ -41,9 +41,10 @@ class ImageSequence(BaseSignal):
         >>> img_sequence_array = [[[column for column in range(20)]for row in range(20)]
         ...                         for frame in range(10)]
         >>> image_sequence = ImageSequence(img_sequence_array, units='V',
-        ...                                sampling_rate=1*pq.Hz, spatial_scale=1*pq.micrometer)
+        ...                                sampling_rate=1 * pq.Hz,
+        ...                                spatial_scale=1 * pq.micrometer)
         >>> image_sequence
-        ImageSequence 10 frame with 20 px of height and 20  px of width; units V; datatype int64
+        ImageSequence 10 frames with width 20 px and height 20 px; units V; datatype int64
         sampling rate: 1.0
         spatial_scale: 1.0
         >>> image_sequence.spatial_scale
@@ -53,12 +54,13 @@ class ImageSequence(BaseSignal):
         :image_data: (3D NumPy array, or a list of 2D arrays)
             The data itself
         :units: (quantity units)
-        :sampling_rate: *or* **sampling_period** (quantity scalar) Number of
+        :sampling_rate: *or* **frame_duration** (quantity scalar) Number of
                                                 samples per unit time or
-                                                interval beween to samples.
+                                                duration of a single image frame.
                                                 If both are specified, they are
                                                 checked for consistency.
         :spatial_scale: (quantity scalar) size for a pixel.
+        :t_start: (quantity scalar) Time when sequence begins. Default 0.
 
     *Recommended attributes/properties*:
         :name: (str) A label for the dataset.
@@ -74,20 +76,29 @@ class ImageSequence(BaseSignal):
 
     *Properties available on this object*:
         :sampling_rate: (quantity scalar) Number of samples per unit time.
-            (1/:attr:`sampling_period`)
-        :sampling_period: (quantity scalar) Interval between two samples.
-            (1/:attr:`quantity scalar`)
-        :spatial_scale: size of a pixel
+            (1/:attr:`frame_duration`)
+        :frame_duration: (quantity scalar) Duration of each image frame.
+            (1/:attr:`sampling_rate`)
+        :spatial_scale: Size of a pixel
+        :duration: (Quantity) Sequence duration, read-only.
+            (size * :attr:`frame_duration`)
+        :t_stop: (quantity scalar) Time when sequence ends, read-only.
+            (:attr:`t_start` + :attr:`duration`)
      """
-    _single_parent_objects = ('Segment',)
-    _single_parent_attrs = ('segment',)
-    _quantity_attr = 'image_data'
-    _necessary_attrs = (('image_data', pq.Quantity, 3),
-                        ('sampling_rate', pq.Quantity, 0),
-                        ('spatial_scale', pq.Quantity, 0))
+
+    _single_parent_objects = ("Segment",)
+    _single_parent_attrs = ("segment",)
+    _quantity_attr = "image_data"
+    _necessary_attrs = (
+        ("image_data", pq.Quantity, 3),
+        ("sampling_rate", pq.Quantity, 0),
+        ("spatial_scale", pq.Quantity, 0),
+        ("t_start", pq.Quantity, 0),
+    )
     _recommended_attrs = BaseNeo._recommended_attrs
 
-    def __new__(cls, image_data, units=None, dtype=None, copy=True, spatial_scale=None, sampling_period=None,
+    def __new__(cls, image_data, units=None, dtype=None, copy=True, t_start=0 * pq.s,
+                spatial_scale=None, frame_duration=None,
                 sampling_rate=None, name=None, description=None, file_origin=None,
                 **annotations):
         """
@@ -99,52 +110,58 @@ def __new__(cls, image_data, units=None, dtype=None, copy=True, spatial_scale=No
         __array_finalize__ is called on the new object.
         """
         if spatial_scale is None:
-            raise ValueError('spatial_scale is required')
+            raise ValueError("spatial_scale is required")
 
         image_data = np.stack(image_data)
         if len(image_data.shape) != 3:
-            raise ValueError('list doesn\'t have the good number of dimension')
+            raise ValueError("list doesn't have the correct number of dimensions")
 
         obj = pq.Quantity(image_data, units=units, dtype=dtype, copy=copy).view(cls)
         obj.segment = None
         # function from analogsignal.py in neo/core directory
-        obj.sampling_rate = _get_sampling_rate(sampling_rate, sampling_period)
+        obj.sampling_rate = _get_sampling_rate(sampling_rate, frame_duration)
         obj.spatial_scale = spatial_scale
+        if t_start is None:
+            raise ValueError("t_start cannot be None")
+        obj._t_start = t_start
 
         return obj
 
-    def __init__(self, image_data, units=None, dtype=None, copy=True, spatial_scale=None, sampling_period=None,
+    def __init__(self, image_data, units=None, dtype=None, copy=True, t_start=0 * pq.s,
+                 spatial_scale=None, frame_duration=None,
                  sampling_rate=None, name=None, description=None, file_origin=None,
                  **annotations):
-        '''
+        """
         Initializes a newly constructed :class:`ImageSequence` instance.
-        '''
-        DataObject.__init__(self, name=name, file_origin=file_origin, description=description,
-                            **annotations)
+        """
+        DataObject.__init__(
+            self, name=name, file_origin=file_origin, description=description, **annotations
+        )
 
     def __array_finalize__spec(self, obj):
 
-        self.sampling_rate = getattr(obj, 'sampling_rate', None)
-        self.spatial_scale = getattr(obj, 'spatial_scale', None)
-        self.units = getattr(obj, 'units', None)
+        self.sampling_rate = getattr(obj, "sampling_rate", None)
+        self.spatial_scale = getattr(obj, "spatial_scale", None)
+        self.units = getattr(obj, "units", None)
+        self._t_start = getattr(obj, "_t_start", 0 * pq.s)
 
         return obj
 
     def signal_from_region(self, *region):
         """
-            Method that takes 1 or multiple regionofinterest, use the method of each region
-            of interest to get the list of pixel to average.
-            return a list of :class:`AnalogSignal` for each regionofinterest
+        Method that takes 1 or multiple regionofinterest, uses the method of each region
+        of interest to get the list of pixels to average.
+        Return a list of :class:`AnalogSignal` for each regionofinterest
         """
 
         if len(region) == 0:
-            raise ValueError('no region of interest have been given')
+            raise ValueError("no regions of interest have been given")
 
         region_pixel = []
         for i, b in enumerate(region):
             r = region[i].pixels_in_region()
             if not r:
-                raise ValueError('region '+str(i)+'is empty')
+                raise ValueError("region " + str(i) + "is empty")
             else:
                 region_pixel.append(r)
         analogsignal_list = []
@@ -158,23 +175,29 @@ def signal_from_region(self, *region):
                 for b in range(1, len(picture_data)):
                     average += picture_data[b]
                 data.append((average * 1.0) / len(i))
-            analogsignal_list.append(AnalogSignal(data, units=self.units,
-                                                  sampling_rate=self.sampling_rate))
+            analogsignal_list.append(
+                AnalogSignal(
+                    data, units=self.units, t_start=self.t_start, sampling_rate=self.sampling_rate
+                )
+            )
 
         return analogsignal_list
 
     def _repr_pretty_(self, pp, cycle):
-        '''
+        """
         Handle pretty-printing the :class:`ImageSequence`.
-        '''
-        pp.text("{cls} {frame} frame with {width} px of width and {height} px of height; "
-                "units {units}; datatype {dtype} ".format(
-                    cls=self.__class__.__name__,
-                    frame=self.shape[0],
-                    height=self.shape[1],
-                    width=self.shape[2],
-                    units=self.units.dimensionality.string,
-                    dtype=self.dtype))
+        """
+        pp.text(
+            "{cls} {nframe} frames with width {width} px and height {height} px; "
+            "units {units}; datatype {dtype} ".format(
+                cls=self.__class__.__name__,
+                nframe=self.shape[0],
+                height=self.shape[1],
+                width=self.shape[2],
+                units=self.units.dimensionality.string,
+                dtype=self.dtype,
+            )
+        )
 
         def _pp(line):
             pp.breakable()
@@ -188,11 +211,75 @@ def _pp(line):
             _pp(line)
 
     def _check_consistency(self, other):
-        '''
+        """
         Check if the attributes of another :class:`ImageSequence`
         are compatible with this one.
-        '''
+        """
         if isinstance(other, ImageSequence):
-            for attr in ("sampling_rate", "spatial_scale"):
+            for attr in ("sampling_rate", "spatial_scale", "t_start"):
                 if getattr(self, attr) != getattr(other, attr):
                     raise ValueError("Inconsistent values of %s" % attr)
+
+    # t_start attribute is handled as a property so type checking can be done
+    @property
+    def t_start(self):
+        """
+        Time when sequence begins.
+        """
+        return self._t_start
+
+    @t_start.setter
+    def t_start(self, start):
+        """
+        Setter for :attr:`t_start`
+        """
+        if start is None:
+            raise ValueError("t_start cannot be None")
+        self._t_start = start
+
+    @property
+    def duration(self):
+        """
+        Sequence duration
+
+        (:attr:`size` * :attr:`frame_duration`)
+        """
+        return self.shape[0] / self.sampling_rate
+
+    @property
+    def t_stop(self):
+        """
+        Time when Sequence ends.
+
+        (:attr:`t_start` + :attr:`duration`)
+        """
+        return self.t_start + self.duration
+
+    @property
+    def times(self):
+        """
+        The time points of each frame in the sequence
+
+        (:attr:`t_start` + arange(:attr:`shape`)/:attr:`sampling_rate`)
+        """
+        return self.t_start + np.arange(self.shape[0]) / self.sampling_rate
+
+    @property
+    def frame_duration(self):
+        """
+        Duration of a single image frame in the sequence.
+
+        (1/:attr:`sampling_rate`)
+        """
+        return 1.0 / self.sampling_rate
+
+    @frame_duration.setter
+    def frame_duration(self, duration):
+        """
+        Setter for :attr:`frame_duration`
+        """
+        if duration is None:
+            raise ValueError("frame_duration cannot be None")
+        elif not hasattr(duration, "units"):
+            raise ValueError("frame_duration must have units")
+        self.sampling_rate = 1.0 / duration

neo/io/nixio.py

@@ -507,10 +507,15 @@ def _nix_to_neo_imagesequence(self, nix_da_group):
         del neo_attrs["sampling_rate"]
         spatial_scale = neo_attrs["spatial_scale"]
         del neo_attrs["spatial_scale"]
+        if "t_start" in neo_attrs:
+            t_start = neo_attrs["t_start"]
+            del neo_attrs["t_start"]
+        else:
+            t_start = 0.0 * pq.ms
 
         neo_seq = ImageSequence(image_data=imgseq, sampling_rate=sampling_rate,
                                 spatial_scale=spatial_scale, units=unit,
-                                **neo_attrs)
+                                t_start=t_start, **neo_attrs)
 
         self._neo_map[neo_attrs["nix_name"]] = neo_seq
         # all DAs reference the same sources
@@ -911,6 +916,9 @@ def _write_imagesequence(self, imgseq, nixblock, nixgroup):
             metadata["spatial_scale"] = imgseq.spatial_scale.magnitude.item()
             units = imgseq.spatial_scale.units
             metadata.props["spatial_scale"].unit = units_to_string(units)
+            metadata["t_start"] = imgseq.t_start.magnitude.item()
+            units = imgseq.t_start.units
+            metadata.props["t_start"].unit = units_to_string(units)
 
             nixdas.append(da)
             if nixgroup: