VIP Documentation. Release Carlos Alberto Gomez Gonzalez, Olivier Wertz & VORTEX team

Transcription

1 VIP Documentation Release Carlos Alberto Gomez Gonzalez, Olivier Wertz & VORTEX team Feb 17, 2018

2

3 Contents 1 Introduction 3 2 Documentation 5 3 Jupyter notebook tutorial 7 4 TL;DR setup guide 9 5 Installation and dependencies Using PIP Using the setup.py file Using GIT Other dependencies Loading VIP Mailing list 13 7 Attribution 15 8 Frequently asked questions FAQ Package structure API 21 i

4 ii

5 VIP Documentation, Release Contents 1

6 VIP Documentation, Release Contents

7 CHAPTER 1 Introduction VIP is a python package for angular, reference star and spectral differential imaging for exoplanet/disk detection through high-contrast imaging. VIP is compatible with Python 2.7 and 3.6. The goal of VIP is to incorporate open-source, efficient, easy-to-use and well-documented implementations of highcontrast 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 is led by C. Gomez with contributions made by collaborators from several teams (take a look at the tab contributors on VIP s Github repository). 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, suggest or add a functionality please create an issue or send a pull request here. 3

8 VIP Documentation, Release Chapter 1. Introduction

9 CHAPTER 2 Documentation The documentation for VIP can be found here: 5

10 VIP Documentation, Release Chapter 2. Documentation

11 CHAPTER 3 Jupyter notebook tutorial A tutorial (Jupyter notebook) showing he use of VIP for ADI data processing is available in this repository. Alternatively, it can be visualized online here. If you are new to the Jupyter notebook application check out the beginner guide. 7

12 VIP Documentation, Release Chapter 3. Jupyter notebook tutorial

13 CHAPTER 4 TL;DR setup guide $ pip install vip_hci 9

14 VIP Documentation, Release Chapter 4. TL;DR setup guide

15 CHAPTER 5 Installation and dependencies The benefits of using a Python package manager (distribution), such as Anaconda 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. I personally recommend using Miniconda which you can find here: 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. 5.1 Using PIP 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 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: 11

16 VIP Documentation, Release $ python setup.py install 5.3 Using GIT If you want to benefit from the git functionalities, you need to clone the repository (make sure your system has git installed): $ git clone Then you can install the package by following the previous steps, using the setup.py file. Creating a fork with Github is recommended to developers or to users who want to experiment with the code. 5.4 Other dependencies Opencv (Open source Computer Vision) provides fast c++ image processing operations and is used by VIP for basic image transformations. If you don t have/want the opencv python bindings (opencv is optional since VIP v0.5.2), VIP will use the much slower ndimage/scikit-image libraries transparently. Fortunately, 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 Anaconda(>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 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 a real (good) GPU card and a proper CUDA environment. 5.5 Loading VIP 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! 12 Chapter 5. Installation and dependencies

17 CHAPTER 6 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). 13

18 VIP Documentation, Release Chapter 6. Mailing list

19 CHAPTER 7 Attribution Please cite Gomez Gonzalez et al ( whenever you publish data reduced with VIP. Astrophysics Source Code Library reference [ascl: ]. 15

20 VIP Documentation, Release Chapter 7. Attribution

21 CHAPTER 8 Frequently asked questions Check out this questions if you find problems when installing or running VIP for the first time. 8.1 FAQ First things first. Please make sure you have the latest version of VIP. Please go and check the repository now. Alternatively, you can run: $ pip install --upgrade vip_hci 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 I get a RuntimeError (Python is not installed as a framework) in Macosx, when using python3 and conda. Why? This is caused by using matplotlib with virtual environments or conda in Macosx, and has nothing to do with VIP. See Working with Matplotlib on OSX in the Matplotlib FAQ for more information. 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 encounter 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: $ pip install <problematic_dependency> Why the setup fails complaining about the lack of a Fortran compiler? 17

22 VIP Documentation, Release 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 18 Chapter 8. Frequently asked questions

23 CHAPTER 9 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 implements algorithm throughput and contrast-curve generation routines. 19

24 VIP Documentation, Release Chapter 9. Package structure

25 CHAPTER 10 API genindex modindex search 21