What's the difference between nib.save and nii.to_filename?

[fepegar]

If I do

import nibabel as nib
nii = nib.load('t1.nii')

Then

nib.save(nii, 'test.img')

works, but

nii.to_filename('test.img')

raises an error:

In [10]: nii.to_filename('test.img')
---------------------------------------------------------------------------
TypesFilenamesError                       Traceback (most recent call last)
/usr/local/Caskroom/miniconda/base/envs/torchio/lib/python3.8/site-packages/nibabel/filebasedimages.py in filespec_to_file_map(klass, filespec)
    298         try:
--> 299             filenames = types_filenames(
    300                 filespec, klass.files_types,

/usr/local/Caskroom/miniconda/base/envs/torchio/lib/python3.8/site-packages/nibabel/filename_parser.py in types_filenames(template_fname, types_exts, trailing_suffixes, enforce_extensions, match_case)
    128                 # an extension, but the wrong one
--> 129                 raise TypesFilenamesError(
    130                     'File extension "%s" was not in expected list: %s'

TypesFilenamesError: File extension ".img" was not in expected list: ['.nii']

During handling of the above exception, another exception occurred:

ImageFileError                            Traceback (most recent call last)
<ipython-input-10-f78e772a360c> in <module>
----> 1 nii.to_filename('test.img')

/usr/local/Caskroom/miniconda/base/envs/torchio/lib/python3.8/site-packages/nibabel/filebasedimages.py in to_filename(self, filename)
    331         None
    332         '''
--> 333         self.file_map = self.filespec_to_file_map(filename)
    334         self.to_file_map()
    335

/usr/local/Caskroom/miniconda/base/envs/torchio/lib/python3.8/site-packages/nibabel/filebasedimages.py in filespec_to_file_map(klass, filespec)
    301                 trailing_suffixes=klass._compressed_suffixes)
    302         except TypesFilenamesError:
--> 303             raise ImageFileError(
    304                 'Filespec "{0}" does not look right for class {1}'.format(
    305                     filespec, klass))

ImageFileError: Filespec "test.img" does not look right for class <class 'nibabel.nifti1.Nifti1Image'>

as pointed by @GFabien in TorchIO-project/torchio#266 (comment).

I always thought these two methods to be equivalent, as no difference is pointed out in the getting started docs.

Maybe related to #107.

[matthew-brett]

No - not related to #107. The problem here is that to_filename is a object method, and the object relates to a single-file NIfTI, which has file output of .nii or .nii.gz. The single-file NIfTI object doesn't know how to save files in other formats, including two-file NIfTI. In contrast, nib.save has the logic for converting the image into any chosen file type, as identified by the extension.

[fepegar]

I see, thanks. If nib.save does some implicit magic to convert the image, why doesn't to_filename do the same thing? Maybe this should be clearer in the docs, as they seem to be the same thing in the page I shared above. I'm happy to contribute.

[matthew-brett]

No magic only because the intention of the `to_filename` method is for the user to be able to force saving in a particular format. For example, `.img` could also be SPM format Analyze. The user can force this by using an SPMAnalyze object instead. Yes, it would be great to have some help with the documentation, if you have time.

[fepegar]

How can I help? A footnote in Getting started doesn't seem too getting-started-friendly.

[matthew-brett]

At a first pass, just removing `to_filename` from Getting started would be good - the method is a little advanced. Then maybe, if you are interested, a better error message ...