Renamed from_filespec to from_filename for consistency; move methods into base class

Author: matthew-brett

doc/examples.txt

@@ -115,7 +115,7 @@ preserving as much header information as possible
   [ 4 32 32 16 10  1  1  1]
   >>> # a filename in our temporary directory
   >>> fname = pjoin(tmpdir, 'part.hdr.gz')
-  >>> nim2.to_filespec(fname)
+  >>> nim2.to_filename(fname)
 
 The :class:`~nifti.image.NiftiImage` constructor takes a dictionary with header
 information as an optional argument. Settings that are not determined by the

nibabel/analyze.py

@@ -19,7 +19,8 @@
 therefore must know how to predict image filenames from header
 filenames, whether these are different, and so on.
 
-You can access and set fields of a particular header type using standard __getitem__ / __setitem__ syntax:
+You can access and set fields of a particular header type using standard
+__getitem__ / __setitem__ syntax:
 
     hdr['field'] = 10
 
@@ -1136,11 +1137,6 @@ def get_data_dtype(self):
     def set_data_dtype(self, dtype):
         self._header.set_data_dtype(dtype)
 
-    @classmethod
-    def from_filespec(klass, filespec):
-        files = klass.filespec_to_files(filespec)
-        return klass.from_files(files)
-    
     @classmethod
     def from_files(klass, files):
         fname = files['header']
@@ -1150,14 +1146,6 @@ def from_files(klass, files):
         ret._files = files
         return ret
 
-    @classmethod
-    def from_image(klass, img):
-        orig_hdr = img.get_header()
-        return klass(img.get_data(),
-                     img.get_affine(),
-                     img.get_header(),
-                     img.extra)
-    
     @staticmethod
     def filespec_to_files(filespec):
         ftups = filetuples.FileTuples(
@@ -1171,29 +1159,6 @@ def filespec_to_files(filespec):
         files = dict(zip(('header', 'image'), ftups.get_filenames()))
         return files
 
-    def to_filespec(self, filename):
-        warnings.warn('``to_filespec`` is deprecated, please '
-                      'use ``to_filename`` instead',
-                      DeprecationWarning)
-        self.to_filename(filename)
-
-    def to_filename(self, filename):
-        ''' Write image to files implied by filename string
-
-        Paraameters
-        -----------
-        filename : str
-           filename to which to save image.  We will parse `filename`
-           with ``filespec_to_files`` to work out names for image,
-           header etc.
-
-        Returns
-        -------
-        None
-        '''
-        files = self.filespec_to_files(filename)
-        self.to_files(files)
-
     def to_files(self, files=None):
         ''' Write image to files passed, or self._files
         '''
@@ -1251,23 +1216,6 @@ def _update_header(self):
             RZS = self._affine[:3,:3]
             vox = np.sqrt(np.sum(RZS * RZS, axis=0))
             hdr['pixdim'][1:4] = vox
-        
-    @classmethod
-    def load(klass, filespec):
-        return klass.from_filespec(filespec)
-
-    @classmethod
-    def save(klass, img, filename):
-        warnings.warn('``save`` class method is deprecated\n'
-                      'You probably want the ``to_filename`` instance '
-                      'method, or the module-level ``save`` function',
-                      DeprecationWarning)
-        klass.instance_to_filename(img, filename)
-
-    @classmethod
-    def instance_to_filename(klass, img, filename):
-        img = klass.from_image(img)
-        img.to_filename(filename)
 
 
 load = AnalyzeImage.load

nibabel/minc.py

@@ -255,11 +255,6 @@ def get_shape(self):
     def get_data_dtype(self):
         return self._header.get_data_dtype()
 
-    @classmethod
-    def from_filespec(klass, filespec):
-        files = klass.filespec_to_files(filespec)
-        return klass.from_files(files)
-    
     @classmethod
     def from_files(klass, files):
         fname = files['image']
@@ -269,20 +264,9 @@ def from_files(klass, files):
         ret._files = files
         return ret
 
-    @classmethod
-    def from_image(klass, img):
-        return klass(img.get_data(),
-                     img.get_affine(),
-                     img.get_header(),
-                     img.extra)
-    
     @staticmethod
     def filespec_to_files(filespec):
         return {'image':filespec}
 
-    @classmethod
-    def load(klass, filespec):
-        return klass.from_filespec(filespec)
-
 
 load = MincImage.load

nibabel/spatialimages.py

@@ -19,7 +19,14 @@
    * .set_shape(shape)
    * .to_filename(fname) - writes data to filename(s) derived from
      ``fname``, where the derivation may differ between formats.
-   * 
+   * to_files() - save image to files with which the image is already
+     associated.  Or ``img.to_files(files)`` saves to the files passed.
+
+classmethods:
+
+   * from_filename(fname) - make instance by loading from filename
+   * instance_to_filename(img, fname) - save ``img`` instance to
+     filename ``fname``.
 
 There are several ways of writing data.
 =======================================
@@ -32,6 +39,19 @@
 the datatype the header expects, setting any available header scaling
 into the header to help the data match.
 
+You can load the data into an image from file with::
+
+   img.from_filename(fname)
+
+The image stores its associated files in a rather secretive way.  In
+order to just save an image, for which you know there is an associated
+filename, or other storage, you can do::
+
+   img.to_files()
+
+alternatively, you can pass in the needed files yourself, into this
+method, as an argument.
+
 You can get the data out again with of::
 
     img.get_data(fileobj)
@@ -41,6 +61,9 @@
 
     unscaled_data = img.get_unscaled_data()
 
+Analyze-type images (including nifti) support this, but others may not
+(MINC, for example).
+
 Sometimes you might to avoid any loss of precision by making the
 data type the same as the input::
 
@@ -50,9 +73,12 @@
 
 '''
 
+import warnings
+
+
 class SpatialImage(object):
     _header_maker = dict
-    ''' Template class for lightweight image '''
+    ''' Template class for images '''
     def __init__(self, data, affine, header=None, extra=None):
         if extra is None:
             extra = {}
@@ -108,8 +134,17 @@ def _set_header(self, header=None):
                 self.extra[key] = value
 
     @classmethod
-    def from_filespec(klass, filespec):
-        raise NotImplementedError
+    def from_filename(klass, filename):
+        files = klass.filespec_to_files(filename)
+        return klass.from_files(files)
+    
+    @classmethod
+    def from_filespec(klass, img, filespec):
+        warnings.warn('``from_filespec`` class method is deprecated\n'
+                      'Please use the ``from_filename`` class method '
+                      'instead',
+                      DeprecationWarning)
+        klass.from_filespec(filespec)
 
     def from_files(klass, files):
         raise NotImplementedError
@@ -121,8 +156,82 @@ def from_image(klass, img):
     def filespec_to_files(filespec):
         raise NotImplementedError
 
-    def to_filespec(self, filespec):
-        raise NotImplementedError
+    def to_filename(self, filename):
+        ''' Write image to files implied by filename string
+
+        Paraameters
+        -----------
+        filename : str
+           filename to which to save image.  We will parse `filename`
+           with ``filespec_to_files`` to work out names for image,
+           header etc.
+
+        Returns
+        -------
+        None
+        '''
+        files = self.filespec_to_files(filename)
+        self.to_files(files)
+
+    def to_filespec(self, filename):
+        warnings.warn('``to_filespec`` is deprecated, please '
+                      'use ``to_filename`` instead',
+                      DeprecationWarning)
+        self.to_filename(filename)
 
     def to_files(self, files=None):
         raise NotImplementedError
+
+    @classmethod
+    def load(klass, filename):
+        return klass.from_filename(filename)
+
+    @classmethod
+    def save(klass, img, filename):
+        warnings.warn('``save`` class method is deprecated\n'
+                      'You probably want the ``to_filename`` instance '
+                      'method, or the module-level ``save`` function',
+                      DeprecationWarning)
+        klass.instance_to_filename(img, filename)
+
+    @classmethod
+    def instance_to_filename(klass, img, filename):
+        ''' Save `img` in our own format, to name implied by `filename`
+
+        This is a class method
+
+        Parameters
+        ----------
+        img : ``spatialimage`` instance
+           In fact, an object with the API of ``spatialimage`` -
+           specifically ``get_data``, ``get_affine``, ``get_header`` and
+           ``extra``.
+        filename : str
+           Filename, implying name to which to save image.
+        '''
+        img = klass.from_image(img)
+        img.to_filename(filename)
+        
+    @classmethod
+    def from_image(klass, img):
+        ''' Create new instance of own class from `img`
+
+        This is a class method
+        
+        Parameters
+        ----------
+        img : ``spatialimage`` instance
+           In fact, an object with the API of ``spatialimage`` -
+           specifically ``get_data``, ``get_affine``, ``get_header`` and
+           ``extra``.
+
+        Returns
+        -------
+        cimg : ``spatialimage`` instance
+           Image, of our own class
+        '''
+        return klass(img.get_data(),
+                     img.get_affine(),
+                     img.get_header(),
+                     img.extra)
+    

nibabel/spm99analyze.py

@@ -214,8 +214,8 @@ def _chk_origin(hdr, fix=True):
 class Spm99AnalyzeImage(analyze.AnalyzeImage):
     _header_maker = Spm99AnalyzeHeader
     @classmethod
-    def from_filespec(klass, filespec):
-        ret = super(Spm99AnalyzeImage, klass).from_filespec(filespec)
+    def from_filename(klass, filename):
+        ret = super(Spm99AnalyzeImage, klass).from_filename(filename)
         import scipy.io as sio
         matf = ret._files['mat']
         try: