Utilities — repytah 0.1.0dev documentation

# 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.