adding some inline comments and updating citations (#204)

src/exoplanet/citations.py

@@ -50,7 +50,8 @@ def get_citations_for_model(model=None, width=79):
 
     txt = (
         r"This research made use of \textsf{{exoplanet}} "
-        r"\citep{{exoplanet}} and its dependencies \citep{{{0}}}."
+        r"\citep{{exoplanet:joss, exoplanet:zenodo}} and its dependencies "
+        r"\citep{{{0}}}."
     )
     txt = txt.format(", ".join(sorted(cite)))
     txt = textwrap.wrap(txt, width=width)
@@ -60,9 +61,30 @@ def get_citations_for_model(model=None, width=79):
 
 CITATIONS = {
     "exoplanet": (
-        ("exoplanet",),
+        ("exoplanet:joss", "exoplanet:zenodo"),
         r"""
-@misc{exoplanet,
+@article{exoplanet:joss,
+       author = {{Foreman-Mackey}, Daniel and {Luger}, Rodrigo and {Agol}, Eric
+                and {Barclay}, Thomas and {Bouma}, Luke G. and {Brandt},
+                Timothy D. and {Czekala}, Ian and {David}, Trevor J. and
+                {Dong}, Jiayin and {Gilbert}, Emily A. and {Gordon}, Tyler A.
+                and {Hedges}, Christina and {Hey}, Daniel R. and {Morris},
+                Brett M. and {Price-Whelan}, Adrian M. and {Savel}, Arjun B.},
+        title = "{exoplanet: Gradient-based probabilistic inference for
+                  exoplanet data \& other astronomical time series}",
+      journal = {arXiv e-prints},
+         year = 2021,
+        month = may,
+          eid = {arXiv:2105.01994},
+        pages = {arXiv:2105.01994},
+archivePrefix = {arXiv},
+       eprint = {2105.01994},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2021arXiv210501994F},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@misc{exoplanet:zenodo,
   author = {Daniel Foreman-Mackey and Arjun Savel and Rodrigo Luger  and
             Eric Agol and Ian Czekala and Adrian Price-Whelan and
             Christina Hedges and Emily Gilbert and Luke Bouma and Tom Barclay
@@ -333,9 +355,9 @@ def get_citations_for_model(model=None, width=79):
         r"""
 @ARTICLE{rebound,
        author = {{Rein}, H. and {Liu}, S. -F.},
-        title = "{REBOUND: an open-source multi-purpose N-body code for collisional dynamics}",
+        title = "{REBOUND: an open-source multi-purpose N-body code for
+                 collisional dynamics}",
       journal = {\aap},
-     keywords = {methods: numerical, planets and satellites: rings, protoplanetary disks, Astrophysics - Earth and Planetary Astrophysics, Astrophysics - Instrumentation and Methods for Astrophysics, Mathematics - Dynamical Systems, Physics - Computational Physics},
          year = 2012,
         month = jan,
        volume = {537},
@@ -355,9 +377,10 @@ def get_citations_for_model(model=None, width=79):
         r"""
 @ARTICLE{reboundias15,
        author = {{Rein}, Hanno and {Spiegel}, David S.},
-        title = "{IAS15: a fast, adaptive, high-order integrator for gravitational dynamics, accurate to machine precision over a billion orbits}",
+        title = "{IAS15: a fast, adaptive, high-order integrator for
+                  gravitational dynamics, accurate to machine precision over a
+                  billion orbits}",
       journal = {\mnras},
-     keywords = {gravitation, methods: numerical, planets and satellites: dynamical evolution and stability, Astrophysics - Earth and Planetary Astrophysics, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Solar and Stellar Astrophysics, Mathematics - Numerical Analysis},
          year = 2015,
         month = jan,
        volume = {446},
@@ -397,14 +420,16 @@ def get_citations_for_model(model=None, width=79):
         ("exoplanet:reboundx",),
         r"""
 @article{tamayo2020reboundx,
-  title={REBOUNDx: a library for adding conservative and dissipative forces to otherwise symplectic N-body integrations},
-  author={Tamayo, Daniel and Rein, Hanno and Shi, Pengshuai and Hernandez, David M},
-  journal={Monthly Notices of the Royal Astronomical Society},
-  volume={491},
-  number={2},
-  pages={2885--2901},
-  year={2020},
-  publisher={Oxford University Press}
+   title  = {REBOUNDx: a library for adding conservative and dissipative forces
+             to otherwise symplectic N-body integrations},
+  author  = {Tamayo, Daniel and Rein, Hanno and Shi, Pengshuai and Hernandez,
+             David M},
+ journal  = {Monthly Notices of the Royal Astronomical Society},
+  volume  = {491},
+  number  = {2},
+   pages  = {2885--2901},
+    year  = {2020},
+publisher = {Oxford University Press}
 }
 """,
     ),

src/exoplanet/light_curves/interpolated.py

@@ -7,6 +7,19 @@
 
 
 def interp(n, x, xmin, xmax, dx, func):
+    """One-dimensional regularly spaced cubic interpolation
+
+    Args:
+        n (int): The axis of the output that should be interpolated
+        x (tensor): The x coordinates where the model should be evaluated
+        xmin (scalar): The first coordinate in the grid
+        xmax (scalar): The last coordinate in the grid
+        dx (scalar): The grid spacing
+        func (callable): The function that should be interpolated
+
+    Returns:
+        y: The function ``func`` interpolated to the coordinates ``x``
+    """
     xp = tt.arange(xmin - dx, xmax + 2.5 * dx, dx)
     yp = func(xp)
 
@@ -26,6 +39,14 @@ def interp(n, x, xmin, xmax, dx, func):
 
 
 class InterpolatedLightCurve:
+    """This light curve object is an EXPERIMENTAL and UNTESTED interface for
+    pre-computing transit light curves on a grid and then interpolating this
+    model onto the observed datapoints. This can improve the computational
+    cost of a light curve model, especially when the dataset is large or the
+    planet is short period. WARNING: You should only use this at your own risk
+    if you know what you're doing!
+    """
+
     def __init__(
         self, base_light_curve, num_phase, num_planets=None, **kwargs
     ):

src/exoplanet/light_curves/limb_dark.py

@@ -161,13 +161,16 @@ def get_light_curve(
         r = tt.reshape(r, (r.size,))
         t = as_tensor_variable(t)
 
+        # If use_in_transit, we should only evaluate the model at times where
+        # at least one planet is transiting
         if use_in_transit:
             transit_model = tt.shape_padleft(
                 tt.zeros_like(r), t.ndim
             ) + tt.shape_padright(tt.zeros_like(t), r.ndim)
             inds = orbit.in_transit(t, r=r, texp=texp, light_delay=light_delay)
             t = t[inds]
 
+        # Handle exposure time integration
         if texp is None:
             tgrid = t
             rgrid = tt.shape_padleft(r, tgrid.ndim) + tt.shape_padright(
@@ -208,6 +211,8 @@ def get_light_curve(
                 tt.zeros_like(tgrid), 1
             )
 
+        # Evalute the coordinates of the transiting body in the plane of the
+        # sky
         coords = orbit.get_relative_position(tgrid, light_delay=light_delay)
         b = tt.sqrt(coords[0] ** 2 + coords[1] ** 2)
         b = tt.reshape(b, rgrid.shape)

src/exoplanet/orbits/dur_to_ecc.py

@@ -1,5 +1,11 @@
 # -*- coding: utf-8 -*-
 
+"""This module has an EXPERIMENTAL and UNTESTED implementation of analytic
+marginalizion over eccentricity as a function of transit duration (since the
+mapping is not 1-to-1). The implementation as written probably DOES NOT WORK,
+but I've (DFM) left it here for my own future reference. Feel free to ping me
+if you're interested in what's going on here!"""
+
 __all__ = ["duration_to_eccentricity"]
 
 from itertools import product