RF: Add units parameter to set_zooms

- Switch 'canonical' to 'norm' for brevity

Author: effigies

nibabel/analyze.py

@@ -401,7 +401,7 @@ def from_header(klass, header=None, check=True):
                                      klass))
         obj.set_data_dtype(header.get_data_dtype())
         obj.set_data_shape(header.get_data_shape())
-        obj.set_zooms(header.get_zooms(units='raw'))
+        obj.set_zooms(header.get_zooms(units='raw'), units='raw')
         if check:
             obj.check_fix()
         return obj
@@ -664,16 +664,16 @@ def get_base_affine(self):
 
     get_best_affine = get_base_affine
 
-    def get_zooms(self, units='canonical', raise_unknown=False):
+    def get_zooms(self, units='norm', 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
+        units : {'norm', 'raw'}, optional
+            Return zooms in normalized 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
+            If normalized units are requested and the units are ambiguous, raise
             a ``ValueError``
 
         Returns
@@ -701,10 +701,19 @@ def get_zooms(self, units='canonical', raise_unknown=False):
         pixdims = hdr['pixdim']
         return tuple(pixdims[1:ndim + 1])
 
-    def set_zooms(self, zooms):
+    def set_zooms(self, zooms, units='norm'):
         ''' Set zooms into header fields
 
         See docstring for ``get_zooms`` for examples
+
+        Parameters
+        ----------
+        zooms : sequence of floats
+            Zoom values to set in header
+        units : {'norm', 'raw'}, optional
+            Zooms are specified in normalized units of mm/sec for
+            spatial/temporal or as raw values to be interpreted according to
+            format specification.
         '''
         hdr = self._structarr
         dims = hdr['dim']
@@ -718,10 +727,6 @@ def set_zooms(self, zooms):
         pixdims = hdr['pixdim']
         pixdims[1:ndim + 1] = zooms[:]
 
-    def set_norm_zooms(self, zooms):
-        ''' Set zooms in mm/s units '''
-        return self.set_zooms(zooms)
-
     def as_analyze_map(self):
         """ Return header as mapping for conversion to Analyze types
 

nibabel/freesurfer/mghformat.py

@@ -238,7 +238,7 @@ def _ndims(self):
         '''
         return 3 + (self._structarr['dims'][3] > 1)
 
-    def get_zooms(self, units='canonical', raise_unknown=False):
+    def get_zooms(self, units='norm', raise_unknown=False):
         ''' Get zooms from header
 
         Returns the spacing of voxels in the x, y, and z dimensions.
@@ -247,18 +247,18 @@ def get_zooms(self, units='canonical', raise_unknown=False):
         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
+        If ``units == 'norm'`` (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
+        units : {'norm', 'raw'}, optional
+            Return zooms in normalized 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
+            If normalized units are requested and the units are ambiguous, raise
             a ``ValueError``
 
         Returns
@@ -268,29 +268,40 @@ def get_zooms(self, units='canonical', raise_unknown=False):
 
         .. _mghformat: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat#line-82
         '''
-        if units == 'canonical':
+        if units == 'norm':
             tfactor = 0.001
         elif units == 'raw':
             tfactor = 1
         else:
-            raise ValueError("`units` parameter must be 'canonical' or 'raw'")
+            raise ValueError("`units` parameter must be 'norm' or 'raw'")
 
         # Do not return time zoom (TR) if 3D image
         tzoom = (self['tr'] * tfactor,) if self._ndims() > 3 else ()
         return tuple(self._structarr['delta']) + tzoom
 
-    def set_zooms(self, zooms):
+    def set_zooms(self, zooms, units='norm'):
         ''' Set zooms into header fields
 
         Sets the spacing of voxels in the x, y, and z dimensions.
-        For four-dimensional files, a temporal zoom (repetition time, or TR, in
-        ms) may be provided as a fourth sequence element.
+        For four-dimensional files, a temporal zoom (repetition time, or TR)
+        may be provided as a fourth sequence element.
+
+        TR is stored in milliseconds (see `The MGH/MGZ Volume Format
+        <mghformat>`_),
+        so if ``units == 'raw'``, the fourth zoom will be interpreted as ms
+        and stored unmodified.
+        If ``units == 'norm'`` (default), the fourth zoom will be interpreted
+        as seconds, and converted to ms before storing in the header.
 
         Parameters
         ----------
         zooms : sequence
             sequence of floats specifying spatial and (optionally) temporal
             zooms
+        units : {'norm', 'raw'}, optional
+            Zooms are specified in normalized units of mm/sec for
+            spatial/temporal dimensions or as raw values to be stored in
+            header.
         '''
         hdr = self._structarr
         zooms = np.asarray(zooms)
@@ -306,13 +317,13 @@ def set_zooms(self, zooms):
             if zooms[3] < 0:
                 raise HeaderDataError('TR must be non-negative; got {!r}'
                                       ''.format(zooms[3]))
-            hdr['tr'] = zooms[3]
-
-    def set_norm_zooms(self, zooms):
-        if len(zooms) == 4:
-            zooms = zooms[:3] + (zooms[3] * 1000,)
-
-        self.set_zooms(zooms)
+            if units == 'norm':
+                tfactor = 1000
+            elif units == 'raw':
+                tfactor = 1
+            else:
+                raise ValueError("`units` parameter must be 'norm' or 'raw'")
+            hdr['tr'] = zooms[3] * tfactor
 
     def get_data_shape(self):
         ''' Get shape of data

nibabel/freesurfer/tests/test_mghformat.py

@@ -70,11 +70,12 @@ def test_read_mgh():
     assert h['dof'] == 0
     assert h['goodRASFlag'] == 1
     assert_array_equal(h['dims'], [3, 4, 5, 2])
-    assert_almost_equal(h['tr'], 2.0)
+    assert_almost_equal(h['tr'], 2)
     assert_almost_equal(h['flip_angle'], 0.0)
     assert_almost_equal(h['te'], 0.0)
     assert_almost_equal(h['ti'], 0.0)
-    assert_array_almost_equal(h.get_zooms(), [1, 1, 1, 2])
+    assert_array_almost_equal(h.get_zooms(units='raw'), [1, 1, 1, 2])
+    assert_array_almost_equal(h.get_zooms(units='norm'), [1, 1, 1, 0.002])
     assert_array_almost_equal(h.get_vox2ras(), v2r)
     assert_array_almost_equal(h.get_vox2ras_tkr(), v2rtkr)
 
@@ -147,7 +148,7 @@ def test_write_noaffine_mgh():
 def test_set_zooms():
     mgz = load(MGZ_FNAME)
     h = mgz.header
-    assert_array_almost_equal(h.get_zooms(), [1, 1, 1, 2])
+    assert_array_almost_equal(h.get_zooms(), [1, 1, 1, 0.002])
     h.set_zooms([1, 1, 1, 3])
     assert_array_almost_equal(h.get_zooms(), [1, 1, 1, 3])
     for zooms in ((-1, 1, 1, 1),
@@ -397,28 +398,28 @@ def test_zooms_edge_cases(self):
 
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                   (1, 1, 1, 0))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                   (1, 1, 1, 0))
 
-        img.header.set_zooms((1, 1, 1, 2000))
+        img.header.set_zooms((1, 1, 1, 2000), units='raw')
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                   (1, 1, 1, 2000))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                   (1, 1, 1, 2))
         assert_array_almost_equal(img.header.get_zooms(), (1, 1, 1, 2))
 
-        img.header.set_norm_zooms((2, 2, 2, 3))
+        img.header.set_zooms((2, 2, 2, 3), units='norm')
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                   (2, 2, 2, 3000))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                   (2, 2, 2, 3))
         assert_array_almost_equal(img.header.get_zooms(), (2, 2, 2, 3))
 
         # It's legal to set zooms for spatial dimensions only
-        img.header.set_norm_zooms((3, 3, 3))
+        img.header.set_zooms((3, 3, 3), units='norm')
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                   (3, 3, 3, 3000))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                   (3, 3, 3, 3))
         assert_array_almost_equal(img.header.get_zooms(), (3, 3, 3, 3))
 
@@ -427,24 +428,24 @@ def test_zooms_edge_cases(self):
 
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                                        (1, 1, 1))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                                        (1, 1, 1))
 
-        img.header.set_zooms((2, 2, 2))
+        img.header.set_zooms((2, 2, 2), units='raw')
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                                        (2, 2, 2))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                                        (2, 2, 2))
 
-        img.header.set_norm_zooms((3, 3, 3))
+        img.header.set_zooms((3, 3, 3), units='norm')
         assert_array_almost_equal(img.header.get_zooms(units='raw'),
                                                        (3, 3, 3))
-        assert_array_almost_equal(img.header.get_zooms(units='canonical'),
+        assert_array_almost_equal(img.header.get_zooms(units='norm'),
                                                        (3, 3, 3))
 
         # Cannot set TR as zoom for 3D image
-        assert_raises(HeaderDataError, img.header.set_zooms, (4, 4, 4, 5))
-        assert_raises(HeaderDataError, img.header.set_norm_zooms, (4, 4, 4, 5))
+        assert_raises(HeaderDataError, img.header.set_zooms, (4, 4, 4, 5), 'raw')
+        assert_raises(HeaderDataError, img.header.set_zooms, (4, 4, 4, 5), 'norm')
 
 
 class TestMGHHeader(_TestLabeledWrapStruct):