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

Code before:
    ValueError
        If any weight is < 0, or the sum of the weights is <= 0.
    ValueError
        If the normalize parameter is not one of the allowed options.

    See Also
    --------
    periodogram: Power spectral density using a periodogram
    welch: Power spectral density by Welch's method
    csd: Cross spectral density by Welch's method

    Notes
    -----
    The algorithm used will not automatically account for any unknown y offset, unless
    floating_mean is True. Therefore, for most use cases, if there is a possibility of
    a y offset, it is recommended to set floating_mean to True. Furthermore,
    floating_mean accounts for sample weights, and will also correct for any bias due
    to consistently missing observations at peaks and/or troughs. The legacy concept of
    "pre-centering" entails removing the mean from parameter `y` before processing,
    i.e., passing ``y - y.mean()`` instead of setting the parameter `floating_mean` to
    ``True``. When the normalize parameter is "amplitude", for any frequency in freqs
    that is below ``(2*pi)/(x.max() - x.min())``, the predicted amplitude will tend
    towards infinity. The concept of a "Nyquist frequency" limit (see Nyquist-Shannon
    sampling theorem) is not generally applicable to unevenly sampled data. Therefore,
    with unevenly sampled data, valid frequencies in freqs can often be much higher
    than expected for those familiar with methods like FFT.

    References
    ----------
    .. [1] N.R. Lomb "Least-squares frequency analysis of unequally spaced
           data", Astrophysics and Space Science, vol 39, pp. 447-462, 1976
           :doi:`10.1007/bf00648343`

    .. [2] J.D. Scargle "Studies in astronomical time series analysis. II -
           Statistical aspects of spectral analysis of unevenly spaced data",
           The Astrophysical Journal, vol 263, pp. 835-853, 1982
           :doi:`10.1086/160554`

    .. [3] M. Zechmeister and M. Kürster, "The generalised Lomb-Scargle periodogram.
           A new formalism for the floating-mean and Keplerian periodograms,"
           Astronomy and Astrophysics, vol. 496, pp. 577-584, 2009
           :doi:`10.1051/0004-6361:200811296`

    .. [4] J.T. VanderPlas, "Understanding the Lomb-Scargle Periodogram,"
           The Astrophysical Journal Supplement Series, vol. 236, no. 1, p. 16,
           May 2018
           :doi:`10.3847/1538-4365/aab766`


    Examples
    --------

Review comment (suggestion):
A purely cosmetic suggestion: Separating this text into paragraphs as well as marking `floating_mean` makes this note easier to read:

```suggestion
    The algorithm used will not automatically account for any unknown y offset, unless
    `floating_mean` is ``True``. Therefore, for most use cases, if there is a
    possibility of a y offset, it is recommended to set `floating_mean` to True.
    Furthermore, `floating_mean` accounts for sample weights, and will also correct for
    any bias due to consistently missing observations at peaks and/or troughs.

    The legacy concept of "pre-centering" entails removing the mean from parameter `y`
    before processing, i.e., passing ``y - y.mean()`` instead of setting the parameter
    `floating_mean` to ``True``.

    When the normalize parameter is "amplitude", for any frequency in freqs that is
    below ``(2*pi)/(x.max() - x.min())``, the predicted amplitude will tend towards
    infinity. The concept of a "Nyquist frequency" limit (see Nyquist-Shannon sampling
    theorem) is not generally applicable to unevenly sampled data. Therefore, with
    unevenly sampled data, valid frequencies in freqs can often be much higher than
    expected for those familiar with methods like FFT.
```

Otherwise, everything looks good.

Code after:
    ValueError
        If any weight is < 0, or the sum of the weights is <= 0.
    ValueError
        If the normalize parameter is not one of the allowed options.

    See Also
    --------
    periodogram: Power spectral density using a periodogram
    welch: Power spectral density by Welch's method
    csd: Cross spectral density by Welch's method

    Notes
    -----
    The algorithm used will not automatically account for any unknown y offset, unless
    `floating_mean` is ``True``. Therefore, for most use cases, if there is a
    possibility of a y offset, it is recommended to set `floating_mean` to ``True``.
    Furthermore, `floating_mean` accounts for sample weights, and will also correct for
    any bias due to consistently missing observations at peaks and/or troughs.

    The legacy concept of "pre-centering" entails removing the mean from parameter `y`
    before processing, i.e., passing ``y - y.mean()`` instead of setting the parameter
    `floating_mean` to ``True``.

    When the normalize parameter is "amplitude", for any frequency in freqs that is
    below ``(2*pi)/(x.max() - x.min())``, the predicted amplitude will tend towards
    infinity. The concept of a "Nyquist frequency" limit (see Nyquist-Shannon sampling
    theorem) is not generally applicable to unevenly sampled data. Therefore, with
    unevenly sampled data, valid frequencies in freqs can often be much higher than
    expected for those familiar with methods like FFT.

    References
    ----------
    .. [1] N.R. Lomb "Least-squares frequency analysis of unequally spaced
           data", Astrophysics and Space Science, vol 39, pp. 447-462, 1976
           :doi:`10.1007/bf00648343`

    .. [2] J.D. Scargle "Studies in astronomical time series analysis. II -
           Statistical aspects of spectral analysis of unevenly spaced data",
           The Astrophysical Journal, vol 263, pp. 835-853, 1982
           :doi:`10.1086/160554`

    .. [3] M. Zechmeister and M. Kürster, "The generalised Lomb-Scargle periodogram.
           A new formalism for the floating-mean and Keplerian periodograms,"
           Astronomy and Astrophysics, vol. 496, pp. 577-584, 2009
           :doi:`10.1051/0004-6361:200811296`

    .. [4] J.T. VanderPlas, "Understanding the Lomb-Scargle Periodogram,"
           The Astrophysical Journal Supplement Series, vol. 236, no. 1, p. 16,
           May 2018
           :doi:`10.3847/1538-4365/aab766`