Skip to content

Commit

Permalink
More docstring tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
@YannickJadoul
YannickJadoul committed Feb 28, 2021
1 parent 18ba987 commit 19bde38
Show file tree
Hide file tree
Showing 5 changed files with 68 additions and 62 deletions.
30 changes: 16 additions & 14 deletions src/parselmouth/Pitch_docstrings.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down
4 changes: 3 additions & 1 deletion src/parselmouth/PointProcess.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
60 changes: 31 additions & 29 deletions src/parselmouth/PointProcess_docstrings.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -52,32 +50,32 @@ 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"\
" For example, if the minimum frequency of periodicity is 50 Hz, set\n" \
" 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" \
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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.
)";

Expand Down Expand Up @@ -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.
)";

Expand All @@ -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.
)";

Expand Down Expand Up @@ -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
Expand All @@ -714,21 +716,21 @@ 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
within ``adaptation_time`` from the previous pulse. This factor is
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.
Expand All @@ -752,30 +754,30 @@ 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
within ``maximum_period`` from the pre-previous pulse. This factor is
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
Expand Down
24 changes: 12 additions & 12 deletions src/parselmouth/Sound_docstrings.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"},
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
12 changes: 6 additions & 6 deletions src/parselmouth/praat.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 19bde38

Please sign in to comment.