VIP Documentation Release 0.8.1

Carlos Gomez Gonzalez, Olivier Wertz & VORTEX team

Nov 17, 2017

Contents

1 Attribution 3

2 Introduction 5

3 Jupyter notebook tutorial 7

4 Mailing list 9

5 Quick Setup Guide 11

6 Installation and dependencies 13 6.1 Installation and dependencies...... 13 6.2 Loading VIP...... 14

7 Frequently asked questions 15 7.1 FAQ...... 15

8 Package structure 17 8.1 vip package...... 19

9 API 21

i ii VIP Documentation, Release 0.8.1

Contents 1 VIP Documentation, Release 0.8.1

2 Contents CHAPTER 1

Attribution

Please cite Gomez Gonzalez et al. 2016 (submitted) whenever you publish data reduced with VIP. Astrophysics Source Code Library reference [ascl:1603.003]

3 VIP Documentation, Release 0.8.1

4 Chapter 1. Attribution CHAPTER 2

Introduction

VIP is an open source package/pipeline for angular, reference star and spectral differential imaging for exoplanet/disk detection through high-contrast imaging. VIP is being developed by the VORTEX team and collaborators. You can check on github the direct contributions to the code (tab contributors). Most of VIP‘s functionalities are mature but it doesn’t mean it’s free from bugs. The code will continue evolving and therefore all the feedback and contributions will be greatly appreciated. If you want to report a bug, suggest or add a functionality please create an issue or send a pull request on the github repository. The goal of VIP is to incorporate robust, efficient, easy-to-use, well-documented and open source 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. Github is a repository hosting service with an amazing web front-end for source-code management and collaboration. It provides features such as access control, bug tracking, feature requests, task management, and wikis for every project. VIP is being developed in Python 2.7, a modern open source high-level programming language, able to express a large amount of functionality per line of code. Python has a vast ecosystem of scientific open source libraries/packages (e.g. numpy, scipy, astropy, scikit-learn, scikit-image) and many well-known libraries have python bindings as well (e.g. opencv). On top of that exist a great tool, the Jupyter (né IPython) notebook. A notebook file is simple a JSON document, containing text, source code, rich media output, and metadata. It allows to combine data analysis and visualization into an easily sharable format.

5 VIP Documentation, Release 0.8.1

6 Chapter 2. Introduction CHAPTER 3

Jupyter notebook tutorial

VIP tutorial (Jupyter notebook) is available in this repository and can be visualized online here.

7 VIP Documentation, Release 0.8.1

8 Chapter 3. Jupyter notebook tutorial CHAPTER 4

Mailing list

You can subscribe to our mailing list if you want to be informed of the latest developments of the VIP package (new versions and/or updates).

9 VIP Documentation, Release 0.8.1

10 Chapter 4. Mailing list CHAPTER 5

Quick Setup Guide

TL;DR:

$ pip install git+https://github.com/vortex-exoplanet/VIP.git

11 VIP Documentation, Release 0.8.1

12 Chapter 5. Quick Setup Guide CHAPTER 6

Installation and dependencies

Here you can find a more detailed description of VIP‘s dependencies, how to clone the repository and install Opencv (optional).

6.1 Installation and dependencies

The benefits of a python package manager or distribution, such as Anaconda or Canoy, are multiple. 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 OSX. I personally recommend using Miniconda which you can find here: https://conda.io/miniconda.html. VIP depends on existing packages from the Python ecosystem, such as numpy, scipy, matplotlib, pandas, astropy, scikit-learn, scikit-image, photutils and emcee. There are different ways of installing VIP suitable for different scenarios.

6.1.1 Using PIP

The easiest way is to install it from the Python Package Index, aka Pypi, with the package manager pip:

$ pip install vip_hci

With pip you can easily uninstall VIP or install specific version of it. Alternatively, you could run pip install and point to the Github repository:

$ pip install git+https://github.com/vortex-exoplanet/VIP.git

6.1.2 Using the setup.py file

You can download VIP from its Github repository as a zip file. A setup.py file (Setuptools Python package) is included in the root folder of VIP. Enter the root folder and run:

13 VIP Documentation, Release 0.8.1

$ python setup.py install

6.1.3 Using GIT

If you want to use the git functionalities, you need to clone the repository (make sure your system has git installed):

$ git clone https://github.com/vortex-exoplanet/VIP.git

Then you need to install the package by following the previous steps, using the setup.py file.

6.1.4 Other dependencies

Opencv (Open source Computer Vision) provides fast c++ image processing operations and is used by VIP for basic image transformations (starting from version 0.5.2 of VIP the dependency on opencv is optional). If you don’t have/want the opencv python bindings, VIP will use the much slower ndimage/scikit-image libraries transparently. Installing opencv library is nowadays and easy process that is done automatically with the VIP installation. Alternatively, you could use conda:

$ conda install opencv

VIP ships a stripped-down version of RO.DS9 (by Russell Owen) for convenient xpaset/xpaget based interaction with DS9. VIP contains a class vipDS9 that works on top of RO.DS9 containing several useful methods for DS9 control such as displaying arrays, manipulating regions, controlling the display options, etc. VipDS9 functionality will only be available if you have DS9 and XPA installed on your system PATH. Also, optionally you can install the Intel Math Kernel Library (MKL) optimizations provided that you have Ana- conda(>v2.5) and conda on your system. This is recommended along with Opencv for maximum speed on VIP computations. Run:

$ conda install mkl

Starting from version 0.8.0 VIP offers the possibility of computing SVDs on GPU by using cupy. This remains an optional requirement, to be installed by the user, as it requires having and actual GPU card and a proper CUDA environment.

6.2 Loading VIP

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!

14 Chapter 6. Installation and dependencies CHAPTER 7

Frequently asked questions

Check out this questions if you find problems when installing or running VIP for the first time.

7.1 FAQ

First things first. Please make sure you have the latest version of VIP. Please go and check the repository now! • On linux, why do I get a matplotlib related error when importing VIP? ImportError: Matplotlib qt-based backends require an external PyQt4, PyQt5, or PySide package to be installed, but it was not found. You may need to change the matplotlib backend. Find your matplotlibrc configuration file and change the backend from WXAgg to TkAgg (or the appropriate backend for your sytem). More info here: http: //matplotlib.org/faq/usage_faq.html#what-is-a-backend. On linux the matplotlibrc file is located in:

$HOME/.config/matplotlib/matplotlibrc

• Why do I get, in OSX, the following RuntimeError? Python is not installed as a framework. The Mac OS X backend will not be able to function correctly if Python is not installed as a framework. See the Python documentation for more information on installing Python as a framework on Mac OS X. Please either reinstall Python as a framework, or try one of the other backends. Again, this is a matplotlib- backend related issue. Read the link in the previous answer. It can be solved setting the backend to WXAgg or TkAgg. Optionally, you can change your matplotlib backend before importing VIP:

import matplotlib as mpl mpl.use('TkAgg') import vip

• The VIP setup.py script doesn’t finish the job, it seems to be stuck. What to do? This is very unlikely to happen with the latest versions of pip, setuptools and VIP‘s setup script. If you en- counter this situation just kill the process (Ctrl + C) and start it again by re-running the setup command. A workaround is to install the problematic dependency before executing VIP setup:

15 VIP Documentation, Release 0.8.1

$ pip install

• Why the setup fails complaining about the lack of a Fortran compiler? Fortran compilers are apparently needed for compiling Scipy from source. Make sure there is a Fortran compiler in your system. A workaround is to install Scipy through conda before running the setup script:

$ conda install scipy

• Why do I get and error related to importing cv2 package when importing VIP? cv2 is the name of Opencv bindings for python. This library is needed for fast image transformations, it is the default library used although it is optional. You can install it with conda:

$ conda install opencv

• Why do I get a warning related to DS9/XPA when importing VIP? Please make sure you have DS9 and XPA in your system path. Try installing them using your system’s package management tool. • Why Python crashes when using some of the parallel functions, e.g. pca_adi_annular and run_mcmc_astrometry? These functions require running SVD on several processes and this can be problematic depending on the linear algebra libraries on your machine. We’ve encountered this problem on OSX systems that use the ACCELERATE library for linear algebra calculations (default in every OSX system). For this library the multiprocessing is broken. A workaround is to compile Python against other linear algebra library (e.g. OPENBLAS). An quick-n-easy fix is to install the latest ANACONDA (2.5 or later) distribution which ships MKL library and effectively replaces ACCELERATE on OSX systems. On linux with the default LAPACK/BLAS libraries VIP successfully distributes the SVDs among all the existing cores. With conda you can run:

$ conda install mkl

• I get an error: ValueError: “unknown locale: UTF-8” when importing VIP. It’s not VIP‘s fault. The problem must be solved if you add these lines in your ~/.bash_profile:

export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8

16 Chapter 7. Frequently asked questions CHAPTER 8

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 e.g. image registration, image rotation, pixel temporal and spatial subsampling. On top of that several pre-processing functions are available such as re-centering and bad frame detection. For Angular differential imaging (ADI) data several point spread function subtraction techniques are available, from a simple median subtraction to different low-rank approximations. Principal Component Analysis (PCA) methods are implemented in different flavours. Also PCA can process RDI and multiple channel SDI (IFS) data. VIP contains a first version 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. Flux and position of point-like sources are estimated using the Negative Fake Companion technique. VIP also imple- ments algorithm throughput and contrast-curve generation routines.

17 VIP Documentation, Release 0.8.1

18 Chapter 8. Package structure VIP Documentation, Release 0.8.1

8.1 vip package

8.1.1 Subpackages vip.calib package

Submodules vip.calib.badframes module vip.calib.badpixremoval module vip.calib.cosmetics module vip.calib.cosmetics_ifs module vip.calib.derotation module vip.calib.parangles module vip.calib.recentering module vip.calib.rescaling module vip.calib.subsampling module vip.conf package

Submodules vip.conf.mem module vip.conf.param module vip.conf.timing module vip.conf.utils_conf module vip.exlib package

Submodules vip.exlib.ds9 module vip.exlib.ds9_getDirs module vip.exlib.ds9_getMacDirs module

8.1.vip.exlib.ds9_getWinDirs vip package module 19 vip.exlib.iuwt module vip.fits package

Submodules vip.fits.fits module vip.fits.vipds9_source module vip.llsg package

Submodules vip.llsg.llsg module vip.llsg.thresholding module vip.madi package

Submodules vip.madi.adi_source module vip.negfc package

Submodules vip.negfc.mcmc_sampling module vip.negfc.simplex_fmerit module vip.negfc.simplex_optim module vip.negfc.utils_negfc module vip.nmf package

Submodules vip.nmf.nmf_fullfr module vip.pca package

Submodules vip.pca.pca_fullfr module vip.pca.pca_local module vip.pca.utils_pca module vip.phot package

Submodules vip.phot.contrcurve module vip.phot.detection module vip.phot.fakecomp module vip.phot.frame_analysis module vip.phot.snr module vip.stats package

Submodules vip.stats.clip_sigma module vip.stats.cube_stats module vip.stats.distances module vip.stats.im_stats module vip.stats.utils_stats module vip.var package

Submodules vip.var.filters module vip.var.fit_2d module vip.var.shapes module vip.var.utils_var module VIP Documentation, Release 0.8.1

20 Chapter 8. Package structure CHAPTER 9

API

• genindex • modindex • search

21