From 19bde38664805cdfe158b67dedaee1b97bab30e3 Mon Sep 17 00:00:00 2001 From: Yannick Jadoul Date: Sun, 28 Feb 2021 22:09:07 +0100 Subject: [PATCH] More docstring tweaks --- src/parselmouth/Pitch_docstrings.h | 30 ++++++------ src/parselmouth/PointProcess.cpp | 4 +- src/parselmouth/PointProcess_docstrings.h | 60 ++++++++++++----------- src/parselmouth/Sound_docstrings.h | 24 ++++----- src/parselmouth/praat.cpp | 12 ++--- 5 files changed, 68 insertions(+), 62 deletions(-) diff --git a/src/parselmouth/Pitch_docstrings.h b/src/parselmouth/Pitch_docstrings.h index 96dfcebc..85c34cba 100644 --- a/src/parselmouth/Pitch_docstrings.h +++ b/src/parselmouth/Pitch_docstrings.h @@ -37,27 +37,29 @@ phonation cycles. Parameters ---------- -sound : parselmouth.Sound or None, default: None +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 `sound` object improves the accuracy of the resulting point - process. + samples in the `Sound` object improves the accuracy of the resulting + point process. -method : {"cc", "peaks"}, default: "cc" - Specify the Sound-assited generation method: +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. + "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. + "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_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) +include_minima : bool, default False + True to include the absolute minimum (for ``method="peaks"`` only). See Also -------- diff --git a/src/parselmouth/PointProcess.cpp b/src/parselmouth/PointProcess.cpp index 81ec5a4f..8572160b 100644 --- a/src/parselmouth/PointProcess.cpp +++ b/src/parselmouth/PointProcess.cpp @@ -125,7 +125,9 @@ PRAAT_CLASS_BINDING(PointProcess) { [](PointProcess self) { return self->nt; }, GET_NUMBER_OF_POINTS_DOCSTRING); - def_readonly("n_points", &structPointProcess::nt); + def_readonly("n_points", + &structPointProcess::nt, + N_POINTS_DOCSTRING); // INTEGER_PointProcess_getNumberOfPeriods def("get_number_of_periods", diff --git a/src/parselmouth/PointProcess_docstrings.h b/src/parselmouth/PointProcess_docstrings.h index 073e3e93..c7d6945c 100644 --- a/src/parselmouth/PointProcess_docstrings.h +++ b/src/parselmouth/PointProcess_docstrings.h @@ -31,8 +31,6 @@ on a domain [``xmin``, ``xmax``]. The points are sorted in time, i.e., Attributes ---------- -n_points : float, readonly - The number of time points tmin : float, readonly Starting time of the analysis domain in seconds tmax : float, readonly @@ -52,13 +50,13 @@ See Also " The end time of the part of the `PointProcess` to be measured in\n" \ " seconds. If `None`, all the points to ``tmax`` are included.\n" \ "\n" \ - "period_floor : float, default: 0.0001\n" \ + "period_floor : float, default 0.0001\n" \ " The shortest possible interval to be used in the computation in\n" \ " seconds. If an interval is shorter than this, it will be ignored (and\n"\ " the previous and next intervals will not be regarded as consecutive).\n"\ " This setting will normally be very small.\n" \ "\n" \ - "period_ceiling : float, default: 0.02\n" \ + "period_ceiling : float, default 0.02\n" \ " The longest possible interval that to be used in the computation in\n" \ " seconds. If an interval is longer than this, it will be ignored (and\n" \ " the previous and next intervals will not be regarded as consecutive).\n"\ @@ -66,18 +64,18 @@ See Also " this setting to 0.02 seconds; intervals longer than that could be\n" \ " regarded as voiceless stretches and will be ignored.\n" \ "\n" \ - "maximum_period_factor : float, positive, default: 1.3\n" \ + "maximum_period_factor : float, positive, default 1.3\n" \ " The largest possible difference between consecutive intervals to\n" \ " be used in the computation. If the ratio of the durations of two\n" \ " consecutive intervals is greater than this, this pair of intervals\n" \ " will be ignored (each of the intervals could still take part in the\n" \ - " computation in a comparison with its neighbour on the other side)." + " computation in a comparison with its neighbour on the other side).\n" #define GET_SHIMMER_RANGE_PARAMETER_DOCSTRING \ "sound : parselmouth.Sound\n" \ " Sound object containing the samples to evaluate the amplitude.\n" \ GET_RANGE_PARAMETER_DOCSTRING \ - "maximum_amplitude_factor : float, positive, default: 1.6\n" \ + "maximum_amplitude_factor : float, positive, default 1.6\n" \ " Maximum amplitude factor.\n" \ "\n" \ "See Also\n" \ @@ -128,11 +126,11 @@ which means that there are, on the average, :math:`\lambda` events per second. Parameters ---------- -start_time : float, default: 0.0 +start_time : float, default 0.0 :math:`t_{min}`, the beginning of the time domain, in seconds. -end_time : float, default: 1.0 +end_time : float, default 1.0 :math:`t_{max}`, the end of the time domain, in seconds. -density : float, default: 100.0 +density : float, default 100.0 The average number of points per second. See Also @@ -161,10 +159,14 @@ See Also constexpr auto GET_NUMBER_OF_POINTS_DOCSTRING = R"(Get the number of time points. -Returns the total number of time points defined in the PointProcess +Returns the total number of time points defined in the `PointProcess` instance. )"; +constexpr auto N_POINTS_DOCSTRING = + R"(The total number of time points defined in the `PointProcess`. +)"; + constexpr auto GET_NUMBER_OF_PERIODS_DOCSTRING = R"(Get the number of periods. Get the number of periods within the specified time range. @@ -283,7 +285,7 @@ end_time : float, optional The end time of the part of the PointProcess to be measured in seconds. If `None`, all the points to ``tmax`` are included. -period_ceiling : float, default: 0.02 +period_ceiling : float, default 0.02 The longest possible interval that to be used in the computation in seconds. If an interval is longer than this, it will be ignored (and the previous and next intervals will not be regarded as consecutive). @@ -539,7 +541,7 @@ point process, nothing happens for that point. Parameters ---------- -times : numpy.ndarray[float] +times : numpy.ndarray of float Array of time points to be added. )"; @@ -628,7 +630,7 @@ from_time : float, optional to_time : float, optional Ending time in seconds. -period : float, default: 0.01 +period : float, default 0.01 Time interval in seconds. )"; @@ -640,10 +642,10 @@ existing periods longer than ``maximum_voiced_period``. Parameters ---------- -period : float, default: 0.01 +period : float, default 0.01 Time interval in seconds. -maximum_voiced_period : float, default: 0.02000000001 +maximum_voiced_period : float, default 0.02000000001 Time period longer than this is considered unvoiced, in seconds. )"; @@ -689,11 +691,11 @@ information. Parameters ---------- -maximum_period : float, default: 0.02 +maximum_period : float, default 0.02 The maximum interval that will be consider part of a larger voiced interval. -mean_period : float, default: 0.01 +mean_period : float, default 0.01 Half of this value will be taken to be the amount to which a voiced interval will extend beyond its initial and final points. Mean period should be less than Maximum period, or you may get intervals with @@ -714,10 +716,10 @@ sampled sinc function. Parameters ---------- -sampling_frequency : float, default: 44100.0 +sampling_frequency : float, default 44100.0 The sampling frequency of the resulting `Sound` object. -adaptation_factor : float, default: 1.0 +adaptation_factor : float, default 1.0 The factor by which a pulse height will be multiplied if the pulse time is not within ``adaptation_time`` from the pre-previous pulse, and by which a pulse height will again be multiplied if the pulse time is not @@ -725,10 +727,10 @@ adaptation_factor : float, default: 1.0 against abrupt starts of the pulse train after silences, and is 1.0 if you do want abrupt starts after silences. -adaptation_time : float, default: 0.05 +adaptation_time : float, default 0.05 The minimal period that will be considered a silence. -interpolation_depth : int, default: 2000 +interpolation_depth : int, default 2000 The extent of the :math:`sinc` function to the left and to the right of the peak. @@ -752,10 +754,10 @@ is the normalized glottal flow in arbitrary units (the real unit is Parameters ---------- -sampling_frequency : float, default: 44100.0 +sampling_frequency : float, default 44100.0 The sampling frequency of the resulting `Sound` object. -adaptation_factor : float, default: 1.0 +adaptation_factor : float, default 1.0 The factor by which a pulse height will be multiplied if the pulse time is not within Maximum period from the previous pulse, and by which a pulse height will again be multiplied if the previous pulse time is not @@ -763,19 +765,19 @@ adaptation_factor : float, default: 1.0 against abrupt starts of the pulse train after silences, and is 1.0 if you do want abrupt starts after silences. -maximum_period : float, default: 0.05 +maximum_period : float, default 0.05 The minimal period that will be considered a silence in seconds. -open_phase: float, default: 0.7 +open_phase: float, default 0.7 Fraction of a period when the glottis is open. -collision_phase : float, default: 0.03 +collision_phase : float, default 0.03 Decay factor to ease the abrupt collision at closure. -power1 : float, default: 3.0 +power1 : float, default 3.0 First glottal flow shape coefficient. -power2 : float, default: 4.0 +power2 : float, default 4.0 Second glottal flow shape coefficient. See also diff --git a/src/parselmouth/Sound_docstrings.h b/src/parselmouth/Sound_docstrings.h index 2b54a740..f745616e 100644 --- a/src/parselmouth/Sound_docstrings.h +++ b/src/parselmouth/Sound_docstrings.h @@ -31,13 +31,13 @@ without pitch estimation. Parameters ---------- -channel : {"LEFT", "RIGHT"}, default: "LEFT" (first channel) +channel : {"LEFT", "RIGHT"}, default "LEFT" (first channel) Sound channel to process. -include_maxima : bool, default: True +include_maxima : bool, default True True to include the absolute maximum. -include_minima : bool, default: False +include_minima : bool, default False True to include the absolute minimum. interpolation : {"NONE", "PARABOLIC", "CUBIC", "SINC70", "SINC700"}, @@ -59,10 +59,10 @@ algorithm in :func:`~parselmouth.Pitch.to_point_process_cc`. Parameters ---------- -minimum_pitch : float, default: 75.0 +minimum_pitch : float, default 75.0 Minimum fundamental frequency to be considered. -maximum_pitch : float, default: 600.0 +maximum_pitch : float, default 600.0 Maximum fundamental frequency to be considered. See Also @@ -81,16 +81,16 @@ in `Sound.to_pitch_cc` and the voice cycle detection algorithm in Parameters ---------- -minimum_pitch : float, default: 75.0 +minimum_pitch : float, default 75.0 Minimum fundamental frequency to be considered -maximum_pitch : float, default: 600.0 +maximum_pitch : float, default 600.0 Maximum fundamental frequency to be considered -include_maxima : bool, default: True +include_maxima : bool, default True True to include the absolute maximum -include_minima : bool, default: False +include_minima : bool, default False True to include the absolute minimum See Also @@ -109,13 +109,13 @@ of the crossing. Parameters ---------- -channel : {"LEFT", "RIGHT"}, default: "LEFT" (first channel) +channel : {"LEFT", "RIGHT"}, default "LEFT" (first channel) Sound channel to process -include_raisers : bool, default: True +include_raisers : bool, default True True to detect the rising edges -include_fallers : bool, default: False +include_fallers : bool, default False True to detect the falling edges See Also diff --git a/src/parselmouth/praat.cpp b/src/parselmouth/praat.cpp index a136cc4c..ca310351 100644 --- a/src/parselmouth/praat.cpp +++ b/src/parselmouth/praat.cpp @@ -475,10 +475,10 @@ command : str Keyword Arguments ----------------- -extra_objects : list of parselmouth.Data, default: ``[]`` +extra_objects : list of parselmouth.Data, default ``[]`` Extra objects added to the Praat object list that will not be selected when the command is called. -return_string : bool, default: False +return_string : bool, default False Return the raw string written in the Praat info window instead of the converted Python object. @@ -566,13 +566,13 @@ script : str Keyword arguments ----------------- -extra_objects : list of parselmouth.Data, default: ``[]`` +extra_objects : list of parselmouth.Data, default ``[]`` Extra objects added to the Praat object list that will not be selected when the command is called. -capture_output : bool, default: False +capture_output : bool, default False Intercept and also return the output written to the Praat info window, instead of forwarding it to the Python standard output; see below. -return_variables : bool, default: False +return_variables : bool, default False Also return a `dict` of the Praat variables and their values at the end of the script's execution; see below. @@ -642,7 +642,7 @@ path : str Keyword arguments ----------------- -keep_cwd : bool, default: False +keep_cwd : bool, default False Keep the current working directory (see `os.getcwd`) when running the script, rather than changing it to the script's parent directory, as Praat does by default. Note that even when set to `True`, the