Merge pull request #617 from VChristiaens/master

Improvements to pca() and pca_annular() and possibility to calculate results for an input ncomp list

Author: VChristiaens

README.rst

@@ -28,7 +28,7 @@ VIP - Vortex Image Processing package
 
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7499314.svg
    :target: https://doi.org/10.5281/zenodo.7499314
-    
+
 .. image:: https://img.shields.io/badge/EMAC-2207--116-blue
    :target: https://emac.gsfc.nasa.gov/?cid=2207-116
 
@@ -50,7 +50,7 @@ VIP - Vortex Image Processing package
 Introduction
 ------------
 
-VIP is a python package for high-contrast imaging of exoplanets and circumstellar disks. 
+VIP is a python package for high-contrast imaging of exoplanets and circumstellar disks.
 VIP is compatible with Python 3.8, 3.9, 3.10 and 3.11 (Python 2 compatibility dropped with VIP 0.9.9, and Python 3.7 compatibility dropped with VIP 1.4.3).
 
 The goal of VIP is to integrate open-source, efficient, easy-to-use and
@@ -74,15 +74,15 @@ The documentation for VIP can be found here: http://vip.readthedocs.io.
 
 Jupyter notebook tutorial
 -------------------------
-Tutorials, in the form of Jupyter notebooks, showcasing VIP's usage and 
-other resources such as test datasets are available in the 
-``VIP-extras`` `repository <https://github.com/vortex-exoplanet/VIP_extras>`_. 
+Tutorials, in the form of Jupyter notebooks, showcasing VIP's usage and
+other resources such as test datasets are available in the
+``VIP-extras`` `repository <https://github.com/vortex-exoplanet/VIP_extras>`_.
 **In order to execute the notebook tutorials, you will have to download or clone the VIP-extras repository, and open each tutorial locally with jupyter notebook.**
-Alternatively, you can execute the notebooks directly on 
-`Binder <https://mybinder.org/v2/gh/vortex-exoplanet/VIP_extras/master>`_ (in 
-the tutorials directory). The first (quick-start) notebook can be visualized 
-online with `nbviewer 
-<http://nbviewer.jupyter.org/github/vortex-exoplanet/VIP_extras/blob/master/tutorials/01_quickstart.ipynb>`_. 
+Alternatively, you can execute the notebooks directly on
+`Binder <https://mybinder.org/v2/gh/vortex-exoplanet/VIP_extras/master>`_ (in
+the tutorials directory). The first (quick-start) notebook can be visualized
+online with `nbviewer
+<http://nbviewer.jupyter.org/github/vortex-exoplanet/VIP_extras/blob/master/tutorials/01_quickstart.ipynb>`_.
 If you are new to the Jupyter notebook application check out the `beginner's guide
 <https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html>`_.
 
@@ -100,7 +100,7 @@ The benefits of using a Python package manager (distribution), such as
 (ana)conda, are many. Mainly, it brings easy and robust package
 management and avoids messing up with your system's default python. An
 alternative is to use package managers like apt-get for Ubuntu or
-Homebrew/MacPorts/Fink for macOS. We recommend using 
+Homebrew/MacPorts/Fink for macOS. We recommend using
 `Miniconda <https://conda.io/miniconda>`_.
 
 VIP depends on existing packages from the Python ecosystem, such as
@@ -109,7 +109,7 @@ VIP depends on existing packages from the Python ecosystem, such as
 installing VIP suitable for different scenarios.
 
 Before installing the package, it is **highly recommended to create a dedicated
-conda environment** to not mess up with the package versions in your base 
+conda environment** to not mess up with the package versions in your base
 environment. This can be done easily with (replace ``vipenv`` by the name you want
 for your environment):
 
@@ -119,14 +119,14 @@ for your environment):
 
 .. note::
   Installing ipython while creating the environment, as in the example above, will
-  avoid a commonly reported issue which stems from trying to import VIP from 
+  avoid a commonly reported issue which stems from trying to import VIP from
   within a base python2.7 ipython console.
 
 
 For users not planning to contribute:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Once within your new environment, the easiest way to install VIP is 
-through the Python Package Index, aka `PyPI <https://pypi.org/>`_, with 
+Once within your new environment, the easiest way to install VIP is
+through the Python Package Index, aka `PyPI <https://pypi.org/>`_, with
 the ``pip`` package manager. Simply run:
 
 .. code-block:: bash
@@ -143,8 +143,8 @@ VIP. For upgrading the package, run:
 
 For potential contributors:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you plan to contribute or experiment with the code you need to make a 
-fork of the repository (click on the fork button in the top right corner) and 
+If you plan to contribute or experiment with the code you need to make a
+fork of the repository (click on the fork button in the top right corner) and
 clone it:
 
 .. code-block:: bash
@@ -159,22 +159,22 @@ functionalities by cloning the repository (but will not be able to contribute):
   $ git clone https://github.com/vortex-exoplanet/VIP.git
 
 
-To install VIP, then simply cd into your local VIP directory and run the installation in editable mode:
+To install VIP, then simply cd into your local VIP directory, and run the installation in editable mode pointing to developer requirements:
 
 .. code-block:: bash
 
   $ cd VIP
-  $ pip install -e .
+  $  pip install -e . -r requirements-dev.txt
 
-If cloned from your fork, make sure to link your VIP directory to the upstream 
-source, to be able to easily update your local copy when a new version comes 
+If cloned from your fork, make sure to link your VIP directory to the upstream
+source, to be able to easily update your local copy when a new version comes
 out or a bug is fixed:
 
 .. code-block:: bash
 
   $ git add remote upstream https://github.com/vortex-exoplanet/VIP.git
 
-If you plan to develop VIP or use it intensively, it is highly recommended to 
+If you plan to develop VIP or use it intensively, it is highly recommended to
 also install the optional dependencies listed below.
 
 
@@ -186,7 +186,8 @@ The following dependencies are not automatically installed upon installation of
 - VIP image operations (e.g. shifts, rotations, scaling) can be performed using ``OpenCV`` instead of the default FFT-based methods. While flux are less well preserved, ``OpenCV`` offers a significant speed improvement (up to a factor 50x), in particular for image rotations, which can be useful to get quick results. Installation: ``pip install opencv-python``.
 - 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``.
 - 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``.
+- 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``.
+- Finally, robust contrast curves and contrast grids can be calculated with `applefy`. Example usage is provided in `VIP tutorial 4 <https://vip.readthedocs.io/en/latest/tutorials/04_metrics.html>`_. See more details in `Bonse et al. (2023) <https://ui.adsabs.harvard.edu/abs/2023AJ....166...71B/abstract>`_.
 
 
 Loading VIP
@@ -206,7 +207,7 @@ 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-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.
@@ -234,6 +235,6 @@ Maintenance and current development is now led by `Valentin Christiaens <https:/
 VIP benefitted from contributions made by collaborators from several teams, including: Ralf Farkas, Julien Milli, Olivier Wertz, Henry Ngo, Alan Rainot, Gary Ruane, Corentin Doco, Miles Lucas, Gilles Orban de Xivry, Lewis Picker, Faustine Cantalloube, Iain Hammond, Christian Delacroix, Arthur Vigan, Dimitri Mawet and Olivier Absil.
 More details about the respective contributions are available `here <https://github.com/vortex-exoplanet/VIP/graphs/contributors?from=2015-07-26&to=2022-03-29&type=a>`_.
 
-Please cite `Gomez Gonzalez et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017AJ....154....7G/abstract>`_ and `Christiaens et al. (2023) <https://ui.adsabs.harvard.edu/abs/2023JOSS....8.4774C/abstract>`_ whenever 
+Please cite `Gomez Gonzalez et al. (2017) <https://ui.adsabs.harvard.edu/abs/2017AJ....154....7G/abstract>`_ and `Christiaens et al. (2023) <https://ui.adsabs.harvard.edu/abs/2023JOSS....8.4774C/abstract>`_ whenever
 you publish data reduced with VIP (Astrophysics Source Code Library reference `ascl:1603.003`).
 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).

docs/source/Installation-and-dependencies.rst

@@ -4,7 +4,7 @@ The benefits of using a Python package manager (distribution), such as
 (ana)conda, are many. Mainly, it brings easy and robust package
 management and avoids messing up with your system's default python. An
 alternative is to use package managers like apt-get for Ubuntu or
-Homebrew/MacPorts/Fink for macOS. We recommend using 
+Homebrew/MacPorts/Fink for macOS. We recommend using
 `Miniconda <https://conda.io/miniconda>`_.
 
 VIP depends on existing packages from the Python ecosystem, such as
@@ -13,7 +13,7 @@ VIP depends on existing packages from the Python ecosystem, such as
 installing VIP suitable for different scenarios.
 
 Before installing the package, it is **highly recommended to create a dedicated
-conda environment** to not mess up with the package versions in your base 
+conda environment** to not mess up with the package versions in your base
 environment. This can be done easily with (replace ``vipenv`` by the name you want
 for your environment):
 
@@ -23,14 +23,14 @@ for your environment):
 
 .. note::
   Installing ipython while creating the environment, as in the example above, will
-  avoid a commonly reported issue which stems from trying to import VIP from 
+  avoid a commonly reported issue which stems from trying to import VIP from
   within a base python2.7 ipython console.
 
 
 For users not planning to contribute:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Once within your new environment, the easiest way to install VIP is 
-through the Python Package Index, aka `PyPI <https://pypi.org/>`_, with 
+Once within your new environment, the easiest way to install VIP is
+through the Python Package Index, aka `PyPI <https://pypi.org/>`_, with
 the ``pip`` package manager. Simply run:
 
 .. code-block:: bash
@@ -47,8 +47,8 @@ VIP. For upgrading the package, run:
 
 For potential contributors:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you plan to contribute or experiment with the code you need to make a 
-fork of the repository (click on the fork button in the top right corner) and 
+If you plan to contribute or experiment with the code you need to make a
+fork of the repository (click on the fork button in the top right corner) and
 clone it:
 
 .. code-block:: bash
@@ -63,22 +63,22 @@ functionalities by cloning the repository (but will not be able to contribute):
   $ git clone https://github.com/vortex-exoplanet/VIP.git
 
 
-To install VIP, then simply cd into your local VIP directory and run the installation in editable mode:
+To install VIP, then simply cd into your local VIP directory, and run the installation in editable mode pointing to developer requirements:
 
 .. code-block:: bash
 
   $ cd VIP
-  $ pip install -e .
+  $  pip install -e . -r requirements-dev.txt
 
-If cloned from your fork, make sure to link your VIP directory to the upstream 
-source, to be able to easily update your local copy when a new version comes 
+If cloned from your fork, make sure to link your VIP directory to the upstream
+source, to be able to easily update your local copy when a new version comes
 out or a bug is fixed:
 
 .. code-block:: bash
 
   $ git add remote upstream https://github.com/vortex-exoplanet/VIP.git
 
-If you plan to develop VIP or use it intensively, it is highly recommended to 
+If you plan to develop VIP or use it intensively, it is highly recommended to
 also install the optional dependencies listed below.
 
 
@@ -90,7 +90,8 @@ The following dependencies are not automatically installed upon installation of
 - VIP image operations (e.g. shifts, rotations, scaling) can be performed using ``OpenCV`` instead of the default FFT-based methods. While flux are less well preserved, ``OpenCV`` offers a significant speed improvement (up to a factor 50x), in particular for image rotations, which can be useful to get quick results. Installation: ``pip install opencv-python``.
 - 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``.
 - 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``.
+- 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``.
+- Finally, robust contrast curves and contrast grids can be calculated with `applefy`. Example usage is provided in `VIP tutorial 4 <https://vip.readthedocs.io/en/latest/tutorials/04_metrics.html>`_. See more details in `Bonse et al. (2023) <https://ui.adsabs.harvard.edu/abs/2023AJ....166...71B/abstract>`_.
 
 
 Loading VIP
@@ -103,4 +104,3 @@ that you are able to import VIP:
   import vip_hci as vip
 
 If everything went fine with the installation, you should not get any error message upon importation, and you can start finding exoplanets!
-

docs/source/tutorials/01A_quickstart.ipynb

@@ -1651,7 +1651,7 @@
     "You're now ready for more advanced tutorials. If you wish to know more about:\n",
     "\n",
     "- pre-processing functionalities available in VIP (star centering, bad frame trimming, bad pixel correction...) --> go to **Tutorial 2**;\n",
-    "- more advanced post-processing algorithms --> go to **Tutorial 3**;\n",
+    "- more advanced post-processing algorithms --> go to **Tutorial 3A** or **3B** (the latter for OO example usage);\n",
     "- metrics to evaluate the significance of a detection or the achieved contrast in your image --> go to **Tutorial 4**;\n",
     "- how to characterize a directly imaged companion --> go to **Tutorial 5**;\n",
     "- how to characterize a circumstellar disk --> go to **Tutorial 6**;\n",

docs/source/tutorials/01B_quickstart_with_objects.ipynb

@@ -1473,7 +1473,7 @@
     "You're now ready for more advanced tutorials. If you wish to know more about:\n",
     "\n",
     "- pre-processing functionalities available in VIP (star centering, bad frame trimming, bad pixel correction...) --> go to **Tutorial 2**;\n",
-    "- more advanced post-processing algorithms --> go to **Tutorial 3**;\n",
+    "- more advanced post-processing algorithms --> go to **Tutorial 3A** or **3B** (the latter for OO example usage);\n",
     "- metrics to evaluate the significance of a detection or the achieved contrast in your image --> go to **Tutorial 4**;\n",
     "- how to characterize a directly imaged companion --> go to **Tutorial 5**;\n",
     "- how to characterize a circumstellar disk --> go to **Tutorial 6**;\n",