From 3bba90ca0b07134d830329284620421d6e4190e0 Mon Sep 17 00:00:00 2001
From: teald <teal.dillon@gmail.com>
Date: Thu, 15 Aug 2024 16:40:54 -0700
Subject: [PATCH] =?UTF-8?q?docs(quickstart):=20=F0=9F=9A=A7=20Add=20first?=
 =?UTF-8?q?=20draft=20of=20tags=20exmaple.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/quickstart.rst | 103 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 6de49ce1..17749d40 100644
--- a/docs/quickstart.rst
+++ b/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
 ==============