| Name | SignalSnap JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | |
| Summary | Spectra at your fingertips |
| upload_time | 2023-01-19 11:37:52 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SignalSnap: Signal Analysis In Python Made Easy
by M. Sifft and D. Hägele
We present a fast Python toolbox for the higher-order spectral analysis of time series. The usual second-order
power spectrum and its higher-order generalization - so-called bi- and trispectra - are efficiently calculated
on any platform. The toolbox supports GPU acceleration using the ArrayFire library. The treatment of large datasets
is not limited by available RAM. We were able to process 11.6 GB of data (given in the hdf5 format) within just one
minute to obtain a power spectrum with a one-million-point resolution using a five-year-old Nvidia GeForce GTX 1080.
Similarly, 1000x1000 points of a trispectrum were obtained from processing 3.3 GB of data per minute.
Here, a few outstanding features of SignalSnap:
* Errors of spectral values are automatically calculated ([beginners example](Examples/Calculating%20Spectra%20from%20Numpy%20Array.ipynb), [example](Examples/Higher-Order%20Example:%20Mixing%20of%20Gaussian%20Noise.ipynb))
* Support for just-in-time import from hdf data (dataset does not have to fit in RAM) ([example](Examples/Calculating%20Polyspectra%20from%20Measurement.ipynb))
* Functions for conversion of Numpy array to hdf data is also provided ([example](Examples/Conversion%20of%20CSV%20to%20h5.ipynb))
* Functions for storing and loading calculated data together with metadata ([example](Examples/Storing%20and%20Loading%20Spectra.ipynb))
* Correlations between two time series can be calculated ([example](Examples/Correlations%20Between%20Two%20Time%20Series.ipynb))
* All calculation can be performed on GPU (NVidia and AMD) (see Arrayfire) ([example](Examples/Comparing%20CPU%20to%20GPU.ipynb))
* Advanced plotting options for two-dimensional higher-order spectra
* Usage of unbiased estimators for higher-order cumulants (see Literature)
* Efficient implementation of the confined Gaussian window for an optimal RMS time-bandwidth product (see Literature)
* Special functions for the verification of the stationarity of a signal ([example](Examples/Testing%20the%20Stationarity%20of%20a%20Signal.ipynb))
## Installation
SignalSnap is available on `pip` and can be installed with
```bash
pip install signalsnap
```
## Documentation
A comprehensive documentation of SignalSnap will follow soon.
### Examples
Examples for every function of the package are currently added to the folder Examples. Here are a few lines
to get you started. We will generate some white noise as signal/dataset store it as Numpy array called `y`.
```python
import SignalSnap as snp
import numpy as np
rng = np.random.default_rng()
# ------ Generation of white noise -----
f_unit = 'kHz'
fs = 10e3 # sampling rate in kHz
N = 1e5 # number of points
t = np.arange(N) / fs # unit is automatically chosen to be 1/f_unit = ms
y = rng.normal(scale=1, size=t.shape)
```
Now we creat a spectrum object and feed it with the data. This object will store the dataset,
later the spectra and errors, all freely chosen variables and contains
the methods for calculating the spectra, plotting and storing.
```python
spec = snp.Spectrum(data=y, delta_t=1/fs, f_unit=f_unit)
T_window = 0.02 # in ms
f_max = 5e3 # in kHz
f, s, serr = spec.calc_spec(order_in=[2], T_window=T_window, f_max=f_max, backend='cpu')
```
```
Actual T_window: 0.02
Maximum frequency: 5000.0
Number of points: 101
```
The output will show you the actual length of a window (in case your T_window is not a multiple of 1/fs), the maximum
frequency (Nyquist frequency) and the number of point of the calculated spectrum. The data points in the first window
are plotted, so you can verify the window length (which is also given in points by chunk shape). The function will
return `f` the frequencies at which the spectrum has been calculated, `s` the spectral values, and `serr` the error
of the spectra value (1 sigma).
Visualization of the results is just as easy as the calculation.
```python
fig = spec.plot(order_in=[2], f_max=f_max/2)
```
Besides the power spectrum (blue line) the error bands (1 to 5 sigma) are shown as grey lines in the plot.
Now, we can even verify that we are dealing with true Gaussian noise by calculating the higher-order spectra of the time
series.
## Why higher-order spectra?
Higher-order spectra contain additional information that is not contained within a power spectrum. The toolbox is
capable of calculating the third- and four-order spectrum (also called bi- and trispectrum, respectively). These have
the following properties:
* Spectra beyond second order are not sensitive to Gaussian noise.
* Bispectrum: shows contributions whenever the phase of two frequencies and their sum are phase correlated (e.g. by
mixing two signals)
* Trispectrum: can be interpreted as intensity correlation between two frequencies
Let's calculate all spectra up to fourth order of the dataset above and verify that the signal does not deviate
significantly from Gaussian noise using the first property (has no significant higher-order contributions). We
only have to change the `order_in` argument:
```python
f, s, serr = spec.calc_spec(order_in=[2, 3, 4], T_window=T_window, f_max=f_max, backend='cpu')
```
Plotting can also be done as before by changing the `order_in` argument:
```python
fig = spec.plot(order_in=[2, 3, 4], f_max=f_max/2, green_alpha=0)
```
Now, the third-and fourth-order spectra (S3 and S4) are visible. Just like the power spectrum they are noisy.
To decide which of the fluctuations are significant we need a way of displaying errors in the two-dimensional
plots. Here, errors are visualized be overlaying a green color on the spectral contributions which deviate from
zero less than a certain number of standard deviations.
```python
fig = spec.plot(order_in=[2, 3, 4], f_max=f_max/2, sigma=3)
```
Clearly, all higher-order contributions are nothing but noise and we have, therefore, verifed that our
original dataset was Gaussian noise (and even white noise due to the flat power spectrum).
## Support
The development of the SignalSnap package is supported by the working group Spectroscopy of Condensed Matter of the
Faculty of Physics and Astronomy at the Ruhr University Bochum.
## Dependencies
For the package multiple libraries are used for the numerics and displaying the results:
* NumPy
* SciPy
* MatPlotLib
* tqdm
* Numba
* h5py
* ArrayFire
## Literature
Unbiased estimators are used for the calculation of higher-order cumulants. Their derivation can be found in
[this paper](https://arxiv.org/abs/2011.07992). An explanation for how the spectra are calculated can be found in
Appendix B of [this paper](https://doi.org/10.1103/PhysRevResearch.3.033123).
Raw data
{
"_id": null,
"home_page": "",
"name": "SignalSnap",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Markus Sifft <markus.sifft@rub.de>",
"download_url": "https://files.pythonhosted.org/packages/c8/8e/40e687095d7ea3dc7bcff48b0d506d95391995a4dfa2280373488d317fbf/signalsnap-0.1.3.tar.gz",
"platform": null,
"description": "# SignalSnap: Signal Analysis In Python Made Easy \nby M. Sifft and D. H\u00e4gele\n\nWe present a fast Python toolbox for the higher-order spectral analysis of time series. The usual second-order \npower spectrum and its higher-order generalization - so-called bi- and trispectra - are efficiently calculated \non any platform. The toolbox supports GPU acceleration using the ArrayFire library. The treatment of large datasets \nis not limited by available RAM. We were able to process 11.6 GB of data (given in the hdf5 format) within just one \nminute to obtain a power spectrum with a one-million-point resolution using a five-year-old Nvidia GeForce GTX 1080. \nSimilarly, 1000x1000 points of a trispectrum were obtained from processing 3.3 GB of data per minute.\n\nHere, a few outstanding features of SignalSnap:\n* Errors of spectral values are automatically calculated ([beginners example](Examples/Calculating%20Spectra%20from%20Numpy%20Array.ipynb), [example](Examples/Higher-Order%20Example:%20Mixing%20of%20Gaussian%20Noise.ipynb))\n* Support for just-in-time import from hdf data (dataset does not have to fit in RAM) ([example](Examples/Calculating%20Polyspectra%20from%20Measurement.ipynb))\n* Functions for conversion of Numpy array to hdf data is also provided ([example](Examples/Conversion%20of%20CSV%20to%20h5.ipynb))\n* Functions for storing and loading calculated data together with metadata ([example](Examples/Storing%20and%20Loading%20Spectra.ipynb)) \n* Correlations between two time series can be calculated ([example](Examples/Correlations%20Between%20Two%20Time%20Series.ipynb))\n* All calculation can be performed on GPU (NVidia and AMD) (see Arrayfire) ([example](Examples/Comparing%20CPU%20to%20GPU.ipynb))\n* Advanced plotting options for two-dimensional higher-order spectra \n* Usage of unbiased estimators for higher-order cumulants (see Literature)\n* Efficient implementation of the confined Gaussian window for an optimal RMS time-bandwidth product (see Literature)\n* Special functions for the verification of the stationarity of a signal ([example](Examples/Testing%20the%20Stationarity%20of%20a%20Signal.ipynb))\n\n## Installation\nSignalSnap is available on `pip` and can be installed with \n```bash\npip install signalsnap\n```\n\n## Documentation\nA comprehensive documentation of SignalSnap will follow soon. \n\n### Examples\nExamples for every function of the package are currently added to the folder Examples. Here are a few lines \nto get you started. We will generate some white noise as signal/dataset store it as Numpy array called `y`.\n\n```python\nimport SignalSnap as snp\nimport numpy as np\nrng = np.random.default_rng()\n\n# ------ Generation of white noise -----\nf_unit = 'kHz'\nfs = 10e3 # sampling rate in kHz\nN = 1e5 # number of points\nt = np.arange(N) / fs # unit is automatically chosen to be 1/f_unit = ms\ny = rng.normal(scale=1, size=t.shape)\n```\n\nNow we creat a spectrum object and feed it with the data. This object will store the dataset, \nlater the spectra and errors, all freely chosen variables and contains \nthe methods for calculating the spectra, plotting and storing.\n\n```python\nspec = snp.Spectrum(data=y, delta_t=1/fs, f_unit=f_unit)\nT_window = 0.02 # in ms\nf_max = 5e3 # in kHz\nf, s, serr = spec.calc_spec(order_in=[2], T_window=T_window, f_max=f_max, backend='cpu')\n```\n\n```\nActual T_window: 0.02\nMaximum frequency: 5000.0\nNumber of points: 101\n```\n\n\nThe output will show you the actual length of a window (in case your T_window is not a multiple of 1/fs), the maximum \nfrequency (Nyquist frequency) and the number of point of the calculated spectrum. The data points in the first window \nare plotted, so you can verify the window length (which is also given in points by chunk shape). The function will \nreturn `f` the frequencies at which the spectrum has been calculated, `s` the spectral values, and `serr` the error \nof the spectra value (1 sigma).\n\nVisualization of the results is just as easy as the calculation.\n\n```python\nfig = spec.plot(order_in=[2], f_max=f_max/2)\n```\n\n\nBesides the power spectrum (blue line) the error bands (1 to 5 sigma) are shown as grey lines in the plot.\nNow, we can even verify that we are dealing with true Gaussian noise by calculating the higher-order spectra of the time\nseries.\n\n## Why higher-order spectra?\nHigher-order spectra contain additional information that is not contained within a power spectrum. The toolbox is \ncapable of calculating the third- and four-order spectrum (also called bi- and trispectrum, respectively). These have \nthe following properties:\n* Spectra beyond second order are not sensitive to Gaussian noise.\n* Bispectrum: shows contributions whenever the phase of two frequencies and their sum are phase correlated (e.g. by \nmixing two signals)\n* Trispectrum: can be interpreted as intensity correlation between two frequencies\n\nLet's calculate all spectra up to fourth order of the dataset above and verify that the signal does not deviate \nsignificantly from Gaussian noise using the first property (has no significant higher-order contributions). We \nonly have to change the `order_in` argument:\n\n```python\nf, s, serr = spec.calc_spec(order_in=[2, 3, 4], T_window=T_window, f_max=f_max, backend='cpu')\n```\n\nPlotting can also be done as before by changing the `order_in` argument:\n```python\nfig = spec.plot(order_in=[2, 3, 4], f_max=f_max/2, green_alpha=0)\n```\n\n\nNow, the third-and fourth-order spectra (S3 and S4) are visible. Just like the power spectrum they are noisy.\nTo decide which of the fluctuations are significant we need a way of displaying errors in the two-dimensional\nplots. Here, errors are visualized be overlaying a green color on the spectral contributions which deviate from \nzero less than a certain number of standard deviations. \n\n```python\nfig = spec.plot(order_in=[2, 3, 4], f_max=f_max/2, sigma=3)\n```\n\n\nClearly, all higher-order contributions are nothing but noise and we have, therefore, verifed that our \noriginal dataset was Gaussian noise (and even white noise due to the flat power spectrum).\n\n## Support\nThe development of the SignalSnap package is supported by the working group Spectroscopy of Condensed Matter of the \nFaculty of Physics and Astronomy at the Ruhr University Bochum.\n\n## Dependencies\nFor the package multiple libraries are used for the numerics and displaying the results:\n* NumPy\n* SciPy\n* MatPlotLib\n* tqdm\n* Numba\n* h5py\n* ArrayFire\n\n## Literature\nUnbiased estimators are used for the calculation of higher-order cumulants. Their derivation can be found in\n[this paper](https://arxiv.org/abs/2011.07992). An explanation for how the spectra are calculated can be found in\nAppendix B of [this paper](https://doi.org/10.1103/PhysRevResearch.3.033123).",
"bugtrack_url": null,
"license": "",
"summary": "Spectra at your fingertips",
"version": "0.1.3",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ee1df20a73aa33068892c527af28a332a55b312aa99105650c836bda707f8bf",
"md5": "8b706cabd09b6d7580fc3a276a1a1b6a",
"sha256": "1cb134531ad41140c3ec72a662dd7e93b4ecba574aa8c4b7b3bee43776524e88"
},
"downloads": -1,
"filename": "signalsnap-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b706cabd09b6d7580fc3a276a1a1b6a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22195,
"upload_time": "2023-01-19T11:37:37",
"upload_time_iso_8601": "2023-01-19T11:37:37.717329Z",
"url": "https://files.pythonhosted.org/packages/7e/e1/df20a73aa33068892c527af28a332a55b312aa99105650c836bda707f8bf/signalsnap-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c88e40e687095d7ea3dc7bcff48b0d506d95391995a4dfa2280373488d317fbf",
"md5": "723700f1f5e8d0282673e015365747e0",
"sha256": "59a70eae8a95ef75f4f349a025c5aea92591785b8e379de31efc9b0a64a50d0e"
},
"downloads": -1,
"filename": "signalsnap-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "723700f1f5e8d0282673e015365747e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26546374,
"upload_time": "2023-01-19T11:37:52",
"upload_time_iso_8601": "2023-01-19T11:37:52.729212Z",
"url": "https://files.pythonhosted.org/packages/c8/8e/40e687095d7ea3dc7bcff48b0d506d95391995a4dfa2280373488d317fbf/signalsnap-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-19 11:37:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "signalsnap"
}
