Transformer NMF Class

Non-negative Matrix Factorization

class nussl.transformers.transformer_nmf.TransformerNMF(input_matrix, num_components=50, activation_matrix=None, template_dictionary=None, distance_measure=None, should_update_activation=None, should_update_template=None, seed=None, max_num_iterations=50, should_do_epsilon=False, stopping_epsilon=10000000000.0)

Bases: object

This is an implementation of the Non-negative Matrix Factorization algorithm for general matrix transformations. This implementation receives an input matrix and num_components, which defines the number of basis vectors (also called the “dictionary”). This implementation uses the multiplicative update rules for euclidean distance and KL divergence as defined by Lee and Seung in [1].

References: [1] Lee, Daniel D., and H. Sebastian Seung. “Algorithms for non-negative matrix factorization.”

Advances in neural information processing systems. 2001.
  • input_matrix (np.array) – The matrix to factor into template and activation matrices (V)
  • num_components (int) – The rank of the resultant factorization matrix
  • activation_matrix (np.array) – Initial state for the activation matrix
  • template_dictionary (np.array) – Initial state for the template dictionary (W)
  • called 'components' and 'bases') ((also) –
  • distance_measure (str) – Specifies whether to use euclidean or divergence distance metrics (H)
  • should_update_activation (bool) – Whether the activation matrix should be updated for another iteration
  • should_update_template (bool) – Whether the template matrix should be updated at every iteration
  • seed (int) – A seed value for the random numbers. If None, no seed is used.
  • will be input to np.random.seed() (This) –
  • max_num_iterations (int) – Maximum number of times that the update rules will be computed
  • should_do_epsilon (bool) –
  • stopping_epsilon (float) –



:ref:’The Transformer NMF Demo Example <transformer_nmf_demo>’

EUCLIDEAN = 'euclidean'
KL_DIVERGENCE = 'kl_divergence'
ALL_DISTANCE_TYPES = ['euclidean', 'kl_divergence']

Calculates the distance between the original matrix (input_matrix) and the dot product of the current template (templates) and activation (activation_matrix) matrices using the distance type specified by ref:distance_measure. Returns:


PROPERTY A reconstruction of the original input_matrix, calculated by doing the dot product of the current values in templates and activation_matrix. :returns: (np.ndarray) of the same shape as input_matrix but containing the dot product of the

current values in templates and activation_matrix.

This runs Non-negative matrix factorization with update rules as outlined in [1].

  • activation_matrix (np.array) - a 2D numpy matrix containing the estimated activation matrix
  • templates (np.array) - a 2D numpy matrix containing the estimated templates


:: input_matrix = np.random.rand(10, 10) nussl_nmf = nussl.TransformerNMF(input_matrix, num_templates=2,

activation_matrix=None, templates=None, distance_measure=”euclidean”, should_update_template=None, should_update_activation=None)

nussl_nmf.transform() signals = nussl_nmf.recombine_calculated_matrices()


Computes a single update using the update function specified. :return: nothing

plot(output_file, matrix_to_dB=True, title=None, max_y=None, max_x=None, show_divider_lines=None)

Makes a fancy plot of NMF that shows the original input_matrix, activation_matrix, template_dictionary, and reconstructed_matrix.

  • output_file (string) – Path to the output file that will be created.
  • matrix_to_dB (bool) – Convert the values in all four matrices to dB-spaced values.
  • title (string) – Title for input matrix
  • max_y (int) – Max index to show along y-axis (Defaults to whole matrix)
  • max_x (int) – Max index to show along x-axis (Defaults to whole matrix)
  • show_divider_lines (bool) – Adds divider lines between activations/templates.

:param (Defaults to True if less than MAX_TEMPLATES_FOR_LINES lines.):