Merge pull request #611 from VChristiaens/master

Re-organization of new OO utilities and solution to Params class incompatibility with contrast curve functions

.github/workflows/ci.yml

@@ -44,7 +44,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.11"]
 
     steps:
     - uses: actions/checkout@v3

README.rst

@@ -123,8 +123,8 @@ for your environment):
   within a base python2.7 ipython console.
 
 
-For users (not planning to contribute):
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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 
 the ``pip`` package manager. Simply run:

docs/source/Installation-and-dependencies.rst

@@ -1,53 +1,52 @@
 Installation and dependencies
 -----------------------------
 The benefits of using a Python package manager (distribution), such as
-(ana)conda or Canopy, are many. Mainly, it brings easy and robust package
+(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 
 `Miniconda <https://conda.io/miniconda>`_.
 
-``VIP`` depends on existing packages from the Python ecosystem, such as
+VIP depends on existing packages from the Python ecosystem, such as
 ``numpy``, ``scipy``, ``matplotlib``, ``pandas``, ``astropy``, ``scikit-learn``,
 ``scikit-image``, ``photutils`` and others. There are different ways of
-installing ``VIP`` suitable for different scenarios.
+installing VIP suitable for different scenarios.
 
-
-Using pip
-^^^^^^^^^
-The easiest way to install ``VIP`` is through the Python Package Index, aka
-`PyPI <https://pypi.org/>`_, with the ``pip`` package manager. Simply run:
+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 
+environment. This can be done easily with (replace ``vipenv`` by the name you want
+for your environment):
 
 .. code-block:: bash
 
-  $ pip install vip_hci
-
-With ``pip`` you can easily uninstall, upgrade or install a specific version of
-``VIP``. For upgrading the package run:
+  $ conda create -n vipenv python=3.10 ipython
 
-.. code-block:: bash
+.. 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 
+  within a base python2.7 ipython console.
 
-  $ pip install --upgrade vip_hci
 
-Alternatively, you can use ``pip install`` and point to the GitHub repo:
+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 
+the ``pip`` package manager. Simply run:
 
 .. code-block:: bash
 
-  $ pip install git+https://github.com/vortex-exoplanet/VIP.git
+  $ pip install vip_hci
 
-Using the setup.py file
-^^^^^^^^^^^^^^^^^^^^^^^
-You can download ``VIP`` from its GitHub repository as a zip file. A ``setup.py``
-file (setuptools) is included in the root folder of ``VIP``. Enter the package's
-root folder and run:
+With ``pip`` you can easily uninstall, upgrade or install a specific version of
+VIP. For upgrading the package, run:
 
 .. code-block:: bash
 
-  $ python setup.py install
+  $ pip install --upgrade vip_hci
 
 
-Using Git
-^^^^^^^^^
+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 
 clone it:
@@ -63,26 +62,13 @@ functionalities by cloning the repository (but will not be able to contribute):
 
   $ git clone https://github.com/vortex-exoplanet/VIP.git
 
-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 
-environment. This can be done easily with (replace vipenv by the name you want
-for your environment):
-
-.. code-block:: bash
-
-  $ conda create -n vipenv python=3.9 ipython
 
-Note: installing ipython while creating the environment with the above line will
-avoid a commonly reported issue which stems from trying to import VIP from 
-within a base python2.7 ipython console.
-
-To install VIP, simply cd into the VIP directory and run the setup file 
-in 'develop' mode:
+To install VIP, then simply cd into your local VIP directory and run the installation in editable mode:
 
 .. code-block:: bash
 
   $ cd VIP
-  $ python setup.py develop
+  $ pip install -e .
 
 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 
@@ -98,25 +84,23 @@ also install the optional dependencies listed below.
 
 Optional dependencies
 ^^^^^^^^^^^^^^^^^^^^^
-The following dependencies are not automatically installed upon installation of ``VIP`` but may significantly improve your experience:
+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``
-- ``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).
+- 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``
+- 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``.
 
 
 Loading VIP
 ^^^^^^^^^^^
 Finally, start Python (or IPython or a Jupyter notebook if you prefer) and check
-that you are able to import ``VIP``:
+that you are able to import VIP:
 
 .. code-block:: python
 
   import vip_hci as vip
 
-If everything went fine with the installation, you will see a welcome message.
-Now you can start finding exoplanets!
-
+If everything went fine with the installation, you should not get any error message upon importation, and you can start finding exoplanets!
 

docs/source/index.rst

@@ -11,15 +11,15 @@ 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, 3.9 and 3.10 (Python 2 compatibility dropped with ``VIP`` 0.9.9).
+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
+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
+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.
 
-Most of ``VIP``'s functionalities are mature but
+Most of VIP's functionalities are mature but
 it does not mean it is free from bugs. The code is continuously evolving and
 therefore feedback/contributions are greatly appreciated. Please refer to `these instructions <https://vip.readthedocs.io/en/latest/Contact.html>`_ if you want to report
 a bug, ask a question, suggest a new functionality or contribute to the code (the latter is particularly welcome)!
@@ -42,9 +42,11 @@ a bug, ask a question, suggest a new functionality or contribute to the code (th
    :hidden:
 
    tutos
-   tutorials/01_quickstart.ipynb
+   tutorials/01A_quickstart.ipynb
+   tutorials/01B_quickstart_with_objects.ipynb
    tutorials/02_preproc.ipynb
-   tutorials/03_psfsub.ipynb
+   tutorials/03A_psfsub.ipynb
+   tutorials/03B_psfsub_as_objects.ipynb
    tutorials/04_metrics.ipynb
    tutorials/05_fm_planets.ipynb
    tutorials/06_fm_disk.ipynb