AllanTools

https://github.com/aewallin/allantools
Admin
AllanTools is a Python library for calculating Allan deviation and related time & frequency...
Tokens:31,137
Snippets:211
Trust Score:9.4
License:LGPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run noise-color-demo.py from command line

Source: https://github.com/aewallin/allantools/blob/master/examples/README.md

Run the Python script version of the noise-color-demo example after installing allantools. The command is executed from the command line.

```bash
> python noise-color-demo.py
```

--------------------------------

### Import pylab, numpy, and allantools

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Imports required libraries for the examples.

```python
import pylab as plt
import numpy as np
import allantools
```

--------------------------------

### Run tests without installing the package

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run the same test command as above without installing the package, using setup.py test.

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

--------------------------------

### Install allantools from cloned repository

Source: https://github.com/aewallin/allantools/blob/master/docs/readme_copy.rst

Install the latest version from a cloned GitHub repository. Run from the cloned directory.

```default
pip install .
```

--------------------------------

### Test source distribution in virtualenv

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Create a virtual environment, install the built package, and verify it imports correctly. The install takes a long time while compiling numpy and scipy.

```default
$ virtualenv tmp
$ tmp/bin/pip install dist/AllanTools-2016.2.tar.gz
$ tmp/bin/python
>>> import allantools
```

--------------------------------

### Install allantools from PyPI

Source: https://github.com/aewallin/allantools/blob/master/docs/readme_copy.rst

Install the latest released version of allantools from PyPI using pip.

```default
pip install allantools
```

--------------------------------

### Minimal phase data example

Source: https://github.com/aewallin/allantools/blob/master/docs/readme_copy.rst

Compute overlapping Allan deviation (oadev) from phase data in seconds. Assumes rate=1.0 and taus='octave' by default.

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

--------------------------------

### Dataset and Plot class API example

Source: https://github.com/aewallin/allantools/blob/master/docs/readme_copy.rst

Use the Dataset class to compute a deviation, write results to a file, and plot with the Plot class. Additional keyword arguments are passed to matplotlib.pyplot.plot().

```default
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_results("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()
```

--------------------------------

### Frequency data example

Source: https://github.com/aewallin/allantools/blob/master/docs/readme_copy.rst

Compute overlapping Allan deviation from frequency data with custom rate and tau values, then plot with matplotlib.

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

--------------------------------

### Output of example1()

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Shows the warnings and result from running example1().

```text
Output:
/usr/lib/python3/dist-packages/numpy/lib/nanfunctions.py:514: FutureWarning: In Numpy 1.9 the sum along empty slices will be zero.
  FutureWarning)
/home/fmeynadier/.local/lib/python3.4/site-packages/ipykernel/__main__.py:14: DeprecationWarning: using a non-integer number instead of an integer will result in an error in the future

```

```text
Result:
<matplotlib.figure.Figure at 0x7f25734b6d30>
```

--------------------------------

### Output of example2()

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Shows the warning and result from running example2().

```text
Output:
/usr/lib/python3/dist-packages/numpy/lib/nanfunctions.py:514: FutureWarning: In Numpy 1.9 the sum along empty slices will be zero.
  FutureWarning)

```

```text
Result:
<matplotlib.figure.Figure at 0x7f25731242b0>
```

--------------------------------

### Build HTML and PDF documentation with Sphinx

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run these commands from the /docs directory to build HTML and PDF documentation. The output is generated in docs/_build/html and docs/_build/latex respectively.

```default
/docs$ make html
/docs$ make latexpdf
```

--------------------------------

### Build source distribution with hatch

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Create a source distribution package in the dist/ directory.

```default
hatch build sdist
```

--------------------------------

### Call example1()

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Executes the example1 function to generate the GRADEV comparison plot.

```python
example1()
```

--------------------------------

### Call example2()

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Executes the example2 function to generate the GRADEV plot for nonstationary noise.

```python
example2()
```

--------------------------------

### Upload package to PyPI with twine

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Upload the built distribution to PyPI. Requires a ~/.pypirc file with username and password.

```default
$ twine upload dist/*
```

--------------------------------

### Run tests with tox

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run tests on multiple Python versions using tox.

```default
$ tox
```

--------------------------------

### GCoDev output for freqBC and freqAB data

Source: https://github.com/aewallin/allantools/blob/master/examples/gcodev_BC_AB.txt

Output from running ./GCoDev data/freqBC.txt data/freqAB.txt. The header notes the SigmaTheta version and that the config file /usr/share/sigmatheta/SigmaTheta.conf could not be opened, so hardcoded defaults were used. The table lists Allan factor (AF) and GCoDev values for the given frequency data.

```text
Project: /aewallin/allantools
# SigmaTheta v3.0-29-g053a Wed Oct 11 12:59:22 2023 +0000
#
# ./GCoDev data/freqBC.txt data/freqAB.txt 
# cannot open config file /usr/share/sigmatheta/SigmaTheta.conf
# using hardcoded defaults.
# AF                          GCoDev( freqBC, freqCA )
  1.0000000000000000e+00  	  -8.6572265057967588e+00
  2.0000000000000000e+00  	  -4.3432005973471712e+00
  4.0000000000000000e+00  	  -2.1721589652062332e+00
  8.0000000000000000e+00  	  -1.0880738273515811e+00
  1.6000000000000000e+01  	  -5.4146914222235154e-01
  3.2000000000000000e+01  	  -2.7216329996649430e-01
  6.4000000000000000e+01  	  -1.3536179632154205e-01
  1.2800000000000000e+02  	  -6.7521150727460719e-02
  2.5600000000000000e+02  	  -3.3923780727460719e-02
```

--------------------------------

### Generate test coverage reports

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run coverage on the test suite and generate reports. The html report is written to ./htmlcov/.

```default
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/
```

--------------------------------

### Run all tests with pytest

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run the full test suite using py.test. The tests compare AllanTools output to other programs like Stable32.

```default
$ py.test
```

--------------------------------

### Generate synthetic phase data and pairwise differences

Source: https://github.com/aewallin/allantools/blob/master/examples/three-cornered-hat-demo.ipynb

Generates synthetic phase data for three clocks (A, B, C) with white phase noise, and computes pairwise differences (AB, BC, CA) for the three-cornered hat analysis.

```python
t = numpy.logspace( 0 ,4,50) # tau values from 1 to 1000

N=10000
rate = 1.0
# white phase noise => 1/tau ADEV
d = numpy.random.randn(4*N)
phaseA = d[0:N] # numpy.random.randn(N) #pink(N)
phaseA = [1*x for x in phaseA]
phaseB = d[N:2*N] #numpy.random.randn(N) #noise.pink(N)
phaseB = [5*x for x in phaseB]
phaseC = d[2*N:3*N] #numpy.random.randn(N) #noise.pink(N)
phaseC = [5*x for x in phaseC]

phaseAB = [a-b for (a,b) in zip(phaseA,phaseB)]
phaseBC = [b-c for (b,c) in zip(phaseB,phaseC)]
phaseCA = [c-a for (c,a) in zip(phaseC,phaseA)]
```

--------------------------------

### Define example1: GRADEV with and without gaps

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Defines a function that computes GRADEV for white phase noise, comparing original data and data with a simulated gap. Uses allantools.gradev and plots error bars on a log-log scale.

```python
def example1():
    """
    Compute the GRADEV of a white phase noise. Compares two different 
    scenarios. 1) The original data and 2) ADEV estimate with gap robust ADEV.
    """
    N = 1000
    f = 1
    y = np.random.randn(1,N)[0,:]
    x = np.linspace(1,len(y),len(y))
    (x_ax, y_ax, [err_l, err_h], ns) = allantools.gradev(y,rate=f,taus=x)
    plt.errorbar(x_ax, y_ax,yerr=[err_l,err_h],label='GRADEV, no gaps')
    
    
    y[np.floor(0.4*N):np.floor(0.6*N)] = np.NaN # Simulate missing data
    (x_ax, y_ax, [err_l, err_h], ns) = allantools.gradev(y,rate=f,taus=x)
    plt.errorbar(x_ax, y_ax,yerr=[err_l,err_h], label='GRADEV, with gaps')
    plt.xscale('log')
    plt.yscale('log')
    plt.grid()
    plt.legend()
    plt.xlabel('Tau / s')
    plt.ylabel('Overlapping Allan deviation')
    plt.show()
```

--------------------------------

### Import numpy, matplotlib, allantools, and noise module

Source: https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb

Imports the required libraries for numerical operations, plotting, and Allan deviation calculations.

```python
import numpy
import matplotlib.pyplot as plt 
import allantools
from allantools import noise
```

--------------------------------

### Enable inline plotting with %matplotlib inline

Source: https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb

Sets up matplotlib to display plots inline in the notebook.

```python
%matplotlib inline
```

--------------------------------

### Run tests excluding slow tests

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run tests while excluding those marked as 'slow' and show the 10 slowest tests. Useful for a quicker test run.

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

--------------------------------

### Run tests excluding known failures

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run tests while excluding those marked as 'fails' and show the 10 slowest tests. Useful for checking the current state of the test suite.

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

--------------------------------

### Run tests excluding slow and failing tests with doctest

Source: https://github.com/aewallin/allantools/blob/master/docs/dev.rst

Run tests excluding both slow and failing tests, and also check docstrings in ReST files. Note the option change from -m to -k.

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

--------------------------------

### Run three-cornered hat phase calculation

Source: https://github.com/aewallin/allantools/blob/master/examples/three-cornered-hat-demo.ipynb

Runs the three-cornered hat phase calculation using allantools.three_cornered_hat_phase with the pairwise phase differences, rate, tau values, and the mdev function.

```python
(taus,devA,err_a,ns_ab) = allantools.three_cornered_hat_phase(phaseAB,phaseBC,phaseCA,rate,t, allantools.mdev)
```

--------------------------------

### Define example2: GRADEV for nonstationary white phase noise

Source: https://github.com/aewallin/allantools/blob/master/examples/gradev-demo.ipynb

Defines a function that computes GRADEV for a nonstationary white phase noise signal, comparing data with and without a simulated gap.

```python
def example2():
    """
    Compute the GRADEV of a nonstationary white phase noise.
    """
    N=1000 # number of samples
    f = 1 # data samples per second
    s=1+5/N*np.arange(0,N)
    y=s*np.random.randn(1,N)[0,:]
    x = np.linspace(1,len(y),len(y))
    x_ax, y_ax, [err_l, err_h], ns = allantools.gradev(y, rate=f, taus=x)
    plt.loglog(x_ax, y_ax,'b.',label="No gaps")
    y[int(0.4*N):int(0.6*N,)] = np.NaN  # Simulate missing data
    x_ax, y_ax, [err_l, err], ns = allantools.gradev(y, rate=f, taus=x)
    plt.loglog(x_ax, y_ax,'g.',label="With gaps")
    plt.grid()
    plt.legend()
    plt.xlabel('Tau / s')
    plt.ylabel('Overlapping Allan deviation')
    plt.show()
```

--------------------------------

### Generate noise types and plot ADEV slopes

Source: https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb

Creates synthetic noise signals (pink, white, violet, brown) and plots their overlapping Allan deviation to verify expected slopes: constant for pink, 1/tau for white phase, 1/sqrt(tau) for white frequency, and sqrt(tau) for random walk frequency.

```python
t = numpy.logspace(0, 3, 50)  # tau values from 1 to 1000
plt.subplot(111, xscale="log", yscale="log")
N = 10000

# pink frequency noise => constant ADEV
freq_pink = noise.pink(N)
phase_p = numpy.cumsum(noise.pink(N))  # integrate to get phase, color??
plotallan_phase(plt, phase_p, 1, t, 'co')
plotallan(plt, freq_pink, 1, t, 'c.')
plotline(plt, 0, t, 'c')

# white phase noise => 1/tau ADEV
phase_white = noise.white(N)
plotallan_phase(plt, phase_white, 1, t, 'ro')
freq_w = noise.violet(N)  # diff to get frequency, "Violet noise"
plotallan(plt, freq_w, 1, t, 'r.')
plotline(plt, -1, t, 'r')

# white frequency modulation => 1/sqrt(tau) ADEV
freq_white = noise.white(N)
phase_rw = noise.brown(N)  # integrate to get Brownian, or random walk phase
plotallan(plt, freq_white, 1, t, 'b.')
plotallan_phase(plt, phase_rw, 1, t, 'bo')
plotline(plt, -0.5, t, 'b')


# Brownian a.k.a random walk  frequency => sqrt(tau) ADEV
freq_rw = noise.brown(N)
phase_rw_rw = numpy.cumsum(noise.brown(N))  # integrate to get  phase
plotallan(plt, freq_rw, 1, t, 'm.')
plotallan_phase(plt, phase_rw_rw, 1, t, 'mo')
plotline(plt, +0.5, t, 'm')

plt.xlabel('Tau')
plt.ylabel('Overlapping Allan deviation')
print("Done.")
plt.grid()
plt.show()
```

--------------------------------

### Define helper functions plotallan and plotallan_phase

Source: https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb

Defines functions to compute and plot overlapping Allan deviation (ADEV) for frequency and phase data, and a helper to plot a reference line with a given slope.

```python
def plotallan(plt, y, rate, taus, style):
    (t2, ad, ade, adn) = allantools.oadev(y, rate=rate, data_type="freq", taus=taus)
    plt.loglog(t2, ad, style)


def plotallan_phase(plt, y, rate, taus, style):
    (t2, ad, ade, adn) = allantools.oadev(y, rate=rate, taus=taus)
    plt.loglog(t2, ad, style)


def plotline(plt, alpha, taus, style):
    """ plot a line with the slope alpha """
    y = [pow(tt, alpha) for tt in taus]
    plt.loglog(taus, y, style)
```

--------------------------------

### Define plotting helpers for Allan deviation and slope lines

Source: https://github.com/aewallin/allantools/blob/master/examples/three-cornered-hat-demo.ipynb

Defines two helper functions: plotallan_phase computes modified Allan deviation (mdev) and plots it on a log-log scale, while plotline plots a line with a given slope alpha for comparison.

```python
def plotallan_phase(plt,y,rate,taus, style):
	(t2, ad, ade,adn) = allantools.mdev(y,rate=rate,taus=taus)
	plt.loglog(t2, ad, style)

# plot a line with the slope alpha
def plotline(plt, alpha, taus,style):
	y = [ pow(tt,alpha) for tt in taus]
	plt.loglog(taus,y,style)
```

--------------------------------

### Output of the plotting script

Source: https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb

The printed output from the script, indicating completion.

```text
Output:
Done.
```

--------------------------------

### GCoDev Output Data

Source: https://github.com/aewallin/allantools/blob/master/examples/gcodev_CA_AB.txt

The output of the GCoDev command, showing the Allan deviation values for averaging factors from 1 to 32768. The header indicates the command used and a warning about a missing config file, with hardcoded defaults applied.

```text
# SigmaTheta v3.0-29-g053a Wed Oct 11 12:59:22 2023 +0000
#
# ./GCoDev data/freqCA.txt data/freqAB.txt 
# cannot open config file /usr/share/sigmatheta/SigmaTheta.conf
# using hardcoded defaults.
# AF                          GCoDev( freqCA, freqAB )
  1.0000000000000000e+00 	  -1.5822698768801253e+00
  2.0000000000000000e+00 	  -7.1516620564809252e-01
  4.0000000000000000e+00 	  -3.6211155665136197e-01
  8.0000000000000000e+00 	  -1.7060913297684019e-01
  1.6000000000000000e+01 	  -1.0714277882857023e-01
  3.2000000000000000e+01 	  -5.0828253381873023e-02
  6.4000000000000000e+01 	  -2.3379022940577421e-02
  1.2800000000000000e+02 	  -1.3214052398385969e-02
  2.5600000000000000e+02 	  -5.9325361833646468e-03
  5.1200000000000000e+02 	  -3.1859793758841873e-03
  1.0240000000000000e+03 	  -1.1872594305012082e-03
  2.0480000000000000e+03 	  -7.9181618114116986e-04
  4.0960000000000000e+03 	  -3.1864022889666255e-04
  8.1920000000000000e+03 	  -1.8946156459394094e-04
  1.6384000000000000e+04 	  -9.2401802887092055e-05
  3.2768000000000000e+04 	  -4.7453355340743471e-05
```

--------------------------------

### Plot Allan deviations and three-cornered hat result

Source: https://github.com/aewallin/allantools/blob/master/examples/three-cornered-hat-demo.ipynb

Plots the Allan deviation of individual phases and pairwise differences, along with the three-cornered hat result (devA) on a log-log scale, with grid and display.

```python
plt.subplot(111, xscale="log", yscale="log")
plotallan_phase(plt, phaseA, 1, t, 'ro')
plotallan_phase(plt, phaseB, 1, t, 'go')
plotallan_phase(plt, phaseC, 1, t, 'bo')

plotallan_phase(plt, phaseAB, 1, t, 'r.')    
plotallan_phase(plt, phaseBC, 1, t, 'g.')
plotallan_phase(plt, phaseCA, 1, t, 'b.')    

plt.loglog(taus, devA, 'rv')

plt.grid()
plt.show()
```

--------------------------------

### Result of the plotting script

Source: https://github.com/aewallin/allantools/blob/master/examples/noise-color-demo.ipynb

The result of the plotting script, showing the matplotlib figure object.

```text
Result:
<matplotlib.figure.Figure at 0x7f4bc7254b38>
```

--------------------------------

### allantools.adev

Source: https://github.com/aewallin/allantools/blob/master/docs/functions.rst

Computes the Allan deviation (ADEV) for the given data. This is a low-level function that returns tau values, deviation estimates, errors, and the number of pairs used.

```APIDOC
## allantools.adev

### Description
Computes the Allan deviation (ADEV) for the given data. This is a low-level function that returns tau values, deviation estimates, errors, and the number of pairs used.

### Method
Function call

### Endpoint
allantools.adev(data, rate=1.0, data_type="phase", taus=None)

### Parameters
#### Inputs
- **data** (list) - Required - List of phase measurements in seconds, or list of fractional frequency measurements (nondimensional).
- **rate** (float) - Optional - Sample rate of data in Hz, i.e., interval between phase measurements is 1/rate seconds. Default is 1.0.
- **data_type** (string) - Optional - Either "phase" or "freq". Default is "phase".
- **taus** (list or string) - Optional - List of tau-values for ADEV computation. The keywords "all", "octave", "decade", or "log10" can also be used.

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

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

### Response
#### Success Response
Returns a tuple (tau_out, adev, adeverr, n) as described above.

#### Response Example
```
(tau_out, adev, adeverr, n)
```
```
Tokens:
Raw