From 1c84f39e6f6a0a114fdb4b2beece16b898108b44 Mon Sep 17 00:00:00 2001
From: Pey Lian Lim <lim@stsci.edu>
Date: Tue, 30 May 2017 14:01:19 -0400
Subject: [PATCH] Expanded tutorials on zeropoints. Update astropy-helpers.

---
 .gitignore                   |  3 +-
 astropy_helpers              |  2 +-
 docs/stsynphot/tutorials.rst | 69 ++++++++++++++++++++++++++++++++----
 3 files changed, 65 insertions(+), 9 deletions(-)

diff --git a/.gitignore b/.gitignore
index 40229ad..76ede21 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,7 +19,8 @@ MANIFEST
 assets
 
 # Sphinx
-docs/api
+docs/api/
+docs/stsynphot/api/
 docs/_build
 
 # Eclipse editor project files
diff --git a/astropy_helpers b/astropy_helpers
index 3e044eb..70b09af 160000
--- a/astropy_helpers
+++ b/astropy_helpers
@@ -1 +1 @@
-Subproject commit 3e044eb26395c8569e3e15bf821c6ae5eeea324a
+Subproject commit 70b09af7e4f6b8a4e409412a913ff2adb05c12b7
diff --git a/docs/stsynphot/tutorials.rst b/docs/stsynphot/tutorials.rst
index 3d7af4c..14c1c59 100644
--- a/docs/stsynphot/tutorials.rst
+++ b/docs/stsynphot/tutorials.rst
@@ -51,17 +51,72 @@ STMAG zeropoint for the respective bandpass (e.g.,
 `WFC3 <http://www.stsci.edu/hst/wfc3/phot_zp_lbn>`_).
 
 In this tutorial, you will learn how to calculate the STMAG zeropoint for
-the ACS/WFC1 F555W bandpass::
+the ACS/WFC1 F555W bandpass, which happens to be time-dependent::
 
     >>> import numpy as np
     >>> import stsynphot as STS
-    >>> bp = STS.band('acs,wfc1,f555w')
-    >>> uresp = bp.unit_response(STS.conf.area)
-    >>> uresp
-    <Quantity 1.9712343504030155e-19 FLAM>
-    >>> st_zpt = -2.5 * np.log10(uresp.value) - 21.1
+    >>> from astropy.time import Time
+    >>> obsdate = Time('2017-05-30').mjd
+    >>> bp = STS.band('acs,wfc1,f555w,mjd#{}'.format(obsdate))
+    >>> photflam = bp.unit_response(STS.conf.area)
+    >>> photflam
+    <Quantity 1.9647813651514673e-19 FLAM>
+    >>> st_zpt = -2.5 * np.log10(photflam.value) - 21.1
     >>> print('STmag zeropoint for {} is {:.5f}'.format(bp.obsmode, st_zpt))
-    STmag zeropoint for acs,wfc1,f555w is 25.66315
+    STmag zeropoint for acs,wfc1,f555w,mjd#57903.0 is 25.66671
+
+
+.. _tutorial_band_abmag:
+
+Bandpass ABMAG Zeropoint
+------------------------
+
+For ABMAG zeropoint, it extends from :ref:`tutorial_band_stmag` by also using
+``PHOTPLAM`` keyword in image headers.
+
+In this tutorial, you will learn how to calculate the ABMAG zeropoint for
+the ACS/WFC1 F555W bandpass, which happens to be time-dependent::
+
+    >>> import numpy as np
+    >>> import stsynphot as STS
+    >>> from astropy.time import Time
+    >>> obsdate = Time('2017-05-30').mjd
+    >>> bp = STS.band('acs,wfc1,f555w,mjd#{}'.format(obsdate))
+    >>> photflam = bp.unit_response(STS.conf.area)
+    >>> photplam = bp.pivot()
+    >>> photplam
+    <Quantity 5360.938362432486 Angstrom>
+    >>> ab_zpt = (-2.5 * np.log10(photflam.value) - 21.1 -
+    ...           5 * np.log10(photplam.value) + 18.6921)
+    >>> print('ABmag zeropoint for {} is {:.5f}'.format(bp.obsmode, ab_zpt))
+    ABmag zeropoint for acs,wfc1,f555w,mjd#57903.0 is 25.71261
+
+
+.. _tutorial_band_vegamag:
+
+Bandpass VEGAMAG Zeropoint
+--------------------------
+
+In addition to :ref:`tutorial_band_stmag` and :ref:`tutorial_band_abmag`,
+HST bandpasses also provide zeropoints in ``VEGAMAG``, which is a magnitude
+system where Vega has magnitude 0 at all wavelengths. Note that this zeropoint
+strongly depends on the actual Vega spectrum used; Therefore, VEGAMAG zeropoint
+values for the same filter might vary in literature as the authors use their
+favorite Vega spectra.
+
+In this tutorial, you will learn how to calculate the VEGAMAG zeropoint for
+the ACS/WFC1 F555W bandpass, which happens to be time-dependent::
+
+    >>> import numpy as np
+    >>> import stsynphot as STS
+    >>> from astropy.time import Time
+    >>> from synphot import Observation
+    >>> obsdate = Time('2017-05-30').mjd
+    >>> bp = STS.band('acs,wfc1,f555w,mjd#{}'.format(obsdate))
+    >>> obs = Observation(STS.Vega, bp, binset=bp.binset)
+    >>> vega_zpt = -obs.effstim(flux_unit='obmag', area=STS.conf.area)
+    >>> print('VEGAMAG zeropoint for {} is {:.5f}'.format(bp.obsmode, vega_zpt))
+    VEGAMAG zeropoint for acs,wfc1,f555w,mjd#57903.0 is 25.71235 OBMAG
 
 
 .. _tutorial_wavetab: