FlareLightCurve

class altaipony.flarelc.FlareLightCurve(time=None, flux=None, flux_err=None, time_format=None, time_scale=None, time_unit=None, centroid_col=None, centroid_row=None, quality=None, quality_bitmask=None, channel=None, campaign=None, quarter=None, sector=None, mission=None, cadenceno=None, targetid=None, ra=None, dec=None, label=None, meta={}, detrended_flux=None, detrended_flux_err=None, flux_trends=None, gaps=None, flares=None, flux_unit=None, primary_header=None, data_header=None, pos_corr1=None, pos_corr2=None, origin='FLC', fake_flares=None, it_med=None, pixel_flux=None, pixel_flux_err=None, pipeline_mask=None, camera=None, ccd=None, saturation=None)[source]

Bases: lightkurve.lightcurve.KeplerLightCurve, lightkurve.lightcurve.TessLightCurve

Flare light curve class that unifies properties of K2SC-de-trended and Kepler’s lightkurve.KeplerLightCurve.

Attributes:
time : array-like

Time measurements.

flux : array-like

Flux count for every time point.

flux_err : array-like

Uncertainty on each flux data point.

pixel_flux : multi-dimensional array

Flux in the target pixels from the KeplerTargetPixelFile.

pixel_flux_err : multi-dimensional array

Uncertainty on pixel_flux.

pipeline_mask : multi-dimensional boolean array

TargetPixelFile mask for aperture photometry.

time_format : str

String specifying how an instant of time is represented, e.g., ‘bkjd’ or ‘jd’.

time_scale : str

String that specifies how the time is measured, e.g., tdb’, ‘tt’, ‘ut1’, or ‘utc’.

time_unit : astropy.unit

Astropy unit object defining unit of time.

centroid_col : array-like

Centroid column coordinates as a function of time.

centroid_row : array-like

Centroid row coordinates as a function of time.

quality : array-like

Kepler quality flags.

quality_bitmask : str

Can be ‘none’, ‘default’, ‘hard’ or ‘hardest’.

channel : int

Channel number, where aperture is located on the CCD.

campaign : int

K2 campaign number.

quarter : int

Kepler Quarter number.

sector : int

TESS sector number

mission : string

Mission identifier, e.g., ‘TESS’, ‘K2’ or ‘Kepler’.

cadenceno : array-like

Cadence number - unique identifier.

targetid : int

EPIC ID number.

ra : float

RA in deg.

dec : float

Declination in deg.

label : string

‘EPIC xxxxxxxxx’.

meta : dict

Free-form metadata associated with the LightCurve. Not populated in general.

detrended_flux : array-like

K2SC detrend flux, same units as flux.

detrended_flux_err : array-like

K2SC detrend flux error, same units as flux.

flux_trends : array-like

Astrophysical variability as derived by K2SC.

gaps : list of tuples of ints

Each tuple contains the start and end indices of observation gaps. See find_gaps.

flares : DataFrame

Table of flares, their start and stop time, recovered equivalent duration (ED), and, if applicable, recovery probability, ratio of recovered ED to injected synthetic ED. Also information about quality flags may be stored here.

it_med : array-like

Iterative median, see the find_iterative_median method.

Methods Summary

characterize_flares(self[, ampl_bins, dur_bins]) Use results from injection recovery to determine corrected flare characteristics.
detrend(self, mode[, save, path, de_niter, …]) De-trends a FlareLightCurve using K2SC.
find_flares(self[, minsep, fake]) Find flares in a FlareLightCurve.
find_gaps(self[, maxgap, minspan]) Find gaps in light curve and stores them in the gaps attribute.
get_saturation(self[, factor, return_level]) Goes back to the TPF and measures the maximum saturation level during a flare, averaged over the aperture mask.
inject_fake_flares(self[, gapwindow, …]) Create a number of events, inject them in to data Use grid of amplitudes and durations, keep ampl in relative flux units Keep track of energy in Equiv Dur.
mark_flagged_flares(self[, explain]) Mark all flares that coincide with K2 flagged cadences.
sample_flare_recovery(self[, iterations, …]) Runs a number of injection recovery cycles and characterizes the light curve by recovery probability and equivalent duration underestimation.
to_fits(self, path) Write FlareLightCurve to a .fits file.

Methods Documentation

characterize_flares(self, ampl_bins=80, dur_bins=160)[source]

Use results from injection recovery to determine corrected flare characteristics.

detrend(self, mode, save=False, path='detrended_lc.fits', de_niter=30, max_sigma=3, func=None, **kwargs)[source]

De-trends a FlareLightCurve using K2SC. Optionally saves the LightCurve in a fits file that can be read as K2SC file.

mode : str
“k2sc” or “savgol” or “custom”
de_niter : int
Differential Evolution global optimizer parameter. K2SC default is 150, here set to 30 as a safety net to avoid unintenional computational effort.
max_sigma: int
Default is 3, value is passed to iterative sigma clipping in K2SC
save : False or bool
If True, the light curve is saved as a fits file to a given folder.
path : str
Path to resulting fits file. As a default, the fits file will be stored in the working directory.
func : function
custom detrending function
kwargs : dict
Keyword arguments to pass to k2sc, detrend_savgol, or custom method
Returns:
FlareLightCurve
find_flares(self, minsep=3, fake=False, **kwargs)[source]

Find flares in a FlareLightCurve.

Parameters:
minsep : 3 or int

Minimum distance between two candidate start times in datapoints.

kwargs : dict

keyword arguments to pass to find_flares_in_cont_obs_period()

Returns:
FlareLightCurve
find_gaps(self, maxgap=0.09, minspan=10)[source]

Find gaps in light curve and stores them in the gaps attribute.

Parameters:
time : numpy array with floats

sorted array, in units of days

maxgap : 0.09 or float

maximum time gap between two datapoints in days, default equals approximately 2h

minspan : 10 or int

minimum number of datapoints in continuous observation, i.e., w/o gaps as defined by maxgap

Returns:
FlareLightCurve
get_saturation(self, factor=10, return_level=False)[source]

Goes back to the TPF and measures the maximum saturation level during a flare, averaged over the aperture mask.

Parameters:
factor : 10 or float

Saturation level in full well depths.

Returns:
FlareLightCurve with modified ‘flares’ attribute.
inject_fake_flares(self, gapwindow=0.1, fakefreq=0.005, inject_before_detrending=False, d=False, seed=None, **kwargs)[source]

Create a number of events, inject them in to data Use grid of amplitudes and durations, keep ampl in relative flux units Keep track of energy in Equiv Dur. Duration defined in minutes Amplitude defined multiples of the median error

mark_flagged_flares(self, explain=False)[source]

Mark all flares that coincide with K2 flagged cadences. Explain the flags if needed.

Parameters:
explain : False or bool

If True, an explanation column will be added to the flares table explaining the flags that were raised during the flare duration.

Returns:
FlareLightCurve with the flares table supplemented with an integer
quality and, if applicable, a string explanation column.
sample_flare_recovery(self, iterations=2000, inject_before_detrending=False, mode=None, func=None, save_lc_to_file=False, folder='', fakefreq=0.05, save=False, path=None, **kwargs)[source]

Runs a number of injection recovery cycles and characterizes the light curve by recovery probability and equivalent duration underestimation. Inject one flare per light curve.

Parameters:
iterations : 2000 or int

Number of injection/recovery cycles

inject_before_detrending : False or bool

If True, fake flare are injected directly into raw data.

mode : str

“savgol” or “k2sc”. Required if inject_before_detrending is True.

fakefreq : 0.05 or float

number of flares per day, but at least one per continuous observation period will be injected

kwargs : dict

Keyword arguments to pass to inject_fake_flares

Returns:
lc : FlareLightCurve

Detrended LC with all fake_flares listed in the attribute

fake_lc : FlareLightCurve

Light curve with the last iteration of synthetic flares injected.

to_fits(self, path)[source]

Write FlareLightCurve to a .fits file. Read it in again using from_path().