---------------------------------------------------
oooooo oooo ooooo ooooooooo.
`888. .8' `888' `888 `Y88.
`888. .8' 888 888 .d88'
`888. .8' 888 888ooo88P'
`888.8' 888 888
`888' 888 888
`8' o888o o888o
---------------------------------------------------
Vortex Image Processing package
---------------------------------------------------
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 (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, 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, a former PhD student of the VORTEX team (ULiege, Belgium). VIP
's development has 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. 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!
The documentation for VIP
can be found here: http://vip.readthedocs.io.
Tutorials, in the form of Jupyter notebooks, showcasing VIP
's usage and other resources such as test/dummy datasets are available on the VIP-extras
repository. Alternatively, you can execute this repository on Binder. The notebook for ADI processing can be visualized online with nbviewer. If you are new to the Jupyter notebook application check out the beginner's guide.
$ pip install vip_hci
The benefits of using a Python package manager (distribution), such as (ana)conda or Canopy, 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.
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.
The easiest way to install VIP
is through the Python Package Index, aka PyPI, with the pip
package manager. Simply run:
$ pip install vip_hci
With pip
you can easily uninstall, upgrade or install a specific version of VIP
. For upgrading the package run:
$ pip install --upgrade vip_hci
Alternatively, you can use pip install
and point to the GitHub repo:
$ pip install git+https://github.com/vortex-exoplanet/VIP.git
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:
$ python setup.py install
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:
$ git clone https://github.com/<replace-by-your-username>/VIP.git
If you do not create a fork, you can still benefit from the git
syncing 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):
$ conda create -n vipenv python=3.7 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:
$ cd VIP
$ python setup.py develop
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:
$ 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 also install the optional dependencies listed below.
- The following dependencies are not automatically installed upon installation of
VIP
but may significantly improve your experience:
VIP
contains a class vip_hci.fits.ds9
that enables, through pyds9
, the interaction with a DS9 window (displaying numpy arrays, controlling the display options, etc). pyds9
is an optional requirement and 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.
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
.
Finally, start Python (or IPython or a Jupyter notebook if you prefer) and check that you are able to import VIP
:
import vip_hci as vip
If everything went fine with the installation, you will see a welcome message. Now you can start finding exoplanets!
Please subscribe to our mailing list if you want to be informed of VIP
's latest developments (new versions and/or updates).
Please cite Gomez Gonzalez et al. (2017) 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);
- leastsq: Lafrenière et al. (2007);
- llsg: Gomez Gonzalez et al. (2016);
- medsub: Marois et al. (2006) for ADI and Sparks and Ford (2002) for SDI;
- negfc: Wertz et al. (2017);
- nmf: Ren et al. (2018);
- pca: Amara and Quanz (2012) and Soummer et al. (2012);
- specfit: Christiaens et al. (2021);