docs(quickstart): 🚧 Add first draft of tags exmaple.

docs/quickstart.rst

@@ -336,6 +336,109 @@ get all descriptors from a class using the ``.descriptors`` attribute.
 You'll see that our ``airmass`` descriptor is available for the
 ``GMOSScienceAstroData`` class, but not for the ``GMOSAstroData`` class.
 
+Tags
+====
+
+Tags are a way to categorize data in |astrodata|. They are meant to be
+used to identify the type of data in a file, and can be used to filter
+data when opening files.
+
+Tags are stored in the ``.tags`` attribute of an |AstroData| object. You
+can add tags to a class by using the ``@astro_data_tag`` decorator on methods
+that output tags. For example, we want to tag our ``GMOSScienceAstroData``
+class as ``'GMOS'`` and ``'SCIENCE'``:
+
+.. code-block:: python
+
+    class GMOSScienceAstroDataTagged(GMOSScienceAstroData):
+        """A class for GMOS science data with tags.
+
+        Note: This still has all the methods from GMOSScienceAstroData! It is a
+        subset of the tags used for the GMOS instrument |AstroData| class.
+        """
+
+        @astro_data_tag
+        def _tag_instrument(self):
+            # tags = ['GMOS', self.instrument().upper().replace('-', '_')]
+            return TagSet(["GMOS"])
+
+        @astro_data_tag
+        def _tag_dark(self):
+            if self.phu.get("OBSTYPE") == "DARK":
+                return TagSet(["DARK", "CAL"], blocks=["IMAGE", "SPECT"])
+
+        @astro_data_tag
+        def _tag_arc(self):
+            if self.phu.get("OBSTYPE") == "ARC":
+                return TagSet(["ARC", "CAL"])
+
+        def _tag_is_bias(self):
+            if self.phu.get("OBSTYPE") == "BIAS":
+                return True
+            else:
+                return False
+
+        def _tag_is_bpm(self):
+            if self.phu.get("OBSTYPE") == "BPM" or "BPMASK" in self.phu:
+                return True
+            else:
+                return False
+
+        @astro_data_tag
+        def _tag_bias(self):
+            if self._tag_is_bias():
+                return TagSet(["BIAS", "CAL"], blocks=["IMAGE", "SPECT"])
+
+        @astro_data_tag
+        def _tag_flat(self):
+            if self.phu.get("OBSTYPE") == "FLAT":
+                if self.phu.get("GRATING") == "MIRROR":
+                    f1, f2 = self.phu.get("FILTER1"), self.phu.get("FILTER2")
+                    # This kind of filter prevents imaging to be classified as FLAT
+                    if any(("Hartmann" in f) for f in (f1, f2)):
+                        return None
+                return TagSet(["GCALFLAT", "FLAT", "CAL"])
+
+        @astro_data_tag
+        def _tag_twilight(self):
+            if self.phu.get("OBJECT", "").upper() == "TWILIGHT":
+                # Twilight flats are of OBSTYPE == OBJECT, meaning that the generic
+                # FLAT tag won't be triggered. Add it explicitly.
+                return TagSet(
+                    [
+                        "TWILIGHT",
+                        "CAL",
+                        "SLITILLUM" if self._tag_is_spect() else "FLAT",
+                    ],
+                )
+
+        @astro_data_tag
+        def _tag_image_or_spect(self):
+            if self.phu.get('GRATING') == 'MIRROR':
+                return TagSet(['IMAGE'])
+            else:
+                return TagSet(['SPECT'])
+
+    factory.add_class(GMOSScienceAstroDataTagged)
+
+
+These tags were taken from the |DRAGONS| GMOS package, and exemplify some
+basic and more complex tag usage in |astrodata|. For example, the ``_tag_dark``
+method will tag the data as ``'DARK'`` and ``'CAL'`` if the ``OBSTYPE`` is
+``'DARK'``. The ``blocks`` argument is used to specify that the tags will
+"block" other tags from being applied to the data, in this case the ``'IMAGE'``
+and ``'SPECT'`` tags.
+
+Let's make new |AstroData| objects for our files and see what tags they have:
+
+.. code-block:: python
+
+    for f in files:
+        ad = astrodata.from_file(f'quickstart_data/{f}')
+        print(f"Opened {ad.filename} with class {ad.__class__}")
+        print(f"Tags: {ad.tags}")
+
+
 Advanced Usage
 ==============