AllanTools
==========
.. image:: https://badge.fury.io/py/AllanTools.svg
:target: https://badge.fury.io/py/AllanTools
.. image:: https://travis-ci.org/aewallin/allantools.svg?branch=master
:target: https://travis-ci.org/aewallin/allantools
.. image:: http://readthedocs.org/projects/allantools/badge/?version=latest
:target: http://allantools.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://coveralls.io/repos/github/aewallin/allantools/badge.svg?branch=master
:target: https://coveralls.io/github/aewallin/allantools?branch=master
.. image:: https://app.fossa.io/api/projects/git%2Bgithub.com%2Faewallin%2Fallantools.svg?type=shield
:target: https://app.fossa.io/projects/git%2Bgithub.com%2Faewallin%2Fallantools?ref=badge_shield
A python library for calculating Allan deviation and related
time & frequency statistics. `LGPL v3+ license <https://www.gnu.org/licenses/lgpl.html>`_.
* Development at https://github.com/aewallin/allantools
* Installation package at https://pypi.python.org/pypi/AllanTools
* Discussion group at https://groups.google.com/d/forum/allantools
* Documentation available at https://allantools.readthedocs.org
Input data should be evenly spaced observations of either fractional frequency,
or phase in seconds. Deviations are calculated for given tau values in seconds.
===================================== ====================================================
Function Description
===================================== ====================================================
``adev()`` Allan deviation
``oadev()`` Overlapping Allan deviation
``mdev()`` Modified Allan deviation
``tdev()`` Time deviation
``hdev()`` Hadamard deviation
``ohdev()`` Overlapping Hadamard deviation
``totdev()`` Total deviation
``mtotdev()`` Modified total deviation
``ttotdev()`` Time total deviation
``htotdev()`` Hadamard total deviation
``theo1()`` Theo1 deviation
``mtie()`` Maximum Time Interval Error
``tierms()`` Time Interval Error RMS
``gradev()`` Gap resistant overlapping Allan 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
More details on available statistics and noise generators : `full list of available functions <functions.html>`_
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!
Installation
------------
Install from pypi::
pip install allantools
Latest version + examples, tests, test data, iPython notebooks : clone from github, then install ::
python setup.py install
(see `python setup.py --help install` for install options)
These commands should be run as root for system-wide installation, or
you can use the `--user` option to install for your account only.
Exact command names may vary depending on your OS / package manager / target python version.
Basic usage
-----------
Minimal example, phase data
~~~~~~~~~~~~~~~~~~~~~~~~~~~
We can call allantools with only one parameter - an array of phase data.
This is suitable for time-interval measurements at 1 Hz, for example
from a time-interval-counter measuring the 1PPS output of two clocks.
::
>>> import allantools
>>> x = allantools.noise.white(10000) # Generate some phase data, in seconds.
>>> (taus, adevs, errors, ns) = allantools.oadev(x)
when only one input parameter is given, phase data in seconds is assumed
when no rate parameter is given, rate=1.0 is the default
when no taus parameter is given, taus='octave' is the default
Frequency data example
~~~~~~~~~~~~~~~~~~~~~~
Note that allantools assumes non-dimensional frequency data input.
Normalization, by e.g. dividing all data points with the average
frequency, is left to the user.
::
>>> import allantools
>>> import pylab as plt
>>> import numpy as np
>>> t = np.logspace(0, 3, 50) # tau values from 1 to 1000
>>> y = allantools.noise.white(10000) # Generate some frequency data
>>> r = 12.3 # sample rate in Hz of the input data
>>> (t2, ad, ade, adn) = allantools.oadev(y, rate=r, data_type="freq", taus=t) # Compute the overlapping ADEV
>>> fig = plt.loglog(t2, ad) # Plot the results
>>> # plt.show()
*New in 2016.11* : simple top-level `API <api.html>`_, using dedicated classes for data handling and plotting.
::
import allantools # https://github.com/aewallin/allantools/
import numpy as np
# Compute a deviation using the Dataset class
a = allantools.Dataset(data=np.random.rand(1000))
a.compute("mdev")
# New in 2019.7 : write results to file
a.write_result("output.dat")
# Plot it using the Plot class
b = allantools.Plot()
# New in 2019.7 : additional keyword arguments are passed to
# matplotlib.pyplot.plot()
b.plot(a, errorbars=True, grid=True)
# You can override defaults before "show" if needed
b.ax.set_xlabel("Tau (s)")
b.show()
Jupyter notebooks with examples
-------------------------------
Jupyter notebooks are interactive python scripts, embedded in a browser,
allowing you to manipulate data and display plots like easily. For guidance
on installing jupyter, please refer to https://jupyter.org/install.
See /examples for some examples in notebook format.
github formats the notebooks into nice web-pages, for example
* https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb
* https://github.com/aewallin/allantools/blob/master/examples/three-cornered-hat-demo.ipynb
Authors
-------
* Anders E.E. Wallin, anders.e.e.wallin "at" gmail.com , https://github.com/aewallin
* Danny Price, https://github.com/telegraphic
* Cantwell G. Carson, carsonc "at" gmail.com
* Frédéric Meynadier, https://github.com/fmeynadier
* Yan Xie, https://github.com/yxie-git
* Erik Benkler, https://github.com/EBenkler