High-level API

This page details the top-level classes that provide access to the vespa module. The simplest entry point into these calculations is the calcfpp command-line script, which creates a FPPCalculation object using FPPCalculation.from_ini(), and creates a bunch of data files/diagnostic plots. A FPPCalculation is made up of a PopulationSet and a TransitSignal.

For more details on the guts of the objects that make up a PopulationSet, please see the documentation on Eclipse Populations, Star Populations, and Orbits.

FPPCalculation

class vespa.FPPCalculation(trsig, popset, folder='.')

An object to organize an FPP calculation.

May be created in one of three ways:

• Manually building a TransitSignal and a PopulationSet and then calling the constructor,
• Loading from a folder in which the correct data files have been saved, using FPPCalculation.load(), or
• Reading from a config file, using FPPCalculation.from_ini()

Parameters:

• trsig – TransitSignal object representing the signal being modeled.
• popset – PopulationSet object representing the set of models being considered as an explanation for the signal.
• folder – (optional) Folder where likelihood cache, results file, plots, etc. are written by default.

FPP(skipmodels=None)

Return the false positive probability (FPP)

FPPplots(folder=None, format='png', tag=None, **kwargs)

Make FPP diagnostic plots

Makes likelihood “fuzz plot” for each model, a FPP summary figure, a plot of the TransitSignal, and writes a results.txt file.

Parameters:

• folder – (optional) Destination folder for plots/results.txt. Default is self.folder.
• format – (optional) Desired format of figures. e.g. png, pdf…
• tag – (optional) If this is provided (string), then filenames will have _[tag] appended to the filename, before the extension.
• **kwargs –

  Additional keyword arguments passed to PopulationSet.lhoodplots().

FPPsummary(fig=None, figsize=(10, 8), saveplot=False, folder='.', starinfo=True, siginfo=True, priorinfo=True, constraintinfo=True, tag=None, simple=False, figformat='png')

Makes FPP summary plot

Note

This is due for updates/improvements.

Parameters:

• figsize (fig,) – (optional) Arguments for plotutils.setfig().
• saveplot – (optional) Whether to save figure. Default is False.
• folder – (optional) Folder to which to save plot; default is current working dir.
• figformat – (optional) Desired format of saved figure.

classmethod from_ini(folder, ini_file='fpp.ini', ichrone='mist', recalc=False, refit_trap=False, **kwargs)

To enable simple usage, initializes a FPPCalculation from a .ini file

By default, a file called fpp.ini will be looked for in the current folder. Also present must be a star.ini file that contains the observed properties of the target star.

fpp.ini must be of the following form:

name = k2oi
ra = 11:30:14.510
dec = +07:35:18.21

period = 32.988 #days
rprs = 0.0534   #Rp/Rstar
photfile = lc_k2oi.csv

[constraints]
maxrad = 10 #exclusion radius [arcsec]
secthresh = 0.001 #maximum allowed secondary signal depth

#This variable defines contrast curves
#ccfiles = Keck_J.cc, Lick_J.cc

Photfile must be a text file with columns (days_from_midtransit, flux, flux_err). Both whitespace- and comma-delimited will be tried, using np.loadtxt. Photfile need not be there if there is a pickled TransitSignal saved in the same directory as ini_file, named trsig.pkl (or another name as defined by trsig keyword in .ini file).

star.ini should look something like the following:

B = 15.005, 0.06
V = 13.496, 0.05
g = 14.223, 0.05
r = 12.858, 0.04
i = 11.661, 0.08
J = 9.763, 0.03
H = 9.135, 0.03
K = 8.899, 0.02
W1 = 8.769, 0.023
W2 = 8.668, 0.02
W3 = 8.552, 0.025
Kepler = 12.473

#Teff = 3503, 80
#feh = 0.09, 0.09
#logg = 4.89, 0.1

Any star properties can be defined; if errors are included then they will be used in the isochrones.StarModel MCMC fit. Spectroscopic parameters (Teff, feh, logg) are optional. If included, then they will also be included in isochrones.StarModel fit. A magnitude for the band in which the transit signal is observed (e.g., Kepler) is required, though need not have associated uncertainty.

Parameters:

• folder – Folder to find configuration files.
• ini_file – Input configuration file.
• star_ini_file – Input config file for isochrones.StarModel fits.
• recalc – Whether to re-calculate PopulationSet, if a popset.h5 file is already present
• **kwargs –

  Keyword arguments passed to PopulationSet.

Creates:

• trsig.pkl: the pickled vespa.TransitSignal object.
• starfield.h5: the TRILEGAL field star simulation
• starmodel.h5: the isochrones.StarModel fit
• popset.h5: the vespa.PopulationSet object representing the model population simulations.

RuntimeError :

If single, double, and triple starmodels are not computed, then raises with admonition to run starfit –all.

AttributeError :

If trsig.pkl not present in folder, and photfile is not defined in config file.

lhood(model, **kwargs)

Return the likelihood for a given model.

lhoodplot(model, suptitle='', **kwargs)

Make a plot of the likelihood for a given model.

lhoodplots(folder='.', tag=None, figformat='png', recalc_lhood=False, **kwargs)

Make a plot of the likelihood for each model in PopulationSet

classmethod load(folder)

Loads PopulationSet from folder

popset.h5 and trsig.pkl must exist in folder.

Parameters:folder – Folder from which to load.

plotsignal(fig=None, saveplot=True, folder=None, figformat='png', **kwargs)

Plots TransitSignal

Calls TransitSignal.plot(), saves to provided folder.

Parameters:

• fig – (optional) Argument for plotutils.setfig().
• saveplot – (optional) Whether to save figure.
• folder – (optional) Folder to which to save plot
• figformat – (optional) Desired format for figure.
• **kwargs –

  Additional keyword arguments passed to TransitSignal.plot().

prior(model)

Return the prior for a given model.

save(overwrite=True)

Saves PopulationSet and TransitSignal.

Shouldn’t need to use this if you’re using FPPCalculation.from_ini().

Saves :class`PopulationSet` to [folder]/popset.h5] and TransitSignal to [folder]/trsig.pkl.

Parameters:overwrite – (optional) Whether to overwrite existing files.

save_popset(filename='popset.h5', **kwargs)

Saves the PopulationSet

Calls PopulationSet.save_hdf().

save_signal(filename=None)

Saves TransitSignal.

Calls TransitSignal.save(); default filename is trsig.pkl in self.folder.

write_results(folder=None, filename='results.txt', to_file=True)

Writes text file of calculation summary.

Parameters:

• folder – (optional) Folder to which to write results.txt.
• filename – Filename to write. Default=``results.txt``.
• to_file – If True, then writes file. Otherwise just return header, line.

Returns:

Header string, line

PopulationSet

This object is essentially an organized list of EclipsePopulation objects.

class vespa.PopulationSet(poplist=None, period=None, cadence=0.018819444444444444, mags=None, n=20000.0, ra=None, dec=None, trilegal_filename=None, Teff=None, logg=None, feh=None, starmodel=None, binary_starmodel=None, triple_starmodel=None, rprs=None, MAfn=None, savefile=None, heb_kws=None, eb_kws=None, beb_kws=None, pl_kws=None, hide_exceptions=False, fit_trap=True, do_only=None)

A set of EclipsePopulations used to calculate a transit signal FPP

This can be initialized with a list of EclipsePopulation objects that have been pre-generated, or it can be passed the arguments required to generate the default list of :class:`EclipsePopulation`s.

Parameters:

• poplist – Can be either a list of EclipsePopulation objects, a filename (in which case a saved PopulationSet will be loaded), or None, in which case the populations will be generated.
• period – Orbital period of signal.
• mags (dict) – Observed magnitudes of target star.
• n – Size of simulations. Default is 2e4.
• dec (ra,) – (optional) Target star position; passed to BEBPopulation.
• trilegal_filename – Passed to BEBPopulation.
• age, feh, radius (mass,) – (optional) Properties of target star. Either in (value, error) form or as simpledist.Distribution objects. Not necessary if starmodel is passed.
• starmodel (isochrones.StarModel) – (optional) The preferred way to define the properties of the host star. If MCMC has been run on this model, then samples are just read off; if it hasn’t, then it will run it.
• rprs – R_planet/R_star. Single-value estimate.
• MAfn – (optional) transit_basic.MAInterpolationFunction object. If not passed, then one with default parameters will be created.
• colors – (optional) Colors to use to constrain multiple star populations; passed to EBPopulation and HEBPopulation. Default will be [‘JK’, ‘HK’]
• logg (Teff,) – (optional) If starmodel not provided, then these can be used (single values only) in order for PlanetPopulation to use the right limb darkening parameters.
• savefile – (optional) HDF file in which to save PopulationSet.
• eb_kws, beb_kws, pl_kws (heb_kws,) – (optional) Keyword arguments to pass on to respective EclipsePopulation constructors.
• hide_exceptions – (optional) If True, then exceptions generated during population simulations will be passed, not raised.
• fit_trap – (optional) If True, then population generation will also call EclipsePopulation.fit_trapezoids() for each model population.
• do_only – (optional) Can be defined in order to make only a subset of populations. List or tuple should contain modelname shortcuts (e.g., ‘beb’, ‘heb’, ‘eb’, or ‘pl’).

add_population(pop)

Adds population to PopulationSet

apply_cc(cc, **kwargs)

Applies contrast curve constraint to each population

See vespa.stars.StarPopulation.apply_cc(); all arguments passed to that function for each population.

apply_dmaglim(dmaglim=None)

Applies a constraint that sets the maximum brightness for non-target star

stars.StarPopulation.set_dmaglim() not yet implemented.

apply_multicolor_transit(band, depth)

Applies constraint corresponding to measuring transit in different band

This is not implemented yet.

apply_secthresh(secthresh, **kwargs)

Applies secondary depth constraint to each population

See EclipsePopulation.apply_secthresh(); all arguments passed to that function for each population.

apply_trend_constraint(limit, dt, **kwargs)

Applies constraint corresponding to RV trend non-detection to each population

See stars.StarPopulation.apply_trend_constraint(); all arguments passed to that function for each population.

apply_vcc(vcc)

Applies velocity contrast curve constraint to each population

See vespa.stars.StarPopulation.apply_vcc(); all arguments passed to that function for each population.

change_prior(**kwargs)

Changes prior factor(s) in all populations

colordict

Dictionary holding colors that correspond to constraints.

constrain_oddeven(diff, **kwargs)

Constrains the difference b/w primary and secondary to be < diff

constrain_property(prop, **kwargs)

Constrains property for each population

See vespa.stars.StarPopulation.constrain_property(); all arguments passed to that function for each population.

constraints

Unique list of constraints among all populations in set.

generate(ra, dec, period, cadence, mags, n=20000.0, Teff=None, logg=None, feh=None, MAfn=None, rprs=None, trilegal_filename=None, starmodel=None, binary_starmodel=None, triple_starmodel=None, heb_kws=None, eb_kws=None, beb_kws=None, pl_kws=None, savefile=None, hide_exceptions=False, fit_trap=True, do_only=None)

Generates PopulationSet.

classmethod load_hdf(filename, path='')

Loads PopulationSet from file

modelnames

List of model names

priorfactors

Combinartion of priorfactors from all populations

remove_constraint(*names)

Removes constraint from each population

See :func:`vespa.stars.StarPopulation.remove_constraint

remove_population(pop)

Removes population from PopulationSet

replace_constraint(name, **kwargs)

Replaces removed constraint in each population.

See vespa.stars.StarPopulation.replace_constraint()

save_hdf(filename, path='', overwrite=False)

Saves PopulationSet to HDF file.

set_maxrad(newrad)

Sets max allowed radius in populations.

Doesn’t operate via the stars.Constraint protocol; rather just rescales the sky positions for the background objects and recalculates sky area, etc.

shortmodelnames

List of short modelnames.

TransitSignal

class vespa.TransitSignal(ts, fs, dfs=None, P=None, p0=None, name='', maxslope=None)

A phased-folded transit signal.

Epoch of the transit at 0, ‘continuum’ set at 1.

Parameters:

• fs, dfs (ts,) – Times (days from mid-transit), fluxes (relative to 1), flux uncertainties. dfs optional
• P – Orbital period.
• p0 – (optional) Initial guess for least-squares trapezoid fit. If not provided, then some decent guess will be made (which is better on made-up data than real…)
• name – (optional) Name of the signal.
• maxslope – (optional) Upper limit to use for “slope” parameter (T/tau) in the MCMC fitting of signal. Default is 15.

Note

The implementation of this object can use some refactoring; as it is directly translated from some older code. As such, not all methods/attributes are well documented.

MCMC(niter=500, nburn=200, nwalkers=200, threads=1, fit_partial=False, width=3, savedir=None, refit=False, thin=10, conf=0.95, maxslope=None, debug=False, p0=None)

Fit transit signal to trapezoid model using MCMC

Note

As currently implemented, this method creates a bunch of attributes relevant to the MCMC fit; I plan to refactor this to define those attributes as properties so as not to have their creation hidden away here. I plan to refactor how this works.

plot(fig=None, plot_trap=False, name=False, trap_color='g', trap_kwargs=None, **kwargs)

Makes a simple plot of signal

Parameters:

• fig – (optional) Argument for plotutils.setfig().
• plot_trap – (optional) Whether to plot the (best-fit least-sq) trapezoid fit.
• name – (optional) Whether to annotate plot with the name of the signal; can be True (in which case self.name will be used), or any arbitrary string.
• trap_color – (optional) Color of trapezoid fit line.
• trap_kwargs – (optional) Keyword arguments to pass to trapezoid fit line.
• **kwargs –

  (optional) Additional keyword arguments passed to plt.plot.

save(filename)

Calls save_pkl function.

save_hdf(filename, path='')

Save transitsignal info using HDF…not yet implemented.

Note

Refactoring plan is to re-write saving to use HDF instead of pickle.

save_pkl(filename)

Pickles TransitSignal.