diff --git a/README.rst b/README.rst index ddb35d8b..1f6565a7 100644 --- a/README.rst +++ b/README.rst @@ -235,7 +235,7 @@ Attribution ----------- Please cite `Gomez Gonzalez et al. (2017) `_ whenever you publish data reduced with ``VIP`` . Astrophysics Source Code Library reference [ascl:1603.003]. -In addition, please cite the relevant publications for the algorithms you use (often mentioned in the documentation of VIP routines, e.g. `Marois et al. 2006 `_ for median-ADI). +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 `_ for median-ADI). Note: The ``specfit`` module, previously part of VIP, has now been moved to a separate `GitHub repository `_. diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png new file mode 100644 index 00000000..de6f8cc8 Binary files /dev/null and b/docs/source/_static/logo.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py index 15f5ad14..9dfbc448 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -42,7 +42,8 @@ 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', - 'nbsphinx' + 'nbsphinx', + 'sphinx_thebe' # 'sphinx.ext.githubpages', ] @@ -138,8 +139,8 @@ # a list of builtin themes. # #html_theme = 'classic' -html_theme = 'sphinx_book_theme' -#html_theme = 'sphinx_rtd_theme' +#html_theme = 'sphinx_book_theme' +html_theme = 'sphinx_rtd_theme' #html_theme = 'bizstyle' #html_theme = 'alabaster' @@ -147,7 +148,7 @@ # further. For a list of options available for each theme, see the # documentation. # -#html_theme_options = { +html_theme_options = { ### for alabaster theme # 'logo': 'logo.png', # 'logo_name': True, @@ -167,18 +168,20 @@ ### for bizstyle theme #'rightsidebar': True -html_theme_options = { - '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', - }, - 'use_edit_page_button': True, - 'use_issues_button': True, - 'use_repository_button': True, - 'use_download_button': 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, } @@ -197,7 +200,7 @@ # The name of an image file (relative to this directory) to place at the top # of the sidebar. # -html_logo = '_static/logo.jpg' +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 diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 8659c22f..102c2f98 100644 --- a/docs/source/faq.rst +++ b/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 diff --git a/docs/source/gen_index.rst b/docs/source/gen_index.rst new file mode 100644 index 00000000..d9ecf2ef --- /dev/null +++ b/docs/source/gen_index.rst @@ -0,0 +1,4 @@ +Index +----- +* :ref:`genindex` +* :ref:`modindex` \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index cff791a3..2e37681a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,19 +7,11 @@ :align: center :width: 400px -.. toctree:: - :maxdepth: 3 - :caption: Getting started - -Introduction +What is VIP? ------------ - -``VIP`` is a python package for angular, reference star and spectral -differential imaging for exoplanet and disk high-contrast imaging. ``VIP`` is -compatible with Python 3.7, 3.8 and 3.9 (Python 2 compatibility dropped with ``VIP`` 0.9.9). - -.. image:: https://github.com/carlgogo/carlgogo.github.io/blob/master/assets/images/vip.png?raw=true - :alt: Mosaic of S/N maps +``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 @@ -27,24 +19,36 @@ the interested scientific community. The main repository of ``VIP`` resides on `GitHub `_, the standard for scientific open source code distribution, using Git as a version control system. -``VIP`` started as the effort of `Carlos Alberto Gomez Gonzalez `_, +The project started as the effort of `Carlos Alberto Gomez Gonzalez `_, a former PhD student of the `VORTEX team `_ -(ULiege, Belgium). ``VIP``'s development has been led by Dr. Gomez with contributions +(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 `_ on -``VIP``'s GitHub repository). It is now maintained by Dr. Valentin Christiaens. +``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! -.. include:: trimmed_readme.rst +.. image:: https://github.com/carlgogo/carlgogo.github.io/blob/master/assets/images/vip.png?raw=true + :alt: Mosaic of S/N maps .. toctree:: :maxdepth: 2 + :caption: Getting started + :hidden: + + trimmed_readme_1 + trimmed_readme_2 + trimmed_readme_3 + +.. toctree:: + :maxdepth: 3 :caption: Tutorials + :hidden: + tuto_link tutorials/01_quickstart.ipynb tutorials/02_preproc.ipynb tutorials/03_psfsub.ipynb @@ -55,54 +59,19 @@ requests are very welcomed! tutorials/08_datasets_as_objects.ipynb .. toctree:: - :maxdepth: 3 + :maxdepth: 2 :caption: About + :hidden: -Frequently asked questions --------------------------- -Check out the FAQ if you encounter problems when installing or running ``VIP`` -for the first time. - -.. include:: faq.rst - -.. include:: about.rst + trimmed_readme_5 + trimmed_readme_4 + faq .. toctree:: - :maxdepth: 3 + :maxdepth: 2 :caption: Package content - -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. - -.. toctree:: - :maxdepth: 3 + :hidden: vip_hci - - -API ---- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + gen_index diff --git a/docs/source/package_structure.rst b/docs/source/package_structure.rst new file mode 100644 index 00000000..937f3c9e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/source/trimmed_readme_1.rst b/docs/source/trimmed_readme_1.rst new file mode 100644 index 00000000..ba8dfc80 --- /dev/null +++ b/docs/source/trimmed_readme_1.rst @@ -0,0 +1,7 @@ +TL;DR setup guide +----------------- +.. code-block:: bash + + $ pip install vip_hci + + diff --git a/docs/source/trimmed_readme.rst b/docs/source/trimmed_readme_2.rst similarity index 89% rename from docs/source/trimmed_readme.rst rename to docs/source/trimmed_readme_2.rst index 1714c5dd..55dcaf07 100644 --- a/docs/source/trimmed_readme.rst +++ b/docs/source/trimmed_readme_2.rst @@ -1,10 +1,3 @@ -TL;DR setup guide ------------------ -.. code-block:: bash - - $ pip install vip_hci - - Installation and dependencies ----------------------------- The benefits of using a Python package manager (distribution), such as @@ -127,14 +120,3 @@ If everything went fine with the installation, you will see a welcome message. Now you can start finding exoplanets! -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): - -- size/2-0.5 for odd-size input images; -- size/2 for even-size input images; - -i.e. exactly on a pixel in either cases. The VIP recentering routines will place the star centroid at one of these locations accordingly. - - diff --git a/docs/source/trimmed_readme_3.rst b/docs/source/trimmed_readme_3.rst new file mode 100644 index 00000000..79c82ab7 --- /dev/null +++ b/docs/source/trimmed_readme_3.rst @@ -0,0 +1,11 @@ +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): + +- size/2-0.5 for odd-size input images; +- size/2 for even-size input images; + +i.e. exactly on a pixel in either cases. The VIP recentering routines will place the star centroid at one of these locations accordingly. + + diff --git a/docs/source/trimmed_readme_4.rst b/docs/source/trimmed_readme_4.rst new file mode 100644 index 00000000..17504595 --- /dev/null +++ b/docs/source/trimmed_readme_4.rst @@ -0,0 +1,7 @@ +Mailing list +------------ +Please subscribe to our `mailing list `_ +if you want to be informed of ``VIP``'s latest developments (new versions +and/or updates). + + diff --git a/docs/source/about.rst b/docs/source/trimmed_readme_5.rst similarity index 74% rename from docs/source/about.rst rename to docs/source/trimmed_readme_5.rst index e4447ded..5da0a43a 100644 --- a/docs/source/about.rst +++ b/docs/source/trimmed_readme_5.rst @@ -1,10 +1,3 @@ -Mailing list ------------- -Please subscribe to our `mailing list `_ -if you want to be informed of ``VIP``'s latest developments (new versions -and/or updates). - - Attribution ----------- Please cite `Gomez Gonzalez et al. (2017) `_ whenever diff --git a/docs/source/tuto_link.rst b/docs/source/tuto_link.rst new file mode 100644 index 00000000..94ac5910 --- /dev/null +++ b/docs/source/tuto_link.rst @@ -0,0 +1,12 @@ +Running the tutorials +--------------------- + +Tutorials, in the form of Jupyter notebooks, showcasing ``VIP``'s usage and +other resources can be visualised within this documentation. +In order to execute them, you can either download/clone the +``VIP-extras`` `repository `_, and open each tutorial locally with jupyter notebook. +Alternatively, you can execute these tutorials on +`Binder `_. + +If you are new to the Jupyter notebook application check out the `beginner's guide +`_. \ No newline at end of file diff --git a/docs/source/tutorials/01_quickstart.ipynb b/docs/source/tutorials/01_quickstart.ipynb index 706db874..979b105d 100644 --- a/docs/source/tutorials/01_quickstart.ipynb +++ b/docs/source/tutorials/01_quickstart.ipynb @@ -11,18 +11,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Tutorial for VIP *v1.0.0* onwards.\n", - "\n", - "Written by: *Carlos Alberto Gomez Gonzalez* and *Valentin Christiaens*.\n", - "\n", - "Last update: *2022/03/16*" + "> Authors: *Valentin Christiaens* and *Carlos Alberto Gomez Gonzalez* \n", + "> Suitable for VIP *v1.0.0* onwards \n", + "> Last update: *2022/03/16*" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "### Table of contents\n", + "**Table of contents**\n", "\n", "* [1.1. Loading ADI data](#1.1.-Loading-ADI-data)\n", " \n", @@ -202,25 +200,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The fits file contains an ADI datacube of 61 images 101x101 px across." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "**IMPORTANT** - VIP's convention regarding centering is:\n", - "- for **odd** number of pixels along the x and y directions: the star is placed on the central pixel;\n", - "- for **even** number of pixels: the star is placed on coordinates (dim/2,dim/2) in 0-based indexing." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ + "The fits file contains an ADI datacube of 61 images 101x101 px across.\n", + "\n", "The parallactic angle vector for this observation is saved in the `naco_betapic_pa.fits` file. \n", "\n", - "Now we load all the data \"in\" memory with the `open_fits` function:" + "Now we load all the data in memory with the `open_fits` function:" ] }, { @@ -2341,12 +2325,12 @@ "\n", "\n", "\n", - "
\n", + "
\n", "\n", "