ref: 16e2bb090f9f805afefcd58e73f21b20c9be822e
parent: 7a7dea24a733bae2b8709fd17ae41f53c8b5a8e7
author: Paul Brossier <piem@piem.org>
date: Fri Oct 26 15:19:49 EDT 2018
[python] improve docstrings for window
--- a/python/ext/py-musicutils.h
+++ b/python/ext/py-musicutils.h
@@ -2,16 +2,95 @@
#define PY_AUBIO_MUSICUTILS_H
static char Py_aubio_window_doc[] = ""
-"window(string, integer) -> fvec\n"
+"window(window_type, size)\n"
"\n"
-"Create a window\n"
+"Create a window of length `size`. `window_type` should be one\n"
+"of the following:\n"
"\n"
-"Example\n"
+"- `default` (same as `hanningz`).\n"
+"- `ones`\n"
+"- `rectangle`\n"
+"- `hamming`\n"
+"- `hanning`\n"
+"- `hanningz` [1]_\n"
+"- `blackman`\n"
+"- `blackman_harris`\n"
+"- `gaussian`\n"
+"- `welch`\n"
+"- `parzen`\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"window_type : str\n"
+" Type of window.\n"
+"size : int\n"
+" Length of window.\n"
+"\n"
+"Returns\n"
"-------\n"
+"fvec\n"
+" Array of shape `(length,)` containing the new window.\n"
"\n"
-">>> window('hanningz', 1024)\n"+"See Also\n"
+"--------\n"
+"pvoc, fft\n"
+"\n"
+"Examples\n"
+"--------\n"
+"Compute a zero-phase Hann window on `1024` points:\n"
+"\n"
+">>> aubio.window('hanningz', 1024)\n""array([ 0.00000000e+00, 9.41753387e-06, 3.76403332e-05, ...,\n"
-" 8.46982002e-05, 3.76403332e-05, 9.41753387e-06], dtype=float32)";
+" 8.46982002e-05, 3.76403332e-05, 9.41753387e-06], dtype=float32)\n"
+"\n"
+"Plot different window types with `matplotlib <https://matplotlib.org/>`_:\n"
+"\n"
+">>> import matplotlib.pyplot as plt\n"
+">>> modes = ['default', 'ones', 'rectangle', 'hamming', 'hanning',\n"
+"... 'hanningz', 'blackman', 'blackman_harris', 'gaussian',\n"
+"... 'welch', 'parzen']; n = 2048\n"
+">>> for m in modes: plt.plot(aubio.window(m, n), label=m)\n"
+"...\n"
+">>> plt.legend(); plt.show()\n"
+"\n"
+"Note\n"
+"----\n"
+"The following examples contain the equivalent source code to compute\n"
+"each type of window with `NumPy <https://numpy.org>`_:\n"
+"\n"
+">>> n = 1024; x = np.arange(n, dtype=aubio.float_type)\n"
+">>> ones = np.ones(n).astype(aubio.float_type)\n"
+">>> rectangle = 0.5 * ones\n"
+">>> hanning = 0.5 - 0.5 * np.cos(2 * np.pi * x / n)\n"
+">>> hanningz = 0.5 * (1 - np.cos(2 * np.pi * x / n))\n"
+">>> hamming = 0.54 - 0.46 * np.cos(2.*np.pi * x / (n - 1))\n"
+">>> blackman = 0.42 \\\n"
+"... - 0.50 * np.cos(2 * np.pi * x / (n - 1)) \\\n"
+"... + 0.08 * np.cos(4 * np.pi * x / (n - 1))\n"
+">>> blackman_harris = 0.35875 \\\n"
+"... - 0.48829 * np.cos(2 * np.pi * x / (n - 1)) \\\n"
+"... + 0.14128 * np.cos(4 * np.pi * x / (n - 1)) \\\n"
+"... + 0.01168 * np.cos(6 * np.pi * x / (n - 1))\n"
+">>> gaussian = np.exp( - 0.5 * ((x - 0.5 * (n - 1)) \\\n"
+"... / (0.25 * (n - 1)) )**2 )\n"
+">>> welch = 1 - ((2 * x - n) / (n + 1))**2\n"
+">>> parzen = 1 - np.abs((2 * x - n) / (n + 1))\n"
+">>> default = hanningz\n"
+"References\n"
+"----------\n"
+#if 0
+"`Window function <https://en.wikipedia.org/wiki/Window_function>`_ on\n"
+"Wikipedia.\n"
+"\n"
+#endif
+".. [1] Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional\n"
+" (?) implementations of a phase vocoder: the tricks of the trade.\n"
+" In *Proceedings of the International Conference on Digital Audio\n"
+" Effects* (DAFx-00), pages 37–44, University of Verona, Italy, 2000.\n"
+" (`online version <"
+"https://www.cs.princeton.edu/courses/archive/spr09/cos325/Bernardini.pdf"
+">`_).\n"
+"";
PyObject * Py_aubio_window(PyObject *self, PyObject *args);