9.1. Input and output: neuroimaging data representation#
9.1.1. Inputing data: file names or image objects#
126.96.36.199. File names and objects, 3D and 4D images#
All Nilearn functions accept file names as arguments:
>>> from nilearn import image >>> smoothed_img = image.smooth_img('/home/user/t_map001.nii')
Nilearn can operate on either file names or NiftiImage objects. The later represent the
data loaded in memory. In the example above, the
smooth_img returns a Nifti1Image object, which can then
be readily passed to other nilearn functions.
In nilearn, we often use the term “niimg” as abbreviation that denotes either a file name or a NiftiImage object.
Niimgs can be 3D or 4D. A 4D niimg may for instance represent a time series of 3D images. It can be a list of file names, if these contain 3D information:
>>> # dataset folder contains subject1.nii and subject2.nii >>> from nilearn.image import smooth_img >>> result_img = smooth_img(['dataset/subject1.nii', 'dataset/subject2.nii'])
result_img is a 4D in-memory image, containing the data of both
188.8.131.52. File name matching: “globbing” and user path expansion#
You can specify files with wildcard matching patterns (as in Unix shell):
Matching multiple files: suppose the dataset folder contains subject_01.nii, subject_03.nii, and subject_03.nii;
dataset/subject_*.niiis a glob expression matching all filenames:>>> # Example with a smoothing process: >>> from nilearn.image import smooth_img >>> result_img = smooth_img("dataset/subject_*.nii")
Note that the resulting is a 4D image.
Expanding the home directory
~is expanded to your home directory:>>> result_img = smooth_img("~/dataset/subject_01.nii")
~rather than specifying the details of the path is good practice, as it will make it more likely that your script work on different computers.
9.1.2. Fetching open datasets from Internet#
Nilearn provides dataset fetching function that
automatically downloads reference
datasets and atlases. They can be imported from
>>> from nilearn import datasets >>> haxby_dataset = datasets.fetch_haxby()
They return a data structure that contains different pieces of information on the retrieved dataset, including the file names on hard disk:
>>> # The different files >>> print(sorted(list(haxby_dataset.keys()))) ['anat', 'description', 'func', 'mask', 'mask_face', 'mask_face_little', 'mask_house', 'mask_house_little', 'mask_vt', 'session_target'] >>> # Path to first functional file >>> print(haxby_dataset.func) /.../nilearn_data/haxby2001/subj1/bold.nii.gz
Explanation and further resources of the dataset at hand can be retrieved as follows:
>>> print(haxby_dataset.description) Haxby 2001 results Notes ----- Results from a classical fMRI study that...
For a list of all the data fetching functions in nilearn, see nilearn.datasets: Automatic Dataset Fetching.
9.1.3. Understanding neuroimaging data#
184.108.40.206. Nifti and Analyze data#
For volumetric data, nilearn works with data stored as in the Nifti structure (via the nibabel package).
The NifTi data structure (also used in Analyze files) is the standard way of sharing data in neuroimaging research. Three main components are:
raw scans in form of a numpy array:
data = nilearn.image.get_data(img)
returns the transformation matrix that maps from voxel indices of the numpy array to actual real-world locations of the brain:
affine = img.affine
low-level information about the data (slice duration, etc.):
header = img.header
If you need to load the data without using nilearn, read the nibabel documentation.
Note: For older versions of nibabel, affine and header can be retrieved
if you create images directly with nibabel, beware of int64 images. the default integer type used by Numpy is (signed) 64-bit. Several popular neuroimaging tools do not handle int64 Nifti images, so if you build Nifti images directly from Numpy arrays it is recommended to specify a smaller integer type, for example:
np.array([1, 2000, 7], dtype="int32")
220.127.116.11. Niimg-like objects#
Nilearn functions take as input argument what we call “Niimg-like objects”:
Niimg: A Niimg-like object can be one of the following:
A string or pathlib.Path object with a file path to a Nifti or Analyse image
SpatialImagefrom nibabel, ie an object exposing
affineattribute, typically a
Niimg-4D: Similarly, some functions require 4D Nifti-like data, which we call Niimgs or Niimg-4D. Accepted input arguments are:
A path to a 4D Nifti image
List of paths to 3D Nifti images
4D Nifti-like object
List of 3D Nifti-like objects
18.104.22.168. Text files: phenotype or behavior#
Phenotypic or behavioral data are often provided as text or CSV (Comma Separated Values) file. They can be loaded with pd.read_csv but you may have to specify some options (typically sep if fields aren’t delimited with a comma).
For the Haxby datasets, we can load the categories of the images presented to the subject:
>>> from nilearn import datasets >>> haxby_dataset = datasets.fetch_haxby() >>> import pandas as pd >>> labels = pd.read_csv(haxby_dataset.session_target, sep=" ") >>> stimuli = labels['labels'] >>> print(stimuli.unique()) ['bottle' 'cat' 'chair' 'face' 'house' 'rest' 'scissors' 'scrambledpix' 'shoe']