Metadata-Version: 2.1
Name: stockwell
Version: 1.0.7
Summary: Time-frequency analysis through Stockwell transform
Home-page: https://github.com/claudiodsf/stockwell
Author: Claudio Satriano
Author-email: satriano@ipgp.fr
License: CeCILL Free Software License Agreement, Version 2.1
Platform: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: CEA CNRS Inria Logiciel Libre License, version 2.1 (CeCILL-2.1)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy (>=1.18)

# Stockwell



Python package for time-frequency analysis through Stockwell transform.



Based on original code from [NIMH MEG Core Facility].



[![cf-badge]][cf-link]

[![PyPI-badge]][PyPI-link]

[![license-badge]][license-link]





## Installation



### Using Anaconda



If you use [Anaconda], the latest release of Stockwell is available via

[conda-forge][cf-link].



To install, simply run:



    conda install -c conda-forge stockwell





### Using pip and PyPI



The latest release of Stockwell is available on the

[Python Package Index][PyPI-link].



You can install it easily through `pip`:



    pip install stockwell





### Installation from source



If no precompiled package is available for you architecture on PyPI, or if you

want to work on the source code, you will need to compile this package from

source.



To obtain the source code, download the latest release from the

[releases page][releases-link], or clone the GitHub project.



#### C compiler



Part of Stockwell is written in C, so you will need a C compiler.



On Linux (Debian or Ubuntu), install the `build-essential` package:



    sudo apt install build-essential



On macOS, install the XCode Command Line Tools:



    xcode-select --install



On Windows, install the [Microsoft C++ Build Tools].



#### FFTW



To compile Stockwell, you will need to have [FFTW]

installed.



If you use [Anaconda]&nbsp;(Linux, macOS, Windows):



    conda install fftw



If you use Homebrew (macOS)



    brew install fftw



If you use `apt` (Debian or Ubuntu)



    sudo apt install libfftw3-dev



#### Install the Python package from source



Finally, install this Python package using pip:



    pip install .



Or, alternatively, in "editable" mode:



    pip install -e .





## Usage



Example usage:



```python

import numpy as np

from scipy.signal import chirp

import matplotlib.pyplot as plt

from stockwell import st



t = np.linspace(0, 10, 5001)

w = chirp(t, f0=12.5, f1=2.5, t1=10, method='linear')



fmin = 0  # Hz

fmax = 25  # Hz

df = 1./(t[-1]-t[0])  # sampling step in frequency domain (Hz)

fmin_samples = int(fmin/df)

fmax_samples = int(fmax/df)

stock = st.st(w, fmin_samples, fmax_samples)

extent = (t[0], t[-1], fmin, fmax)



fig, ax = plt.subplots(2, 1, sharex=True)

ax[0].plot(t, w)

ax[0].set(ylabel='amplitude')

ax[1].imshow(np.abs(stock), origin='lower', extent=extent)

ax[1].axis('tight')

ax[1].set(xlabel='time (s)', ylabel='frequency (Hz)')

plt.show()

```

You should get the following output:



![stockwell.png](https://cdn.jsdelivr.net/gh/claudiodsf/stockwell/stockwell.png)



You can also compute the inverse Stockwell transform, ex:



```python

inv_stock = st.ist(stock, fmin_samples, fmax_samples)

fig, ax = plt.subplots(2, 1, sharex=True)

ax[0].plot(t, w, label='original signal')

ax[0].plot(t, inv_stock, label='inverse Stockwell')

ax[0].set(ylabel='amplitude')

ax[0].legend(loc='upper right')

ax[1].plot(t, w - inv_stock)

ax[1].set_xlim(0, 10)

ax[1].set(xlabel='time (s)', ylabel='amplitude difference')

plt.show()

```

![inv_stockwell.png](https://cdn.jsdelivr.net/gh/claudiodsf/stockwell/inv_stockwell.png)





## References



Stockwell, R.G., Mansinha, L. & Lowe, R.P., 1996. Localization of the complex

spectrum: the S transform, IEEE Trans. Signal Process., 44(4), 998–1001,

doi:[10.1109/78.492555](https://doi.org/10.1109/78.492555)



[S transform on Wikipedia].







[NIMH MEG Core Facility]: https://kurage.nimh.nih.gov/meglab/Meg/Stockwell



[cf-badge]: http://img.shields.io/conda/vn/conda-forge/stockwell.svg

[cf-link]: https://anaconda.org/conda-forge/stockwell

[PyPI-badge]: http://img.shields.io/pypi/v/stockwell.svg

[PyPI-link]: https://pypi.python.org/pypi/stockwell

[license-badge]: https://img.shields.io/badge/license-CeCILL--2.1-green

[license-link]: http://www.cecill.info/licences.en.html

[releases-link]: https://github.com/claudiodsf/stockwell/releases



[Anaconda]: https://www.anaconda.com/products/individual

[Microsoft C++ Build Tools]:

https://visualstudio.microsoft.com/visual-cpp-build-tools

[FFTW]: http://www.fftw.org

[S transform on Wikipedia]: https://en.wikipedia.org/wiki/S_transform
