Crate light_curve_feature

Expand description

§`light-curve-feature`

light-curve-feature is a part of light-curve family that implements extraction of numerous light curve features used in astrophysics.

If you are looking for Python bindings for this package, please see https://github.com/light-curve/light-curve-python

All features are available in Feature enum, and the recommended way to extract multiple features at once is FeatureExtractor struct built from a Vec<Feature>. Data is represented by TimeSeries struct built from time, magnitude (or flux) and weight arrays, all having the same length. Note that multiple features interpret weight array as inversed squared observation errors.

use light_curve_feature::prelude::*;

// Let's find amplitude and reduced Chi-squared of the light curve
let fe = FeatureExtractor::from_features(vec![
    Amplitude::new().into(),
    ReducedChi2::new().into()
]);
// Define light curve
let time = [0.0, 1.0, 2.0, 3.0, 4.0];
let magn = [-1.0, 2.0, 1.0, 3.0, 4.5];
let weights = [5.0, 10.0, 2.0, 10.0, 5.0]; // inverse squared magnitude errors
let mut ts = TimeSeries::new(&time, &magn, &weights);
// Get results and print
let result = fe.eval(&mut ts)?;
let names = fe.get_names();
println!("{:?}", names.iter().zip(result.iter()).collect::<Vec<_>>());

There are a couple of meta-features, which transform a light curve before feature extraction. For example Bins feature accumulates data inside time-windows and extracts features from this new light curve.

use light_curve_feature::prelude::*;
use ndarray::Array1;

// Define features, "raw" MaximumSlope and binned with zero offset and 1-day window
let max_slope: Feature<_> = MaximumSlope::default().into();
let bins: Feature<_> = {
    let mut bins = Bins::new(1.0, 0.0);
    bins.add_feature(max_slope.clone());
    bins.into()
};
let fe = FeatureExtractor::from_features(vec![max_slope, bins]);
// Define light curve
let time = [0.1, 0.2, 1.1, 2.1, 2.1];
let magn = [10.0, 10.1, 10.5, 11.0, 10.9];
// We don't need weight for MaximumSlope, this would assign unity weight
let mut ts = TimeSeries::new_without_weight(&time, &magn);
// Get results and print
let result = fe.eval(&mut ts)?;
println!("{:?}", result);

§Cargo features

The crate is configured with the following Cargo features:

ceres-system and ceres-source - enable Ceres Solver support for non-linear fitting. The former uses system-wide installation of Ceres, the latter builds Ceres from source and links it statically. The latter overrides the former. See ceres-solver-rs crate for details
fftw-system, fftw-source (enabled by default) and fftw-mkl - enable FFTW support for Fourier transforms needed by Periodogram. The first uses system-wide installation of FFTW, the second builds FFTW from source and links it statically, the last downloads and links statically Intel MKL instead of FFTW.
gsl - enables GNU Scientific Library support for non-linear fitting.
default - enables fftw-source feature only, has no side effects.

§Development

Setting up

Install Rust toolchain, the preferred way is rustup.

Install the required system libraries. For main project you need Ceres Solver, FFTW and GSL, as well as C++ compiler and CMake. The example script plots some stuff so it requires fontconfig.

# On macOS:
brew install ceres-solver cmake fftw gsl fontconfig
# On Debian-like:
apt install build-essential cmake libceres-dev libfftw3-dev libgsl-dev libfontconfig-dev

Clone the repository with submodules and run compiler checks:

git clone --recursive https://github.com/light-curve/light-curve-feature
cd light-curve-feature

Run tests with native libraries. Note that Ceres could require manual CPATH specification on some systems, like CPATH=/opt/homebrew/include on ARM macOS:

cargo test --no-default-features --features ceres-system,fftw-system,gsl

You may also run benchmarks, but be patient

cargo bench --no-default-features --features ceres-system,fftw-system,gsl

See examples, .github/workflows and tests for examples of the code usage.

Formatting and linting

We format and check the code with the standard Rust tools: cargo fmt and cargo clippy. Please use clippy’s #[allow] as precise as possible and leave code comments if it is not obvious why its usage is required.

We use pre-commit for running some linters locally before commiting. Please consider installing it and initializing in the repo with pre-commit init. However pre-commit.ci and GitHub Actions will varify cargo fmt and cargo clippy for PRs.

Generally, we are aimed to test all user-level code, add unit-tests to your non-trivial PRs. Currently we have no unsafe code in this repo and we are aimed to avoid it in the future.

Implementing a new feature evaluator

Your new feature evaluator code should go to at least three files:

New file inside src/features directory
Publically import the new struct inside src/features/mod.rs
Add it as a new variant of Feature enum inside src/feature.rs

§Citation

If you found this project useful for your research please cite Malanchev et al., 2021

@ARTICLE{2021MNRAS.502.5147M,
       author = {{Malanchev}, K.~L. and {Pruzhinskaya}, M.~V. and {Korolev}, V.~S. and {Aleo}, P.~D. and {Kornilov}, M.~V. and {Ishida}, E.~E.~O. and {Krushinsky}, V.~V. and {Mondon}, F. and {Sreejith}, S. and {Volnova}, A.~A. and {Belinski}, A.~A. and {Dodin}, A.~V. and {Tatarnikov}, A.~M. and {Zheltoukhov}, S.~G. and {(The SNAD Team)}},
        title = "{Anomaly detection in the Zwicky Transient Facility DR3}",
      journal = {\mnras},
     keywords = {methods: data analysis, astronomical data bases: miscellaneous, stars: variables: general, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Solar and Stellar Astrophysics},
         year = 2021,
        month = apr,
       volume = {502},
       number = {4},
        pages = {5147-5175},
          doi = {10.1093/mnras/stab316},
archivePrefix = {arXiv},
       eprint = {2012.01419},
 primaryClass = {astro-ph.IM},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2021MNRAS.502.5147M},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

Re-exports§

pub use transformers::Transformer;
pub use transformers::TransformerTrait;
pub use ndarray;
pub use features::*;

Modules§

features: Feature sctructs implements crate::FeatureEvaluator trait
prelude
prior
transformers

Structs§

AverageNyquistFreq: $\Delta t = \mathrm{duration} / (N - 1)$ is the mean time interval between observations
CeresCurveFit: Ceres-Solver non-linear least-squares wrapper
CurveFitResult
DataSample: A TimeSeries component
FeatureExtractor: Bulk feature extractor
FixedNyquistFreq: User-defined Nyquist frequency
LmsderCurveFit: LMSDER GSL non-linear least-squares wrapper
McmcCurveFit: MCMC sampler for non-linear least squares
MedianNyquistFreq: $\Delta t$ is the median time interval between observations
PeriodogramPowerDirect: Direct periodogram executor
PeriodogramPowerFft: “Fast” (FFT-based) periodogram executor
QuantileNyquistFreq: $\Delta t$ is the $q$th quantile of time intervals between subsequent observations
RecurrentSinCos: Iterator over sin(kx), cos(kx) pairs
TimeSeries: Time series object to be put into Feature

Enums§

CurveFitAlgorithm: Optimization algorithm for non-linear least squares
EvaluatorError: Error returned from crate::FeatureEvaluator
Feature: All features are available as variants of this enum
LnPrior: Natural logarithm of prior for non-linear curve-fit problem
LnPrior1D: Natural logarithm of prior for a single parameter of the curve-fit problem
NyquistFreq: Derive Nyquist frequency from time series
PeriodogramPower: Periodogram execution algorithm

Traits§

EvaluatorInfoTrait
FeatureEvaluator: The trait each feature should implement
FeatureNamesDescriptionsTrait
FitFeatureEvaluatorGettersTrait
Float: Floating number trait, it is implemented for f32 and f64 only

Crate light_curve_featureCopy item path

§light-curve-feature