add R_V plots to docs

docs/conf.py

@@ -5,8 +5,12 @@
 import sys
 import os
 import sphinx_rtd_theme
+import matplotlib.sphinxext.plot_directive
 import extinction
 
+# ensure that plot helper is on the path
+sys.path.insert(0, os.path.abspath(__file__))
+
 # generate api directory if it doesn't already exist
 if not os.path.exists('api'):
     os.mkdir('api')
@@ -22,7 +26,8 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
-    'numpydoc']
+    'numpydoc',
+    matplotlib.sphinxext.plot_directive.__name__]
 
 numpydoc_show_class_members = False
 autosummary_generate = True
@@ -72,7 +77,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'extinctiondoc'

docs/extinction_plot.py

@@ -0,0 +1,52 @@
+"""Plot extinction functions for comparison"""
+
+from collections import OrderedDict
+
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib import rcParams
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+
+import extinction
+
+rcParams['font.family'] = 'serif'
+
+
+def extinction_figure(wave, a_lambda, residual_from, residual_lims=(-0.1, 0.4), title_text='$R_V = 3.1$'):
+
+    names = list(a_lambda.keys())  # consistent ordering between panels
+    fig = plt.figure(figsize=(8.5, 6.))
+
+    ax = plt.axes()
+    for name in names:
+        plt.plot(wave, a_lambda[name], label=name)
+    plt.axvline(x=2700., ls=':', c='k')
+    plt.axvline(x=3030.3030, ls=':', c='k')
+    plt.axvline(x=9090.9091, ls=':', c='k')
+    plt.axvspan(wave[0], 1150., fc='0.8', ec='none', zorder=-1000)
+    plt.axvspan(1150., 1250., fc='0.9', ec='none', zorder=-1000)    
+    plt.text(0.65, 0.95, title_text, transform=ax.transAxes, va='top',
+             ha='right', size='x-large')
+    plt.ylabel('Extinction ($A(\lambda)$ / $A_V$)')
+    plt.legend()
+    plt.setp(ax.get_xticklabels(), visible=False)
+
+    divider = make_axes_locatable(ax)
+    axresid = divider.append_axes("bottom", size=2.0, pad=0.2, sharex=ax)
+    for name in names:
+        plt.plot(wave, a_lambda[name] - a_lambda[residual_from])
+    plt.axvline(x=2700., ls=':', c='k')
+    plt.axvline(x=3030.3030, ls=':', c='k')
+    plt.axvline(x=9090.9091, ls=':', c='k')
+    plt.axvspan(wave[0], 1150., fc='0.8', ec='none', zorder=-1000)
+    plt.axvspan(1150., 1250., fc='0.9', ec='none', zorder=-1000)
+    plt.xlim(wave[0], wave[-1])
+    plt.ylim(ymin=residual_lims[0], ymax=residual_lims[1])
+    plt.ylabel('residual from ' + residual_from)
+    plt.xlabel(r'Wavelength ($\mathrm{\AA}$)')
+
+    ax.set_xscale('log')
+    axresid.set_xscale('log')
+    plt.tight_layout()
+
+    return fig

docs/index.rst

@@ -9,9 +9,15 @@ found in the literature.
 Installation
 ------------
 
-Extinction depends on numpy and scipy. Install these dependencies and then::
+Using conda::
 
-    pip install --no-deps extinction
+    conda install -c conda-forge extinction
+
+Using pip (requires a C compiler)::
+
+    pip install extinction
+
+Extinction depends on numpy and scipy.
 
 **Development version / source code:** http://github.com/kbarbary/extinction
 
@@ -98,22 +104,109 @@ To "redden" or "deredden" flux values by some amount, use the
   >>> apply(ccm89(wave, -1.0, 3.1), flux)
   array([ 13.70915145,   3.85320647,   1.73378645])
 
-**Comparison of functions**
 
-.. image:: _static/extinction.png
+
+Comparison of functions
+.......................
+
+.. plot::
+
+   import numpy as np
+   import extinction
+   from extinction_plot import extinction_figure
 
-**Parameterization**
+   wave = np.logspace(np.log10(910.), np.log10(30000.), 2000)
+
+   a_lambda = {'ccm89': extinction.ccm89(wave, 1.0, 3.1),
+               'odonnell94': extinction.odonnell94(wave, 1.0, 3.1),
+               'fitzpatrick99': extinction.fitzpatrick99(wave, 1.0),
+               'fm07': extinction.fm07(wave, 1.0)}
+   extinction_figure(wave, a_lambda, 'fitzpatrick99')
 
-The shape of most of the extinction laws here are parameterized by an
-:math:`R_V` parameter, which is defined by :math:`A_V = R_V E(B-V)`,
-where :math:`A_V` is the extinction in the *V* band, and
-:math:`E(B-V)` is the difference in extinction between the *B* and *V*
-bands.
+
+R_V dependence of odonnell94
+............................
+
+.. plot::
+
+   from collections import OrderedDict
+   import numpy as np
+   import extinction
+   from extinction_plot import extinction_figure
+
+   wave = np.logspace(np.log10(910.), np.log10(30000.), 2000)
+
+   a_lambda = OrderedDict([
+       ('$R_V$ = 2.1', extinction.odonnell94(wave, 1.0, 2.1)),
+       ('$R_V$ = 2.6', extinction.odonnell94(wave, 1.0, 2.6)),
+       ('$R_V$ = 3.1', extinction.odonnell94(wave, 1.0, 3.1)),
+       ('$R_V$ = 3.6', extinction.odonnell94(wave, 1.0, 3.6)),
+       ('$R_V$ = 4.1', extinction.odonnell94(wave, 1.0, 4.1))
+       ])
+   extinction_figure(wave, a_lambda, '$R_V$ = 3.1',
+                     residual_lims=(-0.2, 0.6),
+                     title_text='odonnell94')
+
+
+
+R_V dependence of Fitzpatrick99
+...............................
+.. plot::
+
+   from collections import OrderedDict
+   import numpy as np
+   import extinction
+   from extinction_plot import extinction_figure
+
+   wave = np.logspace(np.log10(910.), np.log10(30000.), 2000)
+
+   a_lambda = OrderedDict([
+       ('$R_V$ = 2.1', extinction.Fitzpatrick99(2.1)(wave, 1.0)),
+       ('$R_V$ = 2.6', extinction.Fitzpatrick99(2.6)(wave, 1.0)),
+       ('$R_V$ = 3.1', extinction.Fitzpatrick99(3.1)(wave, 1.0)),
+       ('$R_V$ = 3.6', extinction.Fitzpatrick99(3.6)(wave, 1.0)),
+       ('$R_V$ = 4.1', extinction.Fitzpatrick99(4.1)(wave, 1.0))
+       ])
+   extinction_figure(wave, a_lambda, '$R_V$ = 3.1',
+                     residual_lims=(-0.2, 0.6),
+                     title_text='Fitzpatrick99')
+
+
+
+A note on parameterization
+..........................
+
+Most extinction laws here have two parameters: :math:`A_V` and
+:math:`R_V`.  :math:`A_V` is a simply a linear scaling parameter; that
+is: ``ccm89(wave, 2.0, 3.1)`` is the same as ``2.0 * ccm89(wave, 1.0,
+3.1)``. :math:`R_V` changes the *shape* of the extinction
+curve, rather than just the amplitude.
+
+Traditionally, the meaning ascribed to these parameters was that
+:math:`A_V` is the extinction in the *V* band, and :math:`R_V`
+describes the ratio of total to selective extinction: :math:`R_V = A_V
+/ E(B-V)`, where :math:`E(B-V)` is the difference in extinction
+between the *B* and *V* bands. While this is approximately correct,
+the *measured* extinction of a source in actual *B* and *V* bandpasses
+will generally depend on the source spectrum and the shape of the
+specific bandpasses. Therefore, the :math:`A_V` and :math:`R_V` that
+are parameters in our extinction law will not correspond perfectly to
+measured *B* and *V* extinctions. So, in the context of these
+extinction laws, it is best to think of :math:`A_V` and :math:`R_V` as
+simply parameters that describe the amplitude and shape of the
+wavelength dependence, rather than corresponding directly to measured
+magnitudes.
+
+Finally, for a given shape of the extinction curve (described by
+:math:`R_V`), one can equally well use :math:`E(B-V)` as a linear
+scaling parameter in place of :math:`A_V`, with the equivalence
+:math:`E(B-V) = A_V / R_V`. Note that the above caution applies here:
+:math:`E(B-V)` should be considered simply a parameter describing
+amplitude of extinction; it will not correspond exactly to a
+difference in measured *B* and *V* extinctions.
 
 
 License and Credits
 -------------------
 
-Part of this code originated in the specutils package.
-
-The license is MIT.
+The license is MIT. Part of this code originated in the specutils package.

docs/rtd-pip-requirements

@@ -2,3 +2,4 @@ numpy
 numpydoc
 scipy
 Cython
+matplotlib