README.rst

Note: Current recommendation is to retire VESPA in favor of TRICERATOPS (https://github.com/stevengiacalone/triceratops); see research note posted at https://iopscience.iop.org/article/10.3847/2515-5172/acd9a6 for more details.

VESPA

Validation of Exoplanet Signals using a Probabilistic Algorithm--- calculating false positive probabilities for transit signals

For usage and more info, check out the documentation.

Installation

To install, you can get the most recently released version from PyPI:

pip install vespa [--user]

Or you can clone the repository:

git clone https://github.com/timothydmorton/vespa.git
cd vespa
python setup.py install [--user]

The --user argument may be necessary if you don't have root privileges.

Depends on typical scientific packages (e.g. numpy, scipy, pandas), as well as isochrones, and (in several corners of the code), another package of mine called simpledist. All dependencies should get resolved upon install, though this has only been tested under the anaconda Python distribution, which has all the scientific stuff already well-organized.

For best results, it is also recommended to have MultiNest and pymultinest installed. Without this, emcee will be used for stellar modeling, but the MulitNest results are a bit more trustworthy given the often multi-modal nature of stellar model fitting.

Basic Usage

The simplest way to run an FPP calculation straight out of the box is as follows.

1. Make a text file containing the transit photometry in three columns: t_from_midtransit [days], flux [relative, where out-of-transit is normalized to unity], and flux_err. The file should not have a header row (no titles); and can be either whitespace or comma-delimited (will be ingested by np.loadtxt).

2. Make a star.ini file that contains the observed properties of the target star (photometric and/or spectroscopic, whatever is available):

   #provide spectroscopic properties if available
   #Teff = 3503, 80  #value, uncertainty
   #feh = 0.09, 0.09
   #logg = 4.89, 0.1
   
   #observed magnitudes of target star
   # If uncertainty provided, will be used to fit StarModel
   J = 9.763, 0.03
   H = 9.135, 0.03
   K = 8.899, 0.02
   Kepler = 12.473
   

3. Make a fpp.ini file containing the following information:

   name = k2oi #anything
   ra = 11:30:14.510 #can be decimal form too
   dec = +07:35:18.21
   
   period = 32.988 #days
   rprs = 0.0534   #Rp/Rstar best estimate
   photfile = lc_k2oi.csv #contains transit photometry
   
   [constraints]
   maxrad = 12  # aperture radius [arcsec]
   secthresh = 1e-4 # Maximum allowed depth of potential secondary eclipse
   

4. Run the following from the command line (from within the same folder that has star.ini and fpp.ini):

   $  calcfpp
   

Or, if you put the files in a folder called mycandidate, then you can run calcfpp mycandidate:

This will run the calculation for you, creating result files, diagnostic plots, etc. It should take 20-30 minutes. If you want to do a shorter version to test, you can try calcfpp -n 1000 (the default is 20000). The first time you run it though, about half the time is doing the stellar modeling, so it will still take a few minutes.

Attribution

If you use this code, please cite both the paper and the code.

Paper citation:

@ARTICLE{2012ApJ...761....6M,
author = {{Morton}, T.~D.},
title = "{An Efficient Automated Validation Procedure for Exoplanet Transit Candidates}",
journal = {\apj},
archivePrefix = "arXiv",
eprint = {1206.1568},
primaryClass = "astro-ph.EP",
keywords = {planetary systems, stars: statistics },
year = 2012,
month = dec,
volume = 761,
eid = {6},
pages = {6},
doi = {10.1088/0004-637X/761/1/6},
adsurl = {http://adsabs.harvard.edu/abs/2012ApJ...761....6M},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

code:

@MISC{2015ascl.soft03011M,
   author = {{Morton}, T.~D.},
    title = "{VESPA: False positive probabilities calculator}",
howpublished = {Astrophysics Source Code Library},
     year = 2015,
    month = mar,
archivePrefix = "ascl",
   eprint = {1503.011},
   adsurl = {http://adsabs.harvard.edu/abs/2015ascl.soft03011M},
  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}