API: Measuring sounds¶
Module that measures each continuous CF and FM segment with either inbuilt or user-defined functions.
-
itsfm.measure.measure_hbc_call(call, fs, cf, fm, **kwargs)[source]¶ Performs common or unique measurements on each of the Cf and FM segments detected.
- Parameters
audio (np.array) –
fs (float>0.) – Frequency of sampling in Hz.
cf (np.array) – Boolean array with True indicating samples that define the CF
fm (np.array) – Boolean array with True indicating samples that define the FM
measurements (list, optional) – List with measurement functions
- Returns
measurement_values – A wide format dataframe with one row corresponding to all the measured values for a CF or FM segment
- Return type
pd.DataFrame
See also
Example
Create a call with fs and make fake CF and FM segments
>>> fs = 1.0 >>> call = np.random.normal(0,1,100) >>> cf = np.concatenate((np.tile(0, 50), np.tile(1,50))).astype('bool') >>> fm = np.invert(cf)
Get the default measurements by not specifying any measurements explicitly.
>>> sound_segments, measures = measure_hbc_call(call, fs, cf, fm ) >>> print(measures)
And here’s an example with some custom functions.The default measurements will appear in addition to the custom measurements.
>>> from itsfm.measurement_functions import measure_peak_amplitude, measure_peak_frequency >>> custom_measures = [peak_frequency, measure_peak_amplitude] >>> sound_segments, measures = measure_hbc_call(call, fs, cf, fm, measurements=custom_measures)
-
itsfm.measure.parse_cffm_segments(cf, fm)[source]¶ Recognises continuous stretches of Cf and FM segments, organises them into separate ‘objects’ and orders them in time.
- Parameters
fm (cf,) – Boolean arrays indicating which samples are CF/FM.
- Returns
cffm_regions_numbered – Each tuple corresponds to one CF or FM region in the audio. The tuple has two entries 1) the region identifier, eg. ‘fm1’ and 2) the indices that correspond to the region eg. slice(1,50)
- Return type
np.array with tuples.
Example
# an example sound with two cfs and an fm in the middle
>>> cf = np.array([0,1,1,0,0,0,1,1,0]).astype('bool') >>> fm = np.array([0,0,0,1,1,1,0,0,0]).astype('bool') >>> ordered_regions = parse_cffm_segments(cf, fm) >>> print(ordered_regions) [['cf1', slice(1, 3, None)], ['fm1', slice(3, 6, None)], ['cf2', slice(6, 8, None)]]
-
itsfm.measure.perform_segment_measurements(full_sound, fs, segment, functions_to_apply, **kwargs)[source]¶ Performs one or more measurements on a specific segment of a full audio clip.
- Parameters
full_sound (np.array) –
fs (float>0) –
segment (tuple) – First object is a string with the segment’s id, eg. ‘fm1’ or ‘cf2’ Second object is a slice with the indices of the segment, eg. slice(0,100)
functions_to_apply (list of functions) – Each function must be a ‘measurement function’. A measurement function is one that accepts a strict set of inputs. check See Also for more details.
- Returns
results – A single row with all the measurements results. The first column is always the ‘regionid’, the rest of the columns are measurement function dependent.
- Return type
pd.DataFrame
Example
Here we’ll create a short segment and take the rms and the peak value of the segment. The relevant_region is not an FM region, it is only labelled so here to show how it works with the rest of the package!
>>> np.random.seed(909) >>> audio = np.random.normal(0,1,100) >>> relevant_region = ('fm1',slice(10,30))
The sampling rate doesn’t matter for the custom functions defined below, but, it may be important for some other functions.
>>> fs = 1 # Hz >>> from itsfm.measurement_functions import measure_rms, measure_peak >>> results = perform_segment_measurements(audio, fs, relevant_region, [measure_rms, measure_peak])
-
itsfm.measure.common_measurements()[source]¶ Loads the default common measurement set for any region.
Measurement functions¶
This is a set of measurement functions which are used to measure various things about a part of an audio. A measurement function is a specific kind of
function which accepts three arguments and outputs a dictionary.
What is a measurement function:¶
A measurement function is a specific kind of function which accepts three arguments and outputs a dictionary. User-defined functions can be used to perform custom measurements on the segment of interest.
Measurement function parameters¶
the full audio, a np.array
the sampling rate, a float>0
the segment, a slice object which defines the span of the segment. For instance (‘fm1’, slice(0,100))
What needs to be returned:¶
A measurement function must return a dictionary with >1 keys that are strings and items that can be easily incorporated into a Pandas DataFrame and viewed on a csv file with ease. Ideal item types include strings, floats, or tuples.
See the source code of the built-in measurement functions below for an example of how to satisfy the measurement function pattern.
Attention
Remember to name the output of the measurement function properly. If the output key of one measurement function is the same as the other, it will get overwritten in the final dictionary!