AllanTools

A python library for calculating Allan deviation and related time & frequency statistics. GPL v3+ license.

Developed at https://github.com/aewallin/allantools and also available on PyPi at https://pypi.python.org/pypi/AllanTools

Input data should be evenly spaced observations of either fractional frequency, or phase in seconds. Deviations are calculated for given tau values in seconds.

These statistics are currently included:

  • adev() Allan deviation
  • oadev() overlapping Allan deviation,
  • mdev() modified Allan deviation,
  • tdev() Time deviation
  • hdev() Hadamard deviation
  • ohdev() overlapping Hadamard deviation
  • totdev() total Allan deviation
  • mtie() Maximum time interval error
  • tierms() Time interval error RMS
  • mtotdev() Modified total deviation
  • ttotdev() Time total deviation
  • htotdev() Hadamard total deviation
  • theo1() Thêo1 deviation

Noise generators for creating synthetic datasets are also included:

  • violet noise with f^2 PSD
  • white noise with f^0 PSD
  • pink noise with f^-1 PSD
  • Brownian or random walk noise with f^-2 PSD

see /tests for tests that compare allantools output to other (e.g. Stable32) programs. More test data, benchmarks, ipython notebooks, and comparisons to known-good algorithms are welcome!

Documentation

See /docs for documentation in sphinx format. On Ubuntu this requires the python-sphinx and python-numpydoc packages. html/pdf documentation using sphinx can be built locally with:

/docs$ make html
/docs$ make latexpdf

this generates html documentation in docs/_build/html and pdf documentation in docs/_build/latex.

The sphinx documentation is also auto-generated online

IPython notebooks with examples

See /examples for some examples in IPython notebook format.

github formats the notebooks into nice web-pages, for example

todo: add here a very short guide on how to get started with ipython

Authors

Installation

clone from github, then install with:

sudo python setup.py install

(see python setup.py –help install for install options)

or download from pypi:

sudo pip install allantools

Usage

import allantools # https://github.com/aewallin/allantools/
rate = 1/float(data_interval_in_s) # data rate in Hz
taus = [1,2,4,8,16] #  tau-values in seconds
# fractional frequency data
(taus_used, adev, adeverror, adev_n) = allantools.adev(fract_freqdata, data_type='freq', rate=rate, taus=taus)
# phase data
(taus_used, adev, adeverror, adev_n) = allantools.adev(phasedata, data_type='phase', rate=rate, taus=taus)

# notes:
#  - taus_used may differ from taus, if taus has a non-integer multiples
#  of data_interval - adeverror assumes 1/sqrt(adev_n) errors

Tests

The tests compare the output of allantools to other programs such as Stable32. Tests may be run using py.test (http://pytest.org). Slow tests are marked ‘slow’ and tests failing because of a known reason are marked ‘fails’. To run all tests:

$ py.test

To exclude known failing tests:

$ py.test -m "not fails" --durations=10

To exclude tests that run slowly:

$ py.test -m "not slow" --durations=10

To exclude both (note option change):

$ py.test -k "not (slow or fails)" --durations=10

To run the above command without installing the package:

$ python setup.py test --addopts "-k 'not (fails or slow)'"

Test coverage may be obtained with the (https://pypi.python.org/pypi/coverage) module:

coverage run --source allantools setup.py test --addopts "-k 'not (fails or slow)'"
coverage report # Reports on standard output
coverage html # Writes annotated source code as html in ./htmlcov/

On Ubuntu this requires packages python-pytest and python-coverage.