Merge pull request #502 from VChristiaens/master

Major documentation update + minor bug fixes

README.rst

@@ -194,7 +194,8 @@ Optional dependencies
 The following dependencies are not automatically installed upon installation of ``VIP`` but may significantly improve your experience:
 
 - ``VIP`` contains a class ``vip_hci.vip_ds9`` that enables, through ``pyds9``, the interaction with a DS9 window (displaying numpy arrays, controlling the display options, etc). To enable this feature, ``pyds9`` must be installed from the latest development version: ``pip install git+git://github.com/ericmandel/pyds9.git#egg=pyds9``
-- Also, you can install the Intel Math Kernel Library (``mkl``) optimizations (provided that you have a recent version of ``conda``) or ``openblas`` libraries. Either of them can be installed with ``conda install``. This is recommended along with ``OpenCV`` for maximum speed on ``VIP`` computations.
+- Also, you can install the Intel Math Kernel Library (``mkl``) optimizations (provided that you have a recent version of ``conda``) or ``openblas`` libraries. Either of them can be installed with ``conda install``. 
+- For maximum speed on image operations, such as scaling, shifts or rotations (the latter being a typical bottleneck in most post-processing routines), one can install ``OpenCV`` (`pip install opencv-python`). To use it, just set `imlib='opencv'` (combined e.g. with `interpolation='lanczos4'`) instead of the default `imlib='vip-fft'` when using any routine involving image operations. While it can yield up to 3 orders of magnitude speed improvement, note that flux conservation will be worse than using FFT-based methods.
 - ``VIP`` offers the possibility of computing SVDs on GPU by using ``CuPy`` (starting from version 0.8.0) or ``PyTorch`` (from version 0.9.2). These remain as optional requirements, to be installed by the user, as well as a proper CUDA environment (and a decent GPU card).
 - Finally, bad pixel correction routines can be optimised with ``Numba``, which  converts some Python code, particularly ``NumPy``, into fast machine code. A factor up to ~50x times speed improvement can be obtained on large images compared to NumPy. Numba can be installed with ``conda install numba``.
 
@@ -212,8 +213,8 @@ If everything went fine with the installation, you will see a welcome message.
 Now you can start finding exoplanets!
 
 
-Convention regarding image center and parity of image dimensions
-----------------------------------------------------------------
+Image conventions
+-----------------
 
 By default, VIP routines are compatible with either even- or odd-dimension input frames. For VIP routines that require the star to be centered in the input images (e.g. post-processing routines involving (de)rotation or scaling), the code will assume that it is placed on (zero-based indexing):
 
@@ -234,14 +235,7 @@ Attribution
 -----------
 Please cite `Gomez Gonzalez et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017AJ....154....7G/abstract>`_ whenever 
 you publish data reduced with ``VIP`` . Astrophysics Source Code Library reference [ascl:1603.003].
-In addition, if you use one of the following modules, please also cite:
-
-- andromeda: `Cantalloube et al. (2015) <https://ui.adsabs.harvard.edu/abs/2015A%26A...582A..89C/abstract>`_;
-- leastsq: `Lafrenière et al. (2007) <https://ui.adsabs.harvard.edu/abs/2007ApJ...660..770L/abstract>`_;
-- llsg: `Gomez Gonzalez et al. (2016) <https://ui.adsabs.harvard.edu/abs/2016A%26A...589A..54G/abstract>`_;
-- medsub: `Marois et al. (2006) <https://ui.adsabs.harvard.edu/abs/2006ApJ...641..556M/abstract>`_ for ADI and `Sparks and Ford (2002) <https://ui.adsabs.harvard.edu/abs/2002ApJ...578..543S/abstract>`_ for SDI;
-- negfc: `Wertz et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017A%26A...598A..83W/abstract>`_;
-- pca: `Amara and Quanz (2012) <https://ui.adsabs.harvard.edu/abs/2012MNRAS.427..948A/abstract>`_ and `Soummer et al. (2012) <https://ui.adsabs.harvard.edu/abs/2012ApJ...755L..28S/abstract>`_;
+In addition, please cite the relevant publication(s) for the algorithms you use within VIP (usually mentioned in the documentation, e.g. `Marois et al. 2006 <https://ui.adsabs.harvard.edu/abs/2006ApJ...641..556M/abstract>`_ for median-ADI).
 
 
 Note: The ``specfit`` module, previously part of VIP, has now been moved to a separate `GitHub repository <https://github.com/VChristiaens/special>`_.

docs/source/conf.py

@@ -41,12 +41,14 @@
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'nbsphinx',
+    'sphinx_thebe'
     # 'sphinx.ext.githubpages',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['./_templates']
+templates_path = []#['./_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -63,8 +65,8 @@
 
 # General information about the project.
 project = u'VIP'
-copyright = u'Carlos Alberto Gomez Gonzalez & VORTEX team. Logo by Cristina Gomez Gonzalez'
-author = u'Carlos Alberto Gomez Gonzalez & VORTEX team'
+copyright = u'Carlos Alberto Gomez Gonzalez, Valentin Christiaens & VORTEX team. Logo by Cristina Gomez Gonzalez'
+author = u'Carlos Alberto Gomez Gonzalez, Valentin Christiaens & VORTEX team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -116,7 +118,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+#pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -137,25 +139,26 @@
 # a list of builtin themes.
 #
 #html_theme = 'classic'
-#html_theme = 'sphinx_rtd_theme'
+#html_theme = 'sphinx_book_theme'
+html_theme = 'sphinx_rtd_theme'
 #html_theme = 'bizstyle'
-html_theme = 'alabaster'
+#html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = {
     ### for alabaster theme
-    'logo': 'logo.png',
-    'logo_name': True,
-    'font_family': 'Georgia',
-    'github_banner': True,
-    'github_repo': 'vortex-exoplanet/VIP',
-    'github_count': True,
-    'github_type': 'star',
-    'fixed_sidebar': True,
-    'analytics_id': 'UA-84473187-1',
+    # 'logo': 'logo.png',
+    # 'logo_name': True,
+    # 'font_family': 'Georgia',
+    # 'github_banner': True,
+    # 'github_repo': 'vortex-exoplanet/VIP',
+    # 'github_count': True,
+    # 'github_type': 'star',
+    # 'fixed_sidebar': True,
+    # 'analytics_id': 'UA-84473187-1',
 
     ### for classic theme
     #'stickysidebar': True,
@@ -165,6 +168,21 @@
 
     ### for bizstyle theme
     #'rightsidebar': True
+
+    ### for sphinx_book theme
+    # 'path_to_docs': 'docs/source',
+    # 'repository_url': 'https://github.com/vortex-exoplanets/VIP',
+    # 'repository_branch': 'main',
+    # 'launch_buttons': {
+    #     'binderhub_url': 'https://mybinder.org/',#'v2/gh/vortex-exoplanet/VIP_extras/master',
+    #     'notebook_interface': 'jupyterlab',
+    #     "thebe": True,
+    # },
+    # 'use_edit_page_button': True,
+    # 'use_issues_button': True,
+    # 'use_repository_button': True,
+    # 'use_download_button': True,
+    'logo_only': True,
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -173,7 +191,7 @@
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = u'VIP - Vortex Image Processing v0.5.1'
+html_title = u'VIP - Vortex Image Processing'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -182,7 +200,7 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-# html_logo = None
+html_logo = '_static/logo.png'
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -214,11 +232,11 @@
 
 # Custom sidebar templates, maps document names to template names.
 #
-html_sidebars = {
-    'index':    ['mysidebar.html', 'localtoc.html', 'searchbox.html'],
-    '**':       ['mysidebar.html', 'localtoc.html', 'relations.html',
-                 'searchbox.html']
-}
+# html_sidebars = {
+#     'index':    ['mysidebar.html', 'localtoc.html', 'searchbox.html'],
+#     '**':       ['mysidebar.html', 'localtoc.html', 'relations.html',
+#                  'searchbox.html']
+# }
 
 
 # Additional templates that should be rendered to pages, maps page names to
@@ -305,7 +323,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'VIP-VortexImageProcessing.tex', u'VIP Documentation',
-     u'Carlos Alberto Gomez Gonzalez, Olivier Wertz \\& VORTEX team', 'manual'),
+     u'Carlos Alberto Gomez Gonzalez, Valentin Christiaens \\& VORTEX team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -381,3 +399,8 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #
 # texinfo_no_detailmenu = False
+
+html_context = {'display_github': True,
+                'github_user': 'vortex-exoplanets',
+                'github_repo': 'VIP',
+                'github_version': 'main/docs/'}

docs/source/faq.rst

@@ -1,7 +1,10 @@
+Frequently asked questions
+--------------------------
 
-FAQ
-----
-First things first. Please make sure you have the latest version of ``VIP``.
+Check out the FAQ if you encounter problems when installing or running ``VIP``
+for the first time.
+
+Before skimming this list, please make sure you have the latest version of ``VIP``.
 Please go and check the repository now. Alternatively, you can run:
 
 .. code-block:: bash
@@ -75,7 +78,7 @@ Please make sure you have ``DS9`` and ``XPA`` in your system path. Try installin
 them using your system's package management tool.
 
 
-.. rubric:: Why does Python crash when using some of the parallel functions, e.g. ``pca_adi_annular`` and ``run_mcmc_strometry``?
+.. rubric:: Why does Python crash when using some of the parallel functions, e.g. ``pca_annular`` and ``mcmc_negfc_sampling``?
 
 
 These functions require running SVD on several processes and this can be

docs/source/gen_index.rst

@@ -0,0 +1,4 @@
+Index
+-----
+* :ref:`genindex`
+* :ref:`modindex`

docs/source/index.rst

@@ -1,61 +1,77 @@
 .. This file should at least contain the root `toctree` directive.
 
 .. Welcome to ``VIP``'s documentation
-.. ==============================
+.. ==================================
+
+.. image:: _static/logo.jpg
+   :align: center
+   :width: 400px
+
+What is VIP?
+------------
+``VIP`` stands for Vortex Image Processing. 
+It is a python package for high-contrast imaging of exoplanets and circumstellar disks. 
+``VIP`` is compatible with Python 3.7, 3.8 and 3.9 (Python 2 compatibility dropped with ``VIP`` 0.9.9).
+
+The goal of ``VIP`` is to integrate open-source, efficient, easy-to-use and
+well-documented implementations of high-contrast image processing algorithms to
+the interested scientific community. The main repository of ``VIP`` resides on
+`GitHub <https://github.com/vortex-exoplanet/VIP>`_, the standard for scientific
+open source code distribution, using Git as a version control system.
+
+The project started as the effort of `Carlos Alberto Gomez Gonzalez <https://carlgogo.github.io/>`_,
+a former PhD student of the `VORTEX team <http://www.vortex.ulg.ac.be/>`_
+(ULiege, Belgium). ``VIP``'s development has first been led by Dr. Gomez with contributions
+made by collaborators from several teams (take a look at the 
+`contributors tab <https://github.com/vortex-exoplanet/VIP/graphs/contributors>`_ on
+``VIP``'s GitHub repository). It is now maintained and developed by Dr. Valentin Christiaens.
+Most of ``VIP``'s functionalities are mature but
+it doesn't mean it's free from bugs. The code is continuously evolving and
+therefore feedback/contributions are greatly appreciated. If you want to report
+a bug or suggest a functionality please create an issue on GitHub. Pull
+requests are very welcomed!
+
+.. image:: https://github.com/carlgogo/carlgogo.github.io/blob/master/assets/images/vip.png?raw=true
+    :alt: Mosaic of S/N maps
 
-.. image::  _static/logo.jpg
-   :align:  center
-   :scale:  20 %
-   :target: #
-
-.. include:: ../../README.rst
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting started
+   :hidden:
 
+   trimmed_readme_1
+   trimmed_readme_2
+   trimmed_readme_3
 
-Frequently asked questions
---------------------------
-Check out this questions if you find problems when installing or running ``VIP``
-for the first time.
+.. toctree::
+   :maxdepth: 3
+   :caption: Tutorials
+   :hidden:
+
+   tuto_link
+   tutorials/01_quickstart.ipynb
+   tutorials/02_preproc.ipynb
+   tutorials/03_psfsub.ipynb
+   tutorials/04_metrics.ipynb
+   tutorials/05_fm_planets.ipynb
+   tutorials/06_fm_disk.ipynb
+   tutorials/07_imlib_and_interpolation.ipynb
+   tutorials/08_datasets_as_objects.ipynb
 
 .. toctree::
    :maxdepth: 2
+   :caption: About
+   :hidden:
 
+   trimmed_readme_5
+   trimmed_readme_4
    faq
 
-
-Package structure
------------------
-On the links below you can find the subpackages structure and access the
-docstrings (internal documentation) of each one of ``VIP``'s functions.
-
-``VIP`` implements basic image processing functionalities such as image
-registration, rotation, shift, rescaling, pixel temporal and spatial
-subsampling. On top of that several pre-processing functions are available
-such as re-centering and bad frame removal.
-
-For Angular differential imaging (ADI) data several point spread function
-subtraction techniques are available: pairwise frame differencing, median
-subtraction, least-squares combination, NMF and PCA based algorithms. PCA
-methods are implemented in different flavours. Also PCA can process RDI and
-multiple channel SDI (IFS) data. ``VIP`` contains an implementation of the Local
-Low-rank plus Sparse plus Gaussian-noise decomposition (LLSG, Gomez Gonzalez et
-al. 2016).
-
-Functions for signal-to-noise ratio (S/N) estimation and S/N map generation are
-included, as well as injection of fake companions in 3D and 4D cubes. Flux and
-position of point-like sources are estimated using the Negative Fake Companion
-technique. ``VIP`` also implements algorithm throughput and contrast-curve
-generation routines.
-
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
+   :caption: Package content
+   :hidden:
 
    vip_hci
-
-
-API
----
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   gen_index
 

docs/source/package_structure.rst

@@ -0,0 +1,23 @@
+Structure
+---------
+On the links below you can find the subpackages structure and access the
+docstrings (internal documentation) of each one of ``VIP``'s functions.
+
+``VIP`` implements basic image processing functionalities such as image
+registration, rotation, shift, rescaling, pixel temporal and spatial
+subsampling. On top of that several pre-processing functions are available
+such as recentering and bad frame removal.
+
+For Angular differential imaging (ADI) data several point spread function
+subtraction techniques are available: pairwise frame differencing, median
+subtraction, least-squares combination, NMF and PCA based algorithms. PCA
+methods are implemented in different flavours. Also PCA can process RDI and
+multiple channel SDI (IFS) data. ``VIP`` contains an implementation of the Local
+Low-rank plus Sparse plus Gaussian-noise decomposition (LLSG, Gomez Gonzalez et
+al. 2016).
+
+Functions for signal-to-noise ratio (S/N) estimation and S/N map generation are
+included, as well as injection of fake companions in 3D and 4D cubes. Flux and
+position of point-like sources are estimated using the Negative Fake Companion
+technique. ``VIP`` also implements algorithm throughput and contrast-curve
+generation routines.

docs/source/trimmed_readme_1.rst

@@ -0,0 +1,7 @@
+TL;DR setup guide
+-----------------
+.. code-block:: bash
+
+    $ pip install vip_hci
+
+