ffrprep.analysis.plot_pitch_and_conf

ffrprep.analysis.plot_pitch_and_conf(results)[source]

Plot a smoothed pitch track together with associated confidence measures.

This function visualizes the output of compute_pitch_and_conf() by creating a two-row matplotlib figure: the top row shows the smoothed pitch track (in Hz) with optional per-frame coloring by a confidence metric, and the bottom row shows one or more confidence time-series (rmax, z-score, pnr, etc.).

Parameters:

results (dict) –

Dictionary as returned by compute_pitch_and_conf(). The dictionary must contain at least the following keys:

  • 'times' (array-like) — 1-D array of time stamps in seconds for the pitch track.

  • 'pitch_hz_smooth' (array-like) — 1-D array of smoothed pitch values in Hz. Use NaN for unvoiced frames.

The dictionary may also include the following optional entries:

  • 'peak_strength' (array-like or None) — per-frame peak strength values that can be used as an alternate confidence measure for coloring the pitch scatter.

  • 'conf_rmax' (array-like or None) — preferred confidence metric (e.g., correlation maximum). If present and aligned with the pitch/times vector, it will be used to color the pitch points and plotted in the bottom panel.

  • 'conf_z' (array-like or None) — z-score confidence values (plotted in bottom panel when present).

  • 'conf_pnr' (array-like or None) — PNR (pitch-to-noise ratio) confidence values (plotted in bottom).

Returns:

Displays a matplotlib figure. The top subplot shows the smoothed pitch (points colored by conf_rmax if available, otherwise by peak_strength; falls back to a simple line if no color values are available). The bottom subplot shows available confidence traces aligned in time. The function does not return any value.

Return type:

None

Raises:

  • TypeError – If results is not a dict.

  • ValueError – If required keys (‘times’ and ‘pitch_hz_smooth’) are missing or None.

Notes

  • The function uses numpy.asarray() to coerce array-like inputs into arrays and masks NaN values in the pitch track so unvoiced frames are omitted from the scatter/line points.

  • If confidence arrays have a different length than the pitch array, the code will attempt to align them against the provided time vector; otherwise they are used as-is.

  • Requires matplotlib.pyplot (imported as plt in the function) and numpy (np) to be available in the module scope.

Examples

Assuming compute_pitch_and_conf() returns the expected dict:

results = compute_pitch_and_conf(audio_chunk)
plot_pitch_and_conf(results)