API documentation¶
Target object¶
- class fulmar.target(targname, mission=None)¶
- Parameters
When the object is created, some parameters are automatically retrieved:
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)
- flux_kw (str) – Keyword for the column containing the flux values
(Default: ‘flux’)
- flux_err_kw (str) – Keyword for the column containing the flux uncertainty values
(Default: ‘flux_err’)
lc_folder (str) – Path to the folder where data is produced.
- For Kepler targets:
- KIC (str) – Identifier in the format of the Kepler input
catalog, e.g. “KIC11904151”
- kep (str) – Identifier in the format of the Kepler mission
catalog, e.g. “Kepler-10”
KIC_num (int) – Number of the input catalog, e.g. “11904151”
- For K2 targets:
- EPIC (str) – Identifier in the format of the Ecliptic Plane input
catalog, e.g. “EPIC201437844”
- K2 (str) – Identifier in the format of the K2 mission
catalog, e.g. “K2-109”
EPIC_num (int) – Number of the input catalog, e.g. “201437844”
- For TESS targets:
- TIC (str) – Identifier in the format of the TESS input catalog,
e.g. “TIC307210830”
- TOI (str) – Identifier in the format of the TESS mission catalog,
e.g. “TOI-175”
- TIC_num (int) – Number of the input catalog,
e.g. “307210830”
- target.set_lc_folder(inptfolder)¶
Sets the folder in which the lightcurves are downloaded
- target.set_flux_kw(flux_kw)¶
Sets the keyword for the column containing the flux values.
- target.set_flux_err_kw(flux_err_kw)¶
Sets the keyword for the column containing the flux uncertainty values.
- 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_stitch – TimeSeries object combining data from selected lightcurves.
- Return type
astropy.timeseries.TimeSeries
- 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 toTrue
, this method will also returntrend_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=False)¶
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 toTrue
, this method will also returntrend_ts (~astropy.timeseries.TimeSeries) – New TimeSeries object containing the trend that was removed from the flux.
- target.plot_transitcheck(period, epoch0, duration=<Quantity 3. h>, nbin=40, timeseries=None, savefig=False, 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.
fig_id (str or int) – Suffix for the filename when the figure is exported.
- 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
- 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
- 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
andflux_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
flat_samps
- params_optimizer(timeseries, period_guess, t0_guess, depth_guess, ab, r_star, target_id, tran_window=0.25, ncores=None, mask=None)¶
- 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_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”.
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). Note: the class below derive from an astropy meta class which will automatically register the format for use in astropy.time.Time objects.
- 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
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.
- 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
- 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’, for clarity.