Utilities¶
The module utilities.py, when imported, allows search.py, transform.py and
assemble.py in the repytah package to run smoothly.
This module contains the following functions:
- create_sdm(fv_mat, num_fv_per_shingle)¶
Creates self-dissimilarity matrix; this matrix is found by creating audio shingles from feature vectors, and finding the cosine distance between shingles.
- Parameters
- fv_matnp.ndarray
Matrix of feature vectors where each column is a time step and each row includes feature information i.e. an array of 144 columns/beats and 12 rows corresponding to chroma values.
- num_fv_per_shingleint
Number of feature vectors per audio shingle.
- Returns
- self_dissim_matnp.ndarray
Self-dissimilarity matrix with paired cosine distances between shingles.
- find_initial_repeats(thresh_mat, bandwidth_vec, thresh_bw)¶
Looks for the largest repeated structures in thresh_mat. Finds all repeated structures, represented as diagonals present in thresh_mat, and then stores them with their start/end indices and lengths in a list. As each diagonal is found, they are removed to avoid identifying repeated sub-structures.
- Parameters
- thresh_matnp.ndarray[int]
Thresholded matrix that we extract diagonals from.
- bandwidth_vecnp.ndarray[1D,int]
Array of lengths of diagonals to be found. Should be 1, 2, 3, …, n where n is the number of timesteps.
- thresh_bwint
Smallest allowed diagonal length.
- Returns
- all_lstnp.ndarray[int]
List of pairs of repeats that correspond to diagonals in thresh_mat.
- stretch_diags(thresh_diags, band_width)¶
Creates a binary matrix with full length diagonals from a binary matrix of diagonal starts and length of diagonals.
- Parameters
- thresh_diagsnp.ndarray
Binary matrix where entries equal to 1 signals the existence of a diagonal.
- band_widthint
Length of encoded diagonals.
- Returns
- stretch_diag_matnp.ndarray[bool]
Logical matrix with diagonals of length band_width starting at each entry prescribed in thresh_diag.
- add_annotations(input_mat, song_length)¶
Adds annotations to the pairs of repeats in input_mat.
- Parameters
- input_matnp.ndarray
List of pairs of repeats. The first two columns refer to the first repeat of the pair. The third and fourth columns refer to the second repeat of the pair. The fifth column refers to the repeat lengths. The sixth column contains any previous annotations, which will be removed.
- song_lengthint
Number of audio shingles in the song.
- Returns
- anno_listnp.ndarray
List of pairs of repeats with annotations marked.
- reconstruct_full_block(pattern_mat, pattern_key)¶
Creates a record of when pairs of repeated structures occur, from the first beat in the song to the end. This record is a binary matrix with a block of 1’s for each repeat encoded in pattern_mat whose length is encoded in pattern_key.
- Parameters
- pattern_matnp.ndarray
Binary matrix with 1’s where repeats begin and 0’s otherwise.
- pattern_keynp.ndarray
Vector containing the lengths of the repeats encoded in each row of pattern_mat.
- Returns
- pattern_blocknp.ndarray
Binary matrix representation for pattern_mat with blocks of 1’s equal to the length’s prescribed in pattern_key.
- get_annotation_lst(key_lst)¶
Creates one annotation marker vector, given vector of lengths key_lst.
- Parameters
- key_lstnp.ndarray[int]
Array of lengths in ascending order.
- Returns
- anno_lst_outnp.ndarray[int]
Array of one possible set of annotation markers for key_lst.
- get_y_labels(width_vec, anno_vec)¶
Generates the labels for visualization with width_vec and anno_vec.
- Parameters
- width_vecnp.ndarray[int]
Vector of widths for a visualization.
- anno_vecnp.ndarray[int]
Array of annotations for a visualization.
- Returns
- y_labelsnp.ndarray[str]
Labels for the y-axis of a visualization.
- reformat(pattern_mat, pattern_key)¶
Transforms a binary array with 1’s where repeats start and 0’s otherwise into a list of repeated structures. This list consists of information about the repeats including length, when they occur and when they end.
Every row has a pair of repeated structure. The first two columns are the time steps of when the first repeat of a repeated structure start and end. Similarly, the second two columns are the time steps of when the second repeat of a repeated structure start and end. The fifth column is the length of the repeated structure.
Reformat is not used in the main process for creating the aligned-hierarchies. It is helpful when writing example inputs for the tests.
- Parameters
- pattern_matnp.ndarray
Binary array with 1’s where repeats start and 0’s otherwise.
- pattern_keynp.ndarray
Array with the lengths of each repeated structure in pattern_mat.
- Returns
- info_matnp.ndarray
Array with the time steps of when the pairs of repeated structures start and end organized.