Add PointProcess class

docs/conf.py

@@ -52,7 +52,6 @@
               'sphinx.ext.coverage',
               'sphinx_copybutton',
               'nbsphinx',
-              'pybind11_docstrings',
               'praat_manual']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -135,6 +134,9 @@
                        'numpy': ('https://numpy.org/doc/stable/', None),
                        'tgt': ('https://textgridtools.readthedocs.io/en/stable/', None)}
 
+# Napoleon configuration
+napoleon_preprocess_types = True
+
 default_role = 'py:obj'
 nitpicky = True
 nitpick_ignore = [('py:class', 'pybind11_builtins.pybind11_object'),
@@ -143,6 +145,8 @@
                   ('py:class', 'NonNegative'),
                   ('py:class', 'numpy.float64'),
                   ('py:class', 'numpy.complex128'),
+                  ('py:class', 'positive'),
+                  ('py:class', 'readonly'),
                   ('py:obj', 'List')]
 
 

src/parselmouth.cpp

@@ -40,6 +40,7 @@ Thing_declare(Intensity);
 Thing_declare(Matrix);
 Thing_declare(MFCC);
 Thing_declare(Pitch);
+Thing_declare(PointProcess);
 Thing_declare(Sampled);
 Thing_declare(SampledXY);
 Thing_declare(TextGrid);
@@ -119,6 +120,7 @@ using PraatBindings = Bindings<PraatError,
                                PraatWarning,
                                PraatFatal,
                                ValueInterpolation,
+                               PeakInterpolation,
                                WindowShape,
                                AmplitudeScaling,
                                SignalOutsideTimeDomain,
@@ -139,6 +141,7 @@ using PraatBindings = Bindings<PraatError,
                                Spectrum,
                                Spectrogram,
                                Pitch,
+                               PointProcess,
                                Intensity,
                                Harmonicity,
                                Formant,

src/parselmouth/CMakeLists.txt

@@ -25,6 +25,7 @@ target_sources(parselmouth PRIVATE
     Matrix.cpp
     MFCC.cpp
     Pitch.cpp
+    PointProcess.cpp
     Sampled.cpp
     SampledXY.cpp
     Sound.cpp

src/parselmouth/Parselmouth.h

@@ -34,6 +34,7 @@ enum class kSound_windowShape;
 enum class kSounds_convolve_scaling;
 enum class kSounds_convolve_signalOutsideTimeDomain;
 enum class kVector_valueInterpolation;
+enum class kVector_peakInterpolation;
 
 namespace parselmouth::detail {
 
@@ -94,6 +95,7 @@ namespace parselmouth {
 enum class SoundFileFormat;
 
 using ValueInterpolation = kVector_valueInterpolation;
+using PeakInterpolation = kVector_peakInterpolation;
 using WindowShape = kSound_windowShape;
 using AmplitudeScaling = kSounds_convolve_scaling;
 using SignalOutsideTimeDomain = kSounds_convolve_signalOutsideTimeDomain;

src/parselmouth/Pitch.cpp

@@ -19,6 +19,8 @@
 
 #include "Parselmouth.h"
 
+#include "Pitch_docstrings.h"
+
 #include "TimeClassAspects.h"
 
 #include "utils/praat/MelderUtils.h"
@@ -27,6 +29,7 @@
 
 #include <praat/fon/Matrix_and_Pitch.h>
 #include <praat/fon/Pitch.h>
+#include <praat/fon/Pitch_to_PointProcess.h>
 #include <praat/fon/Pitch_to_Sound.h>
 
 #include <pybind11/numpy.h>
@@ -148,7 +151,7 @@ PRAAT_CLASS_BINDING(Pitch) {
 	    "from_time"_a = std::nullopt, "to_time"_a = std::nullopt, "sampling_frequency"_a = 44100.0, "round_to_nearest_zero_crossing"_a = true);
 
 	def("count_voiced_frames",
-	    &Pitch_countVoicedFrames);
+		&Pitch_countVoicedFrames);
 
 	def("get_value_at_time",
 	    [](Pitch self, double time, kPitch_unit unit, kVector_valueInterpolation interpolation) {
@@ -228,18 +231,47 @@ PRAAT_CLASS_BINDING(Pitch) {
 	    &Pitch_interpolate);
 
 	def("smooth",
-	    args_cast<_, Positive<_>>(Pitch_smooth),
-	    "bandwidth"_a = 10.0);
+		args_cast<_, Positive<_>>(Pitch_smooth),
+		"bandwidth"_a = 10.0);
 
 	def("subtract_linear_fit",
 	    &Pitch_subtractLinearFit,
-	    "unit"_a = kPitch_unit::HERTZ);
+		"unit"_a = kPitch_unit::HERTZ);
 
 	def("kill_octave_jumps",
-	    &Pitch_killOctaveJumps);
+		&Pitch_killOctaveJumps);
 
 	// TODO To PitchTier: depends on PitchTier
 
+	// TODO Not sure what to do with this, yet
+	def("to_point_process",
+	    [](Pitch self, Sound sound, std::string method, bool include_maxima, bool include_minima) {
+		    if (sound) {
+			    if (method == "cc")
+				    return Sound_Pitch_to_PointProcess_cc(sound, self);
+			    else if (method == "peaks")
+				    return Sound_Pitch_to_PointProcess_peaks(sound, self, include_maxima, include_minima);
+			    else
+				    throw std::invalid_argument("Unknown method specified.");
+		    } else {
+			    return Pitch_to_PointProcess(self);
+		    }
+	    },
+	    "sound"_a = nullptr, "method"_a = "cc", "include_maxima"_a = true, "include_minima"_a = false,
+	    TO_POINT_PROCESS_DOCSTRING);
+
+	// NEW1_Sound_Pitch_to_PointProcess_cc
+	def("to_point_process_cc",
+	    [](Pitch self, Sound sound) { return Sound_Pitch_to_PointProcess_cc(sound, self); },
+	    "sound"_a.none(false),
+	    TO_POINT_PROCESS_CC_DOCSTRING);
+
+	// NEW1_Sound_Pitch_to_PointProcess_peaks
+	def("to_point_process_peaks",
+	    [](Pitch self, Sound sound, bool include_maxima, bool include_minima) { return Sound_Pitch_to_PointProcess_peaks(sound, self, include_maxima, include_minima); },
+	    "sound"_a.none(false), "include_maxima"_a = true, "include_minima"_a = false,
+	    TO_POINT_PROCESS_PEAKS_DOCSTRING);
+
 	def("to_matrix",
 	    &Pitch_to_Matrix);
 

src/parselmouth/Pitch_docstrings.h

@@ -0,0 +1,115 @@
+/*
+ * Copyright (C) 2021  Yannick Jadoul and contributors
+ *
+ * This file is part of Parselmouth.
+ *
+ * Parselmouth is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Parselmouth is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Parselmouth.  If not, see <http://www.gnu.org/licenses/>
+ */
+
+#pragma once
+#ifndef INC_PARSELMOUTH_PITCH_DOCSTRINGS_H
+#define INC_PARSELMOUTH_PITCH_DOCSTRINGS_H
+
+namespace parselmouth {
+
+constexpr auto TO_POINT_PROCESS_DOCSTRING =
+	R"(Create a `PointProcess` from a `Pitch` object.
+
+Returns a new PointProcess instance by interpreting the acoustic
+periodicity contour in the `Pitch` object as the frequency of an
+underlying point process (such as the sequence of glottal closures in
+vocal-fold vibration).
+
+The unvoiced intervals in the ``pitch`` object is transferred to the point
+process object, and the voiced intervals are further divided into each
+phonation cycles.
+
+Parameters
+----------
+sound : parselmouth.Sound, optional
+    Sound object containing the target sound waveform. If omitted,
+    `PointProcess` is created only from the pitch contour. Analyzing the
+    samples in the `Sound` object improves the accuracy of the resulting
+    point process.
+
+method : {"cc", "peaks"}, default "cc"
+    Specify the Sound-assisted generation method:
+
+    "cc"
+        Cross-correlation method. The fundamental periods of voice are
+        identified by cross-correlating the sound samples.
+
+    "peaks"
+        Peak-picking method. The fundamental periods of voice are
+        identified by peak-picking the sound samples. Typically, less
+        accurate than the cross-correlation method.
+
+include_maxima : bool, default True
+    True to include the absolute maximum (for ``method="peaks"`` only).
+
+include_minima : bool, default False
+    True to include the absolute minimum (for ``method="peaks"`` only).
+
+See Also
+--------
+:praat:`Pitch: To PointProcess`
+:praat:`Sound & Pitch: To PointProcess (cc)`
+:praat:`Sound & Pitch: To PointProcess (peaks)...`
+)";
+
+constexpr auto TO_POINT_PROCESS_CC_DOCSTRING =
+R"(Create a `PointProcess` using cross-correlation.
+
+Returns a new `PointProcess` instance, generated from the specified `Sound`
+and `Pitch` instances using the cross-correlation method. The resulting
+instance contains voiced and unvoiced intervals according to ``pitch``
+object, and the voiced intervals are further divided into fundamental
+periods of voice, identified by cross-correlating the sound samples.
+
+Parameters
+----------
+sound : parselmouth.Sound
+    Sound object containing the target sound waveform.
+
+See Also
+--------
+:praat:`Sound & Pitch: To PointProcess (cc)`
+)";
+
+constexpr auto TO_POINT_PROCESS_PEAKS_DOCSTRING =
+R"(Create a `PointProcess` using peak-picking.
+
+Returns a new PointProcess instance, generated from the specified `Sound`
+and `Pitch` instances using the peak-picking method. The resulting
+instance contains voiced and unvoiced intervals according to ``pitch``
+object, and the voiced intervals are further divided into fundamental
+periods of voice, identified by peak-picking the sound samples.
+
+The periods that are found in this way are much more variable than those
+found by `Pitch.to_point_process_cc()` and therefore less useful for
+analysis and subsequent overlap-add synthesis.
+
+Parameters
+----------
+sound : parselmouth.Sound
+    Sound object containing the target sound waveform.
+
+See Also
+--------
+:praat:`Sound & Pitch: To PointProcess (peaks)...`
+)";
+
+} // namespace parselmouth
+
+#endif // INC_PARSELMOUTH_PITCH_DOCSTRINGS_H