RF: get_norm_zooms -> get_zooms(units="canonical")

Author: effigies

nibabel/analyze.py

@@ -661,13 +661,22 @@ def get_base_affine(self):
 
     get_best_affine = get_base_affine
 
-    def get_zooms(self):
-        """ Get zooms from header
+    def get_zooms(self, units='canonical', raise_unknown=False):
+        """ Get zooms (spacing between voxels along each axis) from header
+
+        Parameters
+        ----------
+        units : {'canonical', 'raw'}, optional
+            Return zooms in "canonical" units of mm/sec for spatial/temporal or
+            as raw values stored in header.
+        raise_unkown : bool, optional
+            If canonical units are requested and the units are ambiguous, raise
+            a ``ValueError``
 
         Returns
         -------
-        z : tuple
-           tuple of header zoom values
+        zooms : tuple
+            tuple of header zoom values
 
         Examples
         --------
@@ -706,10 +715,6 @@ def set_zooms(self, zooms):
         pixdims = hdr['pixdim']
         pixdims[1:ndim + 1] = zooms[:]
 
-    def get_norm_zooms(self, raise_unknown=False):
-        ''' Get zooms in mm/s units '''
-        return self.get_zooms()
-
     def set_norm_zooms(self, zooms):
         ''' Set zooms in mm/s units '''
         return self.set_zooms(zooms)

nibabel/freesurfer/mghformat.py

@@ -237,25 +237,45 @@ def _ndims(self):
         """
         return 3 + (self._structarr['dims'][3] > 1)
 
-    def get_zooms(self):
+    def get_zooms(self, units='canonical', raise_unknown=False):
         """ Get zooms from header
 
         Returns the spacing of voxels in the x, y, and z dimensions.
         For four-dimensional files, a fourth zoom is included, equal to the
-        repetition time (TR) in ms (see `The MGH/MGZ Volume Format
-        <mghformat>`_).
+        repetition time (TR).
+        TR is stored in milliseconds (see `The MGH/MGZ Volume Format
+        <mghformat>`_),
+        so if ``units == 'raw'``, the fourth zoom will be in ms.
+        If ``units == 'canonical'`` (default), the fourth zoom will be in
+        seconds.
 
         To access only the spatial zooms, use `hdr['delta']`.
 
+        Parameters
+        ----------
+        units : {'canonical', 'raw'}, optional
+            Return zooms in "canonical" units of mm/sec for spatial/temporal or
+            as raw values stored in header.
+        raise_unkown : bool, optional
+            If canonical units are requested and the units are ambiguous, raise
+            a ``ValueError``
+
         Returns
         -------
-        z : tuple
-           tuple of header zoom values
+        zooms : tuple
+            tuple of header zoom values
 
         .. _mghformat: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat#line-82
         """
+        if units == 'canonical':
+            tfactor = 0.001
+        elif units == 'raw':
+            tfactor = 1
+        else:
+            raise ValueError("`units` parameter must be 'canonical' or 'raw'")
+
         # Do not return time zoom (TR) if 3D image
-        tzoom = (self['tr'],) if self._ndims() > 3 else ()
+        tzoom = (self['tr'] * tfactor,) if self._ndims() > 3 else ()
         return tuple(self._structarr['delta']) + tzoom
 
     def set_zooms(self, zooms):
@@ -285,15 +305,6 @@ def set_zooms(self, zooms):
                 raise HeaderDataError(f'TR must be non-negative; got {zooms[3]}')
             hdr['tr'] = zooms[3]
 
-    def get_norm_zooms(self, raise_unknown=False):
-        ''' Get zooms in mm/s units '''
-        zooms = self.get_zooms()
-
-        if len(zooms) == 4:
-            zooms = zooms[:3] + (zooms[3] / 1000,)
-
-        return zooms
-
     def set_norm_zooms(self, zooms):
         if len(zooms) == 4:
             zooms = zooms[:3] + (zooms[3] * 1000,)

nibabel/nifti1.py

@@ -1675,9 +1675,56 @@ def set_xyzt_units(self, xyz=None, t=None):
         t_code = unit_codes[t]
         self.structarr['xyzt_units'] = xyz_code + t_code
 
-    def get_norm_zooms(self, raise_unknown=False):
-        ''' Get zooms in mm/s units '''
-        raw_zooms = self.get_zooms()
+    def get_zooms(self, units=None, raise_unknown=False):
+        ''' Get zooms (spacing between voxels along each axis) from header
+
+        NIfTI1 headers may specify that zooms are encoded in units other than
+        mm and sec (see ``get_xyzt_units``).
+        Default behavior has been to return the raw zooms, and leave it to the
+        programmer to handle non-standard units.
+        However, most files indicate mm/sec units or have unspecified units,
+        and it is common practice to neglect specified units and assume all
+        files will be in mm/sec.
+
+        The default behavior for ``get_zooms`` will remain to return the raw
+        zooms until version 4.0, when it will change to return zooms in
+        canonical mm/sec units.
+        Because the default behavior will change, a warning will be given to
+        prompt programmers to specify whether they intend to retrieve raw
+        values, or values coerced into canonical units.
+
+        Parameters
+        ----------
+        units : {'canonical', 'raw'}
+            Return zooms in "canonical" units of mm/sec for spatial/temporal or
+            as raw values stored in header.
+        raise_unkown : bool, optional
+            If canonical units are requested and the units are ambiguous, raise
+            a ``ValueError``
+
+        Returns
+        -------
+        zooms : tuple
+            tuple of header zoom values
+
+        '''
+        if units is None:
+            units = 'raw'
+            warnings.warn('Units not specified in `{}.get_zooms`. Returning '
+                          'raw zooms, but default will change to canonical.\n'
+                          'Please explicitly specify units parameter.'
+                          ''.format(self.__class__.__name__),
+                          FutureWarning, stacklevel=2)
+
+        raw_zooms = super(Nifti1Header, self).get_zooms(units='raw',
+                                                        raise_unknown=False)
+
+        if units == 'raw':
+            return raw_zooms
+
+        elif units != 'canonical':
+            raise ValueError("`units` parameter must be 'canonical' or 'raw'")
+
         xyz_zooms = raw_zooms[:3]
         t_zoom = raw_zooms[3] if len(raw_zooms) > 3 else None
 

nibabel/spatialimages.py

@@ -224,7 +224,23 @@ def set_data_shape(self, shape):
         nzs = min(len(self._zooms), ndim)
         self._zooms = self._zooms[:nzs] + (1.0,) * (ndim - nzs)
 
-    def get_zooms(self):
+    def get_zooms(self, units='canonical', raise_unknown=False):
+        ''' Get zooms (spacing between voxels along each axis) from header
+
+        Parameters
+        ----------
+        units : {'canonical', 'raw'}, optional
+            Return zooms in "canonical" units of mm/sec for spatial/temporal or
+            as raw values stored in header.
+        raise_unkown : bool, optional
+            If canonical units are requested and the units are ambiguous, raise
+            a ``ValueError``
+
+        Returns
+        -------
+        zooms : tuple
+            Spacing between voxels along each axis
+        '''
         return self._zooms
 
     def set_zooms(self, zooms):
@@ -238,10 +254,6 @@ def set_zooms(self, zooms):
             raise HeaderDataError('zooms must be positive')
         self._zooms = zooms
 
-    def get_norm_zooms(self, raise_unknown=False):
-        ''' Get zooms in mm/s units '''
-        return self.get_zooms()
-
     def set_norm_zooms(self, zooms):
         ''' Get zooms in mm/s units '''
         return self.set_zooms(zooms)