# io.files

## Module: `io.files`

The io.files module provides basic functions for working with file-based images in nipy.

- load : load an image from a file

- save : save an image to a file

### Examples

See documentation for load and save functions for worked examples.

## Functions

nipy.io.files.as_image(image_input)

  Load image from filename or pass through image instance

  Parameters:
    image_input str or Image instance

      image or string filename of image. If a string, load image and return. If an image, pass through without modification

  Returns:
    img Image or Image-like instance

      Input object if image_input seemed to be an image, loaded Image object if image_input was a string.

  Raises:
    TypeError if neither string nor image-like passed

  Examples

      >>> from nipy.testing import anatfile
      >>> from nipy.io.api import load_image
      >>> img = as_image(anatfile)
      >>> img2 = as_image(img)
      >>> img2 is img
      True

nipy.io.files.load(filename)

  Load an image from the given filename.

  Parameters:
    filename string

      Should resolve to a complete filename path.

  Returns:
    image An Image object

      If successful, a new Image object is returned.

  See also

  `save_image`

    function for saving images

  `Image`

    image object

  Examples

      >>> from nipy.io.api import load_image
      >>> from nipy.testing import anatfile
      >>> img = load_image(anatfile)
      >>> img.shape
      (33, 41, 25)

nipy.io.files.save(img, filename, dtype_from='data')

  Write the image to a file.

  Parameters:
    img An Image object
    filename string

      Should be a valid filename.

    dtype_from{‘data’, ‘header’} or dtype specifier, optional

      Method of setting dtype to save data to disk. Value of ‘data’ (default), means use data dtype to save. ‘header’ means use data dtype specified in header, if available, otherwise use data dtype. Can also be any valid specifier for a numpy dtype, e.g. ‘i4’, `np.float32`. Not every format supports every dtype, so some values of this parameter or data dtypes will raise errors.

  Returns:
    image An Image object

      Possibly modified by saving.

  See also

  `load_image`

    function for loading images

  `Image`

    image object

  Notes

  Filetype is determined by the file extension in ‘filename’. Currently the following filetypes are supported:

  - Nifti single file : [‘.nii’, ‘.nii.gz’]

  - Nifti file pair : [‘.hdr’, ‘.hdr.gz’]

  - SPM Analyze : [‘.img’, ‘.img.gz’]

  Examples

  Make a temporary directory to store files

      >>> import os
      >>> from tempfile import mkdtemp
      >>> tmpdir = mkdtemp()

  Make some some files and save them

      >>> import numpy as np
      >>> from nipy.core.api import Image, AffineTransform
      >>> from nipy.io.api import save_image
      >>> data = np.zeros((91,109,91), dtype=np.uint8)
      >>> cmap = AffineTransform('kji', 'zxy', np.eye(4))
      >>> img = Image(data, cmap)
      >>> fname1 = os.path.join(tmpdir, 'img1.nii.gz')
      >>> saved_img1 = save_image(img, fname1)
      >>> saved_img1.shape
      (91, 109, 91)
      >>> fname2 = os.path.join(tmpdir, 'img2.img.gz')
      >>> saved_img2 = save_image(img, fname2)
      >>> saved_img2.shape
      (91, 109, 91)
      >>> fname = 'test.mnc'
      >>> saved_image3 = save_image(img, fname)
      Traceback (most recent call last):
         ...
      ValueError: Sorry, we cannot yet save as format "minc"

  Finally, we clear up our temporary files:

      >>> import shutil
      >>> shutil.rmtree(tmpdir)