VIP Documentation Release 0.8.1
Total Page:16
File Type:pdf, Size:1020Kb
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 <problematic_dependency> • 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.