{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The algorithm used will not automatically account for any unknown y offset, unless " }, { "__type": "ParamRef", "__tag": 4071, "name": "floating_mean" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ". Therefore, for most use cases, if there is a possibility of a y offset, it is recommended to set " }, { "__type": "ParamRef", "__tag": 4071, "name": "floating_mean" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ". Furthermore, " }, { "__type": "ParamRef", "__tag": 4071, "name": "floating_mean" }, { "__type": "Text", "__tag": 4046, "value": " accounts for sample weights, and will also correct for any bias due to consistently missing observations at peaks and/or troughs." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The legacy concept of \"pre-centering\" entails removing the mean from parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " before processing, i.e., passing " }, { "__type": "InlineCode", "__tag": 4051, "value": "y - y.mean()" }, { "__type": "Text", "__tag": 4046, "value": " instead of setting the parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "floating_mean" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the normalize parameter is \"amplitude\", for any frequency in freqs that is below " }, { "__type": "InlineCode", "__tag": 4051, "value": "(2*pi)/(x.max() - x.min())" }, { "__type": "Text", "__tag": 4046, "value": ", 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." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "lombscargle", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:lombscargle" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ⛔ \nPyTorch ⛔ ⛔ \nJAX ⛔ ⛔ \nDask ⛔ n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If any weight is < 0, or the sum of the weights is <= 0." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the normalize parameter is not one of the allowed options." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "pgram", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lomb-Scargle periodogram." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the generalized Lomb-Scargle periodogram." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sample times." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Measurement values. Values are assumed to have a baseline of " }, { "__type": "InlineCode", "__tag": 4051, "value": "y = 0" }, { "__type": "Text", "__tag": 4046, "value": ". If there is a possibility of a y offset, it is recommended to set " }, { "__type": "ParamRef", "__tag": 4071, "name": "floating_mean" }, { "__type": "Text", "__tag": 4046, "value": " to True." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "freqs", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Angular frequencies (e.g., having unit rad/s=2π/s for " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " having unit s) for output periodogram. Frequencies are normally >= 0, as any peak at " }, { "__type": "InlineCode", "__tag": 4051, "value": "-freq" }, { "__type": "Text", "__tag": 4046, "value": " will also exist at " }, { "__type": "InlineCode", "__tag": 4051, "value": "+freq" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "precenter", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pre-center measurement values by subtracting the mean, if True. This is a legacy parameter and unnecessary if " }, { "__type": "ParamRef", "__tag": 4071, "name": "floating_mean" }, { "__type": "Text", "__tag": 4046, "value": " is True." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "deprecated", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "deprecated 1.17.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "ParamRef", "__tag": 4071, "name": "precenter" }, { "__type": "Text", "__tag": 4046, "value": " argument is deprecated and will be removed in SciPy 1.19.0. The functionality can be substituted by passing " }, { "__type": "InlineCode", "__tag": 4051, "value": "y - y.mean()" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "normalize", "annotation": "bool | str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute normalized or complex (amplitude + phase) periodogram. Valid options are: " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": "/" }, { "__type": "InlineCode", "__tag": 4051, "value": "\"power\"" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": "/" }, { "__type": "InlineCode", "__tag": 4051, "value": "\"normalize\"" }, { "__type": "Text", "__tag": 4046, "value": ", or " }, { "__type": "InlineCode", "__tag": 4051, "value": "\"amplitude\"" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "weights", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Weights for each sample. Weights must be nonnegative." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "floating_mean", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determines a y offset for each frequency independently, if True. Else the y offset is assumed to be " }, { "__type": "InlineRole", "__tag": 4003, "value": "0", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Lomb-Scargle periodogram was developed by Lomb " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and further extended by Scargle " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " 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 " }, { "__type": "InlineCode", "__tag": 4051, "value": "y(ω) = a*cos(ω*x) + b*sin(ω*x) + c" }, { "__type": "Text", "__tag": 4046, "value": ", 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) " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ". For more details, and practical considerations, see the excellent reference on the Lomb-Scargle periodogram " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "normalize" } ] }, { "__type": "Text", "__tag": 4046, "value": " is False (or \"power\") (default) the computed periodogram is unnormalized, it takes the value " }, { "__type": "InlineCode", "__tag": 4051, "value": "(A**2) * N/4" }, { "__type": "Text", "__tag": 4046, "value": " for a harmonic signal with amplitude A for sufficiently large N. Where N is the length of x or y." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "normalize" } ] }, { "__type": "Text", "__tag": 4046, "value": " is True (or \"normalize\") the computed periodogram is normalized by the residuals of the data around a constant reference model (at zero)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "normalize" } ] }, { "__type": "Text", "__tag": 4046, "value": " is \"amplitude\" the computed periodogram is the complex representation of the amplitude and phase." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input arrays should be 1-D of a real floating data type, which are converted into float64 arrays before processing." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "deprecated", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "deprecated 1.19.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use of argument(s) " }, { "__type": "InlineCode", "__tag": 4051, "value": "{'precenter', 'weights', 'normalize', 'floating_mean'}" }, { "__type": "Text", "__tag": 4046, "value": " by position is deprecated; beginning in SciPy 1.19.0, these will be keyword-only." } ] } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/signal/_spectral_py.py", "item_line": 19, "item_type": "function", "aliases": [ "scipy.signal.lombscargle" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nrng = np.random.default_rng()\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFirst define some input parameters for the signal:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "A = 2. # amplitude\nc = 2. # offset\nw0 = 1. # rad/sec\nnin = 150\nnout = 1002\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nRandomly generate sample times:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = rng.uniform(0, 10*np.pi, nin)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nPlot a sine wave for the selected times:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "y = A * np.cos(w0*x) + c\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nDefine the array of frequencies for which to compute the periodogram:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "w = np.linspace(0.25, 10, nout)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCalculate Lomb-Scargle periodogram for each of the normalize options:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.signal import lombscargle\npgram_power = lombscargle(x, y, w, normalize=False)\npgram_norm = lombscargle(x, y, w, normalize=True)\npgram_amp = lombscargle(x, y, w, normalize='amplitude')\npgram_power_f = lombscargle(x, y, w, normalize=False, floating_mean=True)\npgram_norm_f = lombscargle(x, y, w, normalize=True, floating_mean=True)\npgram_amp_f = lombscargle(x, y, w, normalize='amplitude', floating_mean=True)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNow make a plot of the input data:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nfig, (ax_t, ax_p, ax_n, ax_a) = plt.subplots(4, 1, figsize=(5, 6))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax_t.plot(x, y, 'b+')\nax_t.set_xlabel('Time [s]')\nax_t.set_ylabel('Amplitude')\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThen plot the periodogram for each of the normalize options, as well as with and\nwithout floating_mean=True:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "ax_p.plot(w, pgram_power, label='default')\nax_p.plot(w, pgram_power_f, label='floating_mean=True')\nax_p.set_xlabel('Angular frequency [rad/s]')\nax_p.set_ylabel('Power')\nax_p.legend(prop={'size': 7})\nax_n.plot(w, pgram_norm, label='default')\nax_n.plot(w, pgram_norm_f, label='floating_mean=True')\nax_n.set_xlabel('Angular frequency [rad/s]')\nax_n.set_ylabel('Normalized')\nax_n.legend(prop={'size': 7})\nax_a.plot(w, np.abs(pgram_amp), label='default')\nax_a.plot(w, np.abs(pgram_amp_f), label='floating_mean=True')\nax_a.set_xlabel('Angular frequency [rad/s]')\nax_a.set_ylabel('Amplitude')\nax_a.legend(prop={'size': 7})\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.tight_layout()\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-f98607a7ed6198cb.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "csd", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:csd" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Cross spectral density by Welch's method" } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "periodogram", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:periodogram" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Power spectral density using a periodogram" } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "welch", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:welch" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Power spectral density by Welch's method" } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": "npt.ArrayLike", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": "npt.ArrayLike", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "freqs", "annotation": "npt.ArrayLike", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "precenter", "annotation": "bool", "kind": "KEYWORD_ONLY", "default": "" }, { "__type": "SigParam", "__tag": 4030, "name": "normalize", "annotation": "bool | Literal['power', 'normalize', 'amplitude']", "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "weights", "annotation": "npt.NDArray | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "floating_mean", "annotation": "bool", "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": "npt.NDArray", "target_name": "lombscargle" }, "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`" ], "qa": "scipy.signal._spectral_py:lombscargle", "arbitrary": [], "local_refs": [ "floating_mean", "freqs", "normalize", "pgram", "precenter", "weights", "x", "y" ] }