brikhead
¶
Class for reading AFNI BRIK/HEAD datasets
See https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html for information on what is required to have a valid BRIK/HEAD dataset.
Unless otherwise noted, descriptions AFNI attributes in the code refer to this document.
Notes¶
In the AFNI HEAD file, the first two values of the attribute DATASET_RANK determine the shape of the data array stored in the corresponding BRIK file. The first value, DATASET_RANK[0], must be set to 3 denoting a 3D image. The second value, DATASET_RANK[1], determines how many “sub-bricks” (in AFNI parlance) / volumes there are along the fourth (traditionally, but not exclusively) time axis. Thus, DATASET_RANK[1] will (at least as far as I (RM) am aware) always be >= 1. This permits sub-brick indexing common in AFNI programs (e.g., example4d+orig’[0]’).
|
Proxy object for AFNI image array. |
|
Class for AFNI header |
Error when reading AFNI HEAD file |
|
|
AFNI Image file |
Error when reading AFNI BRIK files |
|
|
Parses fobj to extract information from HEAD file |
AFNIArrayProxy
¶
- class nibabel.brikhead.AFNIArrayProxy(file_like, header, *, mmap=True, keep_file_open=None)¶
Bases:
ArrayProxy
Proxy object for AFNI image array.
- Attributes:
- scalingnp.ndarray
Scaling factor (one factor per volume/sub-brick) for data. Default is None
Initialize AFNI array proxy
- Parameters:
- file_likefile-like object
File-like object or filename. If file-like object, should implement at least
read
andseek
.- header
AFNIHeader
object - mmap{True, False, ‘c’, ‘r’}, optional, keyword only
mmap controls the use of numpy memory mapping for reading data. If False, do not try numpy
memmap
for data array. If one of {‘c’, ‘r’}, try numpy memmap withmode=mmap
. A mmap value of True gives the same behavior asmmap='c'
. If file_like cannot be memory-mapped, ignore mmap value and read array from file.- keep_file_open{ None, True, False }, optional, keyword only
keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this
ArrayProxy
. IfTrue
, a single file handle is created and used. IfFalse
, a new file handle is created every time the image is accessed. Iffile_like
refers to an open file handle, this setting has no effect. The default value (None
) will result in the value ofnibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT
being used.
- __init__(file_like, header, *, mmap=True, keep_file_open=None)¶
Initialize AFNI array proxy
- Parameters:
- file_likefile-like object
File-like object or filename. If file-like object, should implement at least
read
andseek
.- header
AFNIHeader
object - mmap{True, False, ‘c’, ‘r’}, optional, keyword only
mmap controls the use of numpy memory mapping for reading data. If False, do not try numpy
memmap
for data array. If one of {‘c’, ‘r’}, try numpy memmap withmode=mmap
. A mmap value of True gives the same behavior asmmap='c'
. If file_like cannot be memory-mapped, ignore mmap value and read array from file.- keep_file_open{ None, True, False }, optional, keyword only
keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this
ArrayProxy
. IfTrue
, a single file handle is created and used. IfFalse
, a new file handle is created every time the image is accessed. Iffile_like
refers to an open file handle, this setting has no effect. The default value (None
) will result in the value ofnibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT
being used.
- property scaling¶
AFNIHeader
¶
- class nibabel.brikhead.AFNIHeader(info)¶
Bases:
SpatialHeader
Class for AFNI header
Initialize AFNI header object
- Parameters:
- infodict
Information from HEAD file as obtained by
parse_AFNI_header()
Examples
>>> fname = os.path.join(datadir, 'example4d+orig.HEAD') >>> header = AFNIHeader(parse_AFNI_header(fname)) >>> header.get_data_dtype().str '<i2' >>> header.get_zooms() (3.0, 3.0, 3.0, 3.0) >>> header.get_data_shape() (33, 41, 25, 3)
- __init__(info)¶
Initialize AFNI header object
- Parameters:
- infodict
Information from HEAD file as obtained by
parse_AFNI_header()
Examples
>>> fname = os.path.join(datadir, 'example4d+orig.HEAD') >>> header = AFNIHeader(parse_AFNI_header(fname)) >>> header.get_data_dtype().str '<i2' >>> header.get_zooms() (3.0, 3.0, 3.0, 3.0) >>> header.get_data_shape() (33, 41, 25, 3)
- copy()¶
Copy object to independent representation
The copy should not be affected by any changes to the original object.
- classmethod from_fileobj(fileobj)¶
- classmethod from_header(header=None)¶
- get_affine()¶
Returns affine of dataset
Examples
>>> fname = os.path.join(datadir, 'example4d+orig.HEAD') >>> header = AFNIHeader(parse_AFNI_header(fname)) >>> header.get_affine() array([[ -3. , -0. , -0. , 49.5 ], [ -0. , -3. , -0. , 82.312 ], [ 0. , 0. , 3. , -52.3511], [ 0. , 0. , 0. , 1. ]])
- get_data_offset()¶
Data offset in BRIK file
Offset is always 0.
- get_data_scaling()¶
AFNI applies volume-specific data scaling
Examples
>>> fname = os.path.join(datadir, 'scaled+tlrc.HEAD') >>> header = AFNIHeader(parse_AFNI_header(fname)) >>> header.get_data_scaling() array([3.883363e-08])
- get_slope_inter()¶
Use self.get_data_scaling() instead
Holdover because
AFNIArrayProxy
(inheriting fromArrayProxy
) requires this functionality so as to not error.
- get_space()¶
Return label for anatomical space to which this dataset is aligned.
- Returns:
- spacestr
AFNI “space” designation; one of [ORIG, ANAT, TLRC, MNI]
Notes
There appears to be documentation for these spaces at https://afni.nimh.nih.gov/pub/dist/atlases/elsedemo/AFNI_atlas_spaces.niml
- get_volume_labels()¶
Returns volume labels
- Returns:
- labelslist of str
Labels for volumes along fourth dimension
Examples
>>> header = AFNIHeader(parse_AFNI_header(os.path.join(datadir, 'example4d+orig.HEAD'))) >>> header.get_volume_labels() ['#0', '#1', '#2']
AFNIHeaderError
¶
- class nibabel.brikhead.AFNIHeaderError¶
Bases:
HeaderDataError
Error when reading AFNI HEAD file
- __init__(*args, **kwargs)¶
AFNIImage
¶
- class nibabel.brikhead.AFNIImage(dataobj: ArrayLike, affine: np.ndarray | None, header: FileBasedHeader | ty.Mapping | None = None, extra: ty.Mapping | None = None, file_map: FileMap | None = None)¶
Bases:
SpatialImage
AFNI Image file
Can be loaded from either the BRIK or HEAD file (but MUST specify one!)
Examples
>>> import nibabel as nib >>> brik = nib.load(os.path.join(datadir, 'example4d+orig.BRIK.gz')) >>> brik.shape (33, 41, 25, 3) >>> brik.affine array([[ -3. , -0. , -0. , 49.5 ], [ -0. , -3. , -0. , 82.312 ], [ 0. , 0. , 3. , -52.3511], [ 0. , 0. , 0. , 1. ]]) >>> head = load(os.path.join(datadir, 'example4d+orig.HEAD')) >>> np.array_equal(head.get_fdata(), brik.get_fdata()) True
Initialize image
The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.
- Parameters:
- dataobjobject
Object containing image data. It should be some object that returns an array from
np.asanyarray
. It should have ashape
attribute or property- affineNone or (4,4) array-like
homogeneous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case,
obj.affine
also returns None, and the affine as written to disk will depend on the file format.- headerNone or mapping or header instance, optional
metadata for this image format
- extraNone or mapping, optional
metadata to associate with image that cannot be stored in the metadata of this image type
- file_mapmapping, optional
mapping giving file information for this image format
- __init__(dataobj: ArrayLike, affine: np.ndarray | None, header: FileBasedHeader | ty.Mapping | None = None, extra: ty.Mapping | None = None, file_map: FileMap | None = None)¶
Initialize image
The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.
- Parameters:
- dataobjobject
Object containing image data. It should be some object that returns an array from
np.asanyarray
. It should have ashape
attribute or property- affineNone or (4,4) array-like
homogeneous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case,
obj.affine
also returns None, and the affine as written to disk will depend on the file format.- headerNone or mapping or header instance, optional
metadata for this image format
- extraNone or mapping, optional
metadata to associate with image that cannot be stored in the metadata of this image type
- file_mapmapping, optional
mapping giving file information for this image format
- ImageArrayProxy¶
alias of
AFNIArrayProxy
- classmethod filespec_to_file_map(filespec)¶
Make file_map from filename filespec
AFNI BRIK files can be compressed, but HEAD files cannot - see afni.nimh.nih.gov/pub/dist/doc/program_help/README.compression.html. Thus, if you have AFNI files my_image.HEAD and my_image.BRIK.gz and you want to load the AFNI BRIK / HEAD pair, you can specify:
The HEAD filename - e.g., my_image.HEAD
The BRIK filename w/o compressed extension - e.g., my_image.BRIK
The full BRIK filename - e.g., my_image.BRIK.gz
- Parameters:
- filespecstr
Filename that might be for this image file type.
- Returns:
- file_mapdict
dict with keys
image
andheader
where values are fileholder objects for the respective BRIK and HEAD files
- Raises:
- ImageFileError
If filespec is not recognizable as being a filename for this image type.
- classmethod from_file_map(file_map, *, mmap=True, keep_file_open=None)¶
Creates an AFNIImage instance from file_map
- Parameters:
- file_mapdict
dict with keys
image, header
and values being fileholder objects for the respective BRIK and HEAD files- mmap{True, False, ‘c’, ‘r’}, optional, keyword only
mmap controls the use of numpy memory mapping for reading image array data. If False, do not try numpy
memmap
for data array. If one of {‘c’, ‘r’}, try numpy memmap withmode=mmap
. A mmap value of True gives the same behavior asmmap='c'
. If image data file cannot be memory-mapped, ignore mmap value and read array from file.- keep_file_open{None, True, False}, optional, keyword only
keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this
ArrayProxy
. IfTrue
, a single file handle is created and used. IfFalse
, a new file handle is created every time the image is accessed. Iffile_like
refers to an open file handle, this setting has no effect. The default value (None
) will result in the value ofnibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT
being used.
- header_class¶
alias of
AFNIHeader
AFNIImageError
¶
- class nibabel.brikhead.AFNIImageError¶
Bases:
ImageDataError
Error when reading AFNI BRIK files
- __init__(*args, **kwargs)¶
parse_AFNI_header¶
- nibabel.brikhead.parse_AFNI_header(fobj)¶
Parses fobj to extract information from HEAD file
- Parameters:
- fobjfile-like object
AFNI HEAD file object or filename. If file object, should implement at least
read
- Returns:
- infodict
Dictionary containing AFNI-style key:value pairs from HEAD file
Examples
>>> fname = os.path.join(datadir, 'example4d+orig.HEAD') >>> info = parse_AFNI_header(fname) >>> print(info['BYTEORDER_STRING']) LSB_FIRST >>> print(info['BRICK_TYPES']) [1, 1, 1]