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

Code before:
    -------
    pgram : array_like
        Lomb-Scargle periodogram.

    Raises
    ------
    ValueError
        If any of the input arrays x, y, freqs, or weights are not 1D, or if any are
        zero length. Or, if the input arrays x, y, and weights do not have the same
        shape as each other.
    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. Parameter precenter is
    deprecated and will be removed in version 1.19.0. Precenter is a legacy parameter,
    and unnecessary when floating_mean is True. Furthermore, the mean removed by
    precenter does not account for sample weights, nor will it correct for any bias due
    to consistently missing observations at peaks and/or troughs. The precenter
    operation can be substituted by passing ``y = (y - y.mean())`` into the input. 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.

    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

Review comment (suggestion):
That `precenter` is deprecated is made clear above. Hence, I think it makes more sense to explain the general concept of "pre-centering" here (perhaps in a separate paragraph). Something along the lines of 

```text
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``.
```
would suffice. It would also have the advantage that this paragraph will not have to be changed in version 1.19.

Code after:
        Determines a y offset for each frequency independently, if True.
        Else the y offset is assumed to be `0`.

    Returns
    -------
    pgram : array_like
        Lomb-Scargle periodogram.

    Raises
    ------
    ValueError
        If any of the input arrays x, y, freqs, or weights are not 1D, or if any are
        zero length. Or, if the input arrays x, y, and weights do not have the same
        shape as each other.
    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 -