{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is \"pad\", the function pads the data along the given axis in one of three ways: odd, even or constant. The odd and even extensions have the corresponding symmetry about the end point of the data. The constant extension extends the data with the values at the end points. On both the forward and backward passes, the initial condition of the filter is found by using " }, { "__type": "CrossRef", "__tag": 4002, "value": "lfilter_zi", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:lfilter_zi" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " and scaling it by the end point of the extended data." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is \"gust\", Gustafsson's method " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " is used. Initial conditions are chosen for the forward and backward passes so that the forward-backward filter gives the same result as the backward-forward filter." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The option to use Gustaffson's method was added in scipy version 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": "filtfilt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:filtfilt" }, "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": "y", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The filtered output with the same shape as " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Apply a digital filter forward and backward to a signal." } ] } ], "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": "b", "annotation": "(N,) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The numerator coefficient vector of the filter." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "a", "annotation": "(N,) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The denominator coefficient vector of the filter. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "a[0]" }, { "__type": "Text", "__tag": 4046, "value": " is not 1, then both " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " are normalized by " }, { "__type": "InlineCode", "__tag": 4051, "value": "a[0]" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The array of data to be filtered." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The axis of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " to which the filter is applied. Default is -1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "padtype", "annotation": "str or None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Must be 'odd', 'even', 'constant', or None. This determines the type of extension to use for the padded signal to which the filter is applied. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "padtype" }, { "__type": "Text", "__tag": 4046, "value": " is None, no padding is used. The default is 'odd'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "padlen", "annotation": "int or None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of elements by which to extend " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " at both ends of " }, { "__type": "ParamRef", "__tag": 4071, "name": "axis" }, { "__type": "Text", "__tag": 4046, "value": " before applying the filter. This value must be less than " }, { "__type": "InlineCode", "__tag": 4051, "value": "x.shape[axis] - 1" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "padlen=0" }, { "__type": "Text", "__tag": 4046, "value": " implies no padding. The default value is " }, { "__type": "InlineCode", "__tag": 4051, "value": "3 * max(len(a), len(b))" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determines the method for handling the edges of the signal, either \"pad\" or \"gust\". When " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is \"pad\", the signal is padded; the type of padding is determined by " }, { "__type": "ParamRef", "__tag": 4071, "name": "padtype" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "padlen" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "ParamRef", "__tag": 4071, "name": "irlen" }, { "__type": "Text", "__tag": 4046, "value": " is ignored. When " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is \"gust\", Gustafsson's method is used, and " }, { "__type": "ParamRef", "__tag": 4071, "name": "padtype" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "padlen" }, { "__type": "Text", "__tag": 4046, "value": " are ignored." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "irlen", "annotation": "int or None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is \"gust\", " }, { "__type": "ParamRef", "__tag": 4071, "name": "irlen" }, { "__type": "Text", "__tag": 4046, "value": " specifies the length of the impulse response of the filter. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "irlen" }, { "__type": "Text", "__tag": 4046, "value": " is None, no part of the impulse response is ignored. For a long signal, specifying " }, { "__type": "ParamRef", "__tag": 4071, "name": "irlen" }, { "__type": "Text", "__tag": 4046, "value": " can significantly improve the performance of the filter." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function applies a linear digital filter twice, once forward and once backwards. The combined filter has zero phase and a filter order twice that of the original." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function provides options for handling the edges of the signal." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function " }, { "__type": "CrossRef", "__tag": 4002, "value": "sosfiltfilt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:sosfiltfilt" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " (and filter design using " }, { "__type": "InlineCode", "__tag": 4051, "value": "output='sos'" }, { "__type": "Text", "__tag": 4046, "value": ") should be preferred over " }, { "__type": "CrossRef", "__tag": 4002, "value": "filtfilt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:filtfilt" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for most filtering tasks, as second-order sections have fewer numerical problems." } ] } ], "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/_signaltools.py", "item_line": 4708, "item_type": "function", "aliases": [ "scipy.signal.filtfilt" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "The examples will use several functions from `scipy.signal`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import signal\nimport matplotlib.pyplot as plt\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\nFirst we create a one second signal that is the sum of two pure sine\nwaves, with frequencies 5 Hz and 250 Hz, sampled at 2000 Hz.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "t = np.linspace(0, 1.0, 2001)\nxlow = np.sin(2 * np.pi * 5 * t)\nxhigh = np.sin(2 * np.pi * 250 * t)\nx = xlow + xhigh\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\nNow create a lowpass Butterworth filter with a cutoff of 0.125 times\nthe Nyquist frequency, or 125 Hz, and apply it to ``x`` with `filtfilt`.\nThe result should be approximately ``xlow``, with no phase shift.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b, a = signal.butter(8, 0.125)\ny = signal.filtfilt(b, a, x, padlen=150)\nnp.abs(y - xlow).max()\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\nWe get a fairly clean result for this artificial example because\nthe odd extension is exact, and with the moderately long padding,\nthe filter's transients have dissipated by the time the actual data\nis reached. In general, transient effects at the edges are\nunavoidable.\n\nThe following example demonstrates the option ``method=\"gust\"``.\n\nFirst, create a filter.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b, a = signal.ellip(4, 0.01, 120, 0.125) # Filter to be applied.\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\n`sig` is a random input signal to be filtered.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng()\nn = 60\nsig = rng.standard_normal(n)**3 + 3*rng.standard_normal(n).cumsum()\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\nApply `filtfilt` to `sig`, once using the Gustafsson method, and\nonce using padding, and plot the results for comparison.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fgust = signal.filtfilt(b, a, sig, method=\"gust\")\nfpad = signal.filtfilt(b, a, sig, padlen=50)\nplt.plot(sig, 'k-', label='input')\nplt.plot(fgust, 'b-', linewidth=4, label='gust')\nplt.plot(fpad, 'c-', linewidth=1.5, label='pad')\nplt.legend(loc='best')\nplt.show()\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\nThe `irlen` argument can be used to improve the performance\nof Gustafsson's method.\n\nEstimate the impulse response length of the filter.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "z, p, k = signal.tf2zpk(b, a)\neps = 1e-9\nr = np.max(np.abs(p))\napprox_impulse_len = int(np.ceil(np.log(eps) / np.log(r)))\napprox_impulse_len\n", "execution_status": "none" }, { "__type": "Text", "__tag": 4046, "value": "\nApply the filter to a longer signal, with and without the `irlen`\nargument. The difference between `y1` and `y2` is small. For long\nsignals, using `irlen` gives a significant performance improvement.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = rng.standard_normal(4000)\ny1 = signal.filtfilt(b, a, x, method='gust')\ny2 = signal.filtfilt(b, a, x, method='gust', irlen=approx_impulse_len)\nprint(np.max(np.abs(y1 - y2)))\n", "execution_status": "none" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "lfilter", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:lfilter" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "lfilter_zi", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:lfilter_zi" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "lfiltic", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:lfiltic" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "savgol_filter", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._savitzky_golay:savgol_filter" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "sosfilt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:sosfilt" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "sosfiltfilt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:sosfiltfilt" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__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": "axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "-1" }, { "__type": "SigParam", "__tag": 4030, "name": "padtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "odd" }, { "__type": "SigParam", "__tag": 4030, "name": "padlen", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "pad" }, { "__type": "SigParam", "__tag": 4030, "name": "irlen", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "filtfilt" }, "references": [ ".. [1] F. Gustaffson, \"Determining the initial states in forward-backward", " filtering\", Transactions on Signal Processing, Vol. 46, pp. 988-992,", " 1996." ], "qa": "scipy.signal._signaltools:filtfilt", "arbitrary": [], "local_refs": [ "a", "axis", "b", "irlen", "method", "padlen", "padtype", "x", "y" ] }