FULMAR

Target

class fulmar.target(targname, mission=None)
Parameters
  • targname (str or int) – Name of the target as a string, e.g. “TOI-175” or, if mission is passed as the numerical identifier of the input catalog.

  • mission (str, optional) – ‘Kepler’, ‘K2’, or ‘TESS’

When the object is created, some parameters are automatically created/updated:

  • ab

    (tuple of floats) Quadratic limb darkening parameters a, b.

  • M_star

    (float) Stellar mass (in units of solar masses)

  • M_star_min

    (float) 1-sigma lower confidence interval on stellar mass (in units of solar mass)

  • M_star_max

    (float) 1-sigma upper confidence interval on stellar mass (in units of solar mass)

  • R_star

    (float) Stellar radius (in units of solar radii)

  • R_star_min

    (float) 1-sigma upper confidence interval on stellar radius (in units of solar radii)

  • R_star_max

    (float) 1-sigma lower confidence interval on stellar radius (in units of solar radii)

Once the target is defined, one can look for data or directly build the lightcurve.

target.search_data(author=None, exptime=None, download=False)

Search for available lightcurves of the target

Parameters
  • author (str, tuple of str, or "any") – Author of the data product (provenance_name in the MAST API). Official Kepler, K2, and TESS pipeline products have author names ‘Kepler’, ‘K2’, and ‘SPOC’.

  • exptime ('long', 'short', 'fast', or float) – ‘long’ selects 10-min and 30-min cadence products; ‘short’ selects 1-min and 2-min products; ‘fast’ selects 20-sec products. Alternatively, you can pass the exact exposure time in seconds as an int or a float, e.g., exptime=600 selects 10-minute cadence. By default, all cadence modes are returned.

  • download (bool) – Whether the data should be downloaded or not.

Returns

srch – Object detailing the data products found.

Return type

SearchResult object

target.build_lightcurve(filelist=None, author=None, exptime=None, colnames=None)

Build the timeseries by reading and stitching selected data.

Parameters
  • filelist (list or str, optional) – List of paths/path to the file containing the light curve data.

  • author (str, optional) – Name of the pipeline used to reduce the data.

  • exptime (float, optional) – Exposure time of the observation, in seconds.

  • colnames (list (of str), optional) – Names of the columns. Should have the same number of items as the number of columns.

Returns

ts_stitchTimeSeries object combining data from selected lightcurves.

Return type

astropy.timeseries.TimeSeries

Then one can work on the data by cleaning it.

target.mask_outliers(timeseries=None, sigma=5, sigma_lower=None, sigma_upper=None)

Creates a mask to remove outliers from the lightcurve with special care to avoid removing transits.

Parameters
  • timeseries (~astropy.timeseries.TimeSeries or ~astropy.table.Table, optional) – TimeSeries ot Table object containing the data to filter

  • sigma (float, optional) – The number of standard deviations to use for the clipping limit

  • sigma_lower (float, optional) – The number of standard deviations to use as the lower bound for the clipping limit.

  • sigma_upper (float, optional) – The number of standard deviations to use as the upper bound for the clipping limit.

Returns

clean – mask where outliers are marked as “False”

Return type

np.array

target.clean_subt_activity_flatten(timeseries=None, sigma=3, wl=1501, time_window=None, polyorder=2, return_trend=False, remove_outliers=True, break_tolerance=5, niters=3, mask=None)

Removes the low frequency trend using scipy’s Savitzky-Golay filter. This method wraps scipy.signal.savgol_filter.

Parameters
  • sigma (float, optional) – Number of standard deviations to use for the clipping limit.

  • timeseries (~astropy.timeseries.TimeSeries, optional) – TimeSeries ot Table object containing the data to filter

  • wl (int, optional) – Window_length The length of the filter window (i.e. the number of coefficients). window_length must be a positive odd integer.

  • time_window ('~astropy.units.Quantity' or float, optional) – Time length of the filter window. Window_lenght will be set to the closest odd integer taking exposition time into account. Overrides wl.

  • polyorder (int, optional) – The order of the polynomial used to fit the samples. polyorder must be less than window_length.

  • return_trend (bool, optional) – If True, the method will return a tuple of two elements (ts_clean, trend_ts) where trend_ts is the removed trend.

  • remove_outliers (bool) – If ‘True’, the method uses mask_outliers to created a mask of valid datapoints to be applied to the products before returning them.

  • break_tolerance (int, optional) – If there are large gaps in time, flatten will split the flux into several sub-lightcurves and apply savgol_filter to each individually. A gap is defined as a period in time larger than break_tolerance times the median gap. To disable this feature, set break_tolerance to None.

  • niters (int, optional) – Number of iterations to iteratively sigma clip and flatten. If more than one, will perform the flatten several times, removing outliers each time.

  • mask (boolean array with length of time, optional) – Boolean array to mask data with before flattening. Flux values where mask is True will not be used to flatten the data. An interpolated result will be provided for these points. Use this mask to remove data you want to preserve, e.g. transits.

Returns

  • ts_clean (~astropy.timeseries.TimeSeries) – New TimeSeries object with long-term trends removed.

  • If return_trend is set to True, this method will also return

  • trend_ts (~astropy.timeseries.TimeSeries) – New TimeSeries object containing the trend that was removed from the flux.

target.clean_subt_activity_GP(timeseries=None, bin_duration=<Quantity 40. min>, period_min=0.2, period_max=100.0, tune=2500, draws=2500, chains=2, target_accept=0.95, ncores=None, return_trend=False, remove_outliers=True, sigma_out=3, mask=None, store_trace=True)

Corrects the stellar rotation using GP

Parameters
  • timeseries (~astropy.timeseries.TimeSeries, optional) – TimeSeries ot Table object containing the data to filter

  • bin_duration ('astropy.units.Quantity' or float) – Time interval for the binned time series. (Default is in units of days)

  • period_min (float, optional) – Minimum value for the rotation period of the star. (In days)

  • period_max (float, optional) – Maximum value for the rotation period of the star. (In days)

  • ncores (int, optional) – Number of cores to use for processing. (Default: all)

  • return_trend (bool, optional) – If True, the method will return a tuple of two elements (ts_clean, trend_ts) where trend_ts is the removed trend.

  • remove_outliers (bool) – If ‘True’, the method uses mask_outliers to created a mask of valid datapoints to be applied to the products before returning them.

  • sigma_out (int, optional) – Number of sigma above which to remove outliers from the flatten

  • mask (boolean array with length of self.time) – Boolean array to mask data with before flattening. Flux values where mask is True will not be used to flatten the data. An interpolated result will be provided for these points. Use this mask to remove data you want to preserve, e.g. transits.

  • store_trace (bool, optional) – If True, the posterior sampling of the GP model will be stored as an attribute called “activity_gp_trace” (target.activity_gp_trace). It can be useful to run convergence checks.

Returns

  • ts_clean (~astropy.timeseries.TimeSeries) – New TimeSeries object with long-term trends removed.

  • If return_trend is set to True, this method will also return

  • trend_ts (~astropy.timeseries.TimeSeries) – New TimeSeries object containing the trend that was removed from the flux.

Having a look at a known promising signal.

target.plot_transitcheck(period, epoch0, duration=<Quantity 3. h>, nbin=40, timeseries=None, savefig=False, folder=None, fig_id=None)

Plots a transitcheck image. A visual check at a given period and epoch useful to probe signals detected in RV.

Parameters
  • period ('~astropy.time.Time' or float) – The period to use for folding.

  • epoch0 ('~astropy.units.Quantity' or float) – The time to use as the reference epoch.

  • duration ('~astropy.units.Quantity' or float) – Duration of the transit.

  • nbin (int) – Number of bins in the transit window.

  • timeseries (~astropy.timeseries.TimeSeries, optional) – TimeSeries object

  • savefig (bool) – If True, saves the resulting figure on the disk.

  • folder (str) – Path to the folder in which the figure can be saved

  • fig_id (str or int) – Suffix for the filename when the figure is exported.

Or looking for signals.

target.tls_periodogram(timeseries=None, cleaned=True, mask=None, **kwargs)

Computes the tls periodogram of the selected lightcurve

Parameters
  • timeseries (~astropy.timeseries.TimeSeries, optional) – TimeSeries ot Table object containing the data to filter

  • cleaned (bool, optional) – Whether the periodogram should be conducted on the cleaned or the stitched timeseries (default: True)

  • period_min (float, optional) – Minimum trial period (in units of days). If none is given, the limit is derived from the Roche limit

  • period_max (float, optional) –

    Maximum trial period (in units of days) (default: Half the duration

    of the time series)

  • n_transits_min (int, optional) – Minimum number of transits required. Overrules period_max. (default=2)

  • mask (boolean array with length of time) – Boolean array to mask data, typically transits. Data where mask is “True” will not be taken into account for the periodogram.

Returns

tls_results

Return type

transitleastsquaresresults

Functions

mission_identifier(target)

Identifies the mission (‘Kepler’, ‘K2’ or ‘TESS’) from the identifier of the target.

Parameters

target (str or int) – Name of the target as a string, e.g. “TOI-175” or, if mission is passed as the numerical identifier of the input catalog.

Returns

mission – ‘Kepler’, ‘K2’ or ‘TESS’

Return type

str

Raises

ValueError – If the target was not resolved or linked to a supported mission

target_identifier(target, mission=None)

Translates the target identifiers between different catalogs such as TIC to TOI in the case of TESS or EPIC to KIC” for K2

Parameters
  • target (str or int) – Name of the target as a string, e.g. “TOI-175” or, if mission is passed as the numerical identifier of the input catalog.

  • mission (str, optional) – ‘Kepler’, ‘K2’ or ‘TESS’

Returns

  • inputCatalogID (str) – Identifier in the format of the input catalog, e.g. “TIC307210830”

  • missionCatalogID (str or None) – Identifier in the format of the mission catalog, e.g. “TOI-175”. None if no ID was found.

  • ICnum (int) – Number of the input catalog, e.g. “307210830”

Raises

ValueError – If the target was not resolved or linked to a supported mission

read_lc_from_file(file, author=None, exptime=None, timeformat=None, colnames=None)

Creates a LightCurve from a file.

Parameters
  • file (str) – Path to the file containing the light curve data.

  • author (str, optional.) – Name of the pipeline used to reduce the data.

  • exptime (~astropy.units.Quantity or float, optional.) – Exposure time of the observation, in seconds.

  • timeformat (str, optional.) – Format of the Time values. Should be ‘rjd’, ‘bkjd’, ‘btjd’, or a valid ~astropy.time.Time format. Refer to the docs here: (https://docs.astropy.org/en/stable/time/index.html#time-format)

  • colnames (list (of str), optional.) – Names of the columns. Should have the same number of items as the number of columns.

Returns

lc – LightCurve object with data from the file.

Return type

‘~lightkurve.lightcurve.LightCurve’

normalize_lc(lc_in, unit='unscaled')

Returns a normalized version of the light curve using robust stats.

Parameters
  • lc_in ('~lightkurve.lightcurve.LightCurve') – LightCurve object.

  • unit ('unscaled', 'percent', 'ppt', 'ppm') – The desired relative units of the normalized light curve; ‘ppt’ means ‘parts per thousand’, ‘ppm’ means ‘parts per million’.

Returns

lc – A new light curve object in which flux and flux_err have been divided by the median flux.

Return type

‘~lightkurve.lightcurve.LightCurve’

Warns

LightkurveWarning – If the median flux is negative or within half a standard deviation from zero.

time_flux_err(timeseries, flux_kw='flux', flux_err_kw='flux_err', replace_nan_err=True)

Extracts 3 arrays with time, flux and flux_err from a TimeSeries.

Parameters
  • timeseries (~astropy.timeseries.TimeSeries) – TimeSeries object

  • flux_kw (str, optional) – Keyword for the column containing the flux values (Default: ‘flux’)

  • flux_err_kw (str, optional) – Keyword for the column containing the flux uncertainty values (Default: ‘flux_err’)

  • replace_nan_err (bool, optional) – To deal with the case where the flux_err column is full of NaNs. When True, creates an array filled with the standard deviation of the flux. When false, returns an array full of NaNs. (default : True)

Returns

  • t (array) – Array of time where values of type NaN, None, inf, and negative have been removed, as well as masks.

  • flux (array) – Array of flux where values of type NaN, None, inf, and negative have been removed, as well as masks.

  • flux_err (array) – Array of flux_err where values of type NaN, None, inf, and negative have been removed, as well as masks. If the original was filled with NaNs: if replace_nan_err=True, returns an array filled with the standard deviation of flux. if replace_nan_err=False, returns an array filled with Nans.

ts_binner(timeseries, bin_duration)

Wrap around for astropy’s aggregate_downsample returning a `~astropy.timeseries.TimeSeries`object with Time at the center of the bins.

Parameters
  • timeseries (~astropy.timeseries.TimeSeries) – TimeSeries object

  • bin_duration (~astropy.units.Quantity or float) – Time interval for the binned time series. (Default is in units of days)

Returns

ts_binned – TimeSeries which has been binned. With time corresponding to the center time of all time bins

Return type

~astropy.timeseries.TimeSeries

fbn(timeseries, period, epoch0, duration=<Quantity 3. h>, nbin=40)

fbn for “fold, bin, norm”

Parameters
  • timeseries (~astropy.timeseries.TimeSeries) – TimeSeries object

  • period (~astropy.time.Time or float) – The period to use for folding.

  • epoch0 (~astropy.units.Quantity or float) – The time to use as the reference epoch.

  • duration (~astropy.units.Quantity or float, optional) – Duration of the transit. (Default is 3 hours)

  • nbin (int, optional) – Number of bins in the transit window. (Default is 40)

Returns

  • ts_fold (~astropy.timeseries.TimeSeries) – The folded time series with an extra column ‘phase_norm’.

  • ts_fold_bin (~astropy.timeseries.TimeSeries) – The folded binned time series with an extra column ‘phase_norm’.

GP_fit(time, flux, flux_err=None, mode='rotation', period_min=0.2, period_max=100, tune=2500, draws=2500, chains=2, target_accept=0.95, per=None, ncores=None)

Uses Gaussian Processes to model stellar activity.

Parameters
  • time (array) – array of times at which data were taken

  • flux (array) – array of flux at corresponding time

  • flux_err (array, optional) – array of measurment errors of the flux data. Defaults to np.std(flux)

  • mode ('rotation', others to be implemented, optional) – Type of stellar variablity to correct.

  • period_min (float, optional) – Minimum value for the rotation period of the star. (In days)

  • period_max (float, optional) – Maximum value for the rotation period of the star. (In days)

  • tune (int, optional) – number of tune iterations

  • draws (int, optional) – number of draws iterations

  • chains (int, optional) – number of chains to sample

  • target_accept (float, optional) – number should be between 0 and 1

  • per (float, optional) – Estimation of the variability period.

  • ncores (int, optional) – Number of cores to use for processing. (Default: all)

Returns

  • trace (arviz.data.inference_data.InferenceData)

  • flat_samps (xarray.core.dataset.Dataset)

params_optimizer(timeseries, period_guess, t0_guess, depth_guess, ab, r_star, target_id, tran_window=0.25, tune=2500, draws=2500, chains=2, target_accept=0.95, ncores=None, mask=None)

Translates the target identifiers between different catalogs such as TIC to TOI in the case of TESS or EPIC to KIC” for K2

Parameters
  • timeseries (~astropy.timeseries.TimeSeries, optional) – TimeSeries object

  • period_guess (int or float) – Initial estimate of the orbital period

  • t0_guess (int or float) – Inital estimate of the mid-transit time of the first transit within the time series

  • depth_guess (float) – Initial estimate of the transit depth

  • ab (tuple of floats) – Quadratic limb darkening parameters a, b.

  • r_star (float) – Stellar radius (in units of solar radii).

  • target_id (str) – Name of the target as a string

  • tran_window (int or float) – Window around the center of transits for efficiency (in units of days)

  • tune (int, optional) – number of tune iterations

  • draws (int, optional) – number of draws iterations

  • chains (int, optional) – number of chains to sample

  • target_accept (float, optional) – number should be between 0 and 1

  • ncores (int, optional) – Number of cores to use for processing. (Default: all)

  • mask (boolean array with length of time) – Boolean array to mask data, typically transits. Data where mask is “False” will not be taken into account for the fit.

Returns

  • p (float) – Orbital period

  • t0 (float) – Mid-transit time of the first transit within the time series

  • dur – Duration of the transit

  • depth – Depth of the transit

  • ab (tuple of floats) – Quadratic limb darkening parameters a, b.

  • flat_samps (xarray.core.dataset.Dataset)

estimate_planet_mass(R_p, rho_p)

Estimates the mass of an exoplanet from its radius and density.

Parameters
  • R_p (~astropy.units.Quantity or float) – Radius of the exolanet. (defaults to units of Earth radii)

  • rho_p (~astropy.units.Quantity, float or str) – Density of the exoplanet in kg * m^-3. Can be “Earth” or “Neptune”.

Returns

M_planet – Estimated mass of the exoplanet.

Return type

~astropy.units.Quantity

estimate_semi_amplitude(period, M_star, M_planet=None, R_planet=None, rho_planet=None, inc=<Quantity 90. deg>, ecc=0)

Estimates the radial velocity semi-amplitude corresponding to a planet of given parameters.

Parameters
  • period (~astropy.units.Quantity or float) – The period to use for folding. (defaults to units of days)

  • M_star (~astropy.units.Quantity or float) – Stellar mass (defaults to units of solar masses)

  • M_planet (~astropy.units.Quantity or float) – Mass of the exolanet. (defaults to units of Earth masses)

  • R_planet (~astropy.units.Quantity or float) – Radius of the exolanet. (defaults to units of Earth radii)

  • rho_planet (~astropy.units.Quantity, float or str) – Density of the exoplanet in kg * m^-3. Can be “Earth” or “Neptune”.

  • inc (~astropy.units.Quantity or float) – Orbital inclination (in degrees). Default: 90.

  • ecc (float) – Orbital eccentricity. Default: 0.

Returns

K – Estimated semi-amplitude of the RV.

Return type

~astropy.units.Quantity

Time

Adds the RJD time format for use by Astropy’s Time object. Caution: AstroPy time objects make a distinction between a time’s format (e.g. ISO, JD, MJD) and its scale (e.g. UTC, TDB).

class TimeRJD(val1, val2, scale, precision, in_subfmt, out_subfmt, from_jd=False)

Reduced Julian Date (RJD) time format. This represents the number of days since noon on November 16, 1858. For example, 51544.5 in RJD is midnight on January 1, 2000. Typically used in DACE. RJD = JD − 2400000

rjd_to_astropy_time(rjd) astropy.time.core.Time

Converts Reduced Julian Day (RJD) time values to an ~astropy.time.Time object. Reduced Julian Day (RJD) is a Julian day minus 2400000.0 (UTC=January 1, 2000 12:00:00).. The time is in the Barycentric Dynamical Time frame (TDB), which is a time system that is not affected by leap seconds.

Parameters

rjd (float or array of floats) – Reduced Julian Day.

Returns

time – Resulting time object.

Return type

astropy.time.Time object

Utils

exception FulmarError

To raise exceptions related to FULMAR

exception FulmarWarning

Class from warning to be displayed as “FulmarWarning”

print_version()

Prints the version of FULMAR used.

warning_on_one_line(message, category, filename, lineno, file=None, line=None)

Function to display warnings on one line, as to avoid displaying ‘warnings.warn(‘warning message’)’ under the ‘warning message’