Merge pull request #446 from NASA-Planetary-Science/445-docs-add-example-color-of-reddened-source

Example in documentation showing color computation for a reddened source

Author: hhsieh00

docs/sbpy/spectroscopy/index.rst

@@ -140,6 +140,41 @@ The following example reddens a solar spectrum:
       ylabel='Flux density ({})'.format(fluxd_unit))
   plt.tight_layout()
 
+Conversion to Photometry
+------------------------
+
+Magnitudes using specified filters of a reddened object, which can then be
+used to compute equivalent broadband colors for an object with the specified
+spectral gradient, can be computed using the ``bandpass`` function from the
+`~sbpy.photometry` module.  The following example computes the LSST g-r
+color of an object with a spectral gradient of 18%/100 nm (normalized to 550 nm).
+
+First, create a reddened source (e.g., a comet).  Then, specify the bandpasses
+to be used for the desired color calculation (in this example, LSST g and r),
+and calculate the specified color of the comet, where the list of available
+bandpasses and their sources may be found in the `~sbpy.photometry.bandpass`
+documentation.  Alternatively, any other filter bandpass can also be provided
+as a `~synphot.spectrum.SpectralElement` object and used instead:
+
+.. doctest-requires:: synphot
+.. doctest-remote-data:: 
+
+  >>> import astropy.units as u
+  >>> from sbpy.calib import Sun
+  >>> from sbpy.spectroscopy import SpectralGradient
+  >>> from sbpy.photometry import bandpass
+  >>> import sbpy.units as sbu
+  >>>
+  >>> S = SpectralGradient(18 * u.percent / sbu.hundred_nm, wave0=550 * u.nm)
+  >>> sun = Sun.from_builtin("calspec")
+  >>> comet = sun.redden(S)
+  >>>
+  >>> bp_g = bandpass("LSST g")
+  >>> bp_r = bandpass("LSST r")
+  >>> _, r = comet.observe_bandpass(bp_r, unit=u.ABmag)
+  >>> _, g = comet.observe_bandpass(bp_g, unit=u.ABmag)
+  >>> print("g-r =", g - r)
+  g-r = 0.7007308548908533 mag
 
 Reference/API
 -------------