CandidateTracks

CandidateTracks(self, sound=None, samples=None, sampling_frequency=None, xmin=0.0, min_max_formant=4000, max_max_formant=7000, nstep=20, n_formants=4, window_length=0.025, time_step=0.002, pre_emphasis_from=50, smoother=Smoother(), loss_fun=Loss(), agg_fun=Agg())

A class for candidate tracks for a single formant

You can provide either

  • A parselmouth Sound object to the sound argument

xor

  • An array of audio samples to the samples argument
  • The sampling frequency to the sampling_frequency argument
  • Any optional time offset to the xmin argument.

If a Sound object is passed to sound, any values passed to samples, sampling_frequency and xmin are ignored.

Parameters

Name Type Description Default
sound pm.Sound A parselmouth.Sound object. None
samples np.ndarray A numpy array of audio samples. None
sampling_frequency float The audio sampling frequency. None
xmin float The time offset for the audio. Defaults to 0.0. 0.0
min_max_formant float The lowest max-formant value to try. Defaults to 4000. 4000
max_max_formant float The highest max formant to try. Defaults to 7000. 7000
nstep int The number of steps from the min to the max max formant. Defaults to 20. 20
n_formants int The number of formants to track. Defaults to 4. 4
window_length float Window length of the formant analysis. Defaults to 0.025. 0.025
time_step float Time step of the formant analyusis window. Defaults to 0.002. 0.002
pre_emphasis_from float Pre-emphasis threshold. Defaults to 50. 50
smoother Smoother The smoother method to use. Defaults to Smoother(). Smoother()
loss_fun Loss The loss function to use. Defaults to Loss(). Loss()
agg_fun Agg The loss aggregation function to use. Defaults to Agg(). Agg()

Attributes

Name Type Description
candidates list[OneTrack, …] A list of OneTrack tracks.
smooth_errors np.array The error terms for each treack in candidates
winner_idx int The candidate track with the smallest error term
winner OneTrack The winning OneTrack track.
file_name str The filename of the audio file, if set.
interval aligned_textgrid.SequenceInterval The textgrid interval of the sound, if set.
id str The interval id of the sound, if set.
group str The tier group name of the sound, if set.

Methods

Name Description
spectrograms This will plot a grid of the candidate formant
to_df Return a polars dataframe of the candidate tracks

spectrograms

CandidateTracks.spectrograms(**kwargs)

This will plot a grid of the candidate formant tracks and their spectrograms. If a file_name is provided, it will save the plot to disk.

Parameters

Name Type Description Default
formants int The number of formants to plot. Defaults to 3. required
maximum_frequency float The frequency range the spectrogram and formants will be plotted up to. Defaults to 3500. required
dynamic_range float A all spectrogram values below the dynamic range. will be plotted as white. Defaults to 60. required
figsize tuple[float, float] Width and height of the figure in inches. Defaults to (8,5). required
file_name Path | None If provided, how to save the spectrogram. If not provided (None) the plot will show interactively. Defaults to None. required
dpi float If the plot is being saved, its image resolution in dots per inch. Defaults to 75 required

to_df

CandidateTracks.to_df(which='winner', output='formants')

Return a polars dataframe of the candidate tracks

Parameters

Name Type Description Default
which Literal[‘winner’, ‘all’] Return just the winner track data, or all candidates. Defaults to “winner”. 'winner'
output Literal[‘formants’, ‘param’, ‘log_param’] Whether to output the formants or the smoothing parameters. Defaults to “formants”. 'formants'

Returns

Type Description
pl.DataFrame A polars.DataFrame