class_docstr: Template class for images that have dataobj data stores
class_docstr_tok: ["Template","class","for","images","that","have","dataobj","data","stores"]
docstr: Return image data from image with any necessary scaling applied
  
  .. WARNING::
  
      We recommend you use the ``get_fdata`` method instead of the
      ``get_data`` method, because it is easier to predict the return
      data type.  ``get_data`` will be deprecated around November 2019
      and removed around November 2021.
  
      If you don't care about the predictability of the return data type,
      and you want the minimum possible data size in memory, you can
      replicate the array that would be returned by ``img.get_data()`` by
      using ``np.asanyarray(img.dataobj)``.
  
  The image ``dataobj`` property can be an array proxy or an array.  An
  array proxy is an object that knows how to load the image data from
  disk.  An image with an array proxy ``dataobj`` is a *proxy image*; an
  image with an array in ``dataobj`` is an *array image*.
  
  The default behavior for ``get_data()`` on a proxy image is to read the
  data from the proxy, and store in an internal cache.  Future calls to
  ``get_data`` will return the cached array.  This is the behavior
  selected with `caching` == "fill".
  
  Once the data has been cached and returned from an 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 array image.
  
  Parameters
  ----------
  caching : {'fill', 'unchanged'}, optional
      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.
  
  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.
  
  Array images have a ``dataobj`` property that already refers to an
  array 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 affect the behavior of the image, because if the cache is
  full, or you have an array 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
docstr_tok: ["Return","image","data","from","image","with","any","necessary","scaling","applied","..","WARNING",":",":","We","recommend","you","use","the","``","get_fdata","``","method","instead","of","the","``","get_data","``","method",",","because","it","is","easier","to","predict","the","return","data","type",".","``","get_data","``","will","be","deprecated","around","November","2019","and","removed","around","November","2021",".","If","you","do","n't","care","about","the","predictability","of","the","return","data","type",",","and","you","want","the","minimum","possible","data","size","in","memory",",","you","can","replicate","the","array","that","would","be","returned","by","``","img.get_data","(",")","``","by","using","``","np.asanyarray","(","img.dataobj",")","``",".","The","image","``","dataobj","``","property","can","be","an","array","proxy","or","an","array",".","An","array","proxy","is","an","object","that","knows","how","to","load","the","image","data","from","disk",".","An","image","with","an","array","proxy","``","dataobj","``","is","a","*","proxy","image","*",";","an","image","with","an","array","in","``","dataobj","``","is","an","*","array","image","*",".","The","default","behavior","for","``","get_data","(",")","``","on","a","proxy","image","is","to","read","the","data","from","the","proxy",",","and","store","in","an","internal","cache",".","Future","calls","to","``","get_data","``","will","return","the","cached","array",".","This","is","the","behavior","selected","with","`","caching","`","==","``","fill","''",".","Once","the","data","has","been","cached","and","returned","from","an","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","array","image",".","Parameters","--","--","--","--","--","caching",":","{","'fill","'",",","'unchanged","'","}",",","optional","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",".","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","do","n't","have","to","load","the","array","data","from","disk","again",".","Array","images","have","a","``","dataobj","``","property","that","already","refers","to","an","array","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","do","n'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","affect","the","behavior","of","the","image",",","because","if","the","cache","is","full",",","or","you","have","an","array","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"]
code: def get_data(self, caching="fill"):
      """Return image data from image with any necessary scaling applied
  
      .. WARNING::
  
          We recommend you use the ``get_fdata`` method instead of the
          ``get_data`` method, because it is easier to predict the return
          data type.  ``get_data`` will be deprecated around November 2019
          and removed around November 2021.
  
          If you don't care about the predictability of the return data type,
          and you want the minimum possible data size in memory, you can
          replicate the array that would be returned by ``img.get_data()`` by
          using ``np.asanyarray(img.dataobj)``.
  
      The image ``dataobj`` property can be an array proxy or an array.  An
      array proxy is an object that knows how to load the image data from
      disk.  An image with an array proxy ``dataobj`` is a *proxy image*; an
      image with an array in ``dataobj`` is an *array image*.
  
      The default behavior for ``get_data()`` on a proxy image is to read the
      data from the proxy, and store in an internal cache.  Future calls to
      ``get_data`` will return the cached array.  This is the behavior
      selected with `caching` == "fill".
  
      Once the data has been cached and returned from an 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 array image.
  
      Parameters
      ----------
      caching : {'fill', 'unchanged'}, optional
          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.
  
      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.
  
      Array images have a ``dataobj`` property that already refers to an
      array 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 affect the behavior of the image, because if the cache is
      full, or you have an array 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"'
          )
      if self._data_cache is not None:
          return self._data_cache
      data = np.asanyarray(self._dataobj)
      if caching == "fill":
          self._data_cache = data
      return data
  
file_path: nibabel/nibabel/dataobj_images.py
imports: from __future__ import annotations
  import typing
  import numpy
  from .arrayproxy import ArrayLike
  from .deprecated import deprecate_with_version
  from .filebasedimages import FileBasedHeader, FileBasedImage
  from .fileholders import FileMap
label_desc: Use image node_id 3 for calling the DataobjImage obj's underlying member method code with example usage: obj.get_data(caching) and returns: data, self