Skip to content

Commit

Permalink
Merge pull request #98 from fmeynadier/master
Browse files Browse the repository at this point in the history 
Doc update
  • Loading branch information
@aewallin
aewallin authored Jul 18, 2019
2 parents f792235 + b79cbdb commit f2feeac
Show file tree
Hide file tree
Showing 7 changed files with 231 additions and 291 deletions.
187 changes: 83 additions & 104 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,25 +17,30 @@ time & frequency statistics. `LGPL v3+ license <https://www.gnu.org/licenses/lgp
Developed at https://github.com/aewallin/allantools and also available
on PyPi 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.

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
===================================== ====================================================
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:

Expand All @@ -44,66 +49,71 @@ Noise generators for creating synthetic datasets are also included:
* 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!

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::
Installation
------------

/docs$ make html
/docs$ make latexpdf

this generates html documentation in docs/_build/html and pdf
documentation in docs/_build/latex.
Install from pypi::
pip install allantools

The sphinx documentation is also auto-generated online
Latest version + examples, tests, test data, iPython notebooks : clone from github, then install ::

* http://allantools.readthedocs.org
python setup.py install

IPython notebooks with examples
===============================
See /examples for some examples in IPython notebook format.
(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.

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

* 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
Minimal example, phase data
~~~~~~~~~~~~~~~~~~~~~~~~~~~

todo: add here a very short guide on how to get started with ipython
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.

Authors
=======
* Anders E.E. Wallin, anders.e.e.wallin "at" gmail.com
* 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

Installation
============
::

>>> import allantools
>>> x = allantools.noise.white(10000) # Generate some phase data, in seconds.
>>> (taus, adevs, errors, ns) = allantools.oadev(x)

clone from github, then install with::
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

sudo python setup.py install
Frequency data example
~~~~~~~~~~~~~~~~~~~~~~

(see `python setup.py --help install` for install options)
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.

or download from pypi::
sudo pip install allantools
::

>>> 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()

Usage
=====

New in 2016.11 : simple top-level API, using dedicated classes for data handling and plotting.
*New in 2016.11* : simple top-level `API <api.html>`_, using dedicated classes for data handling and plotting.

::

Expand All @@ -114,70 +124,39 @@ New in 2016.11 : simple top-level API, using dedicated classes for data handling
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()

Lower-level access to the algorithms is still possible :

::
Jupyter notebooks with examples
-------------------------------

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
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.

To exclude known failing tests::
See /examples for some examples in notebook format.

$ 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) and also check docstrings is ReST files ::

$ py.test -k "not (slow or fails)" --durations=10 --doctest-glob='*.rst'

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**.

Testing on multiple python versions can be done with tox (https://testrun.org/tox)

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

Tests run continuously on Travis-CI at https://travis-ci.org/aewallin/allantools
* 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
* 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

96 changes: 0 additions & 96 deletions docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,99 +32,3 @@ This class allows simple data plotting.

.. automethod:: __init__

Implemented statistics functions
--------------------------------

===================================== ====================================================
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
===================================== ====================================================

Low-level access to the statistics functions
--------------------------------------------

The deviation functions are generally of the form::

(tau_out, adev, adeverr, n) = allantools.adev(data, rate=1.0, data_type="phase", taus=None)

*Inputs:*

* **data** = list of phase measurements in seconds, or list of fractional frequency measurements (nondimensional)
* **rate** = sample rate of data in Hz , i.e. interval between phase measurements is 1/rate seconds.
* **data_type=** = either "phase" or "freq"
* **taus** = list of tau-values for ADEV computation. The keywords "all", "octave", or "decade" can also be used.

*Outputs*

* **tau_out** = list of tau-values for which deviations were computed
* **adev** = list of ADEV (or another statistic) deviations
* **adeverr** = list of estimated errors of allan deviations. some functions instead return a confidence interval (**err_l**, **err_h**)
* **n** = list of number of pairs in allan computation. standard error is adeverr = adev/sqrt(n)

Function listing
================


Statistics
----------

.. autofunction:: adev
.. autofunction:: oadev
.. autofunction:: mdev
.. autofunction:: hdev
.. autofunction:: ohdev
.. autofunction:: tdev
.. autofunction:: totdev
.. autofunction:: mtotdev
.. autofunction:: ttotdev
.. autofunction:: htotdev
.. autofunction:: theo1
.. autofunction:: mtie
.. autofunction:: tierms

Real-Time Statistics
--------------------

.. autoclass:: allantools.realtime.oadev_realtime
:members:

.. autoclass:: allantools.realtime.tdev_realtime
:members:

.. autoclass:: allantools.realtime.ohdev_realtime
:members:


Noise Generation
----------------

.. autofunction:: allantools.noise.white
.. autofunction:: allantools.noise.brown
.. autofunction:: allantools.noise.violet
.. autofunction:: allantools.noise.pink

Utilities
---------

.. autofunction:: frequency2phase
.. autofunction:: phase2frequency
.. autofunction:: phase2radians
.. autofunction:: edf_simple
.. autofunction:: edf_greenhall
.. autofunction:: edf_totdev
.. autofunction:: edf_mtotdev
.. autofunction:: three_cornered_hat_phase
7 changes: 5 additions & 2 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
except ImportError:
rtd_theme = False

import numpydoc
#import numpydoc


sys.path.insert(0, os.path.abspath(os.getcwd()))
Expand Down Expand Up @@ -61,7 +61,10 @@
'sphinx.ext.autosummary',
'sphinx.ext.coverage',
'sphinx.ext.intersphinx',
'numpydoc'
'sphinx.ext.napoleon',
# Will be obsolete with sphinx version 1.8:
'sphinx.ext.imgmath',
# 'numpydoc'
]

# Link to external doc
Expand Down
Loading

0 comments on commit f2feeac

Please sign in to comment.