From a3ad64535100de23458699056f4f4dd40d1db6c6 Mon Sep 17 00:00:00 2001 From: Takeshi Ikuma Date: Mon, 1 Mar 2021 18:53:06 -0600 Subject: [PATCH] docstring cleanup --- src/parselmouth/LPC_docstrings.h | 63 ++++++++++--------- .../LineSpectralFrequencies_docstrings.h | 2 +- 2 files changed, 34 insertions(+), 31 deletions(-) diff --git a/src/parselmouth/LPC_docstrings.h b/src/parselmouth/LPC_docstrings.h index 3802c933..635a80bf 100644 --- a/src/parselmouth/LPC_docstrings.h +++ b/src/parselmouth/LPC_docstrings.h @@ -11,7 +11,7 @@ a frame of acoustic data samples. Note that the $a_0=1$ coefficient is omitted in a. -This class is instantiated in :obj:`~parselmouth.LPC` object and not +This class is instantiated in :obj:`~parselmouth.LPC` object and not intended to be instantiated by user. See also @@ -27,17 +27,18 @@ constexpr auto FRAME_A = R"(numpy.ndarray of float : Linear predictive model coe constexpr auto CLASS_DOCSTRING = R"(Praat LPC Class. -A sequence object contains the outcomes of linear predictive coding (LPC) +A sequence object contains the outcomes of linear predictive coding (LPC) analysis outcomes. The analysis is performed repeatedly with a sliding -window, which offsets :attr:`LPC.dt` seconds between +window, which offsets :attr:`LPC.dt` seconds between frames. The i-th item of this object is a :func:`LPC.Frame` object representing the i-th frame. -In the LPC analysis one tries to predict xn on the basis of the p previous -samples, x′n = ∑ ak xn-k then {a1, a2, ..., ap} can be chosen to minimize -the prediction power Qp where Qp = E[ |xn - x′n|2 ]. +In the LPC analysis one tries to predict xn on the basis of the p previous +samples, :math:`x_n^' = \sum_{k=1}^p {a_k x_{n-k}}` then +:math:`{a_1, a_2, \ldots, a_p}` can be chosen to minimize the prediction +power :math:`Q_p` where :math:`Q_p = E[ |x_n - x_n^'|^2 ]`. This class is not intended to be instantiated by user, instead from a :obj:`~parselmouth.Sound` object using one of its to_lpc_xxx() @@ -58,14 +59,14 @@ constexpr auto MAX_N_COEFFICIENTS_DOCSTRING = R"(Largest number of coefficients constexpr auto TO_LINE_SPECTRAL_FREQUENCIES=R"(Convert to line spectra. -Returns :obj:`parselmouth.LineSpectralFrequencies` object with the +Returns :obj:`parselmouth.LineSpectralFrequencies` object with the line frequencies found in the LPC models. Parameter ---------- -grid_size : float, default=0.0 +grid_size : float, default 0.0 TBD - + See also -------- :obj:`parselmouth.LineSpectralFrequencies` @@ -77,7 +78,7 @@ constexpr auto TO_SPECTRUM_SLICE_DOCSTRING=R"(Convert to spectrogram. Returns :obj:`parselmouth.Spectrum` object with the spectral representation of the LPC model found at specified time t. -The Spectrum at t will be calculated from the nearest +The Spectrum at t will be calculated from the nearest :obj:`~parselmouth.LPC.Frame`. See :praat:`LPC: To Spectrum (slice)...` for dedailed algorithm description. @@ -85,24 +86,25 @@ Parameters ---------- time : float Time at which the spectrum should be calculated. - -minimum_frequency_resolution : float, default=20.0 + +minimum_frequency_resolution : float, default 20.0 Maximum distance separation of successive frequencies in the Spectrum, in Hz -bandwidth_reduction : float, default=0.0 - Reduces the bandwidth of each zero by this factor (<=0.0 for no - reduction). Formants with small bandwidths show up very well as darker - regions in the spectrogram because the poles lie close to the contour - along which a spectrum is computed (the unit circle in the z-plane). +bandwidth_reduction : float, default 0.0 + Reduces the bandwidth of each zero by this factor (<=0.0 for no + reduction). Formants with small bandwidths show up very well as darker + regions in the spectrogram because the poles lie close to the contour + along which a spectrum is computed (the unit circle in the z-plane). Peak enhancement can be realized by computing a spectrum in the z-plane along a contour of radius: - r = exp (– pi x bandwidthReduction / samplingFrequency). + :math:`r = exp \left(– \pi \times + \frac{bandwidthReduction}{samplingFrequency}\right)`. -deemphasis_frequency : float, default=50.0 +deemphasis_frequency : float, default 50.0 Performs de-emphasis when value is in this interval, specified in Hz. - (0, Nyquist frequency) + (0, Nyquist frequency) See also -------- @@ -114,30 +116,31 @@ constexpr auto TO_SPECTROGRAM_DOCSTRING=R"(Convert to spectrogram. Returns :obj:`parselmouth.Spectrogram` object with the spectral representation of the LPC models. -For each LPC_Frame the corresponding Spectrum will be calculated according +For each LPC_Frame the corresponding Spectrum will be calculated according to the algorithm explained in :func:`parselmouth.LPC.to_spectrum`. For each frequency the power, i.e., the square of the complex values, will be stored in the corresponding area in the Spectrogram. Parameters ---------- -minimum_frequency_resolution : float, default=20.0 +minimum_frequency_resolution : float, default 20.0 Maximum distance separation of successive frequencies in the Spectrum, in Hz -bandwidth_reduction : float, default=0.0 - Reduces the bandwidth of each zero by this factor (<=0.0 for no - reduction). Formants with small bandwidths show up very well as darker - regions in the spectrogram because the poles lie close to the contour - along which a spectrum is computed (the unit circle in the z-plane). +bandwidth_reduction : float, default 0.0 + Reduces the bandwidth of each zero by this factor (<=0.0 for no + reduction). Formants with small bandwidths show up very well as darker + regions in the spectrogram because the poles lie close to the contour + along which a spectrum is computed (the unit circle in the z-plane). Peak enhancement can be realized by computing a spectrum in the z-plane along a contour of radius: - r = exp (– pi x bandwidthReduction / samplingFrequency). + :math:`r = exp \left(– \pi \times + \frac{bandwidthReduction}{samplingFrequency}\right)`. -deemphasis_frequency : float, default=50.0 +deemphasis_frequency : float, default 50.0 Performs de-emphasis when value is in this interval, specified in Hz. - (0, Nyquist frequency) + (0, Nyquist frequency) See also -------- diff --git a/src/parselmouth/LineSpectralFrequencies_docstrings.h b/src/parselmouth/LineSpectralFrequencies_docstrings.h index 46cd0820..fe40ae80 100644 --- a/src/parselmouth/LineSpectralFrequencies_docstrings.h +++ b/src/parselmouth/LineSpectralFrequencies_docstrings.h @@ -7,7 +7,7 @@ namespace parselmouth { constexpr auto CLASS_DOCSTRING = R"(Praat LineSpectralFrequencies Class. A sequence object contains a set of frequencies of line spectral contents, -found in the linear predictive coding (LPC) analysis. It contains +found in the linear predictive coding (LPC) analysis. It contains frequencies associated with each of LPC analysis frames, which are offset by :attr:`LineSpectralFrequencies.dt` seconds.