Document new features in the manual as well

README.md

@@ -157,7 +157,7 @@ http://measurementsjl.readthedocs.io/ for more details.
 ### Fast Algorithm ###
 
 When the observation times are evenly spaced, you can use a fast O[N log(N)]
-algorithm proposed by Press & Rybicki (1989) that greatly speed-up computations
+algorithm proposed by Press & Rybicki (1989) that greatly speeds up computations
 by giving an approximation of the true Lomb-Scargle periodogram, which has
 complexity O[N^2].  The larger the number of datapoints, the more accurate the
 approximation.  Note that this method internally performs a
@@ -166,24 +166,25 @@ to compute some quantities, but it is in now way equivalento to conventional
 Fourier periodogram analysis.
 
 The prerequisite in order to be able to employ this fast method is to provide a
-`times` array as a `Range` object, which ensures that the times are perfectly
-evenly spaced.  In Julia, `Range`s can be constructed for example with
+`times` vector as a `Range` object, which ensures that the times are perfectly
+evenly spaced.  In Julia, a `Range` object can be constructed for example with
+the
 [`linspace`](http://docs.julialang.org/en/stable/stdlib/arrays/#Base.linspace)
-function (you specify the start, the end of the range, and optionally the length
-of the array) or with the
+function (you specify the start and the end of the range, and optionally the
+length of the vector) or with the
 [colon](http://docs.julialang.org/en/stable/stdlib/math/#Base.:) syntax (you
-specify the start, the end of the range, and optionally the linear step; a
+specify the start and the end of the range, and optionally the linear step; a
 related function is
 [`colon`](http://docs.julialang.org/en/stable/stdlib/math/#Base.colon)).
 Somewhere in the middle is the
 [`range`](http://docs.julialang.org/en/stable/stdlib/math/#Base.range) function:
-you specify the start and the length of the array, and optionally the linear
-step.
+you specify the start of the range and the length of the vector, and optionally
+the linear step.
 
 Since this fast method is accurate only for large datasets, it is enabled by
 default only if the number of output frequencies is larger than 200.  You can
 override the default choice of using this method by setting the `fast` keyword
-to `true` or `false`.  We recall that in any case, the `times` array must be a
+to `true` or `false`.  We recall that in any case, the `times` vector must be a
 `Range` in order to use this method.
 
 The two integer keywords `ovesampling` and `Mfft` can be passed to `lombscargle`
@@ -192,7 +193,7 @@ in order to affect the computation in the fast method:
 * `oversampling`: oversampling the frequency factor for the approximation;
   roughly the number of time samples across the highest-frequency sinusoid.
   This parameter contains the tradeoff between accuracy and speed.
-* `Mfft`: The number of adjacent points to use in the FFT approximation.
+* `Mfft`: the number of adjacent points to use in the FFT approximation.
 
 ### Access Frequency Grid and Power Spectrum of the Periodogram ###
 
@@ -381,6 +382,12 @@ License
 The `LombScargle.jl` package is licensed under the MIT "Expat" License.  The
 original author is Mosè Giordano.
 
+### Acknowledgemets ###
+
+This package greatly benefited from the implementation of the Lomb–Scargle
+periodogram in Astropy, in particular for the fast method by Press & Rybicki
+(1989).
+
 
 
 [docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg

docs/index.rst

@@ -18,6 +18,9 @@ which is a fairly common case in astronomy.
 
 The algorithm used in this package are reported in the following papers:
 
+.. [PR89] Press, W. H., Rybicki, G. B. 1989, ApJ, 338, 277 (URL:
+	  http://dx.doi.org/10.1086/167197, Bibcode:
+	  http://adsabs.harvard.edu/abs/1989ApJ...338..277P)
 .. [TOW10] Townsend, R. H. D. 2010, ApJS, 191, 247 (URL:
 	   http://dx.doi.org/10.1088/0067-0049/191/2/247, Bibcode:
 	   http://adsabs.harvard.edu/abs/2010ApJS..191..247T)
@@ -93,7 +96,11 @@ All these vectors must have the same length.  The complete syntax of
                 errors::AbstractVector{Real}=ones(signal);
                 normalization::AbstractString="standard",
                 noise_level::Real=1.0,
-                center_data::Bool=true, fit_mean::Bool=true,
+                center_data::Bool=true,
+                fit_mean::Bool=true,
+                fast::Bool=true,
+                oversampling::Integer=5,
+                Mfft::Integer=4,
                 samples_per_peak::Integer=5,
                 nyquist_factor::Integer=5,
                 minimum_frequency::Real=NaN,
@@ -150,6 +157,9 @@ The frequency grid is determined by following prescriptions given at
 https://jakevdp.github.io/blog/2015/06/13/lomb-scargle-in-python/ and
 uses the same keywords names adopted in Astropy.
 
+The keywords ``fast``, ``oversampling``, and ``Mfft`` are described in the `Fast
+Algorithm`_ section below.
+
 If the signal has uncertainties, the ``signal`` vector can also be a vector of
 ``Measurement`` objects (from `Measurements.jl
 <https://github.com/giordano/Measurements.jl>`__ package), in which case you
@@ -158,6 +168,67 @@ signal. You can create arrays of ``Measurement`` objects with the
 ``measurement`` function, see ``Measurements.jl`` manual at
 http://measurementsjl.readthedocs.io/ for more details.
 
+Fast Algorithm
+~~~~~~~~~~~~~~
+
+When the observation times are evenly spaced, you can use a fast :math:`O[N
+\log(N)]` algorithm proposed by [PR89]_ that greatly speeds up computations by
+giving an approximation of the true Lomb–Scargle periodogram, which has
+complexity :math:`O[N^2]`.  The larger the number of datapoints, the more
+accurate the approximation.
+
+.. Warning::
+
+   This method internally performs a `Fast Fourier Transform
+   <https://en.wikipedia.org/wiki/Fast_Fourier_transform>`_ to compute some
+   quantities, but it is in now way equivalento to conventional Fourier
+   periodogram analysis.
+
+The prerequisite in order to be able to employ this fast method is to provide a
+``times`` vector as a ``Range`` object, which ensures that the times are
+perfectly evenly spaced.
+
+.. Tip::
+
+   In Julia, a ``Range`` object can be constructed for example with the
+   `linspace
+   <http://docs.julialang.org/en/stable/stdlib/arrays/#Base.linspace>`_ function
+   (you specify the start and the end of the range, and optionally the length of
+   the vector) or with the `colon
+   <http://docs.julialang.org/en/stable/stdlib/math/#Base.:>`_ syntax (you
+   specify the start and the end of the range, and optionally the linear step; a
+   related function is `colon
+   <http://docs.julialang.org/en/stable/stdlib/math/#Base.colon>`_).  Somewhere
+   in the middle is the `range
+   <http://docs.julialang.org/en/stable/stdlib/math/#Base.range>`_ function: you
+   specify the start of the range and the length of the vector, and optionally
+   the linear step.
+
+Since this fast method is accurate only for large datasets, it is enabled by
+default only if the number of output frequencies is larger than 200.  You can
+override the default choice of using this method by setting the ``fast`` keyword
+to ``true`` or ``false``.  We recall that in any case, the ``times`` vector must
+be a ``Range`` in order to use this method.
+
+To summarize, provided that ``times`` vector is a ``Range`` object, you can use
+the fast method:
+
+* by default if the length of the output frequency grid is larger than 200
+  points
+* if the frequency grid has 200 points or less and you explicitely request the
+  method with the ``fast=true`` keyword
+
+Setting ``fast=false`` always ensures you that this method will not be used,
+instead ``fast=true`` enables it (but only if ``times`` is a ``Range``).
+
+The two integer keywords ``ovesampling`` and ``Mfft`` can be passed to
+:func:`lombscargle` in order to affect the computation in the fast method:
+
+* ``oversampling``: oversampling the frequency factor for the approximation;
+  roughly the number of time samples across the highest-frequency sinusoid.
+  This parameter contains the tradeoff between accuracy and speed.
+* ``Mfft``: the number of adjacent points to use in the FFT approximation.
+
 Normalization
 ~~~~~~~~~~~~~
 
@@ -445,3 +516,9 @@ License
 
 The ``LombScargle.jl`` package is licensed under the MIT "Expat"
 License. The original author is Mosè Giordano.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+
+This package greatly benefited from the implementation of the Lomb–Scargle
+periodogram in Astropy, in particular for the fast method by [PR89]_.

src/LombScargle.jl

@@ -561,19 +561,19 @@ Optional keywords arguments are:
 * `center_data`: if `true`, subtract the mean of `signal` from `signal` itself
   before performing the periodogram.  This is especially important if `fit_mean`
   is `false`
-* `fast`: whether to use the fast method by Press & Rybicki, overriding the
-  default choice.  In any case, `times` must be a `Range` object in order to use
-  this method
 * `frequencies`: the frequecy grid (not angular frequencies) at which the
   periodogram will be computed, as a vector.  If not provided, it is
   automatically determined with `LombScargle.autofrequency` function, which see.
   See below for other available keywords that can be used to affect the
   frequency grid without directly setting `frequencies`
+* `fast`: whether to use the fast method by Press & Rybicki, overriding the
+  default choice.  In any case, `times` must be a `Range` object in order to use
+  this method
 * `oversampling`: oversampling the frequency factor for the approximation;
   roughly the number of time samples across the highest-frequency sinusoid.
   This parameter contains the tradeoff between accuracy and speed.  Used only
   when the fast method is employed
-* `Mfft`: The number of adjacent points to use in the FFT approximation.  Used
+* `Mfft`: the number of adjacent points to use in the FFT approximation.  Used
   only when the fast method is employed
 
 In addition, you can use all optional keyword arguments of