Checking shape of CIFTI2 images

[MichielCottaar]

At present there is no checking of whether the shape of the data array is consistent with the CIFTI2 header. In the example below, I expect two numbers (A and B) for each of my three vertices on the left cortex, so a (2, 3)-shaped array. However, nibabel will happily accept the (7,4)-shaped array provided here. Similarly, when reading the CIFTI file no errors or warnings are raised.

from nibabel import cifti2
import numpy as np
data = np.random.rand(7, 4)
bm = cifti2.BrainModelAxis.from_mask([True, True, True], name='left_cortex')
sc = cifti2.ScalarAxis(['A', 'B'])
img = cifti2.Cifti2Image(data, header=(sc, bm))
img.to_filename('test.dscalar.nii')

I'm happy to implement some code to compare the shape of the array with that implied by the header, but I'm not sure what would be the best time to make this check and whether it should be a warning or an error. The options are:

1. warning or error when creating the Cifti2Image itself
2. warning or error when writing the Cifti2Image
3. warning or error when reading the Cifti2Image

Any suggestions on where to plug this test and whether to make it a warning or an error? We can't simply adjust the header shape to match the data as this would involve creating new labels for the rows or columns and hence would lead to very confusing behaviour.

[effigies]

My personal inclination is to be strict on write, forgiving on read, which allows users to use nibabel to fix bad files while hopefully avoiding polluting the ecosystem with bad CIFTI-2 files that others have to deal with.

Do you know what the HCP folks do with inconsistencies?

We do also have a notion of consistency/validity checks that seem reasonable to extend for cases like this:

nibabel/nibabel/nifti1.py

Lines 1656 to 1744 in 0282bb9

	@classmethod
	def _get_checks(klass):
	# We need to return our own versions of - e.g. chk_datatype, to
	# pick up the Nifti datatypes from our class
	return (klass._chk_sizeof_hdr,
	klass._chk_datatype,
	klass._chk_bitpix,
	klass._chk_pixdims,
	klass._chk_qfac,
	klass._chk_magic,
	klass._chk_offset,
	klass._chk_qform_code,
	klass._chk_sform_code)
	@staticmethod
	def _chk_qfac(hdr, fix=False):
	rep = Report(HeaderDataError)
	if hdr['pixdim'][0] in (-1, 1):
	return hdr, rep
	rep.problem_level = 20
	rep.problem_msg = 'pixdim[0] (qfac) should be 1 (default) or -1'
	if fix:
	hdr['pixdim'][0] = 1
	rep.fix_msg = 'setting qfac to 1'
	return hdr, rep
	@staticmethod
	def _chk_magic(hdr, fix=False):
	rep = Report(HeaderDataError)
	magic = hdr['magic'].item()
	if magic in (hdr.pair_magic, hdr.single_magic):
	return hdr, rep
	rep.problem_msg = ('magic string "%s" is not valid' %
	asstr(magic))
	rep.problem_level = 45
	if fix:
	rep.fix_msg = 'leaving as is, but future errors are likely'
	return hdr, rep
	@staticmethod
	def _chk_offset(hdr, fix=False):
	rep = Report(HeaderDataError)
	# for ease of later string formatting, use scalar of byte string
	magic = hdr['magic'].item()
	offset = hdr['vox_offset'].item()
	if offset == 0:
	return hdr, rep
	if magic == hdr.single_magic and offset < hdr.single_vox_offset:
	rep.problem_level = 40
	rep.problem_msg = ('vox offset %d too low for '
	'single file nifti1' % offset)
	if fix:
	hdr['vox_offset'] = hdr.single_vox_offset
	rep.fix_msg = 'setting to minimum value of {0}'.format(
	hdr.single_vox_offset)
	return hdr, rep
	if not offset % 16:
	return hdr, rep
	# SPM uses memory mapping to read the data, and
	# apparently this has to start on 16 byte boundaries
	rep.problem_msg = ('vox offset (={0:g}) not divisible '
	'by 16, not SPM compatible'.format(offset))
	rep.problem_level = 30
	if fix:
	rep.fix_msg = 'leaving at current value'
	return hdr, rep
	@classmethod
	def _chk_qform_code(klass, hdr, fix=False):
	return klass._chk_xform_code('qform_code', hdr, fix)
	@classmethod
	def _chk_sform_code(klass, hdr, fix=False):
	return klass._chk_xform_code('sform_code', hdr, fix)
	@classmethod
	def _chk_xform_code(klass, code_type, hdr, fix):
	# utility method for sform and qform codes
	rep = Report(HeaderDataError)
	code = int(hdr[code_type])
	recoder = klass._field_recoders[code_type]
	if code in recoder.value_set():
	return hdr, rep
	rep.problem_level = 30
	rep.problem_msg = '%s %d not valid' % (code_type, code)
	if fix:
	hdr[code_type] = 0
	rep.fix_msg = 'setting to 0'
	return hdr, rep

If that doesn't fit, I've also been thinking about adding a ConsistencyWarning for other situations (#624) where we have a strictly legal but questionably valid file.

[MichielCottaar]

Thanks, that makes sense. I'll put something together soon. The HCP workbench viewer simply raises an error when the header file does not match (which is how I realized that I was writing CIFTI files with the wrong shape). I have not tested their command line tools, but I would expect the same behavior.