Module `light_curve`

High-performance time-series feature extractor

The module provides a collection of features to be extracted from unevenly separated time-series. This module if based on Rust crates light-curve-feature & light-curve-dmdt.

dm-lg(dt) maps generator is represented by DmDt class, while all other classes are feature extractors

Classes

class Amplitude

Half amplitude of magnitude

$\mathrm{amplitude} \equiv \frac{\left( \max{(m)} - \min{(m)} \right)}{2}$

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

call(t, m, sigma=None, sorted=None, check=True, fill_value=None) Extract features and return them as a numpy array many(lcs, sorted=None, check=True, fill_value=None, n_jobs=-1) Parallel version of call

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class AndersonDarlingNormal

Unbiased Anderson–Darling normality test statistic

$A^2 \equiv \left(1 + \frac4{N} - \frac{25}{N^2}\right) \left(-N - \frac1{N} \sum_{i=0}^{N-1} {(2i + 1)\ln\Phi_i + (2(N - i) - 1)\ln(1 - \Phi_i)}\right),$ where $\Phi_i \equiv \Phi((m_i - \langle m \rangle) / \sigma_m)$ is the standard cumulative distribution, $N$ is the number of observations, $\langle m \rangle$ is the mean magnitude and $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation.

Depends on: magnitude
Minimum number of observations: 4
Number of features: 1

Wikipedia

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class BazinFit (algorithm, mcmc_niter=None, lmsder_niter=None, init=None, bounds=None, ln_prior=None)

Bazin function fit

Five fit parameters and goodness of fit (reduced $\chi^2$) of the Bazin function developed for core-collapsed supernovae:

$f(t) = A \frac{ \mathrm{e}^{ -(t-t_0)/\tau_\mathrm{fall} } }{ 1 + \mathrm{e}^{ -(t - t_0) / \tau_\mathrm{rise} } } + B.$

Note, that the Bazin function is developed to be used with fluxes, not magnitudes. Also note a typo in the Eq. (1) of the original paper, the minus sign is missed in the "rise" exponent.

Depends on: time, magnitude, magnitude error
Minimum number of observations: 6
Number of features: 6

Bazin et al. 2009 DOI:10.1051/0004-6361/200911847

Parameters

algorithm : str

Non-linear least-square algorithm, supported values are: mcmc, lmsder, mcmc-lmsder.

mcmc_niter : int, optional

Number of MCMC iterations, default is 128

lmsder_niter : int, optional

Number of LMSDER iterations, default is 10

init : list or None, optional

Initial conditions, must be None or a list of floats or Nones. The length of the list must be 5, None values will be replaced with some defauls values. It is supported by MCMC only

bounds : list of tuples or None, optional

Boundary conditions, must be None or a list of tuples of floats or Nones. The length of the list must be 5, boundary conditions must include initial conditions, None values will be replaced with some broad defaults. It is supported by MCMC only

ln_prior : list of light_curve.light_curve_ext.ln_prior.LnPrior1D, or str, or None, optional

Prior for MCMC, None means no prior. A list of 5 LnPrior1D specifies logatithms of priors for each fit parameter. Alternatively, a str literal can be used:

"no": no prior

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions
supported_algorithms : list of str: Available argument values for the constructor

Methods

model(t, params) Underlying parametric model function

Examples

>>> import numpy as np
>>> from light_curve import BazinFit
>>>
>>> fit = BazinFit('mcmc')
>>> t = np.linspace(0, 10, 101)
>>> flux = 1 + (t - 3) ** 2
>>> fluxerr = np.sqrt(flux)
>>> result = fit(t, flux, fluxerr, sorted=True, check=False)
>>> # Result is built from a model parameters and reduced chi^2
>>> # So we can use as an input for the model static method
>>> model = BazinFit.model(t, result)

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

Class variables

var supported_algorithms

Static methods

def model(...)

Parametric model function

Parameters

t : np.ndarray of np.float32 or np.float64: Time moments, can be unsorted
params : np.ndarray of np.float32 or np.float64: Parameters of the model, this array can be longer than actual parameter list, the beginning part of the array will be used in this case

Returns

np.ndarray of np.float32 or np.float64: Array of model values corresponded to the given time moments

class BeyondNStd (nstd, /)

Fraction of observations beyond $n\,\sigma_m$ from the mean magnitude $\langle m \rangle$

$\mathrm{beyond}~n\,\sigma\_m \equiv \frac{\sum\_i I\_{|m - \langle m \rangle| > n\,\sigma\_m}(m_i)}{N},$ where $I$ is the indicator function, $N$ is the number of observations, $\langle m \rangle$ is the mean magnitude and $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation.

Depends on: magnitude
Minimum number of observations: 2
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Parameters

nstd : positive float: N

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Bins (features, window, offset)

Sampled time series meta-feature

Binning time series to bins with width $\mathrm{window}$ with respect to some $\mathrm{offset}$. $j-th$ bin interval is $[j \cdot \mathrm{window} + \mathrm{offset}; (j + 1) \cdot \mathrm{window} + \mathrm{offset})$. Binned time series is defined by $t_j^* = (j + \frac12) \cdot \mathrm{window} + \mathrm{offset},$ $m_j^* = \frac{\sum{m_i / \delta_i^2}}{\sum{\delta_i^{-2}}},$ $\delta_j^* = \frac{N_j}{\sum{\delta_i^{-2}}},$ where $N_j$ is a number of sampling observations and all sums are over observations inside considering bin. Bins takes any other feature evaluators to extract features from sample time series

Depends on: time, magnitude, magnitude error
Minimum number of observations: as required by sub-features, but at least 1
Number of features: as provided by sub-features

Parameters

features : iterable: Features to extract from binned time-series
window : positive float: Width of binning interval in units of time
offset : float: Zero time moment

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Cusum

Cusum — a range of cumulative sums

$\mathrm{cusum} \equiv \max(S) - \min(S),$ where $S_j \equiv \frac1{N\sigma_m} \sum_{i=0}^j{\left(m\_i - \langle m \rangle\right)},$ $N$ is the number of observations, $\langle m \rangle$ is the mean magnitude and $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation.

Depends on: magnitude
Minimum number of observations: 2
Number of features: 1

Kim et al. 2014, DOI:10.1051/0004-6361/201323252

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class DmDt (...)

dm-dt map producer

Each pair of observations is mapped to dm-dt plane bringing unity value. dmdt-map is a rectangle on this plane consisted of dt_size x dm_size cells, and limited by [min_dt; max_dt) and [min_dm; max_dm) intervals. .points*() methods assigns unity value of each observation to a single cell, while .gausses*() methods smears this unity value over all cells with given dt value using normal distribution N(m2 - m1, sigma1^2 + sigma2^2), where (t1, m1, sigma1) and (t2, m2, sigma2) are a pair of observations including uncertainties. Optionally, after the map is built, normalisation is performed ("norm" parameter): "dt" means divide each dt = const column by the total number of all observations corresponded to given dt (in this case gausses() output can be interpreted as conditional probability p(dm|dt)); "max" means divide all values by the maximum value; both options can be combined, then "max" is performed after "dt".

Parameters

dt : np.array of float64: Ascending array of dt grid edges
dm : np.array of float64: Ascending array of dm grid edges
dt_type : str, optional: Type of dt grid, one of: - 'auto' (default) means check if grid is linear or logarithmic one, which allows some speed-up - 'linear' says to build a linear grid from the first and last values of dt, using the same number of edges - 'log' is the same as 'linear' but for building logarithmic grid - 'asis' means using the given array as a grid
dm_type : str, optional: Type of dm grid, see dt_type for details
norm : list of str, optional: Types of normalisation, cab be any combination of "dt" and "max", default is an empty list [] which means no normalisation
n_jobs : int, optional: Number of parallel threads to run bulk methods such as points_many() or gausses_batches() default is -1 which means to use as many threads as CPU cores
approx_erf : bool, optional: Use approximation normal CDF in gausses* methods, reduces accuracy, but has better performance, default is False

Attributes

n_jobs : int
shape : (int, int): Shape of a single dmdt map, (dt_size, dm_size)
dt_grid : np.array of float64
min_dt : float
max_dt : float
dm_grid : np.array of float64
min_dm : float
max_dm : float

Methods

from_borders(min_lgdt, max_lgdt, max_abs_dm, lgdt_size, dm_size, **kwargs) Construct DmDt with logarithmic dt grid [10^min_lgdt, 10^max_lgdt) and linear dm grid [-max_abs_dm, max_abs_dm), kwargs are passed to __new__() points(t, m, sorted=None) Produces dmdt-maps from light curve gausses(t, m, sigma, sorted=None) Produces smeared dmdt-map from noisy light curve count_dt(t, sorted=None) Total number of observations per each dt interval points_many(lcs, sorted=None) Produces dmdt-maps from a list of light curves gausses_many(lcs, sorted=None) Produces smeared dmdt-maps from a list of light curves count_dt_many(t_, sorted=None) Number of observations in each dt for a list of arrays points_batches(lcs, sorted=None, batch_size=1, yield_index=False, shuffle=False, drop_nobs=0, random_seed=None) Gives a reusable iterable which yields dmdt-maps gausses_batches(lcs, sorted=None, batch_size=1, yield_index=False, shuffle=False, drop_nobs=0, random_seed=None) Gives a reusable iterable which yields smeared dmdt-maps

Static methods

def from_borders(...)

Instance variables

var dm_grid: Return an attribute of instance, which is of type owner.
var dt_grid: Return an attribute of instance, which is of type owner.
var max_dm: Return an attribute of instance, which is of type owner.
var max_dt: Return an attribute of instance, which is of type owner.
var min_dm: Return an attribute of instance, which is of type owner.
var min_dt: Return an attribute of instance, which is of type owner.
var n_jobs: Return an attribute of instance, which is of type owner.
var shape: Return an attribute of instance, which is of type owner.

Methods

def count_dt(...)

Total number of observations per each dt interval

Output takes into account all observation pairs within [min_dt; max_dt), even if they are not in [min_dm; max_dm)

Parameters

t : 1d-ndarray of float: Time moments, must be sorted
sorted : bool or None, optional: True guarantees that t is sorted
Returns

1d-array of float

def count_dt_many(...)

Total number of observations per each dt interval

Output takes into account all observation pairs within [min_dt; max_dt), even if they are not in [min_dm; max_dm)

Parameters

t_ : list of 1d-ndarray of float: List of arrays, each represents time moments, must be sorted
sorted : bool or None, optional: True guarantees that t is sorted
Returns

1d-array of float

def gausses(...)

Produces smeared dmdt-map from light curve

Parameters

t : 1d-ndarray of float: Time moments, must be sorted
m : 1d-ndarray of float: Magnitudes
sigma : 1d-ndarray of float: Uncertainties
sorted : bool or None, optional: True guarantees that the light curve is sorted

Returns

2d-array of float

def gausses_batches(...)

Reusable iterable yielding dmdt-maps

The dmdt-maps are produced in parallel using n_jobs threads, batches are being generated in background, so the next batch is started to generate just after the previous one is yielded. Note that light curves data are copied, so from the performance point of view it is better to use gausses_many if you don't need observation dropping

Parameters

lcs : list of (ndarray, ndarray, ndarray): List or tuple of tuple pairs (t, m, sigma) represented individual light curves. All arrays must have the same dtype
sorted : bool or None, optional: True guarantees that all light curves is sorted, default is None
batch_size : int, optional: The number of dmdt-maps to yield. The last batch can be smaller. Default is 1
yield_index : bool, optional: Yield a tuple of (indexes, maps) instead of just maps. Could be useful when shuffle is True. Default is False
shuffle : bool, optional: If True, shuffle light curves (not individual observations) on each creating of new iterator. Default is False
drop_nobs : int or float, optional: Drop observations from every light curve. If it is a positive integer, it is a number of observations to drop. If it is a floating point between 0 and 1, it is a part of observation to drop. Default is 0, which means usage of the original data
random_seed : int or None, optional: Random seed for shuffling and dropping. Default is None which means random seed

def gausses_many(...)

Produces smeared dmdt-map from a collection of light curves

The method is performed in parallel using n_jobs threads

Parameters

lcs : list of (ndarray, ndarray, ndarray): List or tuple of tuple pairs (t, m, sigma) represented individual light curves. All arrays must have the same dtype
sorted : bool or None, optional: True guarantees that all light curves are sorted

Returns

3d-ndarray of float

def points(...)

Produces dmdt-map from light curve

Parameters

t : 1d-ndarray of float: Time moments, must be sorted
m : 1d-ndarray of float: Magnitudes
sorted : bool or None, optional: True guarantees that the light curve is sorted

Returns

2d-ndarray of float

def points_batches(...)

Reusable iterable yielding dmdt-maps

The dmdt-maps are produced in parallel using n_jobs threads, batches are being generated in background, so the next batch is started to generate just after the previous one is yielded. Note that light curves data are copied, so from the performance point of view it is better to use points_many if you don't need observation dropping

Parameters

lcs : list of (ndarray, ndarray): List or tuple of tuple pairs (t, m) represented individual light curves. All arrays must have the same dtype
sorted : bool or None, optional: True guarantees that all light curves is sorted, default is None
batch_size : int, optional: The number of dmdt-maps to yield. The last batch can be smaller. Default is 1
yield_index : bool, optional: Yield a tuple of (indexes, maps) instead of just maps. Could be useful when shuffle is True. Default is False
shuffle : bool, optional: If True, shuffle light curves (not individual observations) on each creating of new iterator. Default is False
drop_nobs : int or float, optional: Drop observations from every light curve. If it is a positive integer, it is a number of observations to drop. If it is a floating point between 0 and 1, it is a part of observation to drop. Default is 0, which means usage of the original data
random_seed : int or None, optional: Random seed for shuffling and dropping. Default is None which means random seed

Returns

Iterable of 3d-ndarray or (1d-ndarray, 3d-ndarray)

def points_many(...)

Produces dmdt-map from a collection of light curves

The method is performed in parallel using n_jobs threads

Parameters

lcs : list of (ndarray, ndarray): List or tuple of tuple pairs (t, m) represented individual light curves. All arrays must have the same dtype
sorted : bool or None, optional: True guarantees that all light curves is sorted

Returns

3d-ndarray of float

class Duration

Time-series duration

$t_{N-1} - t_0.$

Note: cadence-dependent feature.

Depends on: time
Minimum number of observations: 1
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Eta

Von Neummann $\eta$

$\eta \equiv \frac1{(N - 1)\\,\sigma_m^2} \sum_{i=0}^{N-2}(m_{i+1} - m_i)^2,$ where $N$ is the number of observations, $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation.

Depends on: magnitude
Minimum number of observations: 2
Number of features: 1

Kim et al. 2014, DOI:10.1051/0004-6361/201323252

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class EtaE

$\eta^e$ — modification of Eta for unevenly time series

$\eta^e \equiv \frac{(t_{N-1} - t_0)^2}{(N - 1)^3} \frac{\sum_{i=0}^{N-2} \left(\frac{m_{i+1} - m_i}{t_{i+1} - t_i}\right)^2}{\sigma_m^2}$ where $N$ is the number of observations, $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation. Note that this definition is a bit different from both Kim et al. 2014 and feets

Note that this feature can have very high values and be highly cadence-dependent in the case of large range of time lags. In this case consider to use this feature with Bins.

Depends on: time, magnitude
Minimum number of observations: 2
Number of features: 1

Kim et al. 2014, DOI:10.1051/0004-6361/201323252

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class ExcessVariance

Measure of the variability amplitude

$\frac{\sigma_m^2 - \langle \delta^2 \rangle}{\langle m \rangle^2},$ where $\langle \delta^2 \rangle$ is the mean of squared error, $\sigma_m$ is the magnitude standard deviation. Note that this definition differs from Sánchez et al. 2017

Depends on: magnitude, error
Minimum number of observations: 2
Number of features: 1

Sánchez et al. 2017 DOI:10.3847/1538-4357/aa9188

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Extractor (*features)

Bulk feature extractor

Depends on: as reuired by feature evaluators
Minimum number of observations: as required by feature evaluators
Number of features: total for all feature evaluators

Parameters

*features : iterable: Feature objects

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class InterPercentileRange (quantile)

Inter-percentile range

$Q(1 - p) - Q(p),$ where $Q(p)$ is the $p$th quantile of the magnitude distribution.

Special cases are the interquartile range which is inter-percentile range for $p = 0.25$ and the interdecile range which is inter-percentile range for $p = 0.1$.

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

Parameters

quantile : positive float: Range is (100% * quantile, 100% * (1 - quantile))

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Kurtosis

Excess kurtosis of magnitude

$G_2 \equiv \frac{N\,(N + 1)}{(N - 1)(N - 2)(N - 3)} \frac{\sum_i(m_i - \langle m \rangle)^4}{\sigma_m^4} \- 3\frac{(N - 1)^2}{(N - 2)(N - 3)},$ where $N$ is the number of observations, $\langle m \rangle$ is the mean magnitude, $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation.

Depends on: magnitude
Minimum number of observations: 4
Number of features: 1

Wikipedia

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class LinearFit

Slope, its error and reduced $\chi^2$ of the light curve in the linear fit

Least squares fit of the linear stochastic model with Gaussian noise described by observation errors ${\delta_i}$: $m_i = c + \mathrm{slope} t_i + \delta_i \varepsilon_i$ where $c$ is a constant, ${\varepsilon_i}$ are standard distributed random variables.

Feature values are $\mathrm{slope}$, $\sigma_\mathrm{slope}$ and $\frac{\sum{((m_i - c - \mathrm{slope} t_i) / \delta_i)^2}}{N - 2}$.

Depends on: time, magnitude, magnitude error
Minimum number of observations: 3
Number of features: 3

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class LinearTrend

The slope, its error and noise level of the light curve in the linear fit

Least squares fit of the linear stochastic model with constant Gaussian noise $\Sigma$ assuming observation errors to be zero: $m_i = c + \mathrm{slope} t_i + \Sigma \varepsilon_i,$ where $c$ is a constant, ${\varepsilon_i}$ are standard distributed random variables. $\mathrm{slope}$, $\sigma_\mathrm{slope}$ and $\Sigma$ are returned.

Depends on: time, magnitude
Minimum number of observations: 3
Number of features: 3

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MagnitudePercentageRatio (quantile_numerator, quantile_denominator)

Magnitude percentage ratio

$\mathrm{magnitude~}q\mathrm{~to~}n\mathrm{~ratio} \equiv \frac{Q(1-n) - Q(n)}{Q(1-d) - Q(d)},$ where $n$ and $d$ denotes user defined percentage, $Q$ is the quantile function of magnitude distribution.

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Parameters

quantile_numerator : positive float: Numerator is inter-percentile range (100% * q, 100% (1 - q))
quantile_denominator : positive float: Denominator is inter-percentile range (100% * q, 100% (1 - q))

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MaximumSlope

Maximum slope between two sub-sequential observations

$\mathrm{maximum~slope} \equiv \max_{i=0..N-2}\left|\frac{m_{i+1} - m_i}{t_{i+1} - t_i}\right|$

Note that this feature can have high values and be cadence-dependent in the case of large range of time lags. In this case consider to use this feature with Bins.

Depends on: time, magnitude
Minimum number of observations: 2
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MaximumTimeInterval

Maximum time interval between consequent observations

$\max{(t_{i+1} - t_i)}$

Note: highly cadence-dependent feature.

Depends on: time
Minimum number of observations: 2
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Mean

Mean magnitude

$\langle m \rangle \equiv \frac1{N} \sum_i m_i.$ This is non-weighted mean, see WeightedMean for weighted mean.

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MeanVariance

Standard deviation to mean ratio

$\frac{\sigma_m}{\langle m \rangle}$

Depends on: magnitude
Minimum number of observations: 2
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Median

Median magnitude

$\mathrm{Median}(m_i)$

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MedianAbsoluteDeviation

Median of the absolute value of the difference between magnitude and its median

$\mathrm{median~absolute~deviation} \equiv \mathrm{Median}\left(|m_i - \mathrm{Median}(m)|\right).$

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MedianBufferRangePercentage (quantile)

Fraction of observations inside $\mathrm{Median}(m) \pm q \times (\max(m) - \min(m)) / 2$ interval

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Parameters

quantile : positive float: Relative range size

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class MinimumTimeInterval

Minimum time interval between consequent observations

$\min{(t_{i+1} - t_i)}$

Note: highly cadence-dependent feature.

Depends on: time
Minimum number of observations: 2
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class ObservationCount

Number of observations

$N$

Note: cadence-dependent feature.

Depends on: nothing
Minimum number of observations: 0
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class PercentAmplitude

Maximum deviation of magnitude from its median

$\mathrm{percent~amplitude} \equiv \max_i\left|m_i - \mathrm{Median}(m)\right| = \max(\max(m) - \mathrm{Median}(m), \mathrm{Median}(m) - \min(m)).$

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class PercentDifferenceMagnitudePercentile (quantile)

Ratio of $p$th inter-percentile range to the median

$p\mathrm{~percent~difference~magnitude~percentile} \equiv \frac{Q(1-p) - Q(p)}{\mathrm{Median}(m)}.$

Depends on: magnitude
Minimum number of observations: 1
Number of features: 1

D’Isanto et al. 2016 DOI:10.1093/mnras/stw157

Parameters

quantile : positive float: Relative range size

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Periodogram (peaks=None, resolution=None, max_freq_factor=None, nyquist=None, fast=None, features=None)

Peaks of Lomb–Scargle periodogram and periodogram as a meta-feature

Periodogram $P(\omega)$ is an estimate of spectral density of unevenly time series. peaks argument corresponds to a number of the most significant spectral density peaks to return. For each peak its period and "signal to noise" ratio is returned:

$\mathrm{signal~to~noise~of~peak} \equiv \frac{P(\omega_\mathrm{peak}) - \langle P(\omega) \rangle}{\sigma\_{P(\omega)}}.$

[Periodogram] can accept other features for feature extraction from periodogram as it was time series without observation errors (unity weights are used if required). You can even pass one [Periodogram] to another one if you are crazy enough

Depends on: time, magnitude
Minimum number of observations: as required by sub-features, but at least two
Number of features: $2 \times \mathrm{peaks}$ plus sub-features

Parameters

peaks : int or None, optional: Number of peaks to find
resolution : float or None, optional: Resolution of frequency grid
max_freq_factor : float or None, optional: Mulitplier for Nyquist frequency
nyquist : str or float or None, optional: Type of Nyquist frequency. Could be one of: - 'average': "Average" Nyquist frequency - 'median': Nyquist frequency is defined by median time interval between observations - float: Nyquist frequency is defined by given quantile of time intervals between observations
fast : bool or None, optional: Use "Fast" (approximate and FFT-based) or direct periodogram algorithm
features : iterable or None, optional: Features to extract from periodogram considering it as a time-series

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions
supported_algorithms : list of str: Available argument values for the constructor

Methods

freq_power(t, m) Get periodogram

Parameters
----------
t : np.ndarray of np.float32 or np.float64
    Time array
m : np.ndarray of np.float32 or np.float64
    Magnitude (flux) array

Returns
-------
freq : np.ndarray of np.float32 or np.float64
    Frequency grid
power : np.ndarray of np.float32 or np.float64
    Periodogram power

Examples

>>> import numpy as np
>>> from light_curve import Periodogram
>>> periodogram = Periodogram(peaks=2, resolution=20.0, max_freq_factor=2.0,
...                           nyquist='average', fast=True)
>>> t = np.linspace(0, 10, 101)
>>> m = np.sin(2*np.pi * t / 0.7) + 0.5 * np.cos(2*np.pi * t / 3.3)
>>> peaks = periodogram(t, m, sorted=True)[::2]
>>> frequency, power = periodogram.freq_power(t, m)

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

Methods

def freq_power(t, m): Angular frequencies and periodogram values

class ReducedChi2

Reduced $\chi^2$ of magnitude measurements

$\mathrm{reduced~}\chi^2 \equiv \frac1{N-1} \sum_i\left(\frac{m_i - \bar{m}}{\delta\_i}\right)^2,$ where $N$ is the number of observations, and $\bar{m}$ is the weighted mean magnitude.

Depends on: magnitude, magnitude error
Minimum number of observations: 2
Number of features: 1

This is a good measure of variability which takes into account observations uncertainties.

Wikipedia

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class Skew

Skewness of magnitude $G_1$

$G_1 \equiv \frac{N}{(N - 1)(N - 2)} \frac{\sum_i(m_i - \langle m \rangle)^3}{\sigma_m^3},$ where $N$ is the number of observations, $\langle m \rangle$ is the mean magnitude, $\sigma_m = \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)}$ is the magnitude standard deviation.

Depends on: magnitude
Minimum number of observations: 3
Number of features: 1

Wikipedia

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class StandardDeviation

Standard deviation of magnitude $\sigma_m$

$\sigma_m \equiv \sqrt{\sum_i (m_i - \langle m \rangle)^2 / (N-1)},$

$N$ is the number of observations and $\langle m \rangle$ is the mean magnitude.

Depends on: magnitude
Minimum number of observations: 2
Number of features: 1

Wikipedia

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class StetsonK

Stetson $K$ coefficient described light curve shape

$\mathrm{Stetson}~K \equiv \frac{\sum_i\left|\frac{m_i - \bar{m}}{\delta_i}\right|}{\sqrt{N\\,\chi^2}},$ where N is the number of observations, $\bar{m}$ is the weighted mean magnitude and $\chi^2 = \sum_i\left(\frac{m_i - \langle m \rangle}{\delta_i}\right)^2$.

Depends on: magnitude, magnitude error
Minimum number of observations: 2
Number of features: 1

P. B. Stetson, 1996. DOI:10.1086/133808

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class TimeMean

Mean time

$\langle t \rangle \equiv \frac1{N} \sum_i {t_i}.$

Note: highly cadence-dependent feature.

Depends on: time
Minimum number of observations: 1
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class TimeStandardDeviation

Standard deviation of time moments

$\sigma_t \equiv \frac{\sum_i {(t_i - \langle t \rangle)^2}}{N - 1}.$

Note: highly cadence-dependent feature.

Depends on: time
Minimum number of observations: 2
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class VillarFit (algorithm, mcmc_niter=None, lmsder_niter=None, init=None, bounds=None, ln_prior=None)

Villar function fit

Seven fit parameters and goodness of fit (reduced $\chi^2$) of the Villar function developed for supernovae classification:

$f(t) = c + \frac{A}{ 1 + \exp{\frac{-(t - t_0)}{\tau_\mathrm{rise}}}} \left\{ \begin{array}{ll} 1 - \frac{\nu (t - t_0)}{\gamma}, &t < t_0 + \gamma \\ (1 - \nu) \exp{\frac{-(t-t_0-\gamma)}{\tau_\mathrm{fall}}}, &t \geq t_0 + \gamma \end{array} \right.$ where $A, \gamma, \tau_\mathrm{rise}, \tau_\mathrm{fall} > 0$, $\nu \in [0; 1)$.

Here we introduce a new dimensionless parameter $\nu$ instead of the plateau slope $\beta$ from the orioginal paper: $\nu \equiv -\beta \gamma / A$.

Note, that the Villar function is developed to be used with fluxes, not magnitudes.

Depends on: time, magnitude, magnitude error
Minimum number of observations: 8
Number of features: 8

Villar et al. 2019 DOI:10.3847/1538-4357/ab418c

Parameters

algorithm : str

Non-linear least-square algorithm, supported values are: mcmc, lmsder, mcmc-lmsder.

mcmc_niter : int, optional

Number of MCMC iterations, default is 128

lmsder_niter : int, optional

Number of LMSDER iterations, default is 10

init : list or None, optional

Initial conditions, must be None or a list of floats or Nones. The length of the list must be 7, None values will be replaced with some defauls values. It is supported by MCMC only

bounds : list of tuples or None, optional

Boundary conditions, must be None or a list of tuples of floats or Nones. The length of the list must be 7, boundary conditions must include initial conditions, None values will be replaced with some broad defaults. It is supported by MCMC only

ln_prior : list of light_curve.light_curve_ext.ln_prior.LnPrior1D, or str, or None, optional

Prior for MCMC, None means no prior. A list of 7 LnPrior1D specifies logatithms of priors for each fit parameter. Alternatively, a str literal can be used:

"no": no prior,
"hosseinzadeh2020": prior addopted from Hosseinzadeh et al. 2020, it assumes that t is in days

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions
supported_algorithms : list of str: Available argument values for the constructor

Methods

model(t, params) Underlying parametric model function

Examples

>>> import numpy as np
>>> from light_curve import VillarFit
>>>
>>> fit = VillarFit('mcmc')
>>> t = np.linspace(0, 10, 101)
>>> flux = 1 + (t - 3) ** 2
>>> fluxerr = np.sqrt(flux)
>>> result = fit(t, flux, fluxerr, sorted=True, check=False)
>>> # Result is built from a model parameters and reduced chi^2
>>> # So we can use as an input for the model static method
>>> model = VillarFit.model(t, result)

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

Class variables

var supported_algorithms

Static methods

def model(...)

Parametric model function

Parameters

t : np.ndarray of np.float32 or np.float64: Time moments, can be unsorted
params : np.ndarray of np.float32 or np.float64: Parameters of the model, this array can be longer than actual parameter list, the beginning part of the array will be used in this case

Returns

np.ndarray of np.float32 or np.float64: Array of model values corresponded to the given time moments

class WeightedMean

Weighted mean magnitude

$\bar{m} \equiv \frac{\sum_i m_i / \delta_i^2}{\sum_i 1 / \delta_i^2}.$ See Mean for non-weighted mean.

Depends on: magnitude, magnitude error
Minimum number of observations: 1
Number of features: 1

Attributes

names : list of str: Feature names
descriptions : list of str: Feature descriptions

Methods

Ancestors

light_curve.light_curve_ext._FeatureEvaluator

class _FeatureEvaluator (...)

Base class for all feature evaluators having low-level Rust implementation

Follow child classes for constructor and specific methods documentation.

Here we present __call__ method description which is implemented in this base class and common for all children:

Parameters

t : numpy.ndarray of np.float32 or np.float64 dtype: Time moments
m : numpy.ndarray of the same dtype as t: Signal in magnitude or fluxes. Refer to the feature description to decide which would work better in your case
sigma : numpy.ndarray of the same dtype as t, optional: Observation error, if None it is assumed to be unity
sorted : bool or None, optional: Specifies if input array are sorted by time moments. True is for certainly sorted, False is for unsorted. If None is specified than sorting is checked and an exception is raised for unsorted t
check : bool, optional: Check all input arrays for NaNs, t and m for infinite values
fill_value : float or None, optional: Value to fill invalid feature values, for example if count of observations is not enough to find a proper value. None causes exception for invalid features

Returns

ndarray of np.float32 or np.float64: Extracted feature array

Notes

This class couldn't be used to create new user-defined features, because it doesn't have a constructor. Consider to use BaseFeature class from high-level Python implementation instead.

Subclasses

light_curve.light_curve_ext.Amplitude
light_curve.light_curve_ext.AndersonDarlingNormal
light_curve.light_curve_ext.BazinFit
light_curve.light_curve_ext.BeyondNStd
light_curve.light_curve_ext.Bins
light_curve.light_curve_ext.Cusum
light_curve.light_curve_ext.Duration
light_curve.light_curve_ext.Eta
light_curve.light_curve_ext.EtaE
light_curve.light_curve_ext.ExcessVariance
light_curve.light_curve_ext.Extractor
light_curve.light_curve_ext.InterPercentileRange
light_curve.light_curve_ext.Kurtosis
light_curve.light_curve_ext.LinearFit
light_curve.light_curve_ext.LinearTrend
light_curve.light_curve_ext.MagnitudePercentageRatio
light_curve.light_curve_ext.MaximumSlope
light_curve.light_curve_ext.MaximumTimeInterval
light_curve.light_curve_ext.Mean
light_curve.light_curve_ext.MeanVariance
light_curve.light_curve_ext.Median
light_curve.light_curve_ext.MedianAbsoluteDeviation
light_curve.light_curve_ext.MedianBufferRangePercentage
light_curve.light_curve_ext.MinimumTimeInterval
light_curve.light_curve_ext.ObservationCount
light_curve.light_curve_ext.PercentAmplitude
light_curve.light_curve_ext.PercentDifferenceMagnitudePercentile
light_curve.light_curve_ext.Periodogram
light_curve.light_curve_ext.ReducedChi2
light_curve.light_curve_ext.Skew
light_curve.light_curve_ext.StandardDeviation
light_curve.light_curve_ext.StetsonK
light_curve.light_curve_ext.TimeMean
light_curve.light_curve_ext.TimeStandardDeviation
light_curve.light_curve_ext.VillarFit
light_curve.light_curve_ext.WeightedMean

Instance variables

var descriptions: Feature descriptions
var names: Feature names

Methods

def many(...)

Extract features from many light curves in parallel

It is an optimized and parallel executed analogue of

>>> def many(self, lcs, sorted=None, fill_value=None):
...     return np.stack([self(*lc, sorted=sorted, fill_value=fill_value)
...                      for lc in lcs])

Parameters

lcs : list ot (t, m, sigma): A collection of light curves packed into three-tuples, all light curves must be represented by numpy.ndarray of the same dtype. See class-level documentation for more details
sorted : bool or None, optional: Specifies if input array are sorted by time moments, see class-level documentation for more details
check : bool, optional: Check all input arrays for NaNs, t and m for infinite values
fill_value : float or None, optional: Fill invalid values by this or raise an exception if None
n_jobs : int: Number of tasks to run in paralell. Default is -1 which means run as many jobs as CPU count. See rayon rust crate documentation for details

Returns

features : np.ndarray: Output feature array, shape is (len(lcs), n_features)