Merge pull request #748 from StingraySoftware/fix-docs

Make the docs page better structured

docs/changes/748.docs.rst

@@ -0,0 +1 @@
+Improved main page of the documentation

docs/history.rst

@@ -2,10 +2,17 @@
 History
 *******
 
-Changelog
-=========
+For a brief overview of the history and state-of-the-art in spectral timing, and for more information about the design and capabilities of Stingray, please refer to `Huppenkothen et al. (2019) <https://ui.adsabs.harvard.edu/abs/2019ApJ...881...39H/abstract>`_.
 
-.. include:: ../CHANGELOG.rst
+Stingray originated during the 2016 workshop `The X-ray Spectral-Timing Revolution <http://www.lorentzcenter.nl/lc/web/2016/720/info.php3?wsid=720&venue=Oort/>`_: a group of X-ray astronomers and developers decided to agree on a common platform to develop a new software package.
+At that time, there were a number of official software packages for X-ray spectral fitting (XSPEC, ISIS, Sherpa, ...), but
+such a widely used and standard software package did not exist for X-ray timing, that was mostly the domain of custom, proprietary software.
+Our goals were to merge existing efforts towards a timing package in Python, following the best guidelines for modern open-source programming, thereby providing the basis for developing spectral-timing analysis tools.
+We needed to provide an easily accessible scripting interface, a GUI, and an API for experienced coders.
+Stingray's ultimate goal is to provide the community with a package that eases the learning curve for advanced spectral-timing techniques, with a correct statistical framework.
+
+Further spectral-timing functionality, in particularly command line scripts based on the API defined within Stingray, is available in the package `HENDRICS <https://github.com/StingraySoftware/HENDRICS>`_.
+A graphical user interface is under development as part of the project `DAVE <https://github.com/StingraySoftware/dave>`_.
 
 Previous projects merged to Stingray
 ====================================
@@ -14,3 +21,24 @@ Previous projects merged to Stingray
 * Matteo Bachetti's `MaLTPyNT <https://github.com/matteobachetti/MaLTPyNT>`_
 * Abigail Stevens' RXTE power spectra code and phase-resolved spectroscopy code
 * Simone Migliari's and Paul Balm's X-ray data exploration GUI commissioned by ESA
+
+
+Changelog
+=========
+
+.. include:: ../CHANGELOG.rst
+
+
+Presentations
+=============
+
+Members of the Stingray team have given a number of presentations which introduce Stingray.
+These include:
+
+- `2nd Severo Ochoa School on Statistics, Data Mining, and Machine Learning (2021) <https://github.com/abigailStev/timeseries-tutorial>`_
+- `9th Microquasar Workshop (2021) <https://speakerdeck.com/abigailstev/time-series-exploration-with-stingray>`_
+- `European Week of Astronomy and Space Science (2018) <http://ascl.net/wordpress/2018/05/24/software-in-astronomy-symposium-presentations-part-3/>`_
+- `ADASS (Astronomical Data Analysis Software and Systems; meeting 2017, proceedings 2020) <https://ui.adsabs.harvard.edu/abs/2020ASPC..522..521M/abstract>`_
+- `AAS 16th High-Energy Astrophysics Division meeting (2017) <https://speakerdeck.com/abigailstev/stingray-open-source-spectral-timing-software>`_
+- `European Week of Astronomy and Space Science 2017 <http://ascl.net/wordpress/2017/07/23/special-session-on-and-about-software-at-ewass-2017/>`_
+- `Python in Astronomy (2016) <https://speakerdeck.com/abigailstev/stingray-pyastro16>`_

docs/index.rst

@@ -2,43 +2,276 @@
 Stingray: Next-Generation Spectral Timing
 *****************************************
 
-Stingray is a community-developed astrophysical spectral-timing software package written in Python.
-
 .. image:: images/stingray_logo.png
    :width: 700
    :scale: 40%
    :alt: Stingray logo, outline of a stingray on top of a graph of the power spectrum of an X-ray binary
    :align: center
 
-There are a number of official software packages for X-ray spectral fitting (XSPEC, ISIS, Sherpa, ...).
-Such a widely used and standard software package does not exist for X-ray timing, so until now it has mainly been the domain of custom, proprietary software.
-Stingray originated during the 2016 workshop `The X-ray Spectral-Timing Revolution <http://www.lorentzcenter.nl/lc/web/2016/720/info.php3?wsid=720&venue=Oort/>`_: a group of X-ray astronomers and developers decided to agree on a common platform to develop a new software package.
-The goals were to merge existing efforts towards a timing package in Python, following the best guidelines for modern open-source programming, thereby providing the basis for developing spectral-timing analysis tools.
-This software provides an easily accessible scripting interface, a GUI, and an API for experienced coders.
-Stingray's ultimate goal is to provide the community with a package that eases the learning curve for advanced spectral-timing techniques, with a correct statistical framework.
-
-Further spectral-timing functionality, in particularly command line scripts based on the API defined within Stingray, is available in the package `HENDRICS <https://github.com/StingraySoftware/HENDRICS>`_.
-A graphical user interface is under development as part of the project `DAVE <https://github.com/StingraySoftware/dave>`_.
+Stingray is a Python library designed to perform times series analysis and related tasks on astronomical light curves.
+It supports a range of commonly-used Fourier analysis techniques, as well as extensions for analyzing pulsar data, simulating data sets, and statistical modelling.
+Stingray is designed to be easy to extend, and easy to incorporate into data analysis workflows and pipelines.
 
 .. important::
 
    If you use Stingray for work presented in a publication or talk, please help the project by providing a proper :doc:`citation <citing>`.
 
-Contents
+Features
 ========
+Current Capabilities
+--------------------
+
+Currently implemented functionality in this library comprises:
+
+* loading event lists from fits files of a few missions (RXTE/PCA, NuSTAR/FPM, XMM-Newton/EPIC, NICER/XTI)
+* constructing light curves from event data, various operations on light curves (e.g. addition, subtraction, joining, and truncation)
+* Good Time Interval operations
+* power spectra in Leahy, rms normalization, absolute rms and no normalization
+* averaged power spectra
+* dynamical power spectra
+* maximum likelihood fitting of periodograms/parametric models
+* (averaged) cross spectra
+* coherence, time lags
+* cross correlation functions
+* RMS spectra and lags (time vs energy, time vs frequency); *needs testing*
+* covariance spectra; *needs testing*
+* bispectra; *needs testing*
+* (Bayesian) quasi-periodic oscillation searches
+* simulating a light curve with a given power spectrum
+* simulating a light curve from another light curve and a 1-d (time) or 2-d (time-energy) impulse response
+* simulating an event list from a given light curve _and_ with a given energy spectrum
+* pulsar searches with Epoch Folding, :math:`Z^2_n` test
+
+Future Plans
+------------
+
+We welcome feature requests: if you need a particular tool that's currently not available or have a new method you think might be usefully implemented in Stingray, please :doc:`get in touch <contributing>`!
+
+Other future additions we are currently implementing are:
+
+* bicoherence
+* phase-resolved spectroscopy of quasi-periodic oscillations
+* Fourier-frequency-resolved spectroscopy
+* power colours
+* full HEASARC-compatible mission support
+* pulsar searches with :math:`H`-test
+* binary pulsar searches
+
+Platform-specific issues
+------------------------
+
+Windows uses an internal 32-bit representation for ``int``. This might create numerical errors when using large integer numbers (e.g. when calculating the sum of a light curve, if the ``lc.counts`` array is an integer).
+On Windows, we automatically convert the ``counts`` array to float. The small numerical errors should be a relatively small issue compare to the above.
+
+Installation instructions
+=========================
+
+There are currently three ways to install Stingray:
+
+* via ``conda``
+* via ``pip``
+* from source
+
+Below, you can find instructions for each of these methods.
+
+Dependencies
+------------
+A **minimal installation** of Stingray requires the following dependencies:
+
++ astropy>=4.0
++ numpy>=1.17.0
++ scipy>=1.1.0
++ matplotlib>=3.0,!=3.4.0
+
+In **typical** uses, requiring input/output, caching of results, and faster processing, we **recommend the following dependencies**:
+
++ numba (**highly** recommended)
++ tbb (needed by numba)
++ tqdm (for progress bars, always useful)
++ pyfftw (for the fastest FFT in the West)
++ h5py (for input/output)
++ pyyaml (for input/output)
++ emcee (for MCMC analysis, e.g. for PSD fitting)
++ corner (for the plotting of MCMC results)
++ statsmodels (for some statistical analysis)
+
+For **pulsar searches and timing**, we recommend installing
+
++ pint-pulsar
+
+Some of the dependencies are available in ``conda``, the others via ``pip``.
+To install all required and recommended dependencies in a recent installation, you should be good running the following command:
+
+    $ pip install astropy scipy matplotlib numpy h5py tqdm numba pint-pulsar emcee corner statsmodels pyfftw tbb
+
+For development work, you will need the following extra libraries:
+
++ pytest
++ pytest-astropy
++ tox
++ jinja2<=3.0.0
++ docutils
++ sphinx-astropy
++ nbsphinx>=0.8.3,!=0.8.8
++ pandoc
++ ipython
++ jupyter
++ notebook
++ towncrier<22.12.0
++ black
+
+Which can be installed with the following command:
+
+    $ pip install pytest pytest-astropy jinja2<=3.0.0 docutils sphinx-astropy nbsphinx pandoc ipython jupyter notebook towncrier<22.12.0 tox black
+
+Installation
+------------
+Installing via ``conda``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you manage your Python installation and packages
+via Anaconda or miniconda, you can install ``stingray``
+via the ``conda-forge`` build: ::
+
+    $ conda install -c conda-forge stingray
+
+That should be all you need to do! Just remember to :ref:`run the tests <testsuite>` before
+you use it!
+
+Installing via ``pip``
+~~~~~~~~~~~~~~~~~~~~~~
+
+``pip``-installing Stingray is easy! Just do::
+
+    $ pip install stingray
+
+And you should be done! Just remember to :ref:`run the tests <testsuite>` before you use it!
+
+Installing from source (bleeding edge version)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For those of you wanting to install the bleeding-edge development version from
+source (it *will* have bugs; you've been warned!), first clone
+`our repository <https://github.com/StingraySoftware/stingray>`_ on GitHub: ::
+
+    $ git clone --recursive https://github.com/StingraySoftware/stingray.git
+
+Now ``cd`` into the newly created ``stingray`` directory.
+Finally, install ``stingray`` itself: ::
+
+    $ pip install -e "."
+
+Installing development environment (for new contributors)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For those of you wanting to contribute to the project, install the bleeding-edge development version from
+source. First fork
+`our repository <https://github.com/StingraySoftware/stingray>`_ on GitHub and clone the forked repository using: ::
+
+    $ git clone --recursive https://github.com/<your github username>/stingray.git
 
+Now, navigate to this folder and run
+the following command to add an upstream remote that's linked to Stingray's main repository.
+(This will be necessary when submitting PRs later.): ::
+
+    $ cd stingray
+    $ git remote add upstream https://github.com/StingraySoftware/stingray.git
+
+Now, install the necessary dependencies::
+
+    $ pip install astropy scipy matplotlib numpy pytest pytest-astropy h5py tqdm
+
+Finally, install ``stingray`` itself::
+
+    $ pip install -e "."
+
+.. _testsuite:
+
+Test Suite
+----------
+
+Please be sure to run the test suite before you use the package, and please report anything
+you think might be bugs on our GitHub `Issues page <https://github.com/StingraySoftware/stingray/issues>`_.
+
+Stingray uses `py.test <https://pytest.org>`_ and `tox
+<https://tox.readthedocs.io>`_ for testing. To run the tests, try::
+
+   $ tox -e test
+
+You may need to install tox first::
+
+   $ pip install tox
+
+To run a specific test file (e.g., test_io.py), try::
+
+    $ cd stingray
+    $ py.test tests/test_io.py
+
+If you have installed Stingray via pip or conda, the source directory might
+not be easily accessible. Once installed, you can also run the tests using::
+
+   $ python -c 'import stingray; stingray.test()'
+
+or from within a python interpreter:
+
+.. doctest-skip::
+
+   >>> import stingray
+   >>> stingray.test()
+
+Building the Documentation
+--------------------------
+
+The documentation including tutorials is hosted `here <https://docs.stingray.science/>`_.
+The documentation uses `sphinx <https://www.sphinx-doc.org/en/stable/>`_ to build and requires the extensions `sphinx-astropy <https://pypi.org/project/sphinx-astropy/>`_ and `nbsphinx <https://pypi.org/project/nbsphinx/>`_.
+
+One quick way to build the documentation is using our tox environment: ::
+
+    $ tox -e build_docs
+
+You can build the API reference yourself by going into the ``docs`` folder within the ``stingray`` root
+directory and running the ``Makefile``: ::
+
+    $ cd stingray/docs
+    $ make html
+
+If that doesn't work on your system, you can invoke ``sphinx-build`` itself from the stingray source directory: ::
+
+    $ cd stingray
+    $ sphinx-build docs docs/_build
+
+The documentation should be located in ``stingray/docs/_build``. Try opening ``./docs/_build/index.rst`` from
+the stingray source directory.
+
+Using Stingray
+===============
+
+Getting started
+---------------
 .. toctree::
    :maxdepth: 2
 
-   intro
-   install
    core
    dataexplo
+   pulsar
+
+Advanced
+--------
+
+.. toctree::
+   :maxdepth: 2
+
    modeling
    simulator
-   pulsar
    deadtime
    api
+
+Additional information
+======================
+
+.. toctree::
+   :maxdepth: 2
+
    history
    contributing
    citing