{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [], "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": "strength", "annotation": "float or 1D array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The strength of the synchronization. 1.0 is perfect synchronization and 0.0 is no synchronization. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "period" }, { "__type": "Text", "__tag": 4046, "value": " is an array, this is also an array with each element containing the vector strength at the corresponding period." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "phase", "annotation": "float or array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The phase that the events are most strongly synchronized to in radians. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "period" }, { "__type": "Text", "__tag": 4046, "value": " is an array, this is also an array with each element containing the phase for the corresponding period." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determine the vector strength of the events corresponding to the given period." } ] } ], "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": "events", "annotation": "1D array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An array of time points containing the timing of the events." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "period", "annotation": "float or array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The period of the signal that the events should synchronize to. The period is in the same units as " }, { "__type": "ParamRef", "__tag": 4071, "name": "events" }, { "__type": "Text", "__tag": 4046, "value": ". It can also be an array of periods, in which case the outputs are arrays of the same length." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The vector strength is a measure of phase synchrony, how well the timing of the events is synchronized to a single period of a periodic signal." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If multiple periods are used, calculate the vector strength of each. This is called the \"resonating vector strength\"." } ] } ], "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": "build-install/usr/lib/python3.14/site-packages/scipy/signal/_signaltools.py", "item_line": 4225, "item_type": "function", "aliases": [ "scipy.signal.vectorstrength" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "In this example, five events occur exactly 1 second apart, starting\nat 0.25 s. The vector strength is 1 for ``period=1`` because all\nevents fall at the same phase of every cycle, and the returned phase\nis π/2, a quarter of the way through the period.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.signal import vectorstrength\nevents = np.array([0.25, 1.25, 2.25, 3.25, 4.25])\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "vectorstrength(events, period=1.0)\n", "execution_status": "failure", "out": "(np.float64(1.0), np.float64(1.5707963267948968))\n" }, { "__type": "Text", "__tag": 4046, "value": "\n``period`` can also be an array of candidate periods. With the same\nevents as above, the strength stays at 1 at the true period of 1 s\nand at the sub-multiple period 0.5 s (a form of aliasing), and drops\nto 0 at ``period=5`` where the events span a single period at\nevenly-spaced phases:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "periods = [1, 5, 0.5]\nstrengths, phases = vectorstrength(events, periods)\nfor p_, s_, ph_ in zip(periods, strengths, phases):\n print(f\"period = {p_:.1f}: strength = {s_:.2f}, \"\n f\"phase = {np.rad2deg(ph_):.1f} deg\")\n", "execution_status": "success", "out": "period = 1.0: strength = 1.00, phase = 90.0 deg\nperiod = 5.0: strength = 0.00, phase = 153.4 deg\nperiod = 0.5: strength = 1.00, phase = -180.0 deg\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThe following example depicts the vector strength and its phase for\n100 samples with a constant period of 10 s. The maximum strength of 1\noccurs at 10 s with phase 0 rad. Due to the finite number of samples,\nthe strength does not drop to zero away from 10 s but exhibits\nsecondary maxima similar to those of an FFT sidelobe pattern. The\nphase decreases roughly linearly with jumps of π rad at each\nsidelobe minimum, consistent with an underlying sinc-like function.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import matplotlib.pyplot as plt\nimport numpy as np\nfrom scipy.signal import vectorstrength\nN, T = 100, 10 # samples and sampling interval in seconds\nevents = np.arange(N) * T\nperiods = np.linspace(9.5, 10.5, 101)\nstrength, phase = vectorstrength(events, periods)\nfig, (ax_strength, ax_phase) = plt.subplots(\n 2, 1, sharex=True, tight_layout=True)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "ax_strength.set_title(\n f\"Vector strength of {N} samples at {T} s spacing\")\nax_strength.set(ylabel=\"Strength\", xlim=(periods[0], periods[-1]))\n", "execution_status": "failure", "out": "[Text(0, 0.5, 'Strength'), (9.5, 10.5)]\n" }, { "__type": "Code", "__tag": 4050, "value": "ax_strength.grid(True)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "ax_phase.set(xlabel=\"Period (s)\", ylabel=\"Phase (rad)\")\n", "execution_status": "failure", "out": "[Text(0.5, 0, 'Period (s)'), Text(0, 0.5, 'Phase (rad)')]\n" }, { "__type": "Code", "__tag": 4050, "value": "ax_phase.grid(True)\n", "execution_status": "success", "out": "" }, { "__type": "Code", "__tag": 4050, "value": "ax_strength.plot(periods, strength, 'C0.-')\nax_phase.plot(periods, phase, 'C1.-')\n", "execution_status": "failure", "out": "[]\n" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success", "out": "" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "2.0.0.dev0+git20260907.41eeb59", "kind": "assets", "path": "fig-3638d37cc4f2ac67.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "events", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "period", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "vectorstrength" }, "references": [ ".. [1] Van Hemmen, JL, Longtin, A, and Vollmayr, AN. \"Testing resonating vector", " strength: Auditory system, electric fish, and noise.\"", " Chaos 21, 047508 (2011), :doi:`10.1063/1.3670512`.", ".. [2] Van Hemmen, JL. \"Vector strength after Goldberg, Brown, and von Mises:", " biological and mathematical perspectives.\"", " Biol Cybern. 2013 Aug; 107(4): 385-96. :doi:`10.1007/s00422-013-0561-7`.", ".. [3] Van Hemmen, JL and Vollmayr, AN. \"Resonating vector strength: what happens", " when we vary the 'probing' frequency while keeping the spike times fixed.\"", " Biol Cybern. 2013 Aug; 107(4): 491-94. :doi:`10.1007/s00422-013-0560-8`." ], "qa": "scipy.signal._signaltools:vectorstrength", "arbitrary": [], "local_refs": [ "events", "period", "phase", "strength" ] }