{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An appropriate amount of overlap will depend on the choice of window and on your requirements. For the default Hann window an overlap of 50% is a reasonable trade-off between accurately estimating the signal power, while not over counting any of the data. Narrower windows may require a larger overlap." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.16.0" } ] } ] }, { "__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": "coherence", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:coherence" }, "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": [], "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": "f", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array of sample frequencies." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "Cxy", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Magnitude squared coherence of x and y." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Estimate the magnitude squared coherence estimate, Cxy, of discrete-time signals X and Y using Welch's method." } ] } ], "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": "Time series of measurement values" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Time series of measurement values" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "fs", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sampling frequency of the " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": " time series. Defaults to 1.0." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "window", "annotation": "str or tuple or array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Desired window to use. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "window" }, { "__type": "Text", "__tag": 4046, "value": " is a string or tuple, it is passed to " }, { "__type": "CrossRef", "__tag": 4002, "value": "get_window", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal.windows._windows:get_window" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to generate the window values, which are DFT-even by default. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "get_window", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal.windows._windows:get_window" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for a list of windows and required parameters. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "window" }, { "__type": "Text", "__tag": 4046, "value": " is array_like it will be used directly as the window and its length must be nperseg. Defaults to a periodic Hann window." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nperseg", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "noverlap: int, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of points to overlap between segments. If " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "noverlap = nperseg // 2" }, { "__type": "Text", "__tag": 4046, "value": ". Defaults to " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nfft", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Length of the FFT used, if a zero padded FFT is desired. If " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", the FFT length is " }, { "__type": "ParamRef", "__tag": 4071, "name": "nperseg" }, { "__type": "Text", "__tag": 4046, "value": ". Defaults to " }, { "__type": "InlineRole", "__tag": 4003, "value": "None", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "detrend", "annotation": "str or function or `False`, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specifies how to detrend each segment. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "detrend" }, { "__type": "Text", "__tag": 4046, "value": " is a string, it is passed as the " }, { "__type": "InlineRole", "__tag": 4003, "value": "type", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " argument to the " }, { "__type": "ParamRef", "__tag": 4071, "name": "detrend" }, { "__type": "Text", "__tag": 4046, "value": " function. If it is a function, it takes a segment and returns a detrended segment. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "detrend" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineRole", "__tag": 4003, "value": "False", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", no detrending is done. Defaults to 'constant'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Axis along which the coherence is computed for both inputs; the default is over the last axis (i.e. " }, { "__type": "InlineCode", "__tag": 4051, "value": "axis=-1" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "Cxy = abs(Pxy)**2/(Pxx*Pyy)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineRole", "__tag": 4003, "value": "Pxx", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "Pyy", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " are power spectral density estimates of X and Y, and " }, { "__type": "InlineRole", "__tag": 4003, "value": "Pxy", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the cross spectral density estimate of X and Y." } ] } ], "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": 1924, "item_type": "function", "aliases": [ "scipy.signal.coherence" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import signal\nimport matplotlib.pyplot as plt\nrng = np.random.default_rng()\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nGenerate two test signals with some common features.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fs = 10e3\nN = 1e5\namp = 20\nfreq = 1234.0\nnoise_power = 0.001 * fs / 2\ntime = np.arange(N) / fs\nb, a = signal.butter(2, 0.25, 'low')\nx = rng.normal(scale=np.sqrt(noise_power), size=time.shape)\ny = signal.lfilter(b, a, x)\nx += amp*np.sin(2*np.pi*freq*time)\ny += rng.normal(scale=0.1*np.sqrt(noise_power), size=time.shape)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCompute and plot the coherence.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "f, Cxy = signal.coherence(x, y, fs, nperseg=1024)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.semilogy(f, Cxy)\nplt.xlabel('frequency [Hz]')\nplt.ylabel('Coherence')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-178f16e23af7feef.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": "lombscargle", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._spectral_py:lombscargle" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lomb-Scargle periodogram for unevenly sampled data" } ] } ], "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": "Simple, optionally modified 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": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "fs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1.0" }, { "__type": "SigParam", "__tag": 4030, "name": "window", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "hann_periodic" }, { "__type": "SigParam", "__tag": 4030, "name": "nperseg", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "noverlap", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "nfft", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "detrend", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "constant" }, { "__type": "SigParam", "__tag": 4030, "name": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "-1" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "coherence" }, "references": [ ".. [1] P. Welch, \"The use of the fast Fourier transform for the", " estimation of power spectra: A method based on time averaging", " over short, modified periodograms\", IEEE Trans. Audio", " Electroacoust. vol. 15, pp. 70-73, 1967.", ".. [2] Stoica, Petre, and Randolph Moses, \"Spectral Analysis of", " Signals\" Prentice Hall, 2005" ], "qa": "scipy.signal._spectral_py:coherence", "arbitrary": [], "local_refs": [ "Cxy", "axis", "detrend", "f", "fs", "nfft", "noverlap: int", "nperseg", "optional", "window", "x", "y" ] }