BLS generators

class gerbls.pyBLSModel

Base class for BLS model generators. Should not be created directly.

property duration_mode: str

Get the current duration_mode value, which affects how the maximum tested transit duration is determined at each orbital period.

property durations: list

Get the list of tested transit durations, if specified during model setup.

property freq: numpy.ndarray

Get the array of tested frequencies.

property max_duration_factor: float

Get the max_duration_factor that affects the maximum tested transit duration.

property max_period: float

Get the maximum tested orbital period.

property min_duration_factor: float

Get the min_duration_factor that affects the minimum tested transit duration.

property min_period: float

Get the minimum tested orbital period.

property N_freq: int

Get the number of tested frequencies.

property target: pyTarget | None

Get a non-mutable reference to the stellar parameters object, if specified.

calculate_N_freq(self)

Calculate the number of tested frequencies without running the model.

Return type:

int

run(self, bool verbose=True)

Run the BLS generator.

Parameters:

verbose (bool) – Whether to print output to the console, by default True.

Return type:

None

class gerbls.pyBruteForceBLS

Bases: pyBLSModel

Brute-force (slow) BLS generator. setup() should be used before run(). Refer to the base class for additional properties and methods.

setup(self, pyDataContainer data, double min_period, double max_period, pyTarget target=None, double dt_per_step=0., double t_bins=0., size_t N_bins_min=0, str duration_mode='', double min_duration_factor=0., double max_duration_factor=0.)

Set up the BLS generation.

Caution

Only references to data and target are stored. Crashes or unexpected results may occur if the referenced objects get deallocated.

Parameters:

  • data (gerbls.pyDataContainer) – Input data.

  • min_period (float) – Minimum searched orbital period.

  • max_period (float) – Maximum searched orbital period.

  • target (gerbls.pyTarget, optional) – Stellar parameters, by default None.

  • dt_per_step (float, optional) – Period spacing will be calculated such that over the course of the entire time baseline of the data, any transit midtime will not be expected to shift by more than this value due to finite period spacing, by default 0.003.

  • t_bins (float, optional) – Time cadence that phase-folded light curves will be binned to, by default 0.007.

  • N_bins_min (int, optional) – Regardless of the value specified by t_bins, phase-folded light curves at each period are guaranteed to have at least this many bins in total, by default 100.

  • duration_mode ({'constant', 'fractional', 'physical'}, optional) – Affects how the maximum tested transit duration is determined at each period, by default ‘fractional’.

  • min_duration_factor (float, optional) – Affects the minimum searched transit duration at each period, by default 0.

  • max_duration_factor (float, optional) – Affects the maximum searched transit duration at each period, by default 0.1.

Return type:

None

setup_from_freq(self, pyDataContainer data, double[:] freq_, pyTarget target=None, double t_bins=0., size_t N_bins_min=0, str duration_mode='', double min_duration_factor=0., double max_duration_factor=0.)

Set up the BLS generation with a predefined array of orbital frequencies.

Caution

Only references to data and target are stored. Crashes or unexpected results may occur if the referenced objects get deallocated.

Parameters:

  • data (gerbls.pyDataContainer) – Input data.

  • freq (ArrayLike) – Array of orbital frequencies (= 1/period) to test.

  • target (gerbls.pyTarget, optional) – Stellar parameters, by default None.

  • t_bins (float, optional) – Time cadence that phase-folded light curves will be binned to, by default 0.007.

  • N_bins_min (int, optional) – Regardless of the value specified by t_bins, phase-folded light curves at each period are guaranteed to have at least this many bins in total, by default 100.

  • duration_mode ({'constant', 'fractional', 'physical'}, optional) – Affects how the maximum tested transit duration is determined at each period, by default ‘fractional’.

  • min_duration_factor (float, optional) – Affects the minimum searched transit duration at each period, by default 0.

  • max_duration_factor (float, optional) – Affects the maximum searched transit duration at each period, by default 0.1.

Return type:

None

class gerbls.pyFastBLS

Bases: pyBLSModel

Fast-folding BLS generator. setup() should be used before run(). Refer to the base class for additional properties and methods.

property rdata: gerbls.pyDataContainer

Get the resampled data generated by run(), with a time sampling given by t_samp.

property t_samp: float

Get or set the desired (initial) time sampling during BLS generation.

property time_spent: numpy.ndarray

Get the runtime spent at each orbital period during run().

duplicate(self) → pyFastBLS
run_double(self, bool verbose=True)

Run the BLS generator with all output results in double precision.

Parameters:

verbose (bool) – Whether to print output to the console, by default True.

Return type:

None

setup(self, pyDataContainer data, double min_period, double max_period, pyTarget target=None, double t_samp=0., bool verbose=True, str duration_mode='', vector[double] durations=[], double min_duration_factor=0., double max_duration_factor=0., bool downsample=False, double downsample_invpower=3., double downsample_threshold=1.1)

Set up the BLS generation.

Caution

Only references to data and target are stored. Crashes or unexpected results may occur if the referenced objects get deallocated.

Parameters:

  • data (gerbls.pyDataContainer) – Input data.

  • min_period (float) – Minimum searched orbital period.

  • max_period (float) – Maximum searched orbital period.

  • target (gerbls.pyTarget, optional) – Stellar parameters, by default None.

  • t_samp (float, optional) – Desired initial time sampling of the data, by default 0. Overwrites the value in t_samp. If 0, the median time cadence of the input data will be used instead.

  • verbose (bool, optional) – Whether to print output to the console, by default True.

  • duration_mode ({'constant', 'fractional', 'physical'}, optional) – Affects how the maximum tested transit duration is determined at each period, by default ‘fractional’.

  • durations (list, optional) – If given, use a specific list of duration factors instead of a range.

  • min_duration_factor (float, optional) – Affects the minimum searched transit duration at each period, by default 0. Has no effect if durations is given.

  • max_duration_factor (float, optional) – Affects the maximum searched transit duration at each period, by default 0.1. Has no effect if durations is given.

  • downsample (bool, optional) – Whether to automatically downsample the data at longer periods, by default False.

  • downsample_invpower (float, optional) – Affects the rate of downsampling, by default 3.

  • downsample_threshold (float, optional) – Affects the threshold that triggers downsampling, by default 1.1.

Return type:

None

class gerbls.pyNoiseBLS(pyBLSModel model)

Noise BLS model.

Parameters:

model (pyBLSModel) – BLS model used to generate the noise BLS. An internal copy will be created.

property dchi2_arr: float

Get the \(\Delta\chi^2\) array of the generated noise BLS model.

property f: numpy.ndarray

Get the array of tested orbital frequencies (= 1/period).

property N_freq: int

Get the number of tested frequencies.

property N_sim: int

Get the number of simulations that were used to generate the noise BLS.

property P: numpy.ndarray

Get the array of tested orbital periods.

property selection_mode: str

Get the current selection_mode value, which affects how the noise BLS value is calculated from simulated BLS spectra.

dchi2(self, P)

Evaluate the \(\Delta\chi^2\) of the generated noise BLS at the given period(s). Uses linear interpolation over the tested period range.

Parameters:

P (float or ArrayLike) – The period(s) at which to evaluate \(\Delta\chi^2\).

Return type:

float or numpy.ndarray

generate(self, size_t N_sim, str selection_mode='', bool verbose=True)

Generate the noise BLS spectrum.

Parameters:

  • N_sim (int) – Number of simulations.

  • selection_mode ({'fit', 'max'}, optional) – Affects how the noise BLS value is calculated from simulated BLS spectra, by default ‘max’.

  • verbose (bool, optional) – Whether to print output to the console, by default True.

Return type:

None

generate_binned(self, size_t N_sim, double bin_width, str selection_mode='', double bin_width_prec=0.1, bool verbose=True)

Generate the noise BLS spectrum.

Parameters:

  • N_sim (int) – Number of simulations.

  • selection_mode ({'fit', 'max'}, optional) – Affects how the noise BLS value is calculated from simulated BLS spectra, by default ‘max’.

  • verbose (bool, optional) – Whether to print output to the console, by default True.

Return type:

None

gerbls.run_bls(time, mag, err, min_period, max_period, durations, t_samp=0.0)[source]

A basic convenience function to generate a BLS spectrum. The input data will be resampled to a uniform time cadence to run the BLS, use t_samp to explicitly provide the cadence for resampling. Automatic downsampling will be used to maintain an optimal period spacing.

Parameters:

  • time (ArrayLike) – Array of observation timestamps.

  • mag (ArrayLike) – Array of observed fluxes.

  • err (ArrayLike) – Array of flux uncertainties for each observation.

  • min_period (float) – Minimum BLS period to search.

  • max_period (float) – Maximum BLS period to search.

  • durations (list or float) – List of transit durations to test at each period.

  • t_samp (float, optional) – Time sampling to bin the data before running the BLS. If 0 (default), the median time difference between observations is used.

Returns:

A dictionary with BLS results:

Key

Value

P

list of tested periods

dchi2

BLS statistic (\(\Delta\chi^2\)) at each period

t0

best-fit transit mid-point at each period

dur

best-fit duration at each period

mag0

best-fit flux baseline at each period

dmag

best-fit transit depth at each period

snr

estimated SNR at each period

Return type:

dict