API : Viewing sounds, parameters and results

Bunch of functions which help in visualising data and results

There is a common pattern in the naming of viewing functions.

  1. functions starting with ‘visualise’ include an overlay of a particular output attribute on top of or with the the original signal. For example visualise_sound

  2. functions starting with ‘plot’ are bare bones plots with just the attribute on the y and time on the x.

class itsfm.view.itsFMInspector(segmeasure_out, whole_audio, fs, **kwargs)[source]

Handles the output from measure_and_segment calls, and allows plotting of the outputs.

Parameters

  • segmeasure_out (tuple) –

    Tuple object containing three other objects which are the output from segment_and_measure_call 1. segmentation_output : tuple

    Tuple with the cf boolean array, fm boolean array and info dictioanry

    1. audio_partsdictionary

      Dictionary with call part labels and values as selected audio parts as np.arrays

    2. measurementspd.DataFrame

      A wide-formate dataframe with one row referring to meaurements done on one call part eg. if a call has 3 parts (fm1, cf1, fm2), then there will be three columns and N columns, if N measurements have been done.

  • whole_audio (np.array) – The audio that was analysed.

  • fs (float>0) – Sampling rate in Hz.

Notes

  • Not all visualise methods may be supported. It depends on the segmentation method at hand.

  • All visualise methods return one/multiple subplots that could be used and embellished further for your own custom laying over.

visualise_fmrate()[source]

Plots the spectrogram + FM rate profile in a 2 row plot

visualise_accelaration()[source]

Plots the spectrogram + accelaration of the frequency profile in a 2 row plot

visualise_cffm_segmentation()[source]
visualise_frequency_profiles(fp_type='all')[source]

Visualises either one or all of the frequency profiles that are present in the info dictionary. The function relies on picking up all keys in the info dictionary that end with ‘<>_fp’ pattern.

Parameters

fp_type (str/list with str's) – Needs to correspond to a key found in the info dictionary

visualise_pkpctage_profiles()[source]
visualise_geq_signallevel()[source]

Some tracking/segmentation methods rely on using only regions that are above a threshold, the signal_level . A moving dB rms window is pass

ed, and only regions above it are

itsfm.view.check_call_background_segmentation(whole_call, fs, main_call_mask, **kwargs)[source]

Visualises the main call selection

Parameters

  • whole_call (np.array) – Call audio

  • fs (float>0) – Sampling rate in Hz

  • main_call_mask (np.array) – Boolean array where True indicates the sample is part of the main call, and False that it is not.

Returns

waveform, spec

Return type

pyplot.subplots

Notes

The appearance of the two subplots can be further changes by varying the keyword arguments. For available keyword arguments see the visualise_sound function.

itsfm.view.show_all_call_parts(only_call, call_parts, fs, **kwargs)[source]
Parameters

  • only_call (np.array) –

  • call_parts (dictionary) – Dictionary with keys ‘cf’ and ‘fm’ The entry for ‘cf’ should only have one audio segment. The entry for ‘fm’ can have multiple audio segments.

  • fs (float>0) – Sampling rate in Hz.

Returns

Return type

None

Notes

For further keyword arguments to customise the spectrograms see documentation for make_specgram This function does not return any output, it only produces a figure with subplots.

itsfm.view.visualise_fmrate_profile(X, freq_profile, fs)[source]
itsfm.view.plot_accelaration_profile(X, fs)[source]

Plots the frequency acclearation profile of a frequency profile

Parameters

  • X (np.array) – The frequency profile with sample-level estimates of frequency in Hz.

  • fs (float>0) –

Returns

  • A plt.plot which can be used as an independent figure ot

  • a subplot.

itsfm.view.plot_movingdbrms(X, fs, **kwargs)[source]
itsfm.view.visualise_sound(audio, fs, **kwargs)[source]
Parameters

  • audio –

  • fs –

  • fft_size (integer>0, optional) –

Returns

a0, a1

Return type

subplots

itsfm.view.make_specgram(audio, fs, **kwargs)[source]
itsfm.view.get_fftsize(fs, **kwargs)[source]
itsfm.view.make_overview_figure(call, fs, measurements, **kwargs)[source]
itsfm.view.plot_dbrms_cffmprofiles(seg_details, fs)[source]

Makes a plot with CF anf FM dB rms profiles. This method only works for peak-percentage based segmentation.

Parameters

  • seg_details (tuple) – Tuple with 3 entries. The third entry needs to be a dictionary with at least the following keys : ‘cf_re_fm’ and ‘fm_re_cf’

  • fs (float>0) – Sample rate in Hz

Returns

Return type

matplotlib plot