Update docs (1st pass)

.travis.yml

@@ -106,6 +106,8 @@ matrix:
           env: PYTHON_VERSION=3.5 NUMPY_VERSION=1.11
         - os: linux
           env: NUMPY_VERSION=1.12
+        - os: linux
+          env: NUMPY_VERSION=1.13
 
         # Try numpy pre-release
         - os: linux
@@ -117,6 +119,14 @@ matrix:
           env: MAIN_CMD='pycodestyle dust_extinction --count' SETUP_CMD=''
 
     allow_failures:
+        - os: linux
+          env: ASTROPY_VERSION=development
+               EVENT_TYPE='pull_request push cron'
+
+        - os: linux
+          env: NUMPY_VERSION=prerelease
+               EVENT_TYPE='pull_request push cron'
+
         # Do a PEP8 test with pycodestyle
         # (allow to fail unless your code completely compliant)
         - os: linux

docs/conf.py

@@ -105,8 +105,8 @@
 
 # Please update these texts to match the name of your package.
 html_theme_options = {
-    'logotext1': 'package',  # white,  semi-bold
-    'logotext2': '-template',  # orange, light
+    'logotext1': 'dust_',  # white,  semi-bold
+    'logotext2': 'extinction',  # orange, light
     'logotext3': ':docs'   # white,  light
     }
 
@@ -131,6 +131,10 @@
 # pixels large.
 #html_favicon = ''
 
+#  example from imexam
+#from os.path import join
+#html_favicon = join('_static', 'imexam.ico')
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = ''
@@ -142,6 +146,13 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = project + 'doc'
 
+# more examples from imexam
+#html_logo = '_static/imexam_logo_trans.png'
+
+# Static files to copy after template files
+#html_static_path = ['_static']
+#html_style = 'imexam.css'
+
 
 # -- Options for LaTeX output -------------------------------------------------
 

docs/dust_extinction/extinguish.rst

@@ -0,0 +1,66 @@
+###############################
+Extinguish or Unextinguish Data
+###############################
+
+Two of the three flavors of models include a function to calculate the 
+factor to multiple (extinguish) or divide (unextinguish) a spectrum by
+to add or remove the effects of dust, respectively.  
+
+Extinguish is also often called reddening.  Extinguishing a spectrum often
+reddens the flux, but not always (e.g, on the short wavelength side of the 
+2175 A bump.  So extinguish is the more generic term.
+
+Example: Extinguish a Blackbody
+===============================
+
+.. plot::
+   :include-source:
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+
+   import astropy.units as u
+   from astropy.modeling.blackbody import blackbody_lambda
+
+   from dust_extinction.dust_extinction import CCM89
+
+   # generate wavelengths between 0.1 and 3 microns
+   #    within the valid range for the CCM89 R(V) dependent relationship
+   lam = np.logspace(np.log10(0.1), np.log10(3.0), num=1000)
+
+   # setup the inputs for the blackbody function
+   wavelengths = lam*1e4*u.AA
+   temperature = 10000*u.K
+
+   # get the blackbody flux
+   flux = blackbody_lambda(wavelengths, temperature)
+
+   # initialize the model
+   ext = CCM89(Rv=3.1)
+
+   # get the extinguished blackbody flux for different amounts of dust
+   flux_ext_av05 = flux*ext.extinguish(wavelengths, Av=0.5)
+   flux_ext_av15 = flux*ext.extinguish(wavelengths, Av=1.5)
+   flux_ext_ebv10 = flux*ext.extinguish(wavelengths, Ebv=1.0)
+
+   # plot the intrinsic and extinguished fluxes
+   fig, ax = plt.subplots()
+
+   ax.plot(wavelengths, flux, label='Intrinsic')
+   ax.plot(wavelengths, flux_ext_av05, label='$A(V) = 0.5$')
+   ax.plot(wavelengths, flux_ext_av15, label='$A(V) = 1.5$')
+   ax.plot(wavelengths, flux_ext_ebv10, label='$E(B-V) = 1.0$')
+
+   ax.set_xlabel('$\lambda$ [$\AA$]')
+   ax.set_ylabel('$Flux$')
+
+   ax.set_xscale('log')
+   ax.set_yscale('log')
+
+   ax.set_title('Example extinguishing a blackbody')
+
+   ax.legend(loc='best')
+   plt.tight_layout()
+   plt.show()
+
+

docs/dust_extinction/fit_extinction.rst

@@ -0,0 +1,122 @@
+#####################
+Fit Extinction Curves
+#####################
+
+The ``dust_extinction`` package is built on the `astropy.modeling
+<http://docs.astropy.org/en/stable/modeling/>`_ package.  Fitting is
+done in the standard way for this package where the model is initialized
+with a starting point (either the default or user input), the fitter
+is choosen, and the fit performed.  
+
+Example: FM90 Fit
+=================
+
+In this example, the FM90 model is used to fit the observed average
+extinction curve for the LMC outside of the LMC2 supershell region 
+(G03_LMCAvg ``dust_extinction`` model). 
+
+.. plot::
+   :include-source:
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+
+   from astropy.modeling.fitting import LevMarLSQFitter
+
+   from dust_extinction.dust_extinction import G03_LMCAvg, FM90
+
+   # get an observed extinction curve to fit
+   g03_model = G03_LMCAvg()
+
+   x = g03_model.obsdata_x
+   # convert to E(x-V)/E(B0V)
+   y = (g03_model.obsdata_axav - 1.0)*g03_model.Rv
+   # only fit the UV portion (FM90 only valid in UV)
+   gindxs, = np.where(x > 3.125)
+
+   # initialize the model
+   fm90_init = FM90()
+
+   # pick the fitter
+   fit = LevMarLSQFitter()
+
+   # fit the data to the FM90 model using the fitter
+   #   use the initialized model as the starting point
+   g03_fit = fit(fm90_init, x[gindxs], y[gindxs])
+
+   # plot the observed data, initial guess, and final fit
+   fig, ax = plt.subplots()
+
+   ax.plot(x, y, 'ko', label='Observed Curve')
+   ax.plot(x[gindxs], fm90_init(x[gindxs]), label='Initial guess')
+   ax.plot(x[gindxs], g03_fit(x[gindxs]), label='Fitted model')
+
+   ax.set_xlabel('$x$ [$\mu m^{-1}$]')
+   ax.set_ylabel('$E(x-V)/E(B-V)$')
+
+   ax.set_title('Example FM90 Fit to G03_LMCAvg curve')
+
+   ax.legend(loc='best')
+   plt.tight_layout()
+   plt.show()
+
+Example: P92 Fit
+================
+
+In this example, the P92 model is used to fit the observed average
+extinction curve for the MW as tabulted by Pei (1992). 
+
+.. plot::
+   :include-source:
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+
+   from astropy.modeling.fitting import LevMarLSQFitter
+
+   from dust_extinction.dust_extinction import P92
+
+   # Milky Way observed extinction as tabulated by Pei (1992)
+   MW_x = [0.21, 0.29, 0.45, 0.61, 0.80, 1.11, 1.43, 1.82,
+           2.27, 2.50, 2.91, 3.65, 4.00, 4.17, 4.35, 4.57, 4.76,
+           5.00, 5.26, 5.56, 5.88, 6.25, 6.71, 7.18, 7.60,
+           8.00, 8.50, 9.00, 9.50, 10.00]
+   MW_x = np.array(MW_x)
+   MW_exvebv = [-3.02, -2.91, -2.76, -2.58, -2.23, -1.60, -0.78, 0.00,
+                1.00, 1.30, 1.80, 3.10, 4.19, 4.90, 5.77, 6.57, 6.23,
+                5.52, 4.90, 4.65, 4.60, 4.73, 4.99, 5.36, 5.91, 
+                6.55, 7.45, 8.45, 9.80, 11.30]
+   MW_exvebv = np.array(MW_exvebv)
+   Rv = 3.08
+   MW_axav = MW_exvebv/Rv + 1.0
+
+   # get an observed extinction curve to fit
+   x = MW_x   
+   y = MW_axav
+
+   # initialize the model
+   p92_init = P92()
+
+   # pick the fitter
+   fit = LevMarLSQFitter()
+
+   # fit the data to the P92 model using the fitter
+   #   use the initialized model as the starting point
+   #   accuracy set to avoid warning the fit may have failed
+   p92_fit = fit(p92_init, x, y, acc=1e-3)
+
+   # plot the observed data, initial guess, and final fit
+   fig, ax = plt.subplots()
+
+   ax.plot(x, y, 'ko', label='Observed Curve')
+   ax.plot(x, p92_init(x), label='Initial guess')
+   ax.plot(x, p92_fit(x), label='Fitted model')
+
+   ax.set_xlabel('$x$ [$\mu m^{-1}$]')
+   ax.set_ylabel('$A(x)/A(V)$')
+
+   ax.set_title('Example P92 Fit to MW average curve')
+
+   ax.legend(loc='best')
+   plt.tight_layout()
+   plt.show()