Merge pull request #287 from matthew-brett/in-memory-doc-rewrite

DOC: `get_data` docstring rewrite

Rewrite of docstring for get_data to give more details on the cache.

Author: matthew-brett

nibabel/spatialimages.py

@@ -6,7 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-''' Very simple spatial image class
+''' A simple spatial image class
 
 The image class maintains the association between a 3D (or greater)
 array, and an affine transform that maps voxel coordinates to some world space.
@@ -27,7 +27,7 @@
      ``fname``, where the derivation may differ between formats.
    * to_file_map() - save image to files with which the image is already
      associated.
-   * .get_shape() (Deprecated)
+   * .get_shape() (deprecated)
 
 properties:
 
@@ -451,34 +451,127 @@ def __str__(self):
     def get_data(self, caching='fill'):
         """ Return image data from image with any necessary scalng applied
 
-        If the image data is a array proxy (data not yet read from disk) then
-        the default behavior (`caching` == "fill") is to read the data, and
-        store in an internal cache.  Future calls to ``get_data`` will return
-        the cached copy.
+        If the image data is an array proxy (an object that knows how to load
+        the image data from disk) then the default behavior (`caching` ==
+        "fill") is to read the data from the proxy, and store in an internal
+        cache.  Future calls to ``get_data`` will return the cached array.
 
-        Once the data has been cached and returned from a proxy array, the
-        cached array can be modified by modifying the returned array, because
-        the returned array is a reference to the array in the cache.  Regardless
-        of the `caching` flag, this is always true of an in-memory image (where
-        the image data is an array rather than an array proxy).
+        Once the data has been cached and returned from an image array proxy,
+        if you modify the returned array, you will also modify the cached
+        array (because they are the same array).  Regardless of the `caching`
+        flag, this is always true of an in-memory image (where the image data
+        is an array rather than an array proxy).
 
         Parameters
         ----------
         caching : {'fill', 'unchanged'}, optional
-            This argument has no effect in the case where the image data is an
-            array, or the image data has already been cached.  If the image data
-            is an array proxy, and the image data has not yet been cached, then
-            'fill' (the default) will read the data from the array proxy, and
-            store in an internal cache, so that future calls to ``get_data``
-            will return the cached copy.  If 'unchanged' then leave the current
-            state of caching unchanged; return the cached copy if it exists, if
-            not, load the data from disk and return that, but without filling
-            the cache.
+            See the Notes section for a detailed explanation.  This argument
+            specifies whether the image object should fill in an internal
+            cached reference to the returned image data array. "fill" specifies
+            that the image should fill an internal cached reference if
+            currently empty.  Future calls to ``get_data`` will return this
+            cached reference.  You might prefer "fill" to save the image object
+            from having to reload the array data from disk on each call to
+            ``get_data``.  "unchanged" means that the image should not fill in
+            the internal cached reference if the cache is currently empty.  You
+            might prefer "unchanged" to "fill" if you want to make sure that
+            the call to ``get_data`` does not create an extra (cached)
+            reference to the returned array.  In this case it is easier for
+            Python to free the memory from the returned array.
 
         Returns
         -------
         data : array
             array of image data
+
+        See also
+        --------
+        uncache: empty the array data cache
+
+        Notes
+        -----
+        All images have a property ``dataobj`` that represents the image array
+        data.  Images that have been loaded from files usually do not load the
+        array data from file immediately, in order to reduce image load time
+        and memory use.  For these images, ``dataobj`` is an *array proxy*; an
+        object that knows how to load the image array data from file.  Images
+        with an array proxy ``dataobj`` are called *proxy images*. In contrast,
+        images created directly from numpy arrays carry a simple reference to
+        their array data in ``dataobj``.  These are *in-memory images*.
+
+        By default (`caching` == "fill"), when you call ``get_data`` on a
+        proxy image, we load the array data from disk, store (cache) an
+        internal reference to this array data, and return the array.  The next
+        time you call ``get_data``, you will get the cached reference to the
+        array, so we don't have to load the array data from disk again.
+
+        In-memory images are already in memory, so there is no benefit to
+        caching, and the `caching` keywords have no effect.
+
+        For proxy images, you may not want to fill the cache after reading the
+        data from disk because the cache will hold onto the array memory until
+        the image object is deleted, or you use the image ``uncache`` method.
+        If you don't want to fill the cache, then always use
+        ``get_data(caching='unchanged')``; in this case ``get_data`` will not
+        fill the cache (store the reference to the array) if the cache is empty
+        (no reference to the array).  If the cache is full, "unchanged" leaves
+        the cache full and returns the cached array reference.
+
+        The cache can effect the behavior of the image, because if the cache is
+        full, or you have an in-memory image, then modifying the returned array
+        will modify the result of future calls to ``get_data()``.  For example
+        you might do this:
+
+        >>> import os
+        >>> import nibabel as nib
+        >>> from nibabel.testing import data_path
+        >>> img_fname = os.path.join(data_path, 'example4d.nii.gz')
+
+        >>> img = nib.load(img_fname) # This is a proxy image
+        >>> nib.is_proxy(img.dataobj)
+        True
+
+        The array is not yet cached by a call to "get_data", so:
+        >>> img.in_memory
+        False
+
+        After we call ``get_data`` using the default `caching='fill', the cache
+        contains a reference to the returned array ``data``:
+
+        >>> data = img.get_data()
+        >>> img.in_memory
+        True
+
+        We modify an element in the returned data array:
+
+        >>> data[0, 0, 0, 0]
+        0
+        >>> data[0, 0, 0, 0] = 99
+        >>> data[0, 0, 0, 0]
+        99
+
+        The next time we call 'get_data', the method returns the cached
+        reference to the (modified) array:
+
+        >>> data_again = img.get_data()
+        >>> data_again is data
+        True
+        >>> data_again[0, 0, 0, 0]
+        99
+
+        If you had *initially* used `caching` == 'unchanged' then the returned
+        ``data`` array would have been loaded from file, but not cached, and:
+
+        >>> img = nib.load(img_fname)  # a proxy image again
+        >>> data = img.get_data(caching='unchanged')
+        >>> img.in_memory
+        False
+        >>> data[0, 0, 0] = 99
+        >>> data_again = img.get_data(caching='unchanged')
+        >>> data_again is data
+        False
+        >>> data_again[0, 0, 0, 0]
+        0
         """
         if caching not in ('fill', 'unchanged'):
             raise ValueError('caching value should be "fill" or "unchanged"')