API

The core classes within photoeccentric are the KeplerStar and KOI classes. After creating a photoeccentric.KeplerStar object with information about the host star of a KOI system, you will be able to create a photoeccentric.KOI object for each planet you wish to investigate. This photoeccentric.KOI object will allow you to fit and save information about the fit Kepler light curve, eccentricity posteriors, etc…)

The KOI object defines the planet in question.

class photoeccentric.KeplerStar(StarKOI)

get_KIC(muirhead_comb): Gets KIC number for KOI (star).

get_stellar_params(isodf): Gets stellar parameters from set of consistent stellar isochrones.

class photoeccentric.KOI(nkoi, StarKOI)

calc_a(smass, srad)

Calculates semi-major axis from planet period and stellar mass using Kepler’s 3rd law

period: float: Planet period (SECONDS)
smass: float: Stellar mass (Msol)
srad: float: Stellar radius (Rsol)

a: float: a/Rs: Semi-major axis of planet’s orbit (units of stellar radii)

calc_durations(): After fitting circular period, Rp/Rs, a/Rs, and inclination, calculates full and total transit duration of circular transit using Winn (2010) Eqs. 14, 15.

delete_nans(): Deletes nans from self.time, self.flux, and self.fluxerr

do_tfit_exoplanet(tune=1000, draw=1000, save_trace=False, direct='ExampleDir', oversample=29, exptime=0.0201389, optimize=False)

Transit light curve fitting with exoplanet.

save_trace: boolean: Save output trace to directory?
direct: str: Output path.
oversample: int, default 29: Number of flux points over which to supersample, default 29 min (Kepler long cadence.)
exptime: float, default 0.0201389: Time over which to supersample, default 29 min (Kepler long cadence)
optimize: boolean: Optimize and start at map_soln?

trace:: pymc3 trace object

download_lightcurves(): Download Kepler lightcurves from MAST for a KOI.

download_planet_params(): Download stellar parameters for a KOI from the Exoplanet Archive.

get_gs(custom_rho_star='None'): Calculates g using Dawson & Johsnon (2012) Eq. 6.

get_midpoints(): Calculates transit midpoints within time bounds of Kepler light curve.

get_simultaneous_transits(KOIS, files=None): Gets a list of all transit midpoints for other transits in a system (specified as a list with KOIS)

get_stitched_lcs(files=None, cadence_combine=False, record_bounds=False)

Stitches Kepler LCs from a list of fits files downloaded from MAST.

files: list: List of FITS file paths containing light curves
KIC: float: KOI of target
cadence_combine: boolean: True if light curve files include both short- a nd long-cadence data. False otherwise.
record_bounds: boolean: True if recording start and end times of each light curve segment is desired. False otherwise.

None

normalize_flux(): Normalizes self.flux array.

planet_params_from_archive(df)

Get stellar parameters for the host of a KOI from exoplanet archive (downloaded data).

df: pandas.DataFrame: dataframe of exop. archive downloaded data
kepoiname: str: Kepler name of planet

period: float: Orbital period (days)
rprs: float: Planet radius (stellar radii)
a: float: Semi-major axis (stellar radii)
e: float: Eccentricity
w: float: Longitude of periastron (degrees)
i: float: Inclination (degrees)

remove_oot_data(nbuffer, linearfit=False, cubicfit=False, custom_data=None, nlinfit=None, include_nans=False, delete_nan_transits=False, nan_limit=10, simultaneous_midpoints=None, simultaneous_threshold=None, return_intransit=True, cadence=0.0201389)

Removes out-of-transit segments of Kepler light curves. Fits a linear model to out-of-transit points immediately surrounding each transit. Subtracts the linear model from each transit cutout.

nbuffer: int: Number of flux points before and after transit midpoint to include in transit cut-out. e.g. if nbuffer = 7, function will preserve 7 flux points before and after each transit midpoint and discard the rest of light curve.
linearfit: boolean: True if subtracting a linear fit to baseline. False otherwise
cubicfit: boolean: True if subtracting a cubic fit to baseline. False otherwise
nlinfit: int: Number of flux points from each end of transit cutout to use in linear fit. e.g. if nbuffer = 7 and nlinfit = 5, function will use the 10 outermost flux points for linear fit.
include_nans: boolean, default False: Include nans in in-transit data?
delete_nan_transits: boolean, default False: Delete entire transit if includes nan flux values > nan_limit?
nan_limit: int: Number of nans to allow in-transit before deleting entire transit.
simultaneous_midpoints: list: Transit midpoints for other planets in system.
simultaneous_threshold: float: Overlap threshold for removing simultaneous transits. If any transit midpoint is closer than [simultaneous_threshold] to a member of [simultaneous_midpoints], that transit is discarded.
return_intransit: boolean: Save the in-transit midpoint times?
cadence: float: Cadence of the light curve data

None

sigma_clip_quarters(sigma=6, maxiters=1): Sigma clips light curve by quarter. Number of sigmas and max # of iterations allowed can be specified

photoeccentric.eccentricity.get_T14(p, rprs, a_rs, i, e, w)

Calculates T14 (total transit duration, 1st to 4th contact). Assumes a circular orbit (e=0, w=0) if ecc_prior=False. If ecc_prior=True, e and w are required. T14 is multiplied by an eccentricity factor.

p: np.array: Period (days)
rprs: np.array: Planet radius/stellar radius
a_rs: np.array: Semi-major axis (in stellar radii) (a/Rs)
i: np.array: Inclination (degrees)
ecc: boolean: Eccentricity taken into account? Default False
e: float: Eccentricity if ecc=True, default None
w: float: Longitude of periastron (degrees) if ecc=True, default None

T14: float: Total transit duration (seconds)

photoeccentric.eccentricity.get_T23(p, rprs, a_rs, i, e, w)

Calculates T23 (full transit duration, 1st to 4th contact). Assumes a circular orbit (e=0, w=0) if ecc_prior=False. If ecc_prior=True, e and w are required. T23 is multiplied by an eccentricity factor.

p: np.array: Period (days)
rprs: np.array: Planet radius/stellar radius
a_rs: np.array: Semi-major axis (in stellar radii) (a/Rs)
i: np.array: Inclination (degrees)
ecc: boolean: Eccentricity taken into account? Default False
e: float: Eccentricity if ecc=True, default None
w: float: Longitude of periastron (degrees) if ecc=True, default None

T23: float: Full transit time (seconds)

photoeccentric.eccentricity.get_a_rs(rhos, periods)

Gets a/Rs guess based on orbital period, density & Kepler’s 3rd law

rhos: np.array: Stellar density array
periods: np.array: Periods array

a_rs: np.array: a/Rs array calculated from periods, rhos

photoeccentric.eccentricity.get_b_from_i(inc, a_rs, e, w)

Gets impact parameter from inclincation.

inc: float: Inclination (degrees)
a_rs: float: Semimajor axis in stellar radii (a/Rstar)
e: float: Eccentricity
w: float: Longitude of periastron/omega (degrees)

b: float: Impact parameter

photoeccentric.eccentricity.get_e(g, w)

Gets eccentricity (from photoeccentric effect)

g: float: Cube root of ratio between rho_circ and rho_star
w: float: Angle of apoapse or periapse (?) (degrees, -90 < w < 90)

e: float: Eccentricity of planet orbit

photoeccentric.eccentricity.get_g(rho_circ, rho_star)

Gets g

rho_circ: float: Stellar density, assuming a circular orbit (kg/m^3)
rho_star: float: Stellar density, calculated from Kepler/Gaia/spectroscopy (kg/m^3)

g: float: Cube root of ratio between rho_circ and rho_star

photoeccentric.eccentricity.get_g_distribution(rhos, per_dist, rprs_dist, T14_dist, T23_dist)

Gets g distribution for a KOI.

rhos: np.array: Density histogram
per_dist: np.array: Best-fit period (days)
rprs_dist: np.array: Best-fit rp/rs
T14_dist: np.array: Total transit duration (seconds) calculated from best-fit planet parameters
T23_dist: np.array: Full transit duration (seconds) calculated from best-fit planet parameters

gs: np.array: g distribution for star/planet.
rho_circ: np.array: Density distribution assuming a circular orbit

photoeccentric.eccentricity.get_g_from_def(e, w)

Gets g from e and omega

e: float: Eccentricity
w: float: Angle of periapse or something

g: float: Cube root of ratio between rho_circ and rho_star

photoeccentric.eccentricity.get_i_from_b(b, a_rs, e, w)

Gets inclination from impact parameter.

b: float: Impact parameter
a_rs: float: Semimajor axis in stellar radii (a/Rstar)
e: float: Eccentricity
w: float: Longitude of periastron/omega (degrees)

inc: float: Inclination (degrees)

photoeccentric.eccentricity.get_inclination(b, a_rs)

Get inclination (in degrees) from an impact parameter and semi-major axis (on stellar radius).

b: float: Impact parameter
a_rs: float: Ratio of semi-major axis to stellar radius (a/Rs)

i: float: Inclination (degrees)

photoeccentric.eccentricity.get_planet_params(p, T14, T23)

Returns planet parameters in correct units.

p: float: Planet orbital period (days)
rp_earth: float: Planet radius (earth radii)
rs: float: Stellar radius (solar radii)
T14: float: Total transit time - first to fourth contact (hours)
a: float: Planet semi-major axis (AU)
i: float: Orbital inclination (degrees)

p_seconds: float: Orbital period (seconds)
rprs: float: Planet radius (stellar host radii)
T14_seconds: float: Total transit time - first to fourth contact (seconds)
T23_seconds: float: Full transit time - second to third contact (seconds)

photoeccentric.eccentricity.get_rho_circ(rprs, T14, T23, p)

Returns stellar density, assuming a perfectly circular planetary orbit.

rprs: float: Planet radius/stellar radii
T14: float: Total transit time - first to fourth contact (seconds)
T23: float: Full transit time - second to third contact (seconds)
p: float: Orbital period (seconds)

rho_circ: float: Stellar density, assuming a circular orbit (kg/m^3)

photoeccentric.eccentricity.row_to_top(df, index)

Bring row to top

df: pandas.dataframe: Dataframe to copy
index: int: Index of row to bring to top

df_cp: pandas.dataframe: Copy of dataframe with specified row at top

photoeccentric.eccentricity.stellar_params_from_archive(df, kep_name)

Get stellar parameters for the host of a KOI from exoplanet archive (downloaded data).

df: pandas.DataFrame: dataframe of exop. archive downloaded data
kep_name: str: Kepler name of planet

smass: float: Stellar mass (solar mass)
srad: float: Stellar radius (solar radius)
limbdark_mod: str: Limb darkening model
ldm_c1: float: Limb darkening coefficient 1
ldm_c2: float: Limb darkening coefficient 2

photoeccentric.eccentricity.zscore(dat, mean, sigma)

Calculates zscore of a data point in (or outside of) a dataset zscore: how many sigmas away is a value from the mean of a dataset?

dat: float: Data point
mean: float: Mean of dataset
sigma: flaot: Sigma of dataset

photoeccentric.lcfitter.cutout_no_linfit(time, flux, flux_err, transitmid, nbuffer, cadence=0.0208333)

For a segment of a Kepler light curve with a transit, fit a line to the out-of-transit data and subtract.

time: np.array: Time array of entire light curve
flux: np.array: Flux array of entire light curve (normalized to 1)
flux_err: np.array: Flux error array of entire light curve (normalized to 1)
transitmid: float: Mid-time of transit (same units as time: BJD, BJD-X, etc.)

t1bjd: np.array: Time cutout in BJD
fnorm: np.array: Flux cutout - linear fit
fe1: np.array: Flux error cutout

photoeccentric.lcfitter.do_cubfit(time, flux, flux_err, transitmid, nbuffer, nlinfit, cadence=0.0201389, odd=False, custom_data=None, midpoint=1)

For a segment of a Kepler light curve with a transit, fit a cubic polynomial to the out-of-transit data and subtract.

time: np.array: Time array of entire light curve
flux: np.array: Flux array of entire light curve (normalized to 1)
flux_err: np.array: Flux error array of entire light curve (normalized to 1)
transitmid: float: Mid-time of transit (same units as time: BJD, BJD-X, etc.)
nbuffer: int: Number of out-of-transit data points to keep before and after transit
nlinfit: int: Number of out-of-transit data points to use in cubic fit (from each end of cutout light curve)

custom_data: custom data to fit to. should have same time array.

t1bjd: np.array: Time cutout in BJD
fnorm: np.array: Flux cutout - linear fit
fe1: np.array: Flux error cutout

photoeccentric.lcfitter.do_linfit(time, flux, flux_err, transitmid, nbuffer, nlinfit, cadence=0.0201389, odd=False)

For a segment of a Kepler light curve with a transit, fit a line to the out-of-transit data and subtract.

time: np.array: Time array of entire light curve
flux: np.array: Flux array of entire light curve (normalized to 1)
flux_err: np.array: Flux error array of entire light curve (normalized to 1)
transitmid: float: Mid-time of transit (same units as time: BJD, BJD-X, etc.)
nbuffer: int: Number of out-of-transit data points to keep before and after transit
nlinfit: int: Number of out-of-transit data points to use in linear fit (from each end of cutout light curve)

t1bjd: np.array: Time cutout in BJD
fnorm: np.array: Flux cutout - linear fit
fe1: np.array: Flux error cutout

photoeccentric.lcfitter.get_transit_cutout(transitmid, ncadences, time, flux, flux_err)

Gets cutout with n cadences before and after transit. transitmid and time have same units.

transitmid: float: Transit mid-time
ncadences: int: Number of cadences before and after transit mid-time.
time: np.array: Time
flux: np.array: Flux

t1: np.array: Cutout time
f1: np.array: Cutout flux
fe1: np.array: Cutout flux error

photoeccentric.lcfitter.get_transit_cutout_full(transitmids, ncadences, time, flux, flux_err)

Removes out of transit data from light curve. n cadences before and after transit for full light curve. transitmid and time must have the same units.

transitmid: array: All transit mid-times
ncadences: int: Number of cadences before and after transit mid-time.
time: np.array: Time
flux: np.array: Flux

t1: np.array: Cutout time
f1: np.array: Cutout flux
fe1: np.array: Cutout flux error

photoeccentric.lcfitter.planetlc_fitter(time, per, rp, ars, inc): Always assumes e=0. w is NOT a free parameter.

photoeccentric.stellardensity.Mann_mass(Mks): Eqn 10 from Mann et al 2019

photoeccentric.stellardensity.asymmetric_gaussian(mean, sigma_minus, sigma_plus, nvals)

Generates an asymmetric Gaussian distribution based on a mean and 2 different sigmas (one (-) and one (+)) Made by generating 2 symmetric Gaussians with different sigmas and sticking them together at the mean. The integral of the resulting Gaussian is 1.

mean: float: Mean of distribution
sigma_minus: float: Negative sigma of distribtion
sigma_plus: float: Positive sigma of distribtion
nvals: int: Number of values

dist: np.ndarray: Asymmetric Gaussian distribution, length nvals

photoeccentric.stellardensity.density(mass, radius, norm=None): Mass in solar density Radius in solar density sol_density in kg/m^3

photoeccentric.stellardensity.find_density_dist_asymmetric(ntargs, masses, masserr1, masserr2, radii, raderr1, raderr2, logg)

Gets asymmetric stellar density distribution for stars, based on asymmetric mass and radius errorbars. Asymmetric stellar density distribution = Gaussian with different sigmas on each end.

ntargs: int: Number of stars to get distribution for
masses: np.ndarray: Array of stellar masses (solar mass)
masserr1: np.ndarray: Array of (-) sigma_mass (solar mass)
masserr2: np.ndarray: Array of (+) sigma_mass (solar mass)
radii: np.ndarray: Array of stellar radii (solar radii)
raderr1: np.ndarray: Array of (-) sigma_radius (solar radii)
raderr2: np.ndarray: Array of (+) sigma_radius (solar radii)
logg: np.ndarray: Array of log(g)s

rho_dist: np.ndarray: Array of density distributions for each star Each element length 1000
mass_dist: np.ndarray: Array of asymmetric Gaussian mass distributions for each star Each element length 1000
rad_dist: np.ndarray: Array of asymmetric Gaussian radius distributions for each star Each element length 1000

photoeccentric.stellardensity.find_density_dist_symmetric(mass, masserr, radius, raderr, npoints)

Gets symmetric stellar density distribution for stars. Symmetric stellar density distribution = Gaussian with same sigma on each end.

mass: float: Mean stellar mass (solar mass)
masserr: np.ndarray: Sigma of mass (solar mass)
radius: float: Mean stellar radius (solar radii)
raderr: np.ndarray: Sigma of radius (solar radii)

npoints: int

rho_dist: np.ndarray: Array of density distributions for each star in kg/m^3 Length npoints
mass_dist: np.ndarray: Array of symmetric Gaussian mass distributions for each star in kg Length npoints
rad_dist: np.ndarray: Array of symmetric Gaussian radius distributions for each star in m Length 100npoints0

photoeccentric.stellardensity.fit_isochrone_lum(data, isochrones, luminosity=True, lum_source='Gaia', lums=None)

Gets stellar isochrones where effective temperature, mass, radius, and luminosity all fall within 1-sigma errorbars from stellar data.

data: pandas.DataFrame: Spectroscopic data + Kepler/Gaia data for n stars in one table. (muirhead_comb)
isochrones: pandas.DataFrame: Table of isochrones. (isochrones)
luminosity: boolean: ‘True’ if including stellar luminosity constraints.
lum_source: ‘Gaia’ or ‘custom’: If ‘Gaia’, use published Gaia stellar luminosity from input data. If ‘custom’, provide custom luminosity constraints (‘lums’ keyword must be defined in this case).
lums: list: List of custom luminosities (length 2) containing [lower luminostiy limit, upper luminosity limit] (Solar Luminosity)

iso_fits: pandas.DataFrame(): Set of all isochrones that are consistent with this star based on spectroscopy and Gaia luminosity.

photoeccentric.stellardensity.get_kepID(hdul)

Pulls KIC IDs from Kepler-Gaia dataset.

hdul: astropy.io.fits.hdu.hdulist.HDUList: Astropy hdulist from FITS file of Kepler-Gaia dataset

kepID_lst: np.array: Array of KIC IDs for entire Kepler-Gaia dataset

photoeccentric.stellardensity.get_logg(hdul)

Pulls stellar log(g) from Kepler-Gaia dataset.

hdul: astropy.io.fits.hdu.hdulist.HDUList: Astropy hdulist from FITS file of Kepler-Gaia dataset

rad_lst: np.array: Array of radii for entire Kepler-Gaia dataset
raderr1_lst: np.array: Array of radius (-) errors for entire Kepler-Gaia dataset
raderr2_lst: np.array: Array of radius (+) errors for entire Kepler-Gaia dataset

photoeccentric.stellardensity.get_masses(hdul)

Pulls stellar masses from Kepler-Gaia dataset.

hdul: astropy.io.fits.hdu.hdulist.HDUList: Astropy hdulist from FITS file of Kepler-Gaia dataset

mass_lst: np.array: Array of masses for entire Kepler-Gaia dataset
masserr1_lst: np.array: Array of mass (-) errors for entire Kepler-Gaia dataset
masserr2_lst: np.array: Array of mass (+) errors for entire Kepler-Gaia dataset

photoeccentric.stellardensity.get_nan_indices(masses, radii, radii2, logg)

Removes stars with nans in any of stellar masses, radii, and log(g). If one or more entry is nan, the whole star is discarded.

masses: np.ndarray: Masses of all stars in dataset
radii: np.ndarray: Radii of all stars in dataset from Kepler
radii2: np.ndarray: Radii of all stars in dataset from Gaia
logg: np.ndarray: log(g)s of all stars in dataset

nan_i = list: Indices of stars with nan values

photoeccentric.stellardensity.get_radii(hdul, mission='Kepler')

Pulls stellar radii from Kepler-Gaia dataset.

hdul: astropy.io.fits.hdu.hdulist.HDUList: Astropy hdulist from FITS file of Kepler-Gaia dataset
mission: ‘Kepler’ or ‘Gaia’: Mission from which radii are measured

rad_lst: np.array: Array of radii for entire Kepler-Gaia dataset
raderr1_lst: np.array: Array of radius (-) errors for entire Kepler-Gaia dataset
raderr2_lst: np.array: Array of radius (+) errors for entire Kepler-Gaia dataset

photoeccentric.stellardensity.get_rho_prior(P, rprs, a_rs, inc, e, w): P in days. inc and w in degrees. Returns rho_starin solar densities.

photoeccentric.stellardensity.remove_nans(nan_indices, stellar_prop)

Removes nans from array of stellar property.

Notes: nan_indices is the output from get_nan_indices() Run remove_nans() on every array input in get_nan_indices().

nan_indices: list: Indices of nan values to be removed
stellar_prop: np.ndarray: Array of stellar property (masses, radii, etc) to remove nans from

stellar_prop_nonans: np.ndarray: Array of stellar property without nans.

photoeccentric.utils.calc_a_from_rho(period, rho_star): Calculate semimajor axis in stellar radii (a/Rs) from orbital period (days) and average stellar density (SI units).

photoeccentric.utils.calc_r(a_rs, e, w)

Calculate r (the planet-star distance) at any point during an eccentric orbit. Equation 20 in Murray & Correia Text

a_rs: float: Semi-major axis (Stellar radius)
e: float: Eccentricity
w: float: Longitude of periastron (degrees)

r_rs: float: Planet-star distance (Stellar radius)

photoeccentric.utils.find_nearest(array, value): Gets the nearest element of array to a value.

photoeccentric.utils.find_nearest_index(array, value): Gets the index of the nearest element of array to a value.

photoeccentric.utils.from_exoarchive(KOI=0, KIC=0, KepName=0): Downloads data from exoplanet archive

photoeccentric.utils.get_N_intransit(tdur, cadence)

Estimates number of in-transit points for transits in a light curve.

tdur: float: Full transit duration
cadence: float: Cadence/integration time for light curve

n_intransit: int: Number of flux points in each transit

photoeccentric.utils.get_cdf(dist, nbins=250): Gets a CDF of a distribution.

photoeccentric.utils.get_e_from_def(g, w)

Gets eccentricity from definition (eqn 4)

g: float: g value
w: float: Omega (angle periapse/apoapse)

e: float: Eccentricity calculated solely on g and w

photoeccentric.utils.get_lc_files(KIC, KICs, lcpath): Gets a list of light curves from a directory.

photoeccentric.utils.get_mid(time): Returns approximately 1/2 of cadence time.

photoeccentric.utils.get_sigma_individual(SNR, N, Ntransits, tdepth)

Gets size of individual error bar for a certain light curve signal to noise ratio.

SNR: float: Target light curve signal to noise ratio
N: int: Number of in-transit flux points for each transit
Ntransits: int: Number of transits in light light curve
tdepth: float: Transit depth (Rp/Rs)^2

sigma_individual: float: Size of individual flux error bar

photoeccentric.utils.get_sigmas(dist)

Gets + and - sigmas from a distribution (gaussian or not). Ignores nan values.

dist: np.array: Distribution from which sigmas are needed

sigma_minus: float

sigma

sigma_plus: float

sigma

photoeccentric.utils.get_timeseries_files(gzfile): path: a tar.gz file downloaded from MAST

photoeccentric.utils.kepler_from_mast(object_of_interest): Perform a MAST query for Kepler light curves.

photoeccentric.utils.mast_query(request)

From https://mast.stsci.edu/api/v0/MastApiTutorial.html

Perform a MAST query for Kepler light curves.

photoeccentric.utils.mode(dist, window=5, polyorder=2, bin_type='int', bins=25)

Gets mode of a histogram.

dist: array: Distribution

mode: float: Mode