`cifti2.cifti2_axes.BrainModelAxis.iter_structures` function behavior differs from documentation

[sguthrie]

The documentation of iter_structures indicates that it yields a (string, slice, BrainModel) tuple; however, the actual behavior returns a (string, slice, slice) object.

[effigies]

Could you provide a minimal reproducible example?

[sguthrie]

Of course!

The relevant code (iter_structures definition) is at

nibabel/nibabel/cifti2/cifti2_axes.py

Lines 473 to 483 in 132ded6

	def iter_structures(self):
	"""
	Iterates over all brain structures in the order that they appear along the axis
	Yields
	------
	tuple with 3 elements:
	- CIFTI-2 brain structure name
	- slice to select the data associated with the brain structure from the tensor
	- brain model covering that specific brain structure
	"""

import nibabel as nib
import os
import urllib.request

from zipfile import ZipFile


# Download example cifti file from NITRC
ex_cifti_zip_filename = 'cifti_2_test_data_1.2.zip'
ex_cifti_file = os.path.join('cifti-2_test_data', 'Conte69.MyelinAndCorrThickness.32k_fs_LR.dscalar.nii')
s = urllib.request.urlretrieve('https://www.nitrc.org/frs/download.php/8541/cifti-2_test_data-1.2.zip',
                               ex_cifti_zip_filename)
# Extract example cifti file from zip file
with ZipFile(ex_cifti_zip_filename) as z_obj:
    z_obj.extract(ex_cifti_file)

# Load image
img = nib.load(ex_cifti_file)
# Check that brain model is the correct type (https://github.com/nipy/nibabel/blob/132ded6fa7576207648bd7d88fd8fea0f0866511/nibabel/cifti2/cifti2_axes.py#L473)

for name, data_slice, brain_model in img.header.get_axis(1).iter_structures():
    assert type(brain_model) == nib.cifti2.cifti2.Cifti2BrainModel, f'Type {type(brain_model)} is not a CiftiBrainModel'

Running this snippet results in the following error:

---------------------------------------------------------------------------
AssertionError                            Traceback (most recent call last)
Cell In[12], line 22
     19 # Check that brain model is the correct type (https://github.com/nipy/nibabel/blob/132ded6fa7576207648bd7d88fd8fea0f0866511/nibabel/cifti2/cifti2_axes.py#L473)
     21 for name, data_slice, brain_model in img.header.get_axis(1).iter_structures():
---> 22     assert type(brain_model) == nib.cifti2.cifti2.Cifti2BrainModel, f'Type {type(brain_model)} is not a CiftiBrainModel'

AssertionError: Type <class 'nibabel.cifti2.cifti2_axes.BrainModelAxis'> is not a CiftiBrainModel

[effigies]

AssertionError: Type <class 'nibabel.cifti2.cifti2_axes.BrainModelAxis'> is not a CiftiBrainModel

Cifti2BrainModel is a faithful rendering of the XML node, while the BrainModelAxis is the Pythonic interface. Use one or the other, not both.

https://nipy.org/nibabel/reference/nibabel.cifti2.html#module-nibabel.cifti2.cifti2_axes

[sguthrie]

It would be helpful to update the docstring to avoid confusion, if that's possible!