{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The filter function is implemented as a series of second-order filters with direct-form II transposed structure. It is designed to minimize numerical precision errors for high-order filters." } ] }, { "__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": "sosfilt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:sosfilt" }, "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 ⚠️ computes graph 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 output of the digital filter." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "zf", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "zi" }, { "__type": "Text", "__tag": 4046, "value": " is None, this is not returned, otherwise, " }, { "__type": "CrossRef", "__tag": 4002, "value": "zf", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "zf" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " holds the final filter delay values." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Filter data along one dimension using cascaded second-order sections." } ] } ], "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": "sos", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array of second-order filter coefficients, must have shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(n_sections, 6)" }, { "__type": "Text", "__tag": 4046, "value": ". Each row corresponds to a second-order section, with the first three columns providing the numerator coefficients and the last three providing the denominator coefficients." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An N-dimensional input array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axis", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The axis of the input data array along which to apply the linear filter. The filter is applied to each subarray along this axis. Default is -1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "zi", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Initial conditions for the cascaded filter delays. It is a (at least 2D) vector of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(n_sections, ..., 2, ...)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "..., 2, ..." }, { "__type": "Text", "__tag": 4046, "value": " denotes the shape of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", but with " }, { "__type": "InlineCode", "__tag": 4051, "value": "x.shape[axis]" }, { "__type": "Text", "__tag": 4046, "value": " replaced by 2. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "zi" }, { "__type": "Text", "__tag": 4046, "value": " is None or is not given then initial rest (i.e. all zeros) is assumed. Note that these initial conditions are " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "not" } ] }, { "__type": "Text", "__tag": 4046, "value": " the same as the initial conditions given by " }, { "__type": "CrossRef", "__tag": 4002, "value": "lfiltic", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:lfiltic" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__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": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Filter a data sequence, " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", using a digital IIR filter defined by " }, { "__type": "ParamRef", "__tag": 4071, "name": "sos" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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": 4957, "item_type": "function", "aliases": [ "scipy.signal.sosfilt" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Plot a 13th-order filter's impulse response using both `lfilter` and\n`sosfilt`, showing the instability that results from trying to do a\n13th-order filter in a single stage (the numerical error pushes some poles\noutside of the unit circle):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nfrom scipy import signal\nb, a = signal.ellip(13, 0.009, 80, 0.05, output='ba')\nsos = signal.ellip(13, 0.009, 80, 0.05, output='sos')\nx = signal.unit_impulse(700)\ny_tf = signal.lfilter(b, a, x)\ny_sos = signal.sosfilt(sos, x)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(y_tf, 'r', label='TF')\nplt.plot(y_sos, 'k', label='SOS')\nplt.legend(loc='best')\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-204dacb6bc2622b6.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "freqz_sos", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._filter_design:freqz_sos" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "sos2zpk", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._filter_design:sos2zpk" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "sosfilt_zi", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:sosfilt_zi" }, "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" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "zpk2sos", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._filter_design:zpk2sos" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "sos", "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": "zi", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "sosfilt" }, "references": null, "qa": "scipy.signal._signaltools:sosfilt", "arbitrary": [], "local_refs": [ "axis", "sos", "x", "y", "zf", "zi" ] }