API

Query Gaia catalog

seismolab.gaia.query_gaia(targets, gaiaDR=3, use_photodist=False, dustmodel='Combined19', plx_offset=None)

query_gaia performs Gaia database query and calculates distance, reddening corrected apparent and absolute magnitudes

Parameters:

targetsint, list, Table, DataFrame

Input Gaia IDs in the given catalog which is currently being used.

gaiaDRint, default: 3

Gaia DataRelease number (2 or 3).

use_photodistbool, default: False

If True photogeometric distances are used. Otherwise geometric distances are used.

dustmodelstr, default: ‘Combined19’

The mwdust model to be used for redding correction. See mwdust documentation for available maps: https://github.com/jobovy/mwdust

plx_offsetstr or float, default: 0.0

If float, the parallax offset (in mas) to be added to the parallaxes. It also can can be one of following names:

“Stassun”, which is +0.08 mas (Stassun et al. 2018) “Riess”, which is +0.046 mas (Riess et al. 2018) “BJ”, which is +0.029 mas (Bailer-Jones et al. 2018) “Zinn”, which is +0.0528 mas (Zinn et al 2019)

Returns:

timeAstropy Table

Calculated distance, brightness and absorption values.

Fourier

Fourier spectrum

class seismolab.fourier.Fourier(t, y, error=None)

Attributes:

tarray-like

Time values of the light curve.

yarray-like

Flux/mag values of the light curve.

errorarray-like, optional

Flux/mag errors values of the light curve. If not given, Fourier parameter errors will be less reliable. In this case use error_estimation.

Methods

spectral_window([minimum_frequency, ...])	Calculates the spectral window.
spectrum([minimum_frequency, ...])	Calculates the classic Fourier spectrum.

spectral_window(minimum_frequency=None, maximum_frequency=None, nyquist_factor=1, samples_per_peak=10, plotting=False)

Calculates the spectral window.

Parameters:

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 10

The approximate number of desired samples across the typical frequency peak.

plotting: bool, default: False

If True, spectral window will be displayed.

Returns:

freqarray-like

Frequency grid.

swarray-like

Spectral window at given frequencies.

spectrum(minimum_frequency=None, maximum_frequency=None, nyquist_factor=1, samples_per_peak=10, plotting=False)

Calculates the classic Fourier spectrum.

Parameters:

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 10

The approximate number of desired samples across the typical frequency peak.

plotting: bool, default: False

If True, spectrum will be displayed.

Returns:

freqarray-like

Frequency grid.

specarray-like

The Fourier spectrum at given frequencies.

Main frequency and its harmonics

class seismolab.fourier.MultiHarmonicFitter(t, y, error=None)

Attributes:

tarray-like

Time values of the light curve.

yarray-like

Flux/mag values of the light curve.

errorarray-like, optional

Flux/mag errors values of the light curve. If not given, Fourier parameter errors will be less reliable. In this case use error_estimation.

Methods

fit_harmonics([maxharmonics, sigma, ...])	fit_harmonics performs Fourier pre-whitening with harmonic fitting.
get_analytic_uncertainties()	Calculates analytically derived uncertainties for multi-harmonic fit.
get_fourier_parameters()	Calculates Fourier parameters from given amplitudes and phases.
get_residual()	Calculates the residual light curve after multi-harmonic Fourier fitting.
lc_model(*arg)	Get model light curve with all harmonic components at the same time.

fit_harmonics(maxharmonics=3, sigma=4, absolute_sigma=True, plotting=False, scale='flux', minimum_frequency=None, maximum_frequency=None, nyquist_factor=1, samples_per_peak=100, kind='sin', error_estimation='analytic', ntry=1000, sample_size=0.7, parallel=True, ncores=-1, refit=False, best_freq=None)

fit_harmonics performs Fourier pre-whitening with harmonic fitting.

Parameters:

maxharmonicsint, default: 3

The maximum number of harmonics to be fitted. Pass a very large number to fit all harmonics, limited by the signal-to-noise ratio.

sigmafloat, default: 4

Signal-to-noise ratio above which a frequency is considered significant and kept.

absolute_sigmabool, default: True

If True, error is used in an absolute sense and the estimated parameter covariance reflects these absolute values.

plotting: bool, default: False

If True, fitting steps will be displayed.

scale: ‘mag’ or ‘flux’, default: ‘flux’

Lightcurve plot scale.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 100

The approximate number of desired samples across the typical frequency peak.

kind: str, ‘sin’ or ‘cos’

Harmonic _function to be fitted.

error_estimation: `analytic`, `bootstrap` or `montecarlo`, default: `analytic`

If bootstrap or montecarlo is choosen, boostrap or monte carlo method will be used to estimate parameter uncertainties. Otherwise given uncertainties are calculated analytically.

ntry: int, default: 1000

Number of resamplings for error estimation.

sample_size: float, default: 0.7

The ratio of data points to be used for bootstrap error estimation in each step. Applies only if error_estimation is set to bootstrap.

parallel: bool, defaultTrue

If True, sampling for error estimation is performed parallel to speed up the process.

ncores: int, default: -1

Number of CPU cores to be used for parallel error estimation. If -1, then all available cores will be used.

best_freqfloat, default: None

If given, then this frequency will be used as the basis of the harmonics, instead of calculating a Lomb-Scargle spectrum to get a frequency.

Returns:

pfitarray-like

Array of fitted parameters. The main frequency, amplitudes and phases of the harmonics, and the zero point.

perrarray-like

Estimated error of the parameters.

get_analytic_uncertainties()

Calculates analytically derived uncertainties for multi-harmonic fit. Method is based on Breger et al. 1999.

Returns:

perrarray-like

Estimated error of the frequency and amplitudes, phases.

get_fourier_parameters()

Calculates Fourier parameters from given amplitudes and phases.

Returns:

freqnumber with uncertainty

Main frequency and its estimated error.

periodnumber with uncertainty

Main period and its estimated error.

Rn1number with uncertainty

Rn1 value(s) and its estimated error(s), where n is the harmonics order.

Pn1number with uncertainty

Phin1 value(s) and its estimated error(s), where n is the harmonics order.

get_residual()

Calculates the residual light curve after multi-harmonic Fourier fitting.

Returns:

tarray

Time stamps.

yarray

Residual flux/amp.

yerrarray, optional

If input errors were given, then error of residual flux/amp.

lc_model(*arg)

Get model light curve with all harmonic components at the same time.

Parameters:

timearray

Desired time points where multi-harmonic component fit is desired.

argarguments

List of arguments containing the frequency, amplitudes, phases, zero point.

Returns:

yarray

Multi-harmonic model light curve.

All frequencies

class seismolab.fourier.MultiFrequencyFitter(t, y, error=None)

Methods

fit_freqs([maxfreqs, sigma, boxwidth, ...])	fit_freqs performs consecutive Fourier pre-whitening with given number of frequencies.
get_analytic_uncertainties()	Calculates analytically derived uncertainties for multi-frequency fit.
get_residual()	Calculates the residual light curve after multi-frequency fitting.
lc_model(*arg)	Get model light curve with all frequency components at the same time.

fit_freqs(maxfreqs=3, sigma=4, boxwidth=1, absolute_sigma=True, plotting=False, scale='flux', minimum_frequency=None, maximum_frequency=None, nyquist_factor=1, samples_per_peak=100, kind='sin', error_estimation='analytic', ntry=1000, sample_size=0.7, parallel=True, ncores=-1, refit=False)

fit_freqs performs consecutive Fourier pre-whitening with given number of frequencies.

Parameters:

maxfreqsint, default: 3

The number of frequencies to be fitted. Pass a very large number to fit all frequencies, limited by the signal-to-noise ratio (sigma).

sigmafloat, default: 4

Signal-to-noise ratio above which a frequency is considered significant and kept.

boxwidthfloat, default: 1

The frequency range to be used to calculate noise in the residual spectrum.

absolute_sigmabool, default: True

If True, error is used in an absolute sense and the estimated parameter covariance reflects these absolute values.

plotting: bool, default: False

If True, fitting steps will be displayed.

scale: ‘mag’ or ‘flux’, default: ‘flux’

Lightcurve plot scale.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 100

The approximate number of desired samples across the typical frequency peak.

kind: str, ‘sin’ or ‘cos’

Harmonic _function to be fitted.

error_estimation: `analytic`, `bootstrap` or `montecarlo`, default: `analytic`

If bootstrap or montecarlo is choosen, boostrap or monte carlo method will be used to estimate parameter uncertainties. Otherwise given uncertainties are calculated analytically.

ntry: int, default: 1000

Number of resamplings for error estimation.

sample_size: float, default: 0.7

The ratio of data points to be used for bootstrap error estimation in each step. Applies only if error_estimation is set to bootstrap.

parallel: bool, defaultTrue

If True, sampling for error estimation is performed parallel to speed up the process.

ncores: int, default: -1

Number of CPU cores to be used for parallel error estimation. If -1, then all available cores will be used.

Returns:

pfitarray-like

Array of fitted parameters. The frequencies, amplitudes and phases, and the zero point.

perrarray-like

Estimated error of the parameters.

get_analytic_uncertainties()

Calculates analytically derived uncertainties for multi-frequency fit. Method is based on Breger et al. 1999.

Returns:

perrarray-like

Estimated error of the frequencies, amplitudes, phases.

get_residual()

Calculates the residual light curve after multi-frequency fitting.

Returns:

tarray

Time stamps.

yarray

Residual flux/amp.

yerrarray, optional

If input errors were given, then error of residual flux/amp.

lc_model(*arg)

Get model light curve with all frequency components at the same time.

Parameters:

timearray

Desired time points where multi-frequency fit is desired.

argarguments

List of arguments containing the frequencies, amplitudes, phases of each periodic component and the zero point.

Returns:

yarray

Multi-frequency model light curve.

Template fitting

class seismolab.template.TemplateFitter(time, flux, fluxerror=None)

Methods

fit([span, step, error_estimation, ...])	Compute amplitude/phase/zero point variation based on template fitting.
get_lc_model([time, amp, phase, zp])	Get modulated model light curve.
get_lc_model_interp([kind])	Get modulated model light curve interpolated at the original time points.

fit(span=3, step=1, error_estimation='analytic', maxharmonics=10, minimum_frequency=None, maximum_frequency=None, nyquist_factor=1, samples_per_peak=100, kind='sin', plotting=False, scale='flux', saveplot=False, saveresult=False, filename='result', showerrorbar=True, smoothness_factor=0.5, duty_cycle=0.6, debug=False, best_freq=None)

Compute amplitude/phase/zero point variation based on template fitting.

Parameters:

spanfloat, default: 5

Number of puls cycles to be fitted.

stepfloat, default: 3

Steps in number of puls cycle.

error_estimation‘analytic’ or ‘montecarlo’, default ‘analytic’

Type of error estimation for results.

maxharmonicsint, default: 5

Max number of harmonics to be used in template.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, optional, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peakfloat, optional, default: 100

The approximate number of desired samples across the typical peak.

kind‘sin’ or ‘cos’, default: ‘sin’

Function type to construct template.

plottingbool, deaful: False

Show result.

scale: ‘mag’ or ‘flux’, default: ‘flux’

Lightcurve plot scale.

saveplotbool, default: False

Save result as txt file.

saveresultbool, default: False

Save results as txt

filenamestr, default: ‘result’

Beginning of txt filename.

showerrorbarbool, default: True

Plot errorbars as well.

smoothness_factorfloat, optional, default: 0.5

Level of Gaussian smoothing of amp/phase/zp values. 0: no smoothing, 0.5-1: slight smoothing, >=1: significant smoothing

duty_cyclefloat, optional, default: 0.6

Minimum duty cycle that is needed in case of each light curve chunk. Should be between 0-1.

best_freqfloat, default: None

If given, then this frequency will be used as the basis of the harmonics, instead of calculating a Lomb-Scargle spectrum to get a frequency.

debugbool, default False

Verbose output.

Returns:

——-

timesarray

Time points.

amparray

Amplitude variation.

amperrarray

Amplitude variation error.

phasearray

Phase variation.

phaseerrarray

Phase variation error.

zparray

Zero point variation.

zperrarray

Zero point variation error.

get_lc_model(time=None, amp=None, phase=None, zp=None)

Get modulated model light curve.

Parameters:

timearray

Time points where modulated model light curve is desired.

amparray

Amplitude variation by time.

phasearray

Phase variation by time.

zparray

Zero point variation by time.

Returns:

——-

ymodelarray

Modulated model light curve.

get_lc_model_interp(kind='slinear')

Get modulated model light curve interpolated at the original time points.

Parameters:

kindstr or int, optional

Specifies the kind of interpolation. Default is ‘slinear’. See scipy.interpolate.interp1d for the kinds.

Returns:

——-

ymodelarray

Modulated model light curve interpolated at the original time points.

Light curve minima fitting

class seismolab.OC.OCFitter(time, flux, fluxerror, period)

Methods

calculate_OC([min_times, period, epoch, ...])	Calculate O-C curve from given period and minimum times.
fit_minima([fittype, phase_interval, order, ...])	Fit all minima(!) one by one.

get_model

calculate_OC(min_times=None, period=None, epoch=None, min_times_err=None, showplot=False, saveplot=False, saveOC=False, filename='')

Calculate O-C curve from given period and minimum times.

Parameters:

min_timesarray, optional

Observed (O) times of minima.

periodfloat, optional

Period to be used to construct calculated (C) values.

epochfloat, default: first min_times value, optional

Epoch to be used to construct calculated (C) values. If note given, then the first minimum time is used as epoch.

min_times_errarray, optional

Error of observed (O) times of minima.

showplotbool, default: False

Show results.

saveplotbool, deaful: False

Save results.

saveOCbool, default: True

Save constructed OC as txt file.

filenamestr, default: ‘’

Beginning of txt filename.

Returns:

——-

mid_timesarray

The given minimum times.

OCarray

The calculated O-C values.

OCerrarray

If min_times_err was given, the error of the O-C values.

fit_minima(fittype='model', phase_interval=0.1, order=3, smoothness=1, epoch='auto', npools=-1, samplings=100, showplot=False, saveplot=False, showfirst=False, filename='', debug=False)

Fit all minima(!) one by one.

Parameters:

fittype‘poly’, ‘nonparametric’ or ‘model’.

The type of the fitted function. - poly fits given order polynomial to each minimum individually.

Requires the order to be set.

• nonparametric fits a smooth function to each minimum individually. Very sensitive to outliers! Requires smoothness to be set.

• model fits a smooth function to the median of phase folded light curve. The resulted function is shifted to each minimum. Error estimation is very slow, set samplings to ~100.

phase_intervalfloat

The phase interval around an expected minimum, which is used to fit the selected function.

orderint

Order of the polynomial to be fitted to each minimum. Applies only if fittype is poly.

smoothnessfloat

The smoothness of fitted nonparametric function. Use ~1, to follow small scale (noise-like) variations. Use >1 to fit a really smooth function. Applies only if fittype is nonparametric or model.

epochfloat or ‘auto’

The time stamp of the first minimium. If auto, then it is inferred automatically by fitting a model.

npoolsint, default: -1

Number of cores during error estimation. If -1, then all cores are used.

samplingsint, default: 100000

Number of resamplings for error estimation.

showplotbool, default: False

Show each fitted minima and other useful plots.

saveplotbool, default: True

Save all plots.

filenamestr, default: ‘’

Filename to be used to save plots.

showfirstbool, default: True

Show epoch estimation and first cycle fit to check parameters of the fitted function.

Returns:

——-

times_of_minimumarray

The calculated minimum times.

error_of_minimumarray

The error of the minimum times.

Inpainting

K-inpainting

seismolab.inpainting.kinpainting(time, brightness, max_sz_gap=None, dt=None, niters=100, verbose=False)

Inpainting method to fill gaps in time series data. Mathematical details are in Pires+, 2009, MNRAS, 395, 1265 and Pires+, 2015, A&A, 574, 18.

Parameters:

timearray-like

Time values of the light curve.

brightnessarray-like

Brightness values of the light curve.

max_sz_gapfloat, default: None

Maximal size of gaps to be filled.

dtfloat, default: None

Regular timing used to create a uniform time grid. By default, it is the median sampling time.

nitersint, default: 100

Number of iterations.

verboseboolean, default: False

Verbose output.

Returns:

inpainted2D array

The filled light curve sampled in a regular grid.

inpainted_irreg2D array

The filled light curve sampled in an irregular grid. The sampling is similar to the input times series’.

Gap insertion

seismolab.inpainting.insert_gaps(timeorig, time, brightness, max_gap_size=0.1)

Insert gaps into a time series by getting gaps from another time series.

Parameters:

timeorigarray-like

Time values of the original light curve.

timearray-like

Time values of the continuous light curve.

brightnessarray-like

Brightness values of the continuous light curve.

max_sz_gapfloat, default: None

Maximal size of gaps to be filled into the continuous light curve.

Returns:

time_gappedarray-like

Time values of the gap inserted light curve.

brightness_gappedarray-like

Brightness values of the gap inserted light curve.

Time-frequency analysis

Windowed Lomb-Scargle transform

seismolab.tfa.windowed_lomb_scargle(time, brightness, minimum_frequency=None, maximum_frequency=None, nyquist_factor=1, samples_per_peak=10, Ntimes=100, sigma=0.5)

Calculates the windowed (short-term) Lomb-Scargle transform.

Parameters:

timearray-like

Time values of the light curve.

brightnessarray-like

Brightness values of the light curve.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 10

The approximate number of desired samples across the typical frequency peak.

Ntimes: int, default: 100

The number of times points to generate a uniformly sampled time grid.

sigma: float, default: 0.5

The width of the Gaussian analyzing window.

Returns:

t_gridarray-like

Time grid.

nu_gridarray-like

Frequency grid.

powersarray-like

Windowed Lomb-Scargle transform at the time-frequency grid points.

Gábor transform

seismolab.tfa.gabor(time, brightness, minimum_frequency=None, maximum_frequency=None, nyquist_factor=1.0, samples_per_peak=10, Ntimes=100, sigma=0.5, ncores=-1)

Calculates the Gabor transform.

Parameters:

timearray-like

Time values of the light curve.

brightnessarray-like

Brightness values of the light curve.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 10

The approximate number of desired samples across the typical frequency peak.

Ntimes: int, default: 100

The number of times points to generate a uniformly sampled time grid.

sigma: float, default: 0.5

The width of the Gaussian analyzing window.

ncores: int, default: -1

Number of CPU cores to be used for parallel error estimation. If -1, then all available cores will be used.

Returns:

t_gridarray-like

Time grid.

nu_gridarray-like

Frequency grid.

stFTarray-like

Gabor transform at the time-frequency grid points.

Morlet Wavelet transform

seismolab.tfa.wavelet(time, brightness, minimum_frequency=None, maximum_frequency=None, nyquist_factor=1.0, samples_per_peak=10, Ntimes=100, c=6.283185307179586, ncores=-1)

Calculates the wavelet transform wit Morlet kernel.

Parameters:

timearray-like

Time values of the light curve.

brightnessarray-like

Brightness values of the light curve.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 10

The approximate number of desired samples across the typical frequency peak.

Ntimes: int, default: 100

The number of times points to generate a uniformly sampled time grid.

c: float, default: 2*pi

The scale parameter. The ratio of the time and frequency resolution.

ncores: int, default: -1

Number of CPU cores to be used for parallel error estimation. If -1, then all available cores will be used.

Returns:

t_gridarray-like

Time grid.

nu_gridarray-like

Frequency grid.

morletarray-like

Morlet wavelet transform at the time-frequency grid points.

Choi and Williams transform

seismolab.tfa.choi_williams(time, brightness, minimum_frequency=None, maximum_frequency=None, nyquist_factor=1.0, samples_per_peak=1, Ntimes=100, sigma=1.0, M=128, max_gap_size=0.5, ncores=-1)

Calculates the Choi-Williams transform.

Parameters:

timearray-like

Time values of the light curve.

brightnessarray-like

Brightness values of the light curve.

minimum_frequencyfloat, optional

If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.

maximum_frequencyfloat, optional

If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.

nyquist_factorfloat, default: 1

The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.

samples_per_peak: float, default: 10

The approximate number of desired samples across the typical frequency peak.

Ntimes: int, default: 100

The number of times points to generate a uniformly sampled time grid.

sigma: float, default: 0.5

The width of the kernel of the analyzing window. More or less this controls the resolution in time.

M: int, default: 128

This controls the length of the temporal window, which is given by M times the sampling time. More or less this controls the resolution in frequency.

max_gap_sizefloat, default: 0.5

Maximal size of gaps which is used to split the time series into chunks.

ncores: int, default: -1

Number of CPU cores to be used for parallel error estimation. If -1, then all available cores will be used.

Returns:

t_gridarray-like

Time grid.

nu_gridarray-like

Frequency grid.

Ctnuarray-like

Choi-Williams transform at the time-frequency grid points.