Repository: scipy/scipy
File: scipy/signal/_spectral_py.py (Python)

Code before:
"""Tools for spectral analysis.
"""
import numpy as np
import numpy.typing as npt
from scipy import fft as sp_fft
from scipy._lib.deprecation import _deprecate_positional_args
from . import _signaltools
from ._short_time_fft import ShortTimeFFT, FFT_MODE_TYPE
from .windows import get_window
from ._arraytools import const_ext, even_ext, odd_ext, zero_ext
import warnings
from typing import cast, Literal


__all__ = ['periodogram', 'welch', 'lombscargle', 'csd', 'coherence',
           'spectrogram', 'stft', 'istft', 'check_COLA', 'check_NOLA']


@_deprecate_positional_args(version="1.19.0")
def lombscargle(
    x: npt.ArrayLike,
    y: npt.ArrayLike,
    freqs: npt.ArrayLike,
    *,
    precenter: bool | None = None,
    normalize: bool | Literal["power", "normalize", "amplitude"] = False,
    weights: npt.NDArray | None = None,
    floating_mean: bool = False,
) -> npt.NDArray:
    """
    Compute the generalized Lomb-Scargle periodogram.

    The Lomb-Scargle periodogram was developed by Lomb [1]_ and further
    extended by Scargle [2]_ to find, and test the significance of weak
    periodic signals with uneven temporal sampling. The algorithm used
    here is based on a weighted least-squares fit of the form
    ``y(ω) = a*cos(ω*x) + b*sin(ω*x) + c``, where the fit is calculated for
    each frequency independently. This algorithm was developed by Zechmeister
    and Kürster which improves the Lomb-Scargle periodogram by enabling
    the weighting of individual samples and calculating an unknown y offset
    (also called a "floating-mean" model) [3]_. For more details, and practical
    considerations, see the excellent reference on the Lomb-Scargle periodogram [4]_.

    When *normalize* is False (or "power") (default) the computed periodogram
    is unnormalized, it takes the value ``(A**2) * N/4`` for a harmonic
    signal with amplitude A for sufficiently large N. Where N is the length of x or y.

    When *normalize* is True (or "normalize") the computed periodogram is normalized
    by the residuals of the data around a constant reference model (at zero).


Review comment (suggestion):
```suggestion
    precenter: bool = _NoValue,
```

Code after:
"""Tools for spectral analysis.
"""
import numpy as np
import numpy.typing as npt
from scipy import fft as sp_fft
from scipy._lib.deprecation import _deprecate_positional_args, _NoValue
from . import _signaltools
from ._short_time_fft import ShortTimeFFT, FFT_MODE_TYPE
from .windows import get_window
from ._arraytools import const_ext, even_ext, odd_ext, zero_ext
import warnings
from typing import cast, Literal


__all__ = ['periodogram', 'welch', 'lombscargle', 'csd', 'coherence',
           'spectrogram', 'stft', 'istft', 'check_COLA', 'check_NOLA']


@_deprecate_positional_args(version="1.19.0")
def lombscargle(
    x: npt.ArrayLike,
    y: npt.ArrayLike,
    freqs: npt.ArrayLike,
    *,
    precenter: bool = _NoValue,
    normalize: bool | Literal["power", "normalize", "amplitude"] = False,
    weights: npt.NDArray | None = None,
    floating_mean: bool = False,
) -> npt.NDArray:
    """
    Compute the generalized Lomb-Scargle periodogram.

    The Lomb-Scargle periodogram was developed by Lomb [1]_ and further
    extended by Scargle [2]_ to find, and test the significance of weak
    periodic signals with uneven temporal sampling. The algorithm used
    here is based on a weighted least-squares fit of the form
    ``y(ω) = a*cos(ω*x) + b*sin(ω*x) + c``, where the fit is calculated for
    each frequency independently. This algorithm was developed by Zechmeister
    and Kürster which improves the Lomb-Scargle periodogram by enabling
    the weighting of individual samples and calculating an unknown y offset
    (also called a "floating-mean" model) [3]_. For more details, and practical
    considerations, see the excellent reference on the Lomb-Scargle periodogram [4]_.

    When *normalize* is False (or "power") (default) the computed periodogram
    is unnormalized, it takes the value ``(A**2) * N/4`` for a harmonic
    signal with amplitude A for sufficiently large N. Where N is the length of x or y.

    When *normalize* is True (or "normalize") the computed periodogram is normalized
    by the residuals of the data around a constant reference model (at zero).