Eclipse Populations¶

All physical eclipse models proposed as potential explanations for an obseved transit signal are defined as EclipsePopulation objects. Currently implemented within vespa are EBPopulation, HEBPopulation, BEBPopulation, and PlanetPopulation.

Note

More subclasses are under development for other scenarios, in particular eclipses around specific observed stars.

Also see the documentation for vespa.stars.StarPopulation, from which EclipsePopulation derives.

class vespa.populations.EclipsePopulation(stars=None, period=None, model='', priorfactors=None, lhoodcachefile=None, orbpop=None, prob=None, cadence=0.018819444444444444, **kwargs)[source]¶

Base class for populations of eclipsing things.

This is the base class for populations of various scenarios that could explain a tranist signal; that is, astrophysical false positives or transiting planets.

Once set up properly, EclipsePopulation.fit_trapezoids() can be used to fit the trapezoidal shape parameters, after which the likelihood of a transit signal under the model may be calculated.

Subclasses vespa.stars.StarPopulation, which enables all the functionality of observational constraints.

if prob is not passed; should be able to calculated from given star/orbit properties.

As with vespa.stars.StarPopulation, any subclass must be able to be initialized with no arguments passed, in order for vespa.stars.StarPopulation.load_hdf() to work properly.

Parameters:

stars – DataFrame with star properties. Must contain M_1, M_2, R_1, R_2, u1_1, u1_2, u2_1, u2_2. Also, either the period keyword argument must be provided or a period column should be in stars. stars must also have the eclipse parameters: ‘inc, ecc, w, dpri, dsec, b_sec, b_pri, fluxfrac_1, fluxfrac_2`.
period – (optional) Orbital period. If not provided, then stars must have period column.
model – (optional) Name of the model.
priorfactors – (optional) Multiplicative factors that quantify the model prior for this particular model; e.g. f_binary, etc.
lhoodcachefile – (optional) File where likelihood calculation cache is written.
orbpop (orbits.OrbitPopulation or orbits.TripleOrbitPopulation) – (optional) Orbit population.
prob – (optional) Averaged eclipse probability of scenario instances. If not provided, this should be calculated, though this is not implemented yet.
cadence – (optional) Observing cadence, in days. Defaults to Kepler value.
**kwargs –
Additional keyword arguments passed to vespa.stars.StarPopulation.

add_priorfactor(**kwargs)[source]¶

Adds given values to priorfactors

If given keyword exists already, error will be raised to use EclipsePopulation.change_prior() instead.

apply_secthresh(*args, **kwargs)[source]¶: Another name for constrain_secdepth

change_prior(**kwargs)[source]¶

Changes existing priorfactors.

If given keyword isn’t already in priorfactors, then will be ignored.

constrain_secdepth(thresh)[source]¶

Constrain the observed secondary depth to be less than a given value

Parameters:	thresh – Maximum allowed fractional depth for diluted secondary eclipse depth

depth¶: Observed primary depth (fitted undiluted depth * dilution factor)

depth_in_band(band)[source]¶: Stub for future multicolor transit implementation

dilution_factor¶: Multiplicative factor (<1) that converts true depth to diluted depth.

eclipse_new(i, secondary=False, npoints=200, width=3, texp=None)[source]¶: Returns times and fluxes of eclipse i (centered at t=0)

eclipseprob¶: Array of eclipse probabilities.

fit_trapezoids(MAfn=None, msg=None, use_pbar=True, **kwargs)[source]¶

Fit trapezoid shape to each eclipse in population

For each instance in the population, first the correct, physical Mandel-Agol transit shape is simulated, and then this curve is fit with a trapezoid model

Parameters:	MAfn – `transit_basic.MAInterpolationFunction` object. If not passed, then one with default parameters will be created. msg – Message to be displayed for progressbar output. **kwargs – Additional keyword arguments passed to `fitebs.fitebs()`.

fluxfrac_eclipsing(band=None)[source]¶: Stub for future multicolor transit implementation

lhood(trsig, recalc=False, cachefile=None)[source]¶

Returns likelihood of transit signal

Returns sum of trsig MCMC samples evaluated at self.kde.

Parameters:	trsig – `vespa.TransitSignal` object. recalc – (optional) Whether to recalculate likelihood (if calculation is cached). cachefile – (optional) File that holds likelihood calculation cache.

lhoodplot(trsig=None, fig=None, piechart=True, figsize=None, logscale=True, constraints='all', suptitle=None, Ltot=None, maxdur=None, maxslope=None, inverse=False, colordict=None, cachefile=None, nbins=20, dur_range=None, slope_range=None, depth_range=None, recalc=False, **kwargs)[source]¶

Makes plot of likelihood density function, optionally with transit signal

If trsig not passed, then just density plot of the likelidhoo will be made; if it is passed, then it will be plotted over the density plot.

Parameters:

trsig – (optional) vespa.TransitSignal object.
fig – (optional) Argument for plotutils.setfig().
piechart – (optional) Whether to include a plot of the piechart that describes the effect of the constraints on the population.
figsize – (optional) Passed to plotutils.setfig().
logscale – (optional) If True, then shading will be based on the log-histogram (thus showing more detail at low density). Passed to vespa.stars.StarPopulation.prophist2d().
constraints – ('all', 'none' or list; optional) Which constraints to apply in making plot. Picking specific constraints allows you to visualize in more detail what the effect of a constraint is.
suptitle – (optional) Title for the figure.
Ltot – (optional) Total of prior * likelihood for all models. If this is passed, then “Probability of scenario” gets a text box in the middle.
inverse – (optional) Intended to allow showing only the instances that are ruled out, rather than those that remain. Not sure if this works anymore.
colordict – (optional) Dictionary to define colors of constraints to be used in pie chart. Intended to unify constraint colors among different models.
cachefile – (optional) Likelihood calculation cache file.
nbins – (optional) Number of bins with which to make the 2D histogram plot; passed to vespa.stars.StarPopulation.prophist2d().
slope_range, depth_range (dur_range,) – (optional) Define ranges of plots.
**kwargs –
Additional keyword arguments passed to vespa.stars.StarPopulation.prophist2d().

classmethod load_hdf(filename, path='')[source]¶

Loads EclipsePopulation from HDF file

Also runs EclipsePopulation._make_kde() if it can.

Parameters:	filename – HDF file path – (optional) Path within HDF file

mean_eclipseprob¶: Mean eclipse probability for population

modelshort¶

Short version of model name

Dictionary defined in populations.py:

SHORT_MODELNAMES = {'Planets':'pl',
        'EBs':'eb',
        'HEBs':'heb',
        'BEBs':'beb',
        'Blended Planets':'bpl',
        'Specific BEB':'sbeb',
        'Specific HEB':'sheb'}

prior¶

Model prior for particular model.

Product of eclipse probability (self.prob), the fraction of scenario that is allowed by the various constraints (self.selectfrac), and all additional factors in self.priorfactors.

resample()[source]¶

Returns a copy of population with stars resampled (with replacement).

Used in bootstrap estimate of FPP uncertainty.

TODO: check to make sure constraints properly copied!

secondary_depth¶: Observed secondary depth (fitted undiluted sec. depth * dilution factor)

Undiluted Eclipsing Binary¶

class vespa.populations.EBPopulation(period=None, cadence=0.018819444444444444, mags=None, mag_errs=None, Teff=None, logg=None, feh=None, starmodel=None, band='Kepler', model='EBs', f_binary=0.4, n=20000.0, MAfn=None, lhoodcachefile=None, **kwargs)[source]¶

Population of Eclipsing Binaries (undiluted)

Eclipsing Binary (EB) population is generated by fitting a two-star model to the observed properties of the system (photometric and/or spectroscopic), using isochrones.starmodel.BinaryStarModel.

Inherits from EclipsePopulation and stars.Observed_BinaryPopulation.

Parameters:

period – Orbital period
mags (dict) – Observed apparent magnitudes. Won’t work if this is None, which is the default.
Teff,logg,feh – Spectroscopic properties of primary, if measured, in (value, err) format.
starmodel (isochrones.BinaryStarModel) – (optional) Must be a BinaryStarModel. If MCMC has been run on this model, then samples are just read off; if it hasn’t, then it will run it.
band – (optional) Photometric bandpass in which transit signal is observed.
model – (optional) Name of model.
f_binary – (optional) Binary fraction to be assumed. Will be one of the priorfactors.
n – (optional) Number of instances to simulate. Default = 2e4.
MAfn – (optional) transit_basic.MAInterpolationFunction object. If not passed, then one with default parameters will be created.
lhoodcachefile – (optional) Likelihood calculation cache file.

generate(mags, n=20000.0, mag_errs=None, Teff=None, logg=None, feh=None, MAfn=None, f_binary=0.4, starmodel=None, **kwargs)[source]¶

Generates stars and eclipses

All arguments previously defined.

Hierarchical Elipsing Binary¶

class vespa.populations.HEBPopulation(period=None, cadence=0.018819444444444444, mags=None, mag_errs=None, Teff=None, logg=None, feh=None, starmodel=None, band='Kepler', model='HEBs', f_triple=0.12, n=20000.0, MAfn=None, lhoodcachefile=None, **kwargs)[source]¶

Population of Hierarchical Eclipsing Binaries

Hierarchical Eclipsing Binary (HEB) population is generated by fitting a two-star model to the observed properties of the system (photometric and/or spectroscopic), using isochrones.starmodel.BinaryStarModel.

by

Inherits from EclipsePopulation and stars.Observed_TriplePopulation.

Parameters:

period – Orbital period
mags,mag_errs – Observed apparent magnitudes; uncertainties optional. If uncertainties not provided, Observed_TriplePopulation will default to uncertainties in all bands of 0.05 mag.
Teff,logg,feh – Spectroscopic properties of primary, if measured, in (value, err) format.
starmodel (isochrones.BinaryStarModel) – (optional) Must be a BinaryStarModel. If MCMC has been run on this model, then samples are just read off; if it hasn’t, then it will run it.
band – (optional) Photometric bandpass in which transit signal is observed.
model – (optional) Name of model.
f_binary – (optional) Binary fraction to be assumed. Will be one of the priorfactors.
n – (optional) Number of instances to simulate. Default = 2e4.
MAfn – (optional) transit_basic.MAInterpolationFunction object. If not passed, then one with default parameters will be created.
lhoodcachefile – (optional) Likelihood calculation cache file.

generate(mags, n=20000.0, mag_errs=None, Teff=None, logg=None, feh=None, MAfn=None, f_triple=0.12, starmodel=None, **kwargs)[source]¶

Generates stars and eclipses

All arguments previously defined.

Background Eclipsing Binary¶

class vespa.populations.BEBPopulation(period=None, cadence=0.018819444444444444, mags=None, ra=None, dec=None, trilegal_filename=None, n=20000.0, ichrone='mist', band='Kepler', maxrad=10, f_binary=0.4, model='BEBs', MAfn=None, lhoodcachefile=None, **kwargs)[source]¶

Population of “Background” eclipsing binaries (BEBs)

Parameters:

period – Orbital period.
mags (dict) – Observed apparent magnitudes of target (foreground) star. Must have at least magnitude in band that eclipse is measured in (band argument).
ra,dec – (optional) Coordinates of star (to simulate field star population). If trilegal_filename not provided, then TRILEGAL simulation will be generated.
trilegal_filename – Name of file that contains TRILEGAL field star simulation to use. Should always be provided if population is to be generated. If file does not exist, then TRILEGAL simulation will be saved as this filename (use .h5 extension).
n – (optional) Size of simulation. Default is 2e4.
ichrone – (optional) isochrones.Isochrone object to use to generate stellar models.
band – (optional) Photometric bandpass in which eclipse signal is observed.
maxrad – (optional) Maximum radius [arcsec] from target star to assign to BG stars.
f_binary – (optional) Assumed binary fraction. Will be part of priorfactors.
model – (optional) Model name.
MAfn – (optional) transit_basic.MAInterpolationFunction object. If not passed, then one with default parameters will be created.
lhoodcachefile – (optional) Likelihood calculation cache file.
**kwargs –
Additional keyword arguments passed to stars.BGStarPopulation_TRILEGAL.

generate(trilegal_filename, ra=None, dec=None, n=20000.0, ichrone='mist', MAfn=None, mags=None, maxrad=None, f_binary=0.4, **kwargs)[source]¶: Generate population.

Transiting Planet¶

class vespa.populations.PlanetPopulation(period=None, cadence=0.018819444444444444, rprs=None, mass=None, radius=None, Teff=None, logg=None, starmodel=None, band='Kepler', model='Planets', n=20000.0, fp_specific=None, u1=None, u2=None, rbin_width=0.3, MAfn=None, lhoodcachefile=None)[source]¶

Population of Transiting Planets

Subclass of EclipsePopulation. This is mostly a copy of EBPopulation, with small modifications.

Star properties may be defined either with either a isochrones.StarModel or by defining just its mass and radius (and Teff and logg if desired to set limb darkening coefficients appropriately).

Parameters:

period – Period of signal.
rprs – Point-estimate of Rp/Rs radius ratio.
radius (mass,) – (optional) Mass and radius of host star. If defined, must be either tuples of form (value, error) or simpledist.Distribution objects.
logg (Teff,) – (optional) Teff and logg point estimates for host star. These are used only for calculating limb darkening coefficients.
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.
band – (optional) Photometric band in which eclipse is detected.
model – (optional) Name of the model.
n – (optional) Number of instances to simulate. Default = 2e4.
fp_specific – (optional) “Specific occurrence rate” for this type of planets; that is, the planet occurrence rate integrated from (1-rbin_width)x to (1+rbin_width)x this planet radius. This goes into the priorfactor for this model.
u2 (u1,) – (optional) Limb darkening parameters. If not provided, then calculated based on Teff, logg or just defaulted to solar values.
rbin_width – (optional) Fractional width of rbin for fp_specific.
MAfn – (optional) transit_basic.MAInterpolationFunction object. If not passed, then one with default parameters will be created.
lhoodcachefile – (optional) Likelihood calculation cache file.

generate(rprs=None, mass=None, radius=None, n=20000.0, fp_specific=0.01, u1=None, u2=None, starmodel=None, Teff=None, logg=None, rbin_width=0.3, MAfn=None, lhoodcachefile=None)[source]¶

Generates Population

All arguments defined in __init__.

save_hdf(filename, path='', **kwargs)[source]¶

Saves to HDF5 file.

Subclasses should be sure to define _properties attribute to ensure that all correct attributes get saved. Load a saved population with StarPopulation.load_hdf().

Example usage:

>>> from vespa.stars import Raghavan_BinaryPopulation, StarPopulation
>>> pop = Raghavan_BinaryPopulation(1., n=1000)
>>> pop.save_hdf('test.h5')
>>> pop2 = StarPopulation.load_hdf('test.h5')
>>> pop == pop2
    True
>>> pop3 = Ragahavan_BinaryPopulation.load_hdf('test.h5')
>>> pop3 == pop2
    True

Parameters:

filename – Name of HDF file.
path – (optional) Path within HDF file to save object.
properties – (optional) Names of any properties (in addition to those defined in _properties attribute) that you wish to save. (This is an old keyword, and should probably be removed. Feel free to ignore it.)
overwrite – (optional) Whether to overwrite file if it already exists. If True, then any existing file will be deleted before object is saved. Use append if you don’t wish this to happen.
append – (optional) If True, then if the file exists, then only the particular path in the file will get written/overwritten. If False and both file and path exist, then an IOError will be raised. If False and file exists but not path, then no error will be raised.