CandidateTracks

CandidateTracks(
    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,
    pitch_floor=75,
    smoother=Smoother(),
    loss_fun=Loss(),
    agg_fun=Agg(),
    heuristics=[],
)

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
pitch_floor	float	Pitch floor for f0 tracking. Defaults to 75.	75
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()
heuristics	list[MinMaxHeuristic | SpacingHeuristic]	A list of formant tracking heuristics to use.	[]

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

Name	Type	Description
	pl.DataFrame	A polars.DataFrame