astrobase.lcmath module¶
Contains various useful tools for calculating various things related to lightcurves (like phasing, sigmaclipping, finding and filling gaps, etc.)

astrobase.lcmath.
find_lc_timegroups
(lctimes, mingap=4.0)[source]¶ Finds gaps in the provided timeseries and indexes them into groups.
This finds the gaps in the provided lctimes array, so we can figure out which times are for consecutive observations and which represent gaps between seasons or observing eras.
Parameters:  lctimes (arraylike) – This contains the times to analyze for gaps; assumed to be some form of Julian date.
 mingap (float) – This defines how much the difference between consecutive measurements is allowed to be to consider them as parts of different timegroups. By default it is set to 4.0 days.
Returns: A tuple of the form: (ngroups, [slice(start_ind_1, end_ind_1), …]) is returned. This contains the number of groups as the first element, and a list of Python slice objects for each timegroup found. These can be used directly to index into the array of times to quickly get measurements associated with each group.
Return type: tuple

astrobase.lcmath.
normalize_magseries
(times, mags, mingap=4.0, normto='globalmedian', magsarefluxes=False, debugmode=False)[source]¶ This normalizes the magnitude timeseries to a specified value.
This is used to normalize time series measurements that may have large time gaps and vertical offsets in mag/flux measurement between these ‘timegroups’, either due to instrument changes or different filters.
NOTE: this works inplace! The mags array will be replaced with normalized mags when this function finishes.
Parameters:  times,mags (arraylike) – The times (assumed to be some form of JD) and mags (or flux) measurements to be normalized.
 mingap (float) – This defines how much the difference between consecutive measurements is allowed to be to consider them as parts of different timegroups. By default it is set to 4.0 days.
 normto ({'globalmedian', 'zero'} or a float) –
Specifies the normalization type:
'globalmedian' > norms each mag to the global median of the LC column 'zero' > norms each mag to zero a float > norms each mag to this specified float value.
 magsarefluxes (bool) –
Indicates if the input mags array is actually an array of flux measurements instead of magnitude measurements. If this is set to True, then:
 if normto is ‘zero’, then the median flux is divided from each observation’s flux value to yield normalized fluxes with 1.0 as the global median.
 if normto is ‘globalmedian’, then the global median flux value across the entire time series is multiplied with each measurement.
 if norm is set to a float, then this number is multiplied with the flux value for each measurement.
 debugmode (bool) – If this is True, will print out verbose info on each timegroup found.
Returns: times,normalized_mags – Normalized magnitude values after normalization. If normalization fails for some reason, times and normalized_mags will both be None.
Return type: np.arrays

astrobase.lcmath.
sigclip_magseries
(times, mags, errs, sigclip=None, iterative=False, niterations=None, meanormedian='median', magsarefluxes=False)[source]¶ Sigmaclips a magnitude or flux timeseries.
Selects the finite times, magnitudes (or fluxes), and errors from the passed values, and apply symmetric or asymmetric sigma clipping to them.
Parameters:  times,mags,errs (np.array) –
The magnitude or flux timeseries arrays to sigmaclip. This doesn’t assume all values are finite or if they’re positive/negative. All of these arrays will have their nonfinite elements removed, and then will be sigmaclipped based on the arguments to this function.
errs is optional. Set it to None if you don’t have values for these. A ‘faked’ errs array will be generated if necessary, which can be ignored in the output as well.
 sigclip (float or int or sequence of two floats/ints or None) –
If a single float or int, a symmetric sigmaclip will be performed using the number provided as the sigmamultiplier to cut out from the input timeseries.
If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigmaclip. The first element in this list is the sigma value to use for fainter flux/mag values; the second element in this list is the sigma value to use for brighter flux/mag values. For example, sigclip=[10., 3.], will sigclip out greater than 10sigma dimmings and greater than 3sigma brightenings. Here the meaning of “dimming” and “brightening” is set by physics (not the magnitude system), which is why the magsarefluxes kwarg must be correctly set.
If sigclip is None, no sigmaclipping will be performed, and the timeseries (with nonfinite elems removed) will be passed through to the output.
 iterative (bool) – If this is set to True, will perform iterative sigmaclipping. If niterations is not set and this is True, sigmaclipping is iterated until no more points are removed.
 niterations (int) – The maximum number of iterations to perform for sigmaclipping. If None, the iterative arg takes precedence, and iterative=True will sigmaclip until no more points are removed. If niterations is not None and iterative is False, niterations takes precedence and iteration will occur for the specified number of iterations.
 meanormedian ({'mean', 'median'}) – Use ‘mean’ for sigmaclipping based on the mean value, or ‘median’ for sigmaclipping based on the median value. Default is ‘median’.
 magsareflux (bool) – True if your “mags” are in fact fluxes, i.e. if “fainter” corresponds to mags getting smaller.
Returns: (stimes, smags, serrs) – The sigmaclipped and nanstripped timeseries.
Return type: tuple
 times,mags,errs (np.array) –

astrobase.lcmath.
sigclip_magseries_with_extparams
(times, mags, errs, extparams, sigclip=None, iterative=False, magsarefluxes=False)[source]¶ Sigmaclips a magnitude or flux timeseries and associated measurement arrays.
Selects the finite times, magnitudes (or fluxes), and errors from the passed values, and apply symmetric or asymmetric sigma clipping to them. Uses the same array indices as these values to filter out the values of all arrays in the extparams list. This can be useful for simultaneously sigmaclipping a magnitude/flux timeseries along with their associated values of external parameters, such as telescope hour angle, zenith distance, temperature, moon phase, etc.
Parameters:  times,mags,errs (np.array) –
The magnitude or flux timeseries arrays to sigmaclip. This doesn’t assume all values are finite or if they’re positive/negative. All of these arrays will have their nonfinite elements removed, and then will be sigmaclipped based on the arguments to this function.
errs is optional. Set it to None if you don’t have values for these. A ‘faked’ errs array will be generated if necessary, which can be ignored in the output as well.
 extparams (list of np.array) – This is a list of all external parameter arrays to simultaneously filter along with the magnitude/flux timeseries. All of these arrays should have the same length as the times, mags, and errs arrays.
 sigclip (float or int or sequence of two floats/ints or None) –
If a single float or int, a symmetric sigmaclip will be performed using the number provided as the sigmamultiplier to cut out from the input timeseries.
If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigmaclip. The first element in this list is the sigma value to use for fainter flux/mag values; the second element in this list is the sigma value to use for brighter flux/mag values. For example, sigclip=[10., 3.], will sigclip out greater than 10sigma dimmings and greater than 3sigma brightenings. Here the meaning of “dimming” and “brightening” is set by physics (not the magnitude system), which is why the magsarefluxes kwarg must be correctly set.
If sigclip is None, no sigmaclipping will be performed, and the timeseries (with nonfinite elems removed) will be passed through to the output.
 iterative (bool) – If this is set to True, will perform iterative sigmaclipping. If niterations is not set and this is True, sigmaclipping is iterated until no more points are removed.
 magsareflux (bool) – True if your “mags” are in fact fluxes, i.e. if “fainter” corresponds to mags getting smaller.
Returns: (stimes, smags, serrs) – The sigmaclipped and nanstripped timeseries in stimes, smags, serrs and the associated values of the extparams in sextparams.
Return type: tuple
 times,mags,errs (np.array) –

astrobase.lcmath.
phase_magseries
(times, mags, period, epoch, wrap=True, sort=True)[source]¶ Phases a magnitude/flux timeseries using a given period and epoch.
The equation used is:
phase = (times  epoch)/period  floor((times  epoch)/period)
This phases the given magnitude timeseries using the given period and epoch. If wrap is True, wraps the result around 0.0 (and returns an array that has twice the number of the original elements). If sort is True, returns the magnitude timeseries in phase sorted order.
Parameters:  times,mags (np.array) – The magnitude/flux timeseries values to phase using the provided period and epoch. Nonfiinite values will be removed.
 period (float) – The period to use to phase the timeseries.
 epoch (float) – The epoch to phase the timeseries. This is usually the timeofminimum or timeofmaximum of some periodic light curve phenomenon. Alternatively, one can use the minimum time value in times.
 wrap (bool) – If this is True, the returned phased timeseries will be wrapped around phase 0.0, which is useful for plotting purposes. The arrays returned will have twice the number of input elements because of this wrapping.
 sort (bool) – If this is True, the returned phased timeseries will be sorted in increasing phase order.
Returns: A dict of the following form is returned:
{'phase': the phase values, 'mags': the mags/flux values at each phase, 'period': the input `period` used to phase the timeseries, 'epoch': the input `epoch` used to phase the timeseries}
Return type: dict

astrobase.lcmath.
phase_magseries_with_errs
(times, mags, errs, period, epoch, wrap=True, sort=True)[source]¶ Phases a magnitude/flux timeseries using a given period and epoch.
The equation used is:
phase = (times  epoch)/period  floor((times  epoch)/period)
This phases the given magnitude timeseries using the given period and epoch. If wrap is True, wraps the result around 0.0 (and returns an array that has twice the number of the original elements). If sort is True, returns the magnitude timeseries in phase sorted order.
Parameters:  times,mags,errs (np.array) – The magnitude/flux timeseries values and associated measurement errors to phase using the provided period and epoch. Nonfiinite values will be removed.
 period (float) – The period to use to phase the timeseries.
 epoch (float) – The epoch to phase the timeseries. This is usually the timeofminimum or timeofmaximum of some periodic light curve phenomenon. Alternatively, one can use the minimum time value in times.
 wrap (bool) – If this is True, the returned phased timeseries will be wrapped around phase 0.0, which is useful for plotting purposes. The arrays returned will have twice the number of input elements because of this wrapping.
 sort (bool) – If this is True, the returned phased timeseries will be sorted in increasing phase order.
Returns: A dict of the following form is returned:
{'phase': the phase values, 'mags': the mags/flux values at each phase, 'errs': the err values at each phase, 'period': the input `period` used to phase the timeseries, 'epoch': the input `epoch` used to phase the timeseries}
Return type: dict

astrobase.lcmath.
time_bin_magseries
(times, mags, binsize=540.0, minbinelems=7)[source]¶ Bins the given mag/flux timeseries in time using the bin size given.
Parameters:  times,mags (np.array) – The magnitude/flux timeseries to bin in time. Nonfinite elements will be removed from these arrays. At least 10 elements in each array are required for this function to operate.
 binsize (float) – The bin size to use to group together measurements closer than this amount in time. This is in seconds.
 minbinelems (int) – The minimum number of elements required per bin to include it in the output.
Returns: A dict of the following form is returned:
{'jdbin_indices': a list of the index arrays into the nanfiltered input arrays per each bin, 'jdbins': list of bin boundaries for each bin, 'nbins': the number of bins generated, 'binnedtimes': the time values associated with each time bin; this is the median of the times in each bin, 'binnedmags': the mag/flux values associated with each time bin; this is the median of the mags/fluxes in each bin}
Return type: dict

astrobase.lcmath.
time_bin_magseries_with_errs
(times, mags, errs, binsize=540.0, minbinelems=7)[source]¶ Bins the given mag/flux timeseries in time using the bin size given.
Parameters:  times,mags,errs (np.array) – The magnitude/flux timeseries and associated measurement errors to bin in time. Nonfinite elements will be removed from these arrays. At least 10 elements in each array are required for this function to operate.
 binsize (float) – The bin size to use to group together measurements closer than this amount in time. This is in seconds.
 minbinelems (int) – The minimum number of elements required per bin to include it in the output.
Returns: A dict of the following form is returned:
{'jdbin_indices': a list of the index arrays into the nanfiltered input arrays per each bin, 'jdbins': list of bin boundaries for each bin, 'nbins': the number of bins generated, 'binnedtimes': the time values associated with each time bin; this is the median of the times in each bin, 'binnedmags': the mag/flux values associated with each time bin; this is the median of the mags/fluxes in each bin, 'binnederrs': the err values associated with each time bin; this is the median of the errs in each bin}
Return type: dict

astrobase.lcmath.
phase_bin_magseries
(phases, mags, binsize=0.005, minbinelems=7)[source]¶ Bins a phased magnitude/flux timeseries using the bin size provided.
Parameters:  phases,mags (np.array) – The phased magnitude/flux timeseries to bin in phase. Nonfinite elements will be removed from these arrays. At least 10 elements in each array are required for this function to operate.
 binsize (float) – The bin size to use to group together measurements closer than this amount in phase. This is in units of phase.
 minbinelems (int) – The minimum number of elements required per bin to include it in the output.
Returns: A dict of the following form is returned:
{'phasebin_indices': a list of the index arrays into the nanfiltered input arrays per each bin, 'phasebins': list of bin boundaries for each bin, 'nbins': the number of bins generated, 'binnedphases': the phase values associated with each phase bin; this is the median of the phase value in each bin, 'binnedmags': the mag/flux values associated with each phase bin; this is the median of the mags/fluxes in each bin}
Return type: dict

astrobase.lcmath.
phase_bin_magseries_with_errs
(phases, mags, errs, binsize=0.005, minbinelems=7, weights=None)[source]¶ Bins a phased magnitude/flux timeseries using the bin size provided.
Parameters:  phases,mags,errs (np.array) – The phased magnitude/flux timeseries and associated errs to bin in phase. Nonfinite elements will be removed from these arrays. At least 10 elements in each array are required for this function to operate.
 binsize (float) – The bin size to use to group together measurements closer than this amount in phase. This is in units of phase.
 minbinelems (int) – The minimum number of elements required per bin to include it in the output.
 weights (np.array or None) – Optional weight vector to be applied during binning. If if is passed,
np.average is used to bin, rather than np.median. A good choice
would be to pass
weights=1/errs**2
, to weight by the inverse variance.
Returns: A dict of the following form is returned:
{'phasebin_indices': a list of the index arrays into the nanfiltered input arrays per each bin, 'phasebins': list of bin boundaries for each bin, 'nbins': the number of bins generated, 'binnedphases': the phase values associated with each phase bin; this is the median of the phase value in each bin, 'binnedmags': the mag/flux values associated with each phase bin; this is the median of the mags/fluxes in each bin, 'binnederrs': the err values associated with each phase bin; this is the median of the errs in each bin}
Return type: dict

astrobase.lcmath.
fill_magseries_gaps
(times, mags, errs, fillgaps=0.0, sigclip=3.0, magsarefluxes=False, filterwindow=11, forcetimebin=None, verbose=True)[source]¶ This fills in gaps in a light curve.
This is mainly intended for use in ACF periodfinding, but maybe useful otherwise (i.e. when we figure out ARMA stuff for LCs). The main steps here are:
 normalize the light curve to zero
 remove giant outliers
 interpolate gaps in the light curve (since ACF requires evenly spaced sampling)
From McQuillan+ 2013a (https://doi.org/10.1093/mnras/stt536):
“The ACF calculation requires the light curves to be regularly sampled and normalized to zero. We divided the flux in each quarter by its median and subtracted unity. Gaps in the light curve longer than the Kepler long cadence were filled using linear interpolation with added white Gaussian noise. This noise level was estimated using the variance of the residuals following subtraction of a smoothed version of the flux. To smooth the flux, we applied an iterative nonlinear filter which consists of a median filter followed by a boxcar filter, both with 11point windows, with iterative 3σ clipping of outliers.”Parameters:  times,mags,errs (np.array) – The magnitude/flux timeseries and associated measurement errors to operate on. Nonfinite elements will be removed from these arrays. At least 10 elements in each array are required for this function to operate.
 fillgaps ({'noiselevel', 'nan'} or float) – If fillgap=’noiselevel’, fills the gaps with the noise level obtained via the procedure above. If fillgaps=’nan’, fills the gaps with np.nan. Otherwise, if fillgaps is a float, will use that value to fill the gaps. The default is to fill the gaps with 0.0 (as in McQuillan+ 2014) to “…prevent them contributing to the ACF”.
 sigclip (float or int or sequence of two floats/ints or None) –
If a single float or int, a symmetric sigmaclip will be performed using the number provided as the sigmamultiplier to cut out from the input timeseries.
If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigmaclip. The first element in this list is the sigma value to use for fainter flux/mag values; the second element in this list is the sigma value to use for brighter flux/mag values. For example, sigclip=[10., 3.], will sigclip out greater than 10sigma dimmings and greater than 3sigma brightenings. Here the meaning of “dimming” and “brightening” is set by physics (not the magnitude system), which is why the magsarefluxes kwarg must be correctly set.
If sigclip is None, no sigmaclipping will be performed, and the timeseries (with nonfinite elems removed) will be passed through to the output.
 magsareflux (bool) – True if your “mags” are in fact fluxes, i.e. if “fainter” corresponds to mags getting smaller.
 filterwindow (int) – The number of timeseries points to include in the SavitskyGolay filter operation when smoothing the light curve. This should be an odd integer.
 forcetimebin (float or None) – If forcetimebin is a float, this value will be used to generate the interpolated time series, effectively binning the light curve to this cadence. If forcetimebin is None, the mode of the gaps (the forward difference between successive time values in times) in the provided light curve will be used as the effective cadence. NOTE: forcetimebin must be in the same units as times, e.g. if times are JD then forcetimebin must be in days as well
 verbose (bool) – If this is True, will indicate progress at various stages in the operation.
Returns: A dict of the following form is returned:
{'itimes': the interpolated time values after gapfilling, 'imags': the interpolated mag/flux values after gapfilling, 'ierrs': the interpolated mag/flux values after gapfilling, 'cadence': the cadence of the output mag/flux timeseries}
Return type: dict