astrobase.lcmath module

Contains various useful tools for calculating various things related to lightcurves (like phasing, sigma-clipping, finding and filling gaps, etc.)

astrobase.lcmath.find_lc_timegroups(lctimes, mingap=4.0)

Finds gaps in the provided time-series 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 (array-like) – 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 time-group 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)

This normalizes the magnitude time-series 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 in-place! The mags array will be replaced with normalized mags when this function finishes.

Parameters:

• times,mags (array-like) – 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)

Sigma-clips a magnitude or flux time-series.

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 time-series arrays to sigma-clip. This doesn’t assume all values are finite or if they’re positive/negative. All of these arrays will have their non-finite elements removed, and then will be sigma-clipped 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 sigma-clip will be performed using the number provided as the sigma-multiplier to cut out from the input time-series.

  If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigma-clip. 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 10-sigma dimmings and greater than 3-sigma 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 sigma-clipping will be performed, and the time-series (with non-finite elems removed) will be passed through to the output.

• iterative (bool) – If this is set to True, will perform iterative sigma-clipping. If niterations is not set and this is True, sigma-clipping is iterated until no more points are removed.
• niterations (int) – The maximum number of iterations to perform for sigma-clipping. If None, the iterative arg takes precedence, and iterative=True will sigma-clip 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 sigma-clipping based on the mean value, or ‘median’ for sigma-clipping 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 sigma-clipped and nan-stripped time-series.

Return type:

tuple

astrobase.lcmath.sigclip_magseries_with_extparams(times, mags, errs, extparams, sigclip=None, iterative=False, magsarefluxes=False)

Sigma-clips a magnitude or flux time-series 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 sigma-clipping a magnitude/flux time-series 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 time-series arrays to sigma-clip. This doesn’t assume all values are finite or if they’re positive/negative. All of these arrays will have their non-finite elements removed, and then will be sigma-clipped 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 time-series. 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 sigma-clip will be performed using the number provided as the sigma-multiplier to cut out from the input time-series.

  If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigma-clip. 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 10-sigma dimmings and greater than 3-sigma 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 sigma-clipping will be performed, and the time-series (with non-finite elems removed) will be passed through to the output.

• iterative (bool) – If this is set to True, will perform iterative sigma-clipping. If niterations is not set and this is True, sigma-clipping 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 sigma-clipped and nan-stripped time-series in stimes, smags, serrs and the associated values of the extparams in sextparams.

Return type:

tuple

astrobase.lcmath.phase_magseries(times, mags, period, epoch, wrap=True, sort=True)

Phases a magnitude/flux time-series 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 time-series values to phase using the provided period and epoch. Non-fiinite values will be removed.
• period (float) – The period to use to phase the time-series.
• epoch (float) – The epoch to phase the time-series. This is usually the time-of-minimum or time-of-maximum 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 time-series 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 time-series 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 time-series,
 'epoch': the input `epoch` used to phase the time-series}

Return type:

dict

astrobase.lcmath.phase_magseries_with_errs(times, mags, errs, period, epoch, wrap=True, sort=True)

Phases a magnitude/flux time-series 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 time-series values and associated measurement errors to phase using the provided period and epoch. Non-fiinite values will be removed.
• period (float) – The period to use to phase the time-series.
• epoch (float) – The epoch to phase the time-series. This is usually the time-of-minimum or time-of-maximum 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 time-series 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 time-series 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 time-series,
 'epoch': the input `epoch` used to phase the time-series}

Return type:

dict

astrobase.lcmath.time_bin_magseries(times, mags, binsize=540.0, minbinelems=7)

Bins the given mag/flux time-series in time using the bin size given.

Parameters:

• times,mags (np.array) – The magnitude/flux time-series to bin in time. Non-finite 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 nan-filtered
                  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)

Bins the given mag/flux time-series in time using the bin size given.

Parameters:

• times,mags,errs (np.array) – The magnitude/flux time-series and associated measurement errors to bin in time. Non-finite 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 nan-filtered
                  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)

Bins a phased magnitude/flux time-series using the bin size provided.

Parameters:

• phases,mags (np.array) – The phased magnitude/flux time-series to bin in phase. Non-finite 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
                     nan-filtered 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)

Bins a phased magnitude/flux time-series using the bin size provided.

Parameters:

• phases,mags,errs (np.array) – The phased magnitude/flux time-series and associated errs to bin in phase. Non-finite 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
                     nan-filtered 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)

This fills in gaps in a light curve.

This is mainly intended for use in ACF period-finding, 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 non-linear filter which consists of a median filter followed by a boxcar filter, both with 11-point windows, with iterative 3σ clipping of outliers.”

Parameters:

• times,mags,errs (np.array) – The magnitude/flux time-series and associated measurement errors to operate on. Non-finite 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 sigma-clip will be performed using the number provided as the sigma-multiplier to cut out from the input time-series.

  If a list of two ints/floats is provided, the function will perform an ‘asymmetric’ sigma-clip. 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 10-sigma dimmings and greater than 3-sigma 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 sigma-clipping will be performed, and the time-series (with non-finite 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 time-series points to include in the Savitsky-Golay 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 gap-filling,
 'imags': the interpolated mag/flux values after gap-filling,
 'ierrs': the interpolated mag/flux values after gap-filling,
 'cadence': the cadence of the output mag/flux time-series}

Return type:

dict