allan-tools

Allantools (python lib) portage to Rust

This library allows easy computations of Allan deviation & similar statistics.
These statistical methods are mostly used in system stability studies.

Variances / Deviations

Compute Allan Deviation over raw data:

  use allantools::*;
  let taus = tau::generator(tau::TauAxis::Octave, 128);
  let (dev, errs) = deviation(&data, taus, Deviation::Allan, false, false).unwrap();

Improve statiscal confidence by using overlapped formulas

  let taus = tau::generator(tau::TauAxis::Octave, 128);
  let (dev, errs) = deviation(&data, taus, Deviation::Allan, false, true).unwrap();

Compute Allan Deviation over a serie of fractionnal error

  let taus = tau::generator(tau::TauAxis::Octave, 10000);
  let ( adev, errs) = deviation(&data, taus, Deviation::Allan, true, false).unwrap();
  let (oadev, errs) = deviation(&data, taus, Deviation::Allan, true, true).unwrap();

Tau offset and errors management

This library computes the requested deviation for all requested τ values, as long as it's feasible.
If τ(n) is not feasible (would require more input data), computations stops and the previous valid deviations are returned (previous offsets).

If not a single τ value is feasible, the lib returns Error::NotEnoughSamplesError

   let data = [0,1,2];
   assert_eq!(deviation(&data, taus, Deviation::Allan, true, false).is_err(), true);

If the user is passing a non valid τ axis, the lib returns an error raised by basic sanity checks

   let my_x = [-1,1,2];
   assert_eq!(deviation(&data, my_x, Deviation::Allan, true, false).is_err(), true);

τ < 0 does not make sense

   let my_x = [0,1,2];
   assert_eq!(deviation(&data, my_x, Deviation::Allan, true, false).is_err(), true);

neither does τ = 0

  let my_x = [0,1,1,2];
  assert_eq!(deviation(&data, my_x, Deviation::Allan, true, false).is_err(), true);

the lib does not check for repeated τ offsets at the moment

Tau axis generation

A Tau axis generator is embedded, for ease of use. Several axis are built in:

TauAxis::Octave is the most efficient
TauAxis::Decade is the standard and is efficient
TauAxis::All requires more computation but is accurate

  let taus = tau::generator(tau::TauAxis::Decade, 10000); //log10

use TauAxis::All to compute the deviation for every single tau value.

  let taus = tau::generator(tau::TauAxis::All, 10000);

Data & Noise generators

Some data generators were integrated or develpped for testing purposes:

White noise generator produces scaled normal distribution

  let psd = -140; // [dBcHz]
  let fs = 10.0E6; // [Hz]
  let x = allantools::noise::white_noise(psd, fs, 10000); // 10k samples

Pink noise generator produces a -10dB/dec shape when raw data is considered, or a -5dB/dec shape if we're considering fractionnal data

  let psd = -140; // [dBcHz]
  let fs = 10.0E6; // [Hz]
  let a0_1hz = -10; // [dB] = level @ 1Hz
  let x = allantools::noise::pink_noise(a0_1hz, psd, fs, 1024); // 1k samples

Tools & utilities

NIST Power Law identification method[[46]]

This is a useful macro to identify noise processes contained in a data serie.
In other words, this tells you how the data serie behaves.

  let x = produce_some_data();
  let exponents = allantools::nist_power_law_identifier(&x, None);

One can use the optionnal "min_dist" attribute to customize the study

  let x = produce_some_data(); // 1k symbols
  // default min_dist=10 -> 1k/10 exponents to be identified
  let exponents = allantools::nist_power_law_identifier(&x, None);
    // 1k/100 exponents to be identified
  let exponents = allantools::nist_power_law_identifier(&x, Some(100));

Cummulative sum (python::numpy like)

   let data: Vec<f64> = some_data();
   allantools::utilities::cumsum(data, None);
   allantools::utilities::cumsum(data, Some(10E6_f64)); // opt. normalization

Derivative (python::numpy like)

   let data: Vec<f64> = some_data();
   allantools::utilities::diff(data, None);
   allantools::utilities::diff(data, Some(10E6_f64)); // opt. normalization

Random generator: generates a pseudo random sequence 0 < x <= 1.0

   let data = allantools::utilities::random(1024); // 1k symbols 
   println!("{:#?}", data);

normalize : normalizes a sequence to 1/norm :

   let data: Vec<f64> = somedata(); 
   let normalized = allantools::utilities::normalize(
       data, 
       2.0_f64 * std::f64::consts::PI); // 1/(2pi)

to_fractionnal_frequency : tool to convert a data serie to a serie of fractionnal data.
Typical use is converting raw frequency measurements (Hz) into fractionnal frequency (n.a):

   let data: Vec<f64> = somedata(); // sampled @ 10kHz
   let fract = allantools::utilities::to_fractionnal_frequency(data, 10E3); // :)

fractionnal_integral : tool to integrate a serie of fractionnal data.
Typical use is converting fractionnal frequency measurements (n.a), to phase time (s).

   let data: Vec<f64> = somedata(); // (n.a) 
   let fract = allantools::utilities::fractionnal_integral(data, 1.0); // sampled @ 1Hz :)

fractional_freq_to_phase_time : macro wrapper of previous function

phase_to_radians : macro to convert phase time (s) to phase radians (rad)