plotting

The plot_* functions behind every .plot() method, and overview.

sonore.plotting

Matplotlib plotting. Every function takes an optional ax and returns it.

Nothing here touches global matplotlib settings; style your notebook however you like (e.g. plt.style.use(...)).

plot_waveform(sound, ax=None, labels=None, **kwargs)

plot_spectrum(spectrum, ax=None, fscale='log', relative=True, **kwargs)

plot_stft(stft, ax=None, channel=0, db_range=80.0, cmap='magma', colorbar=True, fmax=None, trim_edges=True)

plot_mask(mask, ax=None, channel=0, cmap='Greys_r', colorbar=False)

A mask’s gains as an image, black 0 to white 1: time windows by FFT bins for an STFT mask, samples by bands for a subband mask.

plot_modulation_spectrum(ms, ax=None, db_range=60.0, cmap='magma', colorbar=True, wt_max=None, wf_max=None)

plot_modulation_spectrogram(msg, ax=None, channel=0, band=None, rate=None, db_range=30.0, cmap='magma', colorbar=True)

Modulation depth in dB as an image; cells the analysis marks invalid (rate above the band’s width, window past either end) are gray. The default view is modulation rate against time, pooled over bands; band= [Hz] picks one acoustic band, rate= [Hz] shows acoustic band against time at one modulation rate. 0 dB is 100% modulation.

plot_modulation_slices(msg, t, rate=4.0, channel=0, db_range=30.0, cmap='magma', figsize=(13, 3.8))

Three linked cuts through a modulation spectrogram’s time x band x rate cube, with a cursor at t [s]: rate against time (pooled over bands), band against time at rate [Hz], and band against rate at t (Atlas and Shamma’s joint display). One color scale for all three. Returns the figure.

animate_modulation_spectrogram(msg, path=None, sound=None, fps=25.0, channel=0, db_range=30.0, cmap='magma', figsize=(5, 4), dpi=100)

The band x rate image moving with time, one video frame every 1/fps seconds. Returns a matplotlib.animation.FuncAnimation (anim.to_jshtml() shows it in a notebook). With path it is saved with ffmpeg; with sound too, the sound is added as the audio track.

plot_subbands(sb, axes=None, channel=0, sharey=True, color=None, bands=None)

One trace per band, lowest at the bottom. With sharey=True (default) all traces share one amplitude scale, so relative band levels are visible. The bottom and top traces are the lowpass and highpass edge filters (labeled < f_lo and > f_hi).

bands selects which bands to show (indices), e.g. range(1, len(sb) - 1, 5) for every fifth band of a fine filterbank. For an image of all bands, plot the envelopes: sb.envelopes().plot().

plot_envelope(env, ax=None, db=False, **kwargs)

A single Envelope over time.

plot_envelopes(env, ax=None, channel=0, db_range=40.0, cmap='magma', colorbar=True, edges=False, align=None, fscale='log', fmax=None)

Envelopes (a cochleagram) as an image: time x band, in dB re the maximum. Edge bands are hidden unless edges=True.

align="peak" draws each band earlier by its filter’s envelope_peak_delay (a causal gammatone bank’s latency), so a click is a vertical line; only the drawing moves, not the data. fscale="linear" draws frequency linearly in kHz, matching plot_stft(), with an optional fmax [Hz].

plot_tf_db(db, t, f, ax=None, db_range=60.0, cmap='magma', colorbar=True, fmax=None, title=None)

A time-frequency image from levels db (shape (n_freqs, n_windows)) at window times t [s] and frequencies f [Hz], which need not be uniform: each cell extends halfway to its neighbors. Frequency is linear in kHz, as in plot_stft().

plot_cepstrum(cep, ax=None, channel=0, q_range=(0.001, 0.015), cmap='magma', colorbar=True)

A cepstrum as an image: time [s] across, quefrency [ms] up, from q_range [s]. The default, 1 to 15 ms, leaves out the low quefrencies (the spectral envelope, which would set the color scale) and covers the periods of voices from about 67 Hz up. Negative values are drawn as 0, and the color scale tops out at the 99.5th percentile, so that a few isolated peaks do not darken the rest.

plot_mfcc(mfcc, ax=None, channel=0, kind='mfcc', cmap=None, colorbar=True, db_range=60.0)

MFCCs as an image, time [s] across.

kind="mfcc": coefficients c1 and up (c0, the level, would set the color scale), on a diverging color scale symmetric about 0 and clipped at the 99th percentile of the magnitudes. kind="mel": the floored mel spectrogram in dB, one row per band, equally spaced so the rows read as the mel scale, labeled with their center frequencies, over db_range dB.

plot_f0_track(track, ax=None, channel=0, candidates=False, color='C0', **kwargs)

An F0 track: F0 [Hz] against time [s], broken where unvoiced. With candidates=True, every refined candidate the tracker weighed is drawn as a gray dot, darker for a higher periodicity score.

plot_descriptor_track(track, ax=None, channel=0, **kwargs)

A DescriptorTrack against time, one channel.

plot_interaural_cues(cues, ax=None, show_iac=True)

Broadband cues: ITD and ILD on twin axes (plus IAC underneath). Per-band cues: ITD as an image.

plot_ripple_pattern(pattern, duration=1.0, f_lo=250.0, f_hi=8000.0, ax=None, cmap='RdBu_r', colorbar=True, n_t=None, n_x=200)

Envelope of a ripple pattern (dB re its mean level) over time and log-frequency, before any sound is made.

plot_lissajous(sound, ax=None, duration=None, start=0.0, **kwargs)

A Lissajous figure: the left channel of a two-channel sound against the right, over duration seconds from start (by default the rest of the sound). Two tones whose frequencies are in a small whole-number ratio p:q draw a closed figure that stands still; a slightly mistuned pair draws a figure that turns, passing through all its shapes once every 1 / |q f_left - p f_right| seconds.

overview(sound, win_dur=0.02, figsize=(12, 8), fmax=None)

Waveform, spectrum, spectrogram and modulation spectrum in one figure (replaces the old display_STFT). Returns the Figure.