DOC: Update docstrings, comments, for clarity

Author: effigies

nibabel/ecat.py

@@ -705,6 +705,25 @@ def __array__(self):
         return data
 
     def get_scaled(self, dtype=None):
+        """ Read data from file and apply scaling
+
+        The dtype of the returned array is the narrowest dtype that can
+        represent the data without overflow, and is at least as wide as
+        the dtype parameter.
+
+        If dtype is unspecified, it is automatically determined.
+
+        Parameters
+        ----------
+        dtype : numpy dtype specifier
+            A numpy dtype specifier specifying the narrowest acceptable
+            dtype.
+
+        Returns
+        -------
+        array
+            Scaled of image data of data type `dtype`.
+        """
         data = self.__array__()
         if dtype is None:
             return data

nibabel/minc1.py

@@ -269,6 +269,25 @@ def _get_scaled(self, dtype, slicer):
         return data.astype(final_type, copy=False)
 
     def get_scaled(self, dtype=None):
+        """ Read data from file and apply scaling
+
+        The dtype of the returned array is the narrowest dtype that can
+        represent the data without overflow, and is at least as wide as
+        the dtype parameter.
+
+        If dtype is unspecified, it is automatically determined.
+
+        Parameters
+        ----------
+        dtype : numpy dtype specifier
+            A numpy dtype specifier specifying the narrowest acceptable
+            dtype.
+
+        Returns
+        -------
+        array
+            Scaled of image data of data type `dtype`.
+        """
         return self._get_scaled(dtype=dtype, slicer=())
 
     def __array__(self):

nibabel/parrec.py

@@ -670,9 +670,33 @@ def _get_scaled(self, dtype, slicer):
 
 
     def get_unscaled(self):
+        """ Read data from file
+
+        This is an optional part of the proxy API
+        """
         return self._get_unscaled(slicer=())
 
     def get_scaled(self, dtype=None):
+        """ Read data from file and apply scaling
+
+        The dtype of the returned array is the narrowest dtype that can
+        represent the data without overflow, and is at least as wide as
+        the dtype parameter.
+
+        If dtype is unspecified, it is the wider of the dtypes of the slopes
+        or intercepts
+
+        Parameters
+        ----------
+        dtype : numpy dtype specifier
+            A numpy dtype specifier specifying the narrowest acceptable
+            dtype.
+
+        Returns
+        -------
+        array
+            Scaled of image data of data type `dtype`.
+        """
         return self._get_scaled(dtype=dtype, slicer=())
 
     def __array__(self):

nibabel/tests/test_image_api.py

@@ -314,6 +314,9 @@ def _check_proxy_interface(self, imaker, meth_name):
         # New data dtype, no caching, doesn't use or alter cache
         fdata_new_dt = img.get_fdata(caching='unchanged', dtype='f4')
         # We get back the original read, not the modified cache
+        # Allow for small rounding error when the data is scaled with 32-bit
+        # factors, rather than 64-bit factors and then cast to float-32
+        # Use rtol/atol from numpy.allclose
         assert_allclose(fdata_new_dt, proxy_data.astype('f4'), rtol=1e-05, atol=1e-08)
         assert_equal(fdata_new_dt.dtype, np.float32)
         # The original cache stays in place, for default float64