Adding tutorial

.travis.yml

@@ -90,12 +90,6 @@ matrix:
           stage: Initial tests
           env: SETUP_CMD='test --coverage'
 
-        # Check for sphinx doc build warnings - we do this first because it
-        # may run for a long time
-        - os: linux
-          env: SETUP_CMD='build_docs -w'
-               CONDA_DEPENDENCIES=$CONDA_DEPENDENCIES_DOC
-
         # Do a PEP8 test with flake8
         - os: linux
           stage: Initial tests

docs/hipparchus/tutorial.rst

@@ -0,0 +1,199 @@
+Tutorials
+=========
+
+Loading a spectrum
+------------------
+
+First, we need a spectrum to work with, so we'll download a HARPS E2DS spectrum
+of Proxima Centauri that's currently hosted on Google Drive, like so:
+
+.. code-block:: python
+
+    from astropy.utils.data import download_file
+
+    proxima_spectrum_url = 'https://drive.google.com/uc?export=download&id=1I7E1x1XRjcxXNQXiuaajb_Jz7Wn2N_Eo'
+    proxima_spectrum_path = download_file(proxima_spectrum_url)
+
+We now have a local copy of the spectrum of Proxima Cen. We can
+load this file into a `~hipparchus.EchelleSpectrum` object like so:
+
+.. code-block:: python
+
+    from hipparchus import EchelleSpectrum
+
+    spectrum = EchelleSpectrum.from_e2ds(proxima_spectrum_path)
+
+    spectrum.plot()
+
+.. plot::
+
+    from astropy.utils.data import download_file
+    import matplotlib.pyplot as plt
+
+    proxima_spectrum_url = 'https://drive.google.com/uc?export=download&id=1I7E1x1XRjcxXNQXiuaajb_Jz7Wn2N_Eo'
+    proxima_spectrum_path = download_file(proxima_spectrum_url, cache=True,
+                                          show_progress=False)
+
+    from hipparchus import EchelleSpectrum
+
+    spectrum = EchelleSpectrum.from_e2ds(proxima_spectrum_path)
+
+    spectrum.plot()
+    plt.xlabel('Wavelength [$\AA$]')
+    plt.ylabel('Counts')
+
+Continuum normalize
+-------------------
+
+Next we might want to continuum normalize each echelle order. We can do that
+simply with the following command:
+
+.. code-block:: python
+
+    spectrum.continuum_normalize()
+    spectrum.plot()
+
+.. plot::
+
+    from astropy.utils.data import download_file
+    import matplotlib.pyplot as plt
+
+    proxima_spectrum_url = 'https://drive.google.com/uc?export=download&id=1I7E1x1XRjcxXNQXiuaajb_Jz7Wn2N_Eo'
+    proxima_spectrum_path = download_file(proxima_spectrum_url, cache=True,
+                                          show_progress=False)
+
+    from hipparchus import EchelleSpectrum
+
+    spectrum = EchelleSpectrum.from_e2ds(proxima_spectrum_path)
+
+    spectrum.continuum_normalize()
+    spectrum.plot()
+    plt.xlabel('Wavelength [$\AA$]')
+    plt.ylabel('Normalized Flux')
+    plt.ylim([0, 1.5])
+
+You can see that the continuum flux is now mostly normalized near unity.
+
+Our spectrum is now ready for cross-correlation business!
+
+Loading a spectral template
+---------------------------
+
+Next we need to load spectral templates which we will cross-correlate with the
+observed spectrum of Proxima Centauri. We'll be loading emission spectra
+generated by Daniel Kitzmann which represent: TiO at 3000 K (roughly the
+effective temperature of Proxima Cen), and H2O at 2500 K (roughly the
+temperature of hypothesized starspots on Proxima Cen).
+
+First we download the spectral templates:
+
+.. code-block:: python
+
+    from astropy.utils.data import download_file
+
+    template_2500_h2o_url = 'https://drive.google.com/uc?export=download&id=1RIXBl3L3J_R9PQ-k_0BqAtO-9zYn2mag'
+    template_3000_tio_url = 'https://drive.google.com/uc?export=download&id=1eGUBfk7Q9zaXgJQJtVFB6pit7cmoGCpn'
+
+    template_2500_h2o_path = download_file(template_2500_h2o_url)
+    template_3000_tio_path = download_file(template_3000_tio_url)
+
+We now have a local copy of the spectral templates for TiO and water. Let's
+load those templates into the `~hipparchus.Template` object:
+
+.. code-block:: python
+
+    from hipparchus import Template
+
+    template_2500_h2o = Template.from_npy(template_2500_h2o_path)
+    template_3000_tio = Template.from_npy(template_3000_tio_path)
+
+    template_3000_tio.plot()
+
+.. plot::
+
+    from astropy.utils.data import download_file
+    import matplotlib.pyplot as plt
+    from hipparchus import Template
+
+    template_2500_h2o_url = 'https://drive.google.com/uc?export=download&id=1RIXBl3L3J_R9PQ-k_0BqAtO-9zYn2mag'
+    template_3000_tio_url = 'https://drive.google.com/uc?export=download&id=1eGUBfk7Q9zaXgJQJtVFB6pit7cmoGCpn'
+
+    template_2500_h2o_path = download_file(template_2500_h2o_url, cache=True)
+    template_3000_tio_path = download_file(template_3000_tio_url, cache=True)
+
+    template_2500_h2o = Template.from_npy(template_2500_h2o_path)
+    template_3000_tio = Template.from_npy(template_3000_tio_path)
+
+    template_3000_tio.plot()
+    plt.xlabel('Wavelength [$\AA$]')
+    plt.ylabel('Template Weighting')
+
+By default the template spectrum is normalized such that it is near zero in the
+continuum, and greater than zero in absorption lines. This allows one to easily
+compute the cross-correlation via the weighted mean.
+
+Cross correlation
+-----------------
+
+So we have a spectrum, and a template. Now let's take the cross-correlation of
+the two! We define the cross-correlation function (CCF) for an observed
+spectrum :math:`x`, given a template spectrum evaluated at a specific velocity
+:math:`T(v)`,
+
+.. math::
+
+    \mathrm{CCF} = \sum_i x_i T_i(v),
+
+where we have normalized the template such that it is positive in molecular
+absorption features and near-zero in the continuum, and
+
+.. math::
+
+    \sum_i T_i(v) = 1.
+
+This definition of the CCF is straightforward to interpret: the CCF is a mean
+of the flux in each echelle order weighted by the values of the spectral
+template. When the velocity :math:`v` is incorrect and/or the template does not
+match the observed spectrum, the weighted-mean flux is near unity (continuum).
+When the velocity is correct and the template matches absorption features in
+the observed spectrum, the absorption features in the spectrum "align" with the
+inverse absorption features in the template, and the weighted-mean flux is less
+than one. In this way, the CCF yields a "mean absorption line" due to the
+molecule specified by the template at the velocity of the star.
+
+
+Let's compute the CCF between the template and the observed Proxima
+Cen spectrum in the echelle order nearest to the wavelength 6800 Angstroms:
+
+.. code-block:: python
+
+    from hipparchus import cross_cor
+
+    ccf = cross_corr(spectrum.nearest_order(6800), template_3000_tio)
+    ccf.plot()
+
+.. plot::
+
+    from astropy.utils.data import download_file
+    import matplotlib.pyplot as plt
+    from hipparchus import Template, EchelleSpectrum, cross_corr
+
+    proxima_spectrum_url = 'https://drive.google.com/uc?export=download&id=1I7E1x1XRjcxXNQXiuaajb_Jz7Wn2N_Eo'
+    proxima_spectrum_path = download_file(proxima_spectrum_url, cache=True,
+                                          show_progress=False)
+    spectrum = EchelleSpectrum.from_e2ds(proxima_spectrum_path)
+
+    template_3000_tio_url = 'https://drive.google.com/uc?export=download&id=1eGUBfk7Q9zaXgJQJtVFB6pit7cmoGCpn'
+    template_3000_tio_path = download_file(template_3000_tio_url, cache=True)
+    template_3000_tio = Template.from_npy(template_3000_tio_path)
+
+    ccf = cross_corr(spectrum.nearest_order(6800), template_3000_tio)
+    ccf.plot()
+
+    plt.xlabel('Radial Velocity [km/s]')
+    plt.ylabel('CCF')
+
+We can see a significant "mean absorption line" in the cross-correlation
+function of the TiO emission spectrum near the known radial velocity of
+Proxima Cen at -22 km/s. This is an (unsurprisingly) significant detection of
+TiO in the atmosphere of the cool star Proxima Centauri.

docs/index.rst

@@ -1,15 +1,12 @@
-Documentation
-=============
+hipparchus
+==========
 
-This is the documentation for hipparchus.
+This is the documentation for hipparchus, a lightweight Python package for
+cross correlation of high resolution spectroscopy.
 
 
 .. toctree::
   :maxdepth: 2
 
   hipparchus/index.rst
-
-.. note:: The layout of this directory is simply a suggestion.  To follow
-          traditional practice, do *not* edit this page, but instead place
-          all documentation for the package inside ``hipparchus/``.
-          You can follow this practice or choose your own layout.
+  hipparchus/tutorial.rst