Assemble

The module assemble.py finds and forms essential structure components, which are the smallest building blocks that form every repeat in the song. These functions ensure that each time step of a song is contained in at most one of the song’s essential structure components by checking that there are no overlapping repeats in time. When repeats overlap, they undergo a process where they are divided until there are only non-overlapping pieces left.

This module contains the following functions:

breakup_overlaps_by_intersect(input_pattern_obj, bw_vec, thresh_bw)

Extracts repeats in input_pattern_obj that has the starting indices of the repeats, into the essential structure components using bw_vec, that has the lengths of each repeat. The essential structure components are the smallest building blocks that form every repeat in the song.

Parameters:
input_pattern_objnp.ndarray

Binary matrix with 1’s where repeats begin and 0’s otherwise.

bw_vecnp.ndarray

Vector containing the lengths of the repeats encoded in input_pattern_obj.

thresh_bwint

Smallest allowable repeat length.

Returns:

pattern_no_overlapsnp.ndrray

Binary matrix with 1’s where repeats of essential structure components begin.

pattern_no_overlaps_keynp.ndarray

Vector containing the lengths of the repeats of essential structure components in pattern_no_overlaps.

check_overlaps(input_mat)

Compares every pair of groups and determines if there are any repeats in any pairs of the groups that overlap.

Parameters:
input_matnp.array[int]

Matrix to be checked for overlaps.

Returns:

overlaps_ynnp.array[bool]

Logical array where (i,j) = 1 if row i of input matrix and row j of input matrix overlap and (i,j) = 0 elsewhere.

hierarchical_structure(matrix_no_overlaps, key_no_overlaps, sn, vis=False)

Distills the repeats encoded in matrix_no_overlaps (and key_no_overlaps) to the essential structure components and then builds the hierarchical representation. Optionally shows visualizations of the hierarchical structure via the vis argument.

Parameters:
matrix_no_overlapsnp.ndarray[int]

Binary matrix with 1’s where repeats begin and 0’s otherwise.

key_no_overlapsnp.ndarray[int]

Vector containing the lengths of the repeats encoded in matrix_no_overlaps.

snint

Song length, which is the number of audio shingles.

visbool

Shows visualizations if True (default = False).

Returns:

full_visualizationnp.ndarray[int]

Binary matrix representation for full_matrix_no_overlaps with blocks of 1’s equal to the length’s prescribed in full_key.

full_keynp.ndarray[int]

Vector containing the lengths of the hierarchical structure encoded in full_matrix_no_overlaps.

full_matrix_no_overlapsnp.ndarray[int]

Binary matrix with 1’s where hierarchical structure begins and 0’s otherwise.

full_anno_lstnp.ndarray[int]

Vector containing the annotation markers of the hierarchical structure encoded in each row of full_matrix_no_overlaps.