{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The \"single-orthant\" transform, as defined in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", is calculated by performing the following steps:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the two-dimensional FFT of the input, i.e.," } ] }, { "__type": "Math", "__tag": 4058, "value": "X[p,q] = \\sum_{k,l=0}^{N_0,N_1} x[k,l]\\,\n e^{-2j\\pi k p/N_0}\\, e^{-2j\\pi l q/N_1}" } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Zero negative frequency bins and double their positive counterparts, i.e.," } ] }, { "__type": "Math", "__tag": 4058, "value": "X_a[p,q] = \\big(1 + s_{N_0}(p)\\big) \\big(1 + s_{N_1}(q)\\big) X[p,q]" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with " }, { "__type": "InlineMath", "__tag": 4057, "value": "s_N(.)" }, { "__type": "Text", "__tag": 4046, "value": " being a modified sign function defined as" } ] }, { "__type": "Math", "__tag": 4058, "value": "s_N(p) := \\begin{cases}\n -1 & \\text{ for } p < 0\\ ,\\\\\n \\phantom{-}0 & \\text{ for } p = 0\\ ,\\\\\n +1 & \\text{ for } 1 \\leq p < (N+1) // 2\\ ,\\\\\n \\phantom{-}0 & \\text{ elsewhere.}\n \\end{cases}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The limitation of the \"" }, { "__type": "InlineMath", "__tag": 4057, "value": "+1" }, { "__type": "Text", "__tag": 4046, "value": "\" case to the range of " }, { "__type": "InlineCode", "__tag": 4051, "value": "[1:(N+1)//2]" }, { "__type": "Text", "__tag": 4046, "value": " accounts for the unpaired Nyquist frequency bin at " }, { "__type": "InlineMath", "__tag": 4057, "value": "N/2" }, { "__type": "Text", "__tag": 4046, "value": " for even " }, { "__type": "InlineMath", "__tag": 4057, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": ". Note that " }, { "__type": "InlineMath", "__tag": 4057, "value": "X_a[p] = \\big(1 + s_N(p)\\big) X[p]" }, { "__type": "Text", "__tag": 4046, "value": " is the one-dimensional Hilbert function (as in " }, { "__type": "CrossRef", "__tag": 4002, "value": "hilbert", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.signal._signaltools:hilbert" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ") in Fourier space." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Produce the analytic signal by performing the inverse FFT, i.e.," } ] }, { "__type": "Math", "__tag": 4058, "value": "x_a[k, l] = \\frac{1}{N_0 N_1}\n \\sum_{p,q=0}^{N_0,N_1} X_a[p,q]\\, e^{2j\\pi k p/N_0}\\, e^{2j\\pi l q/N_1}" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The \"single-orthant\" transform is not the only possible definition of an analytic signal in multiple dimensions (as noted in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "). Consult " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " for a description of properties that this 2-D transform does and does not share with the 1-D transform. The second example below shows one of the downsides of this approach." } ] }, { "__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": "hilbert2", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:hilbert2" }, "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": "xa", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Analytic signal of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " taken along given axes." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the '2-D' analytic signal of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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": "Input signal. Must be at least two-dimensional." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "N", "annotation": "int or tuple of two ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of output samples. " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " is initially cropped or zero-padded to length " }, { "__type": "ParamRef", "__tag": 4071, "name": "N" }, { "__type": "Text", "__tag": 4046, "value": " along " }, { "__type": "ParamRef", "__tag": 4071, "name": "axes" }, { "__type": "Text", "__tag": 4046, "value": ". Default: " }, { "__type": "InlineCode", "__tag": 4051, "value": "x.shape[i] for i in axes" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "axes", "annotation": "tuple of two ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Axes along which to do the transformation. Default: (-2, -1)." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 1.17" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Added " }, { "__type": "ParamRef", "__tag": 4071, "name": "axes" }, { "__type": "Text", "__tag": 4046, "value": " parameter" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The 2-D analytic signal is calculated as a so-called \"single-orthant\" transform. This is achieved by applying one-dimensional Hilbert functions (as in " }, { "__type": "CrossRef", "__tag": 4002, "value": "hilbert", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.signal._signaltools:hilbert" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ") to the first and to the second array axis in Fourier space." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For NumPy arrays, " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.fft.set_workers", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.fft._pocketfft.helper:set_workers" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " can be used to change the number of workers used for the FFTs." } ] } ], "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": 2533, "item_type": "function", "aliases": [ "scipy.signal.hilbert2" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following example calculates the two-dimensional analytic signal from a single\nimpulse with an added constant offset. The impulse produces an FFT where each bin\nhas a value of one and the constant offset component produces only a non-zero\ncomponent at the ``(0,0)`` bin.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.fft import fft2, fftshift, ifftshift\nfrom scipy.signal import hilbert2\nx = np.ones((5, 5)) / 5\nx[0, 0] += 1\nX = fftshift(fft2(x)) # Zero frequency bin is at center\nprint(X)\nx_a = hilbert2(x)\nX_a = fftshift(fft2(x_a))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "print(np.round(X_a, 3))\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe FFT of the result illustrates that the values of the lower right quadrant (or\northant) with purely positive frequency bins have been quadrupled. The values at its\nborders, where only one frequency component is zero, are doubled. The zero frequency\nbin ``(0, 0)`` has not been altered. All other quadrants have been set to zero.\n\nThis second example illustrates a problem with the \"single-orthant\" convention. A\npurely real signal can produce an analytic signal which is completely zero:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.fft import fft2, fftshift, ifft2, ifftshift\nfrom scipy.signal import hilbert2\nZ = np.array([[0, 0, 0, 0, 0],\n [0, 0, 0, 1, 0],\n [0, 0, 0, 0, 0],\n [0, 1, 0, 0, 0],\n [0, 0, 0, 0, 0]]) * 25\nz = ifft2(ifftshift(Z))\nnp.allclose(z.imag, 0) # z is a real signal\nnp.sum(z.real**2) # z.real is non-zero\nz_a = hilbert2(z.real)\nnp.allclose(z_a, 0) # analytic signal is zero\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "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": "N", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "axes", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "(-2, -1)" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "hilbert2" }, "references": [ ".. [1] Wikipedia, \"Analytic signal\",", " https://en.wikipedia.org/wiki/Analytic_signal", ".. [2] Hahn, Stefan L. \"Multidimensional complex signals with", " single-orthant spectra.\" Proceedings of the IEEE 80.8", " (1992): 1287-1300.", " `PDF `__", ".. [3] Bülow, Thomas, and Gerald Sommer. \"A novel approach to the 2D analytic", " signal.\" In International Conference on Computer Analysis of Images and", " Patterns, pp. 25-32. Berlin, Heidelberg: Springer Berlin Heidelberg, 1999.", " `PDF `__" ], "qa": "scipy.signal._signaltools:hilbert2", "arbitrary": [], "local_refs": [ "N", "axes", "x", "xa" ] }