{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There are four possible options for the parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": ", which have a (long) standard form and some allowed abbreviations. The formulas for the instantaneous frequency " }, { "__type": "InlineMath", "__tag": 4057, "value": "f(t)" }, { "__type": "Text", "__tag": 4046, "value": " of the generated signal are as follows:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "('linear', 'lin', 'li')" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Math", "__tag": 4058, "value": "f(t) = f_0 + \\beta\\, t \\quad\\text{with}\\quad\n \\beta = \\frac{f_1 - f_0}{t_1}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Frequency " }, { "__type": "InlineMath", "__tag": 4057, "value": "f(t)" }, { "__type": "Text", "__tag": 4046, "value": " varies linearly over time with a constant rate " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\beta" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "('quadratic', 'quad', 'q')" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Math", "__tag": 4058, "value": "f(t) =\n \\begin{cases}\n f_0 + \\beta\\, t^2 & \\text{if vertex_zero is True,}\\\\\n f_1 + \\beta\\, (t_1 - t)^2 & \\text{otherwise,}\n \\end{cases}\n \\quad\\text{with}\\quad\n \\beta = \\frac{f_1 - f_0}{t_1^2}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The graph of the frequency f(t) is a parabola through " }, { "__type": "InlineMath", "__tag": 4057, "value": "(0, f_0)" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "(t_1, f_1)" }, { "__type": "Text", "__tag": 4046, "value": ". By default, the vertex of the parabola is at " }, { "__type": "InlineMath", "__tag": 4057, "value": "(0, f_0)" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "ParamRef", "__tag": 4071, "name": "vertex_zero" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": ", then the vertex is at " }, { "__type": "InlineMath", "__tag": 4057, "value": "(t_1, f_1)" }, { "__type": "Text", "__tag": 4046, "value": ". To use a more general quadratic function, or an arbitrary polynomial, use the function " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.signal.sweep_poly", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.signal._waveforms:sweep_poly" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "('logarithmic', 'log', 'lo')" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Math", "__tag": 4058, "value": "f(t) = f_0 \\left(\\frac{f_1}{f_0}\\right)^{t/t_1}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineMath", "__tag": 4057, "value": "f_0" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "f_1" }, { "__type": "Text", "__tag": 4046, "value": " must be nonzero and have the same sign. This signal is also known as a geometric or exponential chirp." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "('hyperbolic', 'hyp')" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Math", "__tag": 4058, "value": "f(t) = \\frac{\\alpha}{\\beta\\, t + \\gamma} \\quad\\text{with}\\quad\n \\alpha = f_0 f_1 t_1, \\ \\beta = f_0 - f_1, \\ \\gamma = f_1 t_1" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineMath", "__tag": 4057, "value": "f_0" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineMath", "__tag": 4057, "value": "f_1" }, { "__type": "Text", "__tag": 4046, "value": " must be nonzero." } ] } ] } ] }, { "__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": "chirp", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._waveforms:chirp" }, "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": "A numpy array containing the signal evaluated at " }, { "__type": "ParamRef", "__tag": 4071, "name": "t" }, { "__type": "Text", "__tag": 4046, "value": " with the requested time-varying frequency. More precisely, the function returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "exp(1j*phase + 1j*(pi/180)*phi) if complex else cos(phase + (pi/180)*phi)" }, { "__type": "Text", "__tag": 4046, "value": " where " }, { "__type": "InlineRole", "__tag": 4003, "value": "phase", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the integral (from 0 to " }, { "__type": "ParamRef", "__tag": 4071, "name": "t" }, { "__type": "Text", "__tag": 4046, "value": ") of " }, { "__type": "InlineCode", "__tag": 4051, "value": "2*pi*f(t)" }, { "__type": "Text", "__tag": 4046, "value": ". The instantaneous frequency " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(t)" }, { "__type": "Text", "__tag": 4046, "value": " is defined below." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Frequency-swept cosine generator." } ] } ], "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": "t", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Times at which to evaluate the waveform." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "f0", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Frequency (e.g. Hz) at time t=0." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "t1", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Time at which " }, { "__type": "ParamRef", "__tag": 4071, "name": "f1" }, { "__type": "Text", "__tag": 4046, "value": " is specified." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "f1", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Frequency (e.g. Hz) of the waveform at time " }, { "__type": "ParamRef", "__tag": 4071, "name": "t1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "{'linear', 'quadratic', 'logarithmic', 'hyperbolic'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Kind of frequency sweep. If not given, " }, { "__type": "CrossRef", "__tag": 4002, "value": "linear", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.interpolate._rbfinterp_xp:linear" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is assumed. See Notes below for more details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "phi", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Phase offset, in degrees. Default is 0." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "vertex_zero", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This parameter is only used when " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": " is 'quadratic'. It determines whether the vertex of the parabola that is the graph of the frequency is at t=0 or t=t1." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "complex", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This parameter creates a complex-valued analytic signal instead of a real-valued signal. It allows the use of complex baseband (in communications domain). Default is False." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.15.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the following, 'Hz' should be interpreted as 'cycles per unit'; there is no requirement here that the unit is one second. The important distinction is that the units of rotation are cycles, not radians. Likewise, " }, { "__type": "ParamRef", "__tag": 4071, "name": "t" }, { "__type": "Text", "__tag": 4046, "value": " could be a measurement of space instead of time." } ] } ], "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/_waveforms.py", "item_line": 251, "item_type": "function", "aliases": [ "scipy.signal.chirp" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "For the first example, a linear chirp ranging from 6 Hz to 1 Hz over 10 seconds is\nplotted:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom matplotlib.pyplot import tight_layout\nfrom scipy.signal import chirp, square, ShortTimeFFT\nfrom scipy.signal.windows import gaussian\nimport matplotlib.pyplot as plt\nN, T = 1000, 0.01 # number of samples and sampling interval for 10 s signal\nt = np.arange(N) * T # timestamps\nx_lin = chirp(t, f0=6, f1=1, t1=10, method='linear')\nfg0, ax0 = plt.subplots()\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax0.set_title(r\"Linear Chirp from $f(0)=6\\,$Hz to $f(10)=1\\,$Hz\")\nax0.set(xlabel=\"Time $t$ in Seconds\", ylabel=r\"Amplitude $x_\\text{lin}(t)$\")\nax0.plot(t, x_lin)\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-123c9c797275608a.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThe following four plots each show the short-time Fourier transform of a chirp\nranging from 45 Hz to 5 Hz with different values for the parameter `method`\n(and `vertex_zero`):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x_qu0 = chirp(t, f0=45, f1=5, t1=N*T, method='quadratic', vertex_zero=True)\nx_qu1 = chirp(t, f0=45, f1=5, t1=N*T, method='quadratic', vertex_zero=False)\nx_log = chirp(t, f0=45, f1=5, t1=N*T, method='logarithmic')\nx_hyp = chirp(t, f0=45, f1=5, t1=N*T, method='hyperbolic')\nwin = gaussian(50, std=12, sym=True)\nSFT = ShortTimeFFT(win, hop=2, fs=1/T, mfft=800, scale_to='magnitude')\nts = (\"'quadratic', vertex_zero=True\", \"'quadratic', vertex_zero=False\",\n \"'logarithmic'\", \"'hyperbolic'\")\nfg1, ax1s = plt.subplots(2, 2, sharex='all', sharey='all',\n figsize=(6, 5), layout=\"constrained\")\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "for x_, ax_, t_ in zip([x_qu0, x_qu1, x_log, x_hyp], ax1s.ravel(), ts):\n aSx = abs(SFT.stft(x_))\n im_ = ax_.imshow(aSx, origin='lower', aspect='auto', extent=SFT.extent(N),\n cmap='plasma')\n ax_.set_title(t_)\n if t_ == \"'hyperbolic'\":\n fg1.colorbar(im_, ax=ax1s, label='Magnitude $|S_z(t,f)|$')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "_ = fg1.supxlabel(\"Time $t$ in Seconds\") # `_ =` is needed to pass doctests\n_ = fg1.supylabel(\"Frequency $f$ in Hertz\")\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-aceefb79a8a95c50.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nFinally, the short-time Fourier transform of a complex-valued linear chirp\nranging from -30 Hz to 30 Hz is depicted:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "z_lin = chirp(t, f0=-30, f1=30, t1=N*T, method=\"linear\", complex=True)\nSFT.fft_mode = 'centered' # needed to work with complex signals\naSz = abs(SFT.stft(z_lin))\nfg2, ax2 = plt.subplots()\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax2.set_title(r\"Linear Chirp from $-30\\,$Hz to $30\\,$Hz\")\nax2.set(xlabel=\"Time $t$ in Seconds\", ylabel=\"Frequency $f$ in Hertz\")\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "im2 = ax2.imshow(aSz, origin='lower', aspect='auto',\n extent=SFT.extent(N), cmap='viridis')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "fg2.colorbar(im2, label='Magnitude $|S_z(t,f)|$')\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-6aad1ba849c8469f.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nNote that using negative frequencies makes only sense with complex-valued signals.\nFurthermore, the magnitude of the complex exponential function is one whereas the\nmagnitude of the real-valued cosine function is only 1/2." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "sweep_poly", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._waveforms:sweep_poly" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "t", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "f0", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "t1", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "f1", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "linear" }, { "__type": "SigParam", "__tag": 4030, "name": "phi", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "vertex_zero", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "complex", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "chirp" }, "references": null, "qa": "scipy.signal._waveforms:chirp", "arbitrary": [], "local_refs": [ "complex", "f0", "f1", "method", "phi", "t", "t1", "vertex_zero", "y" ] }