bioverse.survey module

class bioverse.survey.Survey(label: str = None, diameter: float = 15.0, t_max: float = 3652.5, t_slew: float = 0.00347, FOV_center: ndarray = None, FOV_size: ndarray = None)

Bases: dict, Object

Describes an exoplanet survey, including methods for creating simulated datasets. This class should not be called directly; instead use ImagingSurvey or TransitSurvey.

label: str = None

diameter: float = 15.0

t_max: float = 3652.5

t_slew: float = 0.00347

FOV_center: ndarray = None

FOV_size: ndarray = None

add_measurement(key, idx=None, **kwargs)

Adds a Measurement to the Survey.

Parameters:

• key (str) – Name of the measured parameter.

• idx (int) – Position in the measurement sequence. By default, it is placed at the end.

• **kwargs – Keyword arguments passed to Measurement.__init__().

add_measurements(noise_model=None, **m_kwargs)

Adds Multiple Measurement to the Survey.

Parameters:

**m_kwargs – Keyword arguments in terms of measurement name and precision

move_measurement(key, idx)

Moves a Measurement to the designated position in the sequence.

Parameters:

• key (str) – Name of the measured parameter.

• idx (int) – Position in the measurement sequence to which to move the Measurement.

quickrun(generator, N_sim=1, method='detectable', **kwargs)

Convenience function that generates a sample, computes the detection yield, and returns a simulated data set.

Parameters:

• generator (Generator) – Generator used to generate the planet population.

• N_sim (int, optional) – If greater than 1, simulate the survey this many times and return the combined result.

• method (str, optional) – Method used for the yield calculation. Default is ‘detectable’, observing all detectable planets without considering exposure time and mission duration.

• **kwargs – Keyword arguments passed to Generator.generate().

Returns:

• sample (Table) – Table of all simulated planets.

• detected (Table) – Table of planets detected by the Survey.

• data (Table) – Simulated data set produced by the Survey. data.error gives uncertainties on the measurements in data.

observe(y, data=None, error=None, demographics=False)

Returns a simulated data set for a Table of simulated planets.

Parameters:

• y (Table) – Table containing the set of planets to be observed, usually the detection yield of the survey.

• data (Table, optional) – Pre-existing Table in which to store the new measurements.

• error (Table, optional) – Pre-existing Table containing uncertainties on data values.

• demographics (Bool, optional) – compute some population-level statistics after taking all measurements

Returns:

data – Table of measurements made by the Survey, with one row for each planet observed.

Return type:

Table

compute_overhead_time(d, N_obs=1)

Computes the overheads associated with each observation.

compute_debias(d)

Removes detection biases from the data set (transit mode only).

schedule_observations(d, texp_col='t_exp', N_obs_col='N_obs', debias=False, zero_overhead=False)

set_weight(key, weight, min=None, max=None, value=None)

Adds a new rule for determining target weight. weight can be set for targets whose parameter fall within (min, max) or exactly match value.

Parameters:

• key (str) – Name of the parameter being checked.

• weight (float) – Weight of targets that meet the conditions.

• min (float, optional) – Minimum value of range. Default is -inf.

• max (float, optional) – Maximum value of range. Default is +inf.

• value (int or str or bool, optional) – Exact value with which to compare.

compute_weights(d)

Computes the priority weight of each planet in d.

set_reference_observation(**ref_kwargs)

exp_time_scaling_relation(d, t_ref=3.1, wl_eff=0.6, T_st_ref=5788.0, R_st_ref=1.0, D_ref=15.0, d_ref=10.0, R_pl_ref=1.0, H_ref=9, **kwargs)

Computes the exposure time and number of observations required to characterize each planet in d.

d: data table t_ref: exposure time for example psg run (days?) wl_eff: wavelength in um T_st_ref: reference stellar temperature in K R_st_ref: reference stellar radius in R_sun D_ref: reference telescope diameter in m d_ref: reference distance in pc R_pl_ref: reference planet radius in R_earth H_ref: reference atmosphere scale height kwargs: additional keyword arguments (allows us to pass unused kwargs as well)

in_telescope_FOV(d)

Function to filter objects based on whether they are in telescope field of view. Applicable for an array of telescopes such as Nautilus or Chronos

Relies on Survey.FOV_center, Survey.FOV_size required format: numpy array of shape (nFOV,2) or (2) for RA and DEC centers and widths

if these are None, return results for whole sky

Parameters:

d (Table) – Table of all objects

Returns:

d – Table of objects in the combined FOV

Return type:

Table

class bioverse.survey.ImagingSurvey(label: str = None, diameter: float = 15.0, t_max: float = 3652.5, t_slew: float = 0.00347, FOV_center: numpy.ndarray = None, FOV_size: numpy.ndarray = None, inner_working_angle: float = 3.5, outer_working_angle: float = 64, contrast_limit: float = -10.6, mode: str = 'imaging')

Bases: Survey

inner_working_angle: float = 3.5

outer_working_angle: float = 64

contrast_limit: float = -10.6

mode: str = 'imaging'

compute_detectable(d, wl_eff=0.5, A_g=0.3)

Computes a simple estimate of the number of detectable planets for an imaging survey. Compares the contrast ratio and projected separation of each planet to the contrast limit and inner/outer working angles of the survey. Planets that satisfy these criteria are considered to be detectable. Not all these planets will actually be observed by a mission.

Parameters:

• d (Table) – Table of all simulated planets which the survey could attempt to observe.

• wl_eff (float, optional) – Effective wavelength of observation in microns (used for calculating the IWA/OWA).

• A_g (float, optional) – Geometric albedo of each planet, ignored if ‘A_g’ is already assigned.

Returns:

yield – Copy of the input Table containing only planets which were detected by the survey.

Return type:

Table

compute_yield(d0, method='detectable', SNR=7, band_width=0.2, wl_eff=0.5, A_g=0.3, zero_overhead=False, **exp_kwargs)

Computes the yield of a survey. Compares whether stars will be observed for long enough duration for planets to be detected at given SNR. Old versions of the yield calculation considering only contrast and separation can be replicated using method=’detectable’

Parameters:

• d0 (Table) – Table of all simulated planets which the survey could attempt to observe.

• method (str, optional) –

  Method used for yield calculation. “detectable” implies all detectable planets are observed without consideration of exposure time

  and total mission duration.

  ”exp_time” uses an exposure time calculator to determine if simulated planets were detected.

  Requires survey to have been scheduled in generation or pre-generator

  ”scaling_relation” is a legacy option to use a reference exposure time from PSG calculations

• wl_eff (float, optional) – Effective wavelength of observation in microns (used for calculating the IWA/OWA).

• A_g (float, optional) – Geometric albedo of each planet, ignored if ‘A_g’ is already assigned.

• zero_overhead (bool, optional) – set overhead time to zero

• exp_kwargs (dict, optional) – Additional keyword arguments for exposure time calculator

Returns:

d – Copy of the input Table containing only planets which were detected by the survey.

Return type:

Table

call_exposure_time_calculator(d, SNR=7, func=<function DI_exposure_time_calculator>, band='Vmag', C_col='contrast', sep_col='ang_sep_mas', texp_col='t_exp', **kwargs)

class bioverse.survey.TransitSurvey(label: str = None, diameter: float = 15.0, t_max: float = 3652.5, t_slew: float = 0.00347, FOV_center: numpy.ndarray = None, FOV_size: numpy.ndarray = None, N_obs_max: int = 1000, mode: str = 'transit', d_max: float = nan, P_max: float = nan, min_depth: float = nan, m_G_max: float = nan)

Bases: Survey

N_obs_max: int = 1000

mode: str = 'transit'

d_max: float = nan

P_max: float = nan

min_depth: float = nan

m_G_max: float = nan

compute_detectable(d)

Computes whether planets are detectable for the survey

Parameters:

d (Table) – Table of all simulated planets which the survey could attempt to observe.

Returns:

detectable – Copy of the input table containing only planets which are detectable by the survey.

Return type:

Table

calc_photometric_precision(d, t_fixed=60.0, t_exp=2.0, n_pix=108, R=20, **kwargs)

Function to calculate the photometric precision of a survey assuming all transits in a fixed duration are observed

Parameters:

• survey – bioverse survey object

• d – bioverse table of planets

• t_fixed – fixed field survey duration in days

• t_exp – time for individual exposure in seconds

• n_pix – number of pixels on detector

• R – spectral resolution

• kwargs – keyword arguments for SNR calculation/ fixed field yield function

Returns:

d

calc_integration_time(d, target_precision=100, t_exp=2.0, mag_col='Gmag', **kwargs)

Function to calculation integration time (days) to obtain a target photometric precision in ppm

Parameters:

• d – bioverse table of planets

• target_precision – target photometric precision in ppm

• t_exp – time for individual exposure in seconds

• kwargs – additional keyword arguments for util.calc_nexp function

fixed_field_yield(d, n_sigma=1.0, min_num_tr=1, t_fixed=None, t_exp=2.0, n_pix=108, R=20, feature_col='depth', feature_ppm=False, **kwargs)

target_precision_yield(d, target_precision=100, n_sigma=1.0, feature_ppm=False, feature_col='depth', t_exp=2.0, mag_col='Gmag', zero_overhead=True, debias=False, **kwargs)

Function to calculate the yield of a survey where stars are observed to a given target photometric precision Stars are selected based on the integration time to obtain that precision, prioritized base off 1 over the required integration time until all the survey duration is allocated

Parameters:

• d – bioverse table of planets

• target_precision – target photometric precision in ppm

• n_sigma – number of standard deviations in transit depth necessary for detection/characterization

• feature_ppm – boolean, are feature strengths given in units of ppm (parts per million) as opposed to a ratio

• feature_col – column name of feature to use

• t_exp – time for individual exposure in seconds

• mag_col – column name of stellar apparent magnitude to use

• zero_overhead – boolean, whether to include zero overhead time in survey scheduling

compute_yield(d0, method='detectable', debias=False, zero_overhead=True, **y_kwargs)

Computes a simple estimate of the detection yield for a transit survey. Select between multiple yield methods.

Parameters:

• d0 (Table) – Table of all simulated planets which the survey could attempt to observe.

• method (str, optional) –

  Method used for yield calculation.

  ”detectable”: implies all detectable planets are observed without consideration of exposure time

  and total mission duration.

  ”scaling_relation”: uses estimated exposure times from PSG and a scaling relation “fixed_field”: assumes that all stars in a field of view are observed for a given duration,

  features in planetary spectra are assumed to be observed if the photometric precision is smaller than the feature depth (times n_sigma)

  ”target_precision”: Stars are selected for survey based on the integration time required to obtain a

  specified photometric precision. If the planet feature strength is above this threshold features are consider to be detected.

• debias (bool, optional) – Apply debias correction for transiting planets.

• zero_overhead (bool, optional) – set overhead to zero

• y_kwargs (dict, optional) – keyword arges for specific yield method for “scaling relation”: sets reference observation, updates self.reference for “fixed field”: kwargs for SNR calculator for “target precision”:kwargs for util.calc_nexp

Returns:

yield – Copy of the input table containing only planets which were detected by the survey.

Return type:

Table

class bioverse.survey.Measurement(key, precision=0.0, bounds=[], noise_model=None)

Bases: object

Class describing a simple measurement to be applied to a set of planets detected by a Survey.

Parameters:

• key (str) – Name of the parameter that will be measured.

• precision (str or float, optional) – Precision of measurement, e.g. ‘10%’ or 0.10 units. Default is zero.

• bounds (list or np.ndarray, optional) – Upper and lower bounds of measurement, e.g. [0.0, 1.0]. Default is [] (unbounded)

• noise_model (str, optional) – Name of noise model to use. Current choices are truncated Gaussian and Gaussian. If not specified, defaults to ‘trunc_gaussian’.

measure(detected, data=None, error=None)

Produces the measurement for planets in a Table and places them into a data Table.

Parameters:

• detected (Table) – Table containing detected planets.

• data (Table, optional) – Table in which to store the measured values for each planet. If not given, then a new table is created.

• error (Table, optional) – Table in which to store the measurement uncertainties. Must be given if data is given.

Returns:

• data (Table) – Table containing the measured values for each planet.

• error (Table) – Table containing the measurement uncertainties for each planet.

perform_measurement(x)

Simulates measurements of the parameter from a set of true values. Measurements are clipped to +- 5 sigma of the true value to avoid non-physical results.

Parameters:

x (array) – Array of true values on which to perform the measurement.

Returns:

xm – Array of measured values with the same length and type as x.

Return type:

array

bioverse.survey.reset_imaging_survey()

Re-creates the default imaging survey.

bioverse.survey.reset_transit_survey()

Re-creates the default transit survey.

bioverse.survey.prioritize_survey(survey, label)

bioverse.survey.read_scaling_dict(label)