Merge 5c2c2b6 into 848539e

CHANGES.rst

@@ -16,6 +16,9 @@ New Features
 - Added an option to disregard negative values passed to ``create_deviation``
   and assume the error is represented by the read noise [#688]
 
+- Add ``filter`` method to ``ImageFileCollection`` that creates a new
+  collection by filtering based on header keywords. [#596, #690]
+
 Other Changes and Additions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

ccdproc/image_collection.py

@@ -404,6 +404,35 @@ def sort(self, keys):
             self._summary.sort(keys)
             self._files = self.summary['file'].tolist()
 
+    def filter(self, **kwd):
+        """
+        Create a new collection by filtering the current collection.
+
+        Parameters
+        ----------
+
+        regex_match : bool, keyword-only
+            If ``True``, then string values in the ``**kwd`` dictionary are
+            treated as regular expression patterns and matching is done by
+            regular expression search. The search is always
+            **case insensitive**.
+
+        **kwd :
+            ``**kwd`` is dict of keywords and values the files must have.
+            The value '*' represents any value.
+            A missing keyword is indicated by value ''.
+
+        Returns
+        -------
+
+        `ImageFileCollection`
+            A new collection with the files matched by the arguments
+            to filter.
+        """
+        files = self.files_filtered(include_path=True, **kwd)
+        return ImageFileCollection(filenames=files,
+                                   keywords=self.keywords)
+
     def _get_files(self):
         """ Helper method which checks whether ``files`` should be set
         to a subset of file names or to all file names in a directory.

ccdproc/tests/test_image_collection.py

@@ -1072,3 +1072,17 @@ def test_generator_with_regex(self, triage_setup):
             n_light += 1
 
         assert n_light == triage_setup.n_test['light']
+
+    def test_make_collection_by_filtering(self, triage_setup):
+        # Test for implementation of feature at
+        #
+        #    https://github.com/astropy/ccdproc/issues/596
+        #
+        # which adds the ability to create a new collection by filtering
+        # an existing ImageFileCollection.
+
+        ic = ImageFileCollection(location=triage_setup.test_dir)
+        new_ic = ic.filter(imagetyp='light')
+        assert len(new_ic.summary) == triage_setup.n_test['light']
+        for header in new_ic.headers():
+            assert header['imagetyp'].lower() == 'light'

docs/image_management.rst

@@ -102,6 +102,13 @@ file name matching (or "globbing") at the command line. The
 `Python documentation on the re module <https://docs.python.org/3.7/library/re.html#module-re>`_
 is useful for learning about regular expressions.
 
+Finally, a new `~ccdproc.ImageFileCollection` can be created with by providing
+a list of keywords. The example below makes a new collection containing the
+files whose ``imagetyp`` is ``BIAS`` or ``LIGHT``::
+
+    >>> new_ic = ic1.filter(regex_match=True,
+    ...                     imagetyp='bias|light')
+
 Sorting files
 -------------