Music Structure Analysis (libfmp.c4)

The FMP notebooks provide detailed textbook-like explanations of central techniques and algorithms implemented in the libfmp. The part of FMP related to this module is available at the following URL:

https://www.audiolabs-erlangen.de/resources/MIR/FMP/C4/C4.html

libfmp.c4.c4s1_annotation.convert_structure_annotation(ann, Fs=1, remove_digits=False, index=False)

Convert structure annotations

Notebook: C4/C4S1_MusicStructureGeneral.ipynb

Parameters

• ann (list) – Structure annotions

• Fs (scalar) – Sampling rate (Default value = 1)

• remove_digits (bool) – Remove digits from labels (Default value = False)

• index (bool) – Round to nearest integer (Default value = False)

Returns

ann_converted (list) – Converted annotation

libfmp.c4.c4s1_annotation.get_color_for_annotation_file(filename)

Gets color dict for annotation file. This function is specialized for some specfic files used in the FMP notebooks, i.e.:

• FMP_C4_Audio_Brahms_HungarianDances-05_Ormandy

• FMP_C6_Audio_Brahms_HungarianDances-05_Ormandy

• FMP_C4_F13_ZagerEvans_InTheYear2525

• FMP_C6_Audio_ZagerEvans_InTheYear2525

Parameters

filename (str) – Annotation file

Returns

color_ann (dict) – Dictionary encoding color scheme

libfmp.c4.c4s1_annotation.read_structure_annotation(fn_ann, fn_ann_color='', Fs=1, remove_digits=False, index=False)

Read and convert structure annotation and colors

Notebook: C4/C4S1_MusicStructureGeneral.ipynb

Parameters

• fn_ann (str) – Path and filename for structure annotions

• fn_ann_color (str) – Filename used to identify colors (Default value = ‘’)

• Fs (scalar) – Sampling rate (Default value = 1)

• remove_digits (bool) – Remove digits from labels (Default value = False)

• index (bool) – Round to nearest integer (Default value = False)

Returns

• ann (list) – Annotations

• color_ann (dict) – Color scheme

libfmp.c4.c4s2_ssm.compute_sm_dot(X, Y)

Computes similarty matrix from feature sequences using dot (inner) product

Notebook: C4/C4S2_SSM.ipynb

Parameters

• X (np.ndarray) – First sequence

• Y (np.ndarray) – Second Sequence

Returns

S (float) – Dot product

libfmp.c4.c4s2_ssm.compute_sm_from_filename(fn_wav, L=21, H=5, L_smooth=16, tempo_rel_set=np.array([1]), shift_set=np.array([0]), strategy='relative', scale=True, thresh=0.15, penalty=0.0, binarize=False)

Compute an SSM

Notebook: C4/C4S2_SSM-Thresholding.ipynb

Parameters

• fn_wav (str) – Path and filename of wav file

• L (int) – Length of smoothing filter (Default value = 21)

• H (int) – Downsampling factor (Default value = 5)

• L_smooth (int) – Length of filter (Default value = 16)

• tempo_rel_set (np.ndarray) – Set of relative tempo values (Default value = np.array([1]))

• shift_set (np.ndarray) – Set of shift indices (Default value = np.array([0]))

• strategy (str) – Thresholding strategy (see libfmp.c4.c4s2_ssm.compute_sm_ti()) (Default value = ‘relative’)

• scale (bool) – If scale=True, then scaling of positive values to range [0,1] (Default value = True)

• thresh (float) – Treshold (meaning depends on strategy) (Default value = 0.15)

• penalty (float) – Set values below treshold to value specified (Default value = 0.0)

• binarize (bool) – Binarizes final matrix (positive: 1; otherwise: 0) (Default value = False)

Returns

• x (np.ndarray) – Audio signal

• x_duration (float) – Duration of audio signal (seconds)

• X (np.ndarray) – Feature sequence

• Fs_feature (scalar) – Feature rate

• S_thresh (np.ndarray) – SSM

• I (np.ndarray) – Index matrix

libfmp.c4.c4s2_ssm.compute_sm_ti(X, Y, L=1, tempo_rel_set=np.asarray([1]), shift_set=np.asarray([0]), direction=2)

Compute enhanced similaity matrix by applying path smoothing and transpositions

Notebook: C4/C4S2_SSM-TranspositionInvariance.ipynb

Parameters

• X (np.ndarray) – First feature sequence

• Y (np.ndarray) – Second feature sequence

• L (int) – Length of filter (Default value = 1)

• tempo_rel_set (np.ndarray) – Set of relative tempo values (Default value = np.asarray([1]))

• shift_set (np.ndarray) – Set of shift indices (Default value = np.asarray([0]))

• direction (int) – Direction of smoothing (0: forward; 1: backward; 2: both directions) (Default value = 2)

Returns

• S_TI (np.ndarray) – Transposition-invariant SM

• I_TI (np.ndarray) – Transposition index matrix

libfmp.c4.c4s2_ssm.compute_tempo_rel_set(tempo_rel_min, tempo_rel_max, num)

Compute logarithmically spaced relative tempo values

Notebook: C4/C4S2_SSM-PathEnhancement.ipynb

Parameters

• tempo_rel_min (float) – Minimum relative tempo

• tempo_rel_max (float) – Maximum relative tempo

• num (int) – Number of relative tempo values (inlcuding the min and max)

Returns

tempo_rel_set (np.ndarray) – Set of relative tempo values

libfmp.c4.c4s2_ssm.filter_diag_mult_sm(S, L=1, tempo_rel_set=np.asarray([1]), direction=0)

Path smoothing of similarity matrix by filtering in forward or backward direction along various directions around main diagonal. Note: Directions are simulated by resampling one axis using relative tempo values

Notebook: C4/C4S2_SSM-PathEnhancement.ipynb

Parameters

• S (np.ndarray) – Self-similarity matrix (SSM)

• L (int) – Length of filter (Default value = 1)

• tempo_rel_set (np.ndarray) – Set of relative tempo values (Default value = np.asarray([1]))

• direction (int) – Direction of smoothing (0: forward; 1: backward) (Default value = 0)

Returns

S_L_final (np.ndarray) – Smoothed SM

libfmp.c4.c4s2_ssm.filter_diag_sm(S, L)

Path smoothing of similarity matrix by forward filtering along main diagonal

Notebook: C4/C4S2_SSM-PathEnhancement.ipynb

Parameters

• S (np.ndarray) – Similarity matrix (SM)

• L (int) – Length of filter

Returns

S_L (np.ndarray) – Smoothed SM

libfmp.c4.c4s2_ssm.plot_feature_ssm(X, Fs_X, S, Fs_S, ann, duration, color_ann=None, title='', label='Time (seconds)', time=True, figsize=(5, 6), fontsize=10, clim_X=None, clim=None)

Plot SSM along with feature representation and annotations (standard setting is time in seconds)

Notebook: C4/C4S2_SSM.ipynb

Parameters

• X – Feature representation

• Fs_X – Feature rate of X

• S – Similarity matrix (SM)

• Fs_S – Feature rate of S

• ann – Annotaions

• duration – Duration

• color_ann – Color annotations (see libfmp.b.b_plot.plot_segments()) (Default value = None)

• title – Figure title (Default value = ‘’)

• label – Label for time axes (Default value = ‘Time (seconds)’)

• time – Display time axis ticks or not (Default value = True)

• figsize – Figure size (Default value = (5, 6))

• fontsize – Font size (Default value = 10)

• clim_X – Color limits for matrix X (Default value = None)

• clim – Color limits for matrix S (Default value = None)

Returns

• fig – Handle for figure

• ax – Handle for axes

libfmp.c4.c4s2_ssm.shift_cyc_matrix(X, shift=0)

Cyclic shift of features matrix along first dimension

Notebook: C4/C4S2_SSM-TranspositionInvariance.ipynb

Parameters

• X (np.ndarray) – Feature respresentation

• shift (int) – Number of bins to be shifted (Default value = 0)

Returns

X_cyc (np.ndarray) – Cyclically shifted feature matrix

libfmp.c4.c4s2_ssm.subplot_matrix_colorbar(S, fig, ax, title='', Fs=1, xlabel='Time (seconds)', ylabel='Time (seconds)', clim=None, xlim=None, ylim=None, cmap=None, interpolation='nearest')

Visualization function for showing zoomed sections of matrices

Notebook: C4/C4S2_SSM-PathEnhancement.ipynb

Parameters

• S – Similarity matrix (SM)

• fig – Figure handle

• ax – Axes handle

• title – Title for figure (Default value = ‘’)

• Fs – Feature rate (Default value = 1)

• xlabel – Label for x-axis (Default value = ‘Time (seconds)’)

• ylabel – Label for y-axis (Default value = ‘Time (seconds)’)

• clim – Color limits (Default value = None)

• xlim – Limits for x-axis (Default value = None)

• ylim – Limits for x-axis (Default value = None)

• cmap – Colormap for imshow (Default value = None)

• interpolation – Interpolation value for imshow (Default value = ‘nearest’)

Returns

im – Imshow handle

libfmp.c4.c4s2_ssm.subplot_matrix_ti_colorbar(S, fig, ax, title='', Fs=1, xlabel='Time (seconds)', ylabel='Time (seconds)', clim=None, xlim=None, ylim=None, cmap=None, alpha=1, interpolation='nearest', ind_zero=False)

Visualization function for showing transposition index matrix

Notebook: C4/C4S2_SSM-TranspositionInvariance.ipynb

Parameters

• S – Self-similarity matrix (SSM)

• fig – Figure handle

• ax – Axes handle

• title – Title for figure (Default value = ‘’)

• Fs – Feature rate (Default value = 1)

• xlabel – Label for x-axis (Default value = ‘Time (seconds)’)

• ylabel – Label for y-axis (Default value = ‘Time (seconds)’)

• clim – Color limits (Default value = None)

• xlim – Limits for x-axis (Default value = None)

• ylim – Limits for y-axis (Default value = None)

• cmap – Color map (Default value = None)

• alpha – Alpha value for imshow (Default value = 1)

• interpolation – Interpolation value for imshow (Default value = ‘nearest’)

• ind_zero – Use white (True) or black (False) color for index zero (Default value = False)

Returns

im – Imshow handle

libfmp.c4.c4s2_synthetic_ssm.generate_ssm_from_annotation(ann, label_ann=None, score_path=1.0, score_block=0.5, main_diagonal=True, smooth_sigma=0.0, noise_power=0.0)

Generation of a SSM

Notebook: C4/C4S2_SSM-Synthetic.ipynb

Parameters

• ann (list) – Description of sections (see explanation above)

• label_ann (dict) – Specification of property (path, block relation) (Default value = None)

• score_path (float) – SSM values for occurring paths (Default value = 1.0)

• score_block (float) – SSM values of blocks covering the same labels (Default value = 0.5)

• main_diagonal (bool) – True if a filled main diagonal should be enforced (Default value = True)

• smooth_sigma (float) – Standard deviation of a Gaussian smoothing filter. filter length is 4*smooth_sigma (Default value = 0.0)

• noise_power (float) – Variance of additive white Gaussian noise (Default value = 0.0)

Returns

S (np.ndarray) – Generated SSM

libfmp.c4.c4s2_threshold.threshold_matrix(S, thresh, strategy='absolute', scale=False, penalty=0.0, binarize=False)

Treshold matrix in a relative fashion

Notebook: C4/C4S2_SSM-Thresholding.ipynb

Parameters

• S (np.ndarray) – Input matrix

• thresh (float or list) – Treshold (meaning depends on strategy)

• strategy (str) – Thresholding strategy (‘absolute’, ‘relative’, ‘local’) (Default value = ‘absolute’)

• scale (bool) – If scale=True, then scaling of positive values to range [0,1] (Default value = False)

• penalty (float) – Set values below treshold to value specified (Default value = 0.0)

• binarize (bool) – Binarizes final matrix (positive: 1; otherwise: 0) (Default value = False)

Returns

S_thresh (np.ndarray) – Thresholded matrix

libfmp.c4.c4s2_threshold.threshold_matrix_relative(S, thresh_rel=0.2, details=False)

Treshold matrix in a relative fashion

Notebook: C4/C4S2_SSM-Thresholding.ipynb

Parameters

• S (np.ndarray) – Input matrix

• thresh_rel (float) – Relative treshold (Default value = 0.2)

• details (bool) – Print details on thresholding procedure (Default value = False)

Returns

• S_thresh (np.ndarray) – Thresholded matrix

• thresh_abs (float) – Absolute threshold used for thresholding

libfmp.c4.c4s3_thumbnail.check_segment(seg, S)

Prints properties of segments with regard to SSM S

Notebook: C4/C4S3_ScapePlot.ipynb

Parameters

• seg (tuple) – Segment (start_index, end_index)

• S (np.ndarray) – Self-similarity matrix

Returns

path_family (list) – Optimal path family

libfmp.c4.c4s3_thumbnail.colormap_penalty(penalty=- 2, cmap=libfmp.b.compressed_gray_cmap(alpha=5))

Extend colormap with white color between the penalty value and zero

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

• penalty (float) – Negative number (Default value = -2.0)

• cmap (mpl.colors.Colormap) – Original colormap (Default value = libfmp.b.compressed_gray_cmap(alpha=5))

Returns

cmap_penalty (mpl.colors.Colormap) – Extended colormap

libfmp.c4.c4s3_thumbnail.compute_accumulated_score_matrix(S_seg)

Compute the accumulated score matrix

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

S_seg (np.ndarray) – Submatrix of an enhanced and normalized SSM S. Note: S must satisfy S(n,m) <= 1 and S(n,n) = 1

Returns

• D (np.ndarray) – Accumulated score matrix

• score (float) – Score of optimal path family

libfmp.c4.c4s3_thumbnail.compute_fitness(path_family, score, N)

Compute fitness measure and other metrics from path family

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

• path_family (list) – Path family

• score (float) – Score

• N (int) – Length of feature sequence

Returns

• fitness (float) – Fitness

• score (float) – Score

• score_n (float) – Normalized score

• coverage (float) – Coverage

• coverage_n (float) – Normalized coverage

• path_family_length (int) – Length of path family (total number of cells)

libfmp.c4.c4s3_thumbnail.compute_fitness_scape_plot(S)

Compute scape plot for fitness and other measures

Notebook: C4/C4S3_ScapePlot.ipynb

Parameters

S (np.ndarray) – Self-similarity matrix

Returns

SP_all (np.ndarray) – Vector containing five different scape plots for five measures (fitness, score, normalized score, coverage, normlized coverage)

libfmp.c4.c4s3_thumbnail.compute_induced_segment_family_coverage(path_family)

Compute induced segment family and coverage from path family

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

path_family (list) – Path family

Returns

• segment_family (np.ndarray) – Induced segment family

• coverage (float) – Coverage of path family

libfmp.c4.c4s3_thumbnail.compute_optimal_path_family(D)

Compute an optimal path family given an accumulated score matrix

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

D (np.ndarray) – Accumulated score matrix

Returns

path_family (list) – Optimal path family consisting of list of paths (each path being a list of index pairs)

libfmp.c4.c4s3_thumbnail.normalization_properties_ssm(S)

Normalizes self-similartiy matrix to fulfill S(n,n)=1. Yields a warning if max(S)<=1 is not fulfilled

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

S (np.ndarray) – Self-similarity matrix (SSM)

Returns

S_normalized (np.ndarray) – Normalized self-similarity matrix

libfmp.c4.c4s3_thumbnail.plot_path_family(ax, path_family, Fs=1, x_offset=0, y_offset=0, proj_x=True, w_x=7, proj_y=True, w_y=7)

Plot path family into a given axis

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

• ax – Axis of plot

• path_family – Path family

• Fs – Feature rate of path_family (Default value = 1)

• x_offset – Offset x-axis (Default value = 0)

• y_offset – Yffset x-axis (Default value = 0)

• proj_x – Display projection on x-axis (Default value = True)

• w_x – Width used for projection on x-axis (Default value = 7)

• proj_y – Display projection on y-axis (Default value = True)

• w_y – Width used for projection on y-axis (Default value = 7)

libfmp.c4.c4s3_thumbnail.plot_seg_in_sp(ax, seg, S=None, Fs=1)

Plot segment and induced segements as points in SP visualization

Notebook: C4/C4S3_ScapePlot.ipynb

Parameters

• ax – Axis for image

• seg – Segment (start_index, end_index)

• S – Self-similarity matrix (Default value = None)

• Fs – Sampling rate (Default value = 1)

libfmp.c4.c4s3_thumbnail.plot_sp_ssm(SP, seg, S, ann, color_ann=[], title='', figsize=(5, 4))

Visulization of SP and SSM

Notebook: C4/C4S3_ScapePlot.ipynb

Parameters

• SP – Scape plot

• seg – Segment (start_index, end_index)

• S – Self-similarity matrix

• ann – Annotation

• color_ann – color scheme used for annotations (Default value = [])

• title – Title of figure (Default value = ‘’)

• figsize – Figure size (Default value = (5, 4))

libfmp.c4.c4s3_thumbnail.plot_ssm_ann(S, ann, Fs=1, cmap='gray_r', color_ann=[], ann_x=True, ann_y=True, fontsize=12, figsize=(5, 4.5), xlabel='', ylabel='', title='')

Plot SSM and annotations (horizontal and vertical as overlay)

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

• S – Self-similarity matrix

• ann – Annotations

• Fs – Feature rate of path_family (Default value = 1)

• cmap – Color map for S (Default value = ‘gray_r’)

• color_ann – color scheme used for annotations (see libfmp.b.b_plot.plot_segments()) (Default value = [])

• ann_x – Plot annotations on x-axis (Default value = True)

• ann_y – Plot annotations on y-axis (Default value = True)

• fontsize – Font size used for annotation labels (Default value = 12)

• figsize – Size of figure (Default value = (5, 4.5))

• xlabel – Label for x-axis (Default value = ‘’)

• ylabel – Label for y-axis (Default value = ‘’)

• title – Figure size (Default value = ‘’)

Returns

• fig – Handle for figure

• ax – Handle for axes

• im – Handle for imshow

libfmp.c4.c4s3_thumbnail.plot_ssm_ann_optimal_path_family(S, ann, seg, Fs=1, cmap='gray_r', color_ann=[], fontsize=12, figsize=(5, 4.5), ylabel='')

Plot SSM, annotations, and computed optimal path family

Notebook: C4/C4S3_AudioThumbnailing.ipynb

Parameters

• S – Self-similarity matrix

• ann – Annotations

• seg – Segment for computing the optimal path family

• Fs – Feature rate of path_family (Default value = 1)

• cmap – Color map for S (Default value = ‘gray_r’)

• color_ann – color scheme used for annotations (see libfmp.b.b_plot.plot_segments()) (Default value = [])

• fontsize – Font size used for annotation labels (Default value = 12)

• figsize – Size of figure (Default value = (5, 4.5))

• ylabel – Label for y-axis (Default value = ‘’)

Returns

• fig – Handle for figure

• ax – Handle for axes

• im – Handle for imshow

libfmp.c4.c4s3_thumbnail.seg_max_sp(SP)

Return segment with maximal value in SP

Notebook: C4/C4S3_ScapePlot.ipynb

Parameters

SP (np.ndarray) – Scape plot

Returns

seg (tuple) – Segment (start_index, end_index)

libfmp.c4.c4s3_thumbnail.visualize_scape_plot(SP, Fs=1, ax=None, figsize=(4, 3), title='', xlabel='Center (seconds)', ylabel='Length (seconds)', interpolation='nearest')

Visualize scape plot

Notebook: C4/C4S3_ScapePlot.ipynb

Parameters

• SP – Scape plot data (encodes as start-duration matrix)

• Fs – Sampling rate (Default value = 1)

• ax – Used axes (Default value = None)

• figsize – Figure size (Default value = (4, 3))

• title – Title of figure (Default value = ‘’)

• xlabel – Label for x-axis (Default value = ‘Center (seconds)’)

• ylabel – Label for y-axis (Default value = ‘Length (seconds)’)

• interpolation – Interpolation value for imshow (Default value = ‘nearest’)

Returns

• fig – Handle for figure

• ax – Handle for axes

• im – Handle for imshow

libfmp.c4.c4s4_novelty_kernel.compute_kernel_checkerboard_box(L)

Compute box-like checkerboard kernel [FMP, Section 4.4.1]

Notebook: C4/C4S4_NoveltySegmentation.ipynb

Parameters

L (int) – Parameter specifying the kernel size 2*L+1

Returns

kernel (np.ndarray) – Kernel matrix of size (2*L+1) x (2*L+1)

libfmp.c4.c4s4_novelty_kernel.compute_kernel_checkerboard_gaussian(L, var=1.0, normalize=True)

Compute Guassian-like checkerboard kernel [FMP, Section 4.4.1]. See also: https://scipython.com/blog/visualizing-the-bivariate-gaussian-distribution/

Notebook: C4/C4S4_NoveltySegmentation.ipynb

Parameters

• L (int) – Parameter specifying the kernel size M=2*L+1

• var (float) – Variance parameter determing the tapering (epsilon) (Default value = 1.0)

• normalize (bool) – Normalize kernel (Default value = True)

Returns

kernel (np.ndarray) – Kernel matrix of size M x M

libfmp.c4.c4s4_novelty_kernel.compute_novelty_ssm(S, kernel=None, L=10, var=0.5, exclude=False)

Compute novelty function from SSM [FMP, Section 4.4.1]

Notebook: C4/C4S4_NoveltySegmentation.ipynb

Parameters

• S (np.ndarray) – SSM

• kernel (np.ndarray) – Checkerboard kernel (if kernel==None, it will be computed) (Default value = None)

• L (int) – Parameter specifying the kernel size M=2*L+1 (Default value = 10)

• var (float) – Variance parameter determing the tapering (epsilon) (Default value = 0.5)

• exclude (bool) – Sets the first L and last L values of novelty function to zero (Default value = False)

Returns

nov (np.ndarray) – Novelty function

libfmp.c4.c4s4_structure_feature.compute_time_lag_representation(S, circular=True)

Computation of (circular) time-lag representation

Notebook: C4/C4S4_StructureFeature.ipynb

Parameters

• S (np.ndarray) – Self-similarity matrix

• circular (bool) – Computes circular version (Default value = True)

Returns

L (np.ndarray) – (Circular) time-lag representation of S

libfmp.c4.c4s4_structure_feature.novelty_structure_feature(L, padding=True)

Computation of the novelty function from a circular time-lag representation

Notebook: C4/C4S4_StructureFeature.ipynb

Parameters

• L (np.ndarray) – Circular time-lag representation

• padding (bool) – Padding the result with the value zero (Default value = True)

Returns

nov (np.ndarray) – Novelty function

libfmp.c4.c4s4_structure_feature.plot_ssm_structure_feature_nov(S, L, nov, Fs=1, figsize=(10, 3), ann=[], color_ann=[])

Plotting an SSM, structure features, and a novelty function

Notebook: C4/C4S4_StructureFeature.ipynb

Parameters

• S – SSM

• L – Circular time-lag representation

• nov – Novelty function

• Fs – Feature rate (indicated in title of SSM) (Default value = 1)

• figsize – Figure size (Default value = (10, 3))

• ann – Annotations (Default value = [])

• color_ann – Colors used for annotations (see libfmp.b.b_plot.plot_segments()) (Default value = [])

Returns

• ax1 – First subplot

• ax2 – Second subplot

• ax3 – Third subplot

libfmp.c4.c4s5_evaluation.compare_pairwise(X)

Compute set of positive items from label sequence [FMP, Section 4.5.3]

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

X (list or np.ndarray) – Label sequence

Returns

I_pos (np.ndarray) – Set of positive items

libfmp.c4.c4s5_evaluation.convert_ann_to_seq_label(ann)

Convert structure annotation with integer time positions (given in indices) into label sequence

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

ann (list) – Annotation (list [[s, t, 'label'], ...], with s, t being integers)

Returns

X (list) – Sequencs of labels

libfmp.c4.c4s5_evaluation.evaluate_boundary(B_ref, B_est, tau)

Compute boundary evaluation measures [FMP, Section 4.5.4]

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• B_ref (np.ndarray) – Reference boundary annotations

• B_est (np.ndarray) – Estimated boundary annotations

• tau (int) – Tolerance parameter. Note: Condition |b_{k+1}-b_k|>2tau should be fulfilled [FMP, Eq. 4.58]

Returns

• P (float) – Precision

• R (float) – Recall

• F (float) – F-measure

• num_TP (int) – Number of true positives

• num_FN (int) – Number of false negatives

• num_FP (int) – Number of false positives

• B_tol (np.ndarray) – Data structure encoding B_ref with tolerance

• I_eval (np.ndarray) – Data structure encoding TP, FN, FP

libfmp.c4.c4s5_evaluation.evaluate_pairwise(I_ref_pos, I_est_pos)

Compute pairwise evaluation measures [FMP, Section 4.5.3]

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• I_ref_pos (np.ndarray) – Referenence set of positive items

• I_est_pos (np.ndarray) – Set of items being estimated as positive

Returns

• P (float) – Precision

• R (float) – Recall

• F (float) – F-measure

• num_TP (int) – Number of true positives

• num_FN (int) – Number of false negatives

• num_FP (int) – Number of false positives

• I_eval (np.ndarray) – Data structure encoding TP, FN, FP

libfmp.c4.c4s5_evaluation.measure_prf(num_TP, num_FN, num_FP)

Compute P, R, and F from size of TP, FN, and FP [FMP, Section 4.5.1]

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• num_TP (int) – True positives

• num_FN (int) – False negative

• num_FP (int) – False positives

Returns

• P (float) – Precision

• R (float) – Recall

• F (float) – F-measure

libfmp.c4.c4s5_evaluation.measure_prf_sets(I, I_ref_pos, I_est_pos, details=False)

Compute P, R, and F from sets I, I_ref_pos, I_est_pos [FMP, Section 4.5.1]

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• I – Set of items

• I_ref_pos – Reference set of positive items

• I_est_pos – Set of items being estimated as positive

• details – Print details (Default value = False)

Returns

• P (float) – Precision

• R (float) – Recall

• F (float) – F-measure

libfmp.c4.c4s5_evaluation.plot_boundary_measures(B_ref, B_est, tau, figsize=(8, 2.5))

Plot B_ref and B_est (see libfmp.c4.c4s5_evaluation.evaluate_boundary())

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• B_ref – Reference boundary annotations

• B_est – Estimated boundary annotations

• tau – Tolerance parameter

• figsize – Figure size (Default value = (8, 2.5))

Returns

• fig – Handle for figure

• ax – Handle for axes

libfmp.c4.c4s5_evaluation.plot_matrix_label(M, X, color_label=None, figsize=(3, 3), cmap='gray_r', fontsize=8, print_labels=True)

Plot matrix and label sequence

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• M – Matrix

• X – Label sequence

• color_label – List of colors for labels (Default value = None)

• figsize – Figure size (Default value = (3, 3))

• cmap – Colormap for imshow (Default value = ‘gray_r’)

• fontsize – Font size (Default value = 8)

• print_labels – Display labels inside Rectangles (Default value = True)

Returns

• fig – Handle for figure

• ax – Handle for axes

libfmp.c4.c4s5_evaluation.plot_matrix_pairwise(I_eval, figsize=(3, 2.5))

Plot matrix I_eval encoding TP, FN, FP (see libfmp.c4.c4s5_evaluation.evaluate_pairwise())

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• I_eval – Data structure encoding TP, FN, FP

• figsize – Figure size (Default value = (3, 2.5))

Returns

• fig – Handle for figure

• im – Handle for imshow

libfmp.c4.c4s5_evaluation.plot_seq_label(ax, X, Fs=1, color_label=[], direction='horizontal', fontsize=10, time_axis=False, print_labels=True)

Plot label sequence in the style of annotations

Notebook: C4/C4S5_Evaluation.ipynb

Parameters

• ax – Axis used for plotting

• X – Label sequence

• Fs – Sampling rate (Default value = 1)

• color_label – List of colors for labels (Default value = [])

• direction – Parameter used for libfmp.b.b_plot.plot_segments() (Default value = ‘horizontal’)

• fontsize – Parameter used for libfmp.b.b_plot.plot_segments() (Default value = 10)

• time_axis – Parameter used for libfmp.b.b_plot.plot_segments() (Default value = False)

• print_labels – Parameter used for libfmp.b.b_plot.plot_segments() (Default value = True)

Returns

ann_X – Structure annotation for label sequence