Add a 'sort' method to ImageFileCollection

CHANGES.rst

@@ -20,6 +20,8 @@ Bug Fixes
 New Features
 ^^^^^^^^^^^^
 
+- add a ``sort`` method to ImageFileCollection [#274]
+
 Other Changes and Additions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

ccdproc/image_collection.py

@@ -269,6 +269,21 @@ def refresh(self):
         self._files = self._fits_files_in_directory()
         self._summary_info = self._fits_summary(header_keywords=keywords)
 
+    def sort(self, keys=None):
+        """Sort the list of files to determine the order of iteration.
+
+        Sort the table of files according to one or more keys. This does not
+        create a new object, instead is sorts in place.
+
+        Parameters
+        ----------
+        keys : str or list of str
+            The key(s) to order the table by.
+        """
+        if len(self._summary_info) > 0:
+            self._summary_info.sort(keys)
+            self._files = list(self.summary_info['file'])
+
     def _dict_from_fits_header(self, file_name, input_summary=None,
                                missing_marker=None):
         """
@@ -540,6 +555,7 @@ def _fits_files_in_directory(self, extensions=None,
         for extension in full_extensions:
             files.extend(fnmatch.filter(all_files, '*' + extension))
 
+        files.sort()
         return files
 
     def _generator(self, return_type,

ccdproc/tests/test_image_collection.py

@@ -571,3 +571,20 @@ def test_keyword_order_is_preserved(self, triage_setup):
         ic = image_collection.ImageFileCollection(triage_setup.test_dir,
                                                   keywords=keywords)
         assert ic.keywords == ['file'] + keywords
+
+    def test_sorting(self, triage_setup):
+        collection = image_collection.ImageFileCollection(location=triage_setup.test_dir,
+                                             keywords=['imagetyp',
+                                                       'filter',
+                                                       'object'])
+
+        all_elements = []
+        for hdu, fname in collection.hdus(return_fname=True):
+            all_elements.append((str(hdu.header), fname))
+        # Now sort
+        collection.sort(keys=['filter', 'object'])
+        # and check it's all still right
+        for hdu, fname in collection.hdus(return_fname=True):
+            assert((str(hdu.header), fname) in all_elements)
+        for i in range(len(collection.summary)):
+            assert(collection.summary['file'][i] == collection.files[i])

docs/ccdproc/image_management.rst

@@ -62,6 +62,16 @@ seconds, there is a convenience method ``.files_filtered``::
 The optional arguments to ``files_filtered`` are used to filter the list of
 files.
 
+Sorting files
+-------------
+Sometimes it is useful to bring the files into a specific order, e.g. if you
+make a plot for each object you probably want all images of the same object
+next to each other. To do this, the images in a collection can be sorted with
+the ``sort`` method using the fits header keys in the same way you would sort a
+:class:`~astropy.table.Table`::
+
+    >>> ic1.sort(['object', 'filter'])
+
 Iterating over hdus, headers or data
 ------------------------------------