lspopt 1.4.0
A Python implementation of a multitaper window method for estimating Wigner spectra for certain locally stationary processes
License: MIT
Requires Python: >=3.9
Keywords: Mathematical Statistics, Multitaper, Spectrogram

# LSPOpt

![Build and Test](https://github.com/hbldh/lspopt/workflows/Build%20and%20Test/badge.svg)
[![PyPI version](https://img.shields.io/pypi/v/lspopt.svg)](https://pypi.org/project/lspopt/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)

This module is a Python implementation of the multitaper window method 
described in [\[1\]](#references) for estimating Wigner spectra for certain locally
stationary processes.

Abstract from [\[1\]](#references):

> This paper investigates the time-discrete multitapers that give a mean square error optimal Wigner spectrum estimate for a class
> of locally stationary processes (LSPs). The accuracy in the estimation of the time-variable Wigner spectrum of the LSP is evaluated
> and compared with other frequently used methods. The optimal multitapers are also approximated by Hermite functions, which is
> computationally more efficient, and the errors introduced by this approximation are studied. Additionally, the number of windows
> included in a multitaper spectrum estimate is often crucial and an investigation of the error caused by limiting this number is made.
> Finally, the same optimal set of weights can be stored and utilized for different window lengths. As a result, the optimal multitapers
> are shown to be well approximated by Hermite functions, and a limited number of windows can be used for a mean square error
> optimal spectrogram estimate.
    
## Installation

Install via pip:

    pip install lspopt

If you prefer to use `conda`, see [instructions in this repo](https://github.com/conda-forge/lspopt-feedstock).

## Testing

Test with `pytest`:

    pytest tests/

See test badge at the top of this README for link to test coverage and reports.

## Usage

To generate the taper windows only, use the `lspopt` method:

```python
from lspopt import lspopt
H, w = lspopt(n=256, c_parameter=20.0)
```
    
There is also a convenience method for using the [SciPy spectrogram method](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.spectrogram.html#scipy.signal.spectrogram)
with the `lspopt` multitaper windows:

```python
from lspopt import spectrogram_lspopt
f, t, Sxx = spectrogram_lspopt(x, fs, c_parameter=20.0)
```
    
This can then be plotted with e.g. [matplotlib](http://matplotlib.org/).

### Example

One can generate a [chirp](https://docs.scipy.org/doc/scipy-0.16.0/reference/generated/scipy.signal.chirp.html)
process realisation and run spectrogram methods on this. 

```python
import numpy as np
from scipy.signal import chirp, spectrogram
import matplotlib.pyplot as plt

from lspopt.lsp import spectrogram_lspopt

fs = 10000
N = 100000
amp = 2 * np.sqrt(2)
noise_power = 0.001 * fs / 2
time = np.arange(N) / fs
freq = np.linspace(1000, 2000, N)
x = amp * chirp(time, 1000, 2.0, 6000, method='quadratic') + \
    np.random.normal(scale=np.sqrt(noise_power), size=time.shape)

f, t, Sxx = spectrogram(x, fs)

ax = plt.subplot(211)
ax.pcolormesh(t, f, Sxx)
ax.set_ylabel('Frequency [Hz]')
ax.set_xlabel('Time [sec]')

f, t, Sxx = spectrogram_lspopt(x, fs, c_parameter=20.0)

ax = plt.subplot(212)
ax.pcolormesh(t, f, Sxx)
ax.set_ylabel('Frequency [Hz]')
ax.set_xlabel('Time [sec]')

plt.tight_layout()
plt.show()
```

![Spectrogram plot](https://github.com/hbldh/lspopt/blob/master/plot.png "Top: Using SciPy's spectrogram method. Bottom: Using LSPOpt's spectrogram solution.")

*Top: Using SciPy's spectrogram method. Bottom: Using LSPOpt's spectrogram solution.*

## References

\[1\] [Hansson-Sandsten, M. (2011). Optimal multitaper Wigner spectrum 
estimation of a class of locally stationary processes using Hermite functions. 
EURASIP Journal on Advances in Signal Processing, 2011, 10.](https://dx.doi.org/10.1155/2011/980805)

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.4.0] - 2025-01-07

### Added

- Support for Python 3.12
- Support for `pip>=25`
- Support for `numpy>=2`
- Support for Windows and macOS
- Converted `setup.py` to `setup.cfg`

### Removed

- Support for Python 3.7 and 3.8
- Unused imports


## [1.3.0] - 2023-01-24

### Changed

- Modified test matrix in CI

### Removed

- Support for Python 2.7 and 3.6.
- Dependency on `six`.


## [1.2.0] - 2022-06-08

### Added

- New plot file

### Fixed

- Source distribution was broken on PyPI. Modified `MANIFEST.in` to correct that (#5 and #6)
- Url to missing plot file
- Fixed some incorrect int declarations using `1e3` notation

### Removed

- Removed Pipfile

## [1.1.1] - 2020-09-28

### Added

- Added `CHANGELOG.md`

### Changed

- Change CI from Azure Devops to Github Actions


## [1.1.0] - 2019-06-19

### Added

- First PyPI-released version


## [1.0.0] - 2016-08-22

### Added

- Regarded as a feature-complete, stable library.


[Unreleased]: https://github.com/hbldh/lspopt/compare/v1.3.0...HEAD
[1.3.0]: https://github.com/hbldh/lspopt/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/hbldh/lspopt/compare/v1.1.1...v1.2.0
[1.1.1]: https://github.com/hbldh/lspopt/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/hbldh/lspopt/compare/v1.0.0...v1.1.0