Documentation

tnmf.py

Contents

The tnmf module is used to perform task-driven nonnegative matrix factorisation (TNMF). It includes the SupervisedDL class, fit and score methods

Created on Wed Jun 29 16:37:28 2016

@authors: bisot, serizel

[1]	V.Bisot, R. Serizel, S. Essid, and G. Richard. “Feature Learning with Matrix Factorization Applied to Acoustic Scene Classification”. Accepted for publication in IEEE Transactions on Audio, Speech and Language Processing, 2017

class tnmf.SupervisedDL(data=array([[0, 0]]), n_components=64, n_labels=2, pos=True, n_iter=1, lambda1=0, lambda2=0, rho=0.001, verbose=0, mu=1, agreg=1, init='random', n_iter_init=10, batch_size=6250, max_iter_init=10, max_iter_inloop=1)

Supervised DL class

Task-driven Dictionary Learning with modified algorithm

Parameters:

data : array, shape (n_samples, n_features)

Training data matrix Needs to be provided if initialization is done in the model

n_components : int

Size of the dictionary

n_labels : int

number of classes

pos : bool, default: True

When set to True, the model is fit in its nonnegative formulation

n_iter : int

Number of epochs on which to run the algorithm

lambda1 : float, default: 0.1

Paramter controlling the l1 norm penality for the projection step

lambda2 : float, default: 0

Paramter controlling the l2 norm penality for the projection step

rho : float, default: 0.001

Initial gradient step parameter

mu : float, default: 1

Regularization strenght of the classifier; must be positive. Smaller values specify stronger regularization.

agreg : int, optional (default: 1)

In the case classification is done on bags of agreg successive projections. Every successive group of agreg projections (without overlapp) will be averaged before classification

init : str, {‘random’, ‘nmf’, ‘dic-learning’}

Controls the nature of the dictionary initialization.

• Use ‘random’ for a random initalization of
• Use ‘nmf’ for intializaing with nonnegative matrix factorization
• Use ‘dic-learning’ to intilaize with the scikit-learn DictionaryLearning class

n_iter_init : int, optional

Number of iterations for the dictionary initialization

max_iter_init : int, optional

Maximum number of iterations for the classifier initialization

max_iter_inloop : int, optional

Maximum number of iterations at each epoch for the classifier update

batch_size : int, optional

Size of the batch (1 for stochastic gradient)

verbose : int

Set verbose to any positive number for verbosity.

Attributes

clf	(object) Classifier
D	(array) Dictionnary

Methods

fit(X_train, y_train[, X_test, dtype, ...])	Fits the model to input training data
mean_frames([X, agreg])	Averages every successive group of agreg rows in the a matrix
predict(X)	Predicts labels from a given matrix using the model classifier
project_data(X[, agreg])	Projects data on the model dictionary
scores(X, y)	Compute classification scores (accurracy and F1-score).
update_D([x_mat, y, alpha_mat, denom, ...])	Updates dictionary

fit(X_train, y_train, X_test=array([], dtype=float64), y_test=array([], dtype=float64))

Fits the model to input training data

Parameters:

X_train : array, shape (n_samples, n_features)

Training data matrix

X_test : array, shape (n_samples_test, n_features), optional

Test data matrix Usefull only to check performance during development

y_train : array-like, shape (n_samples/self.agreg,)

Target vector relative to X_train.

y_train : array-like, shape (n_samples_test/self.agreg,)

Target vector relative to X_test.

mean_frames(X=0, agreg=15)

Averages every successive group of agreg rows in the a matrix

Parameters:

X : array, shape (n_samples, n_features)

Matrix to reduce by averaging

agreg : int

Specifies size of the groups to average

Returns:

X_mean: array, shape(n_samples/agreg, n_features)

Averaged matrix

predict(X)

Predicts labels from a given matrix using the model classifier

Parameters:

X : array, shape (n_samples, n_features)

Matrix to project on dictoonary

Returns:

y_pred: array, shape(n_samples/agreg,)

Predicted labels

project_data(X, agreg=1)

Projects data on the model dictionary

Parameters:

X : array, shape (n_samples, n_features)

Matrix to project on dictoonary

agreg : int

Specifies size of the groups to average after projection

Returns:

projections: array, shape(n_samples/agreg, n_components)

Projection matrix

scores(X, y)

Compute classification scores (accurracy and F1-score). on a given dataset.

Parameters:

X_train : array, shape (n_samples, n_features)

Training data matrix

X_test : array, shape (n_samples_test, n_features), optional

Test data matrix Usefull only to check performance during development

y_train : array-like, shape (n_samples/self.agreg,)

Target vector relative to X_train.

y_train : array-like, shape (n_samples_test/self.agreg,)

Target vector relative to X_test.

Returns:

y_pred: array, shape(n_samples/agreg,)

update_D(x_mat=0, y=0, alpha_mat=0, denom=0, num_alpha=0, d_alpha=0, rho_t=0.001)

Updates dictionary

Parameters:

x_mat : array shape (n_features, batch_size)

Input data (batch_size = 1 in the stochastic gradient case)

y : array shape (batch_size, )

Labels corresponding to the input data

alpha_mat : array shape (batch_size, n_components)

Projections

d_alpha : array shape (batch_size, n_components)

Gradient of loss with respect to projections

denom : array shape (n_components, )

Gradient denominator

num_alpha : array (batch_size, n_components)

Gradient numerator

rho_t : float

Learning rate

tgnmf.py

Contents

The tgnmf module is used to perform task-driven group nonnegative matrix factorisation (TGNMF). It includes the SupervisedDL class, fit and score methods

Created on Wed Jun 29 16:37:28 2016

@authors: bisot, serizel

[2]	V.Bisot, R. Serizel, S. Essid, and G. Richard. “Feature Learning with Matrix Factorization Applied to Acoustic Scene Classification”. Accepted for publication in IEEE Transactions on Audio, Speech and Language Processing, 2017

[3]	R. Serizel, V.Bisot, S. Essid, and G. Richard. “Supervised group nonnegative matrix factorisation with similarity constraints and applications to speaker identification”. In Proc. of 2017 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP), 2017.

class tgnmf.SupervisedDL(data=array([[0, 0]]), n_labels=2, pos=True, n_iter=1, lambda1=0, lambda2=0, rho=0.001, verbose=0, mu=1, agreg=1, init='random', n_iter_init=10, batch_size=6250, max_iter_init=10, max_iter_inloop=1, max_iter_fin=0, lbl=array([[0, 0]]), ses_train=0, sub_dict_size=1, k_cls=0, k_ses=0, nu1=0, nu2=0)

Supervised DL class

Task-driven Dictionary Learning with modified algorithm

Parameters:

data : array, shape (n_samples, n_features)

Training data matrix Needs to be provided if initialization is done in the model

n_labels : int

number of classes

pos : bool, default: True

When set to True, the model is fit in its nonnegative formulation

n_iter : int

Number of epochs on which to run the algorithm

lambda1 : float, default: 0.1

Paramter controlling the l1 norm penality for the projection step

lambda2 : float, default: 0

Paramter controlling the l2 norm penality for the projection step

rho : float, default: 0.001

Initial gradient step parameter

mu : float, default: 1

Regularization strenght of the classifier; must be positive. Smaller values specify stronger regularization.

agreg : int, optional (default: 1)

In the case classification is done on bags of agreg successive projections. Every successive group of agreg projections (without overlapp) will be averaged before classification

init : str, {‘random’, ‘nmf’, ‘dic-learning’}

Controls the nature of the dictionary initialization.

• Use ‘random’ for a random initalization of
• Use ‘nmf’ for intializaing with nonnegative matrix factorization
• Use ‘dic-learning’ to intilaize with the scikit-learn DictionaryLearning class

n_iter_init : int, optional

Number of iterations for the dictionary initialization

max_iter_init : int, optional

Maximum number of iterations for the classifier initialization

max_iter_inloop : int, optional

Maximum number of iterations at each epoch for the classifier update

max_iter_fin : int, optional

Maximum number of iterations once the dictionnary is learnt

batch_size : int, optional

Size of the batch (1 for stochastic gradient)

lbl : array (n_couples, 2)

Unique (class, session) couples (See also [3])

• ‘lbl[:, 0]’: class labels
• ‘lbl[:, 1]’: session labels

This is equivalent to the attribute ‘self.iters[‘cls’]’ in GNMF

ses_train : array (n_samples, 1)

Session labels for the data

sub_dict_size : int

Size of the sub-dictionnaries related to a unique couple (cls, ses) See also [3]

k_cls : int

Number of components that are affected to cls related bases. See also [3]

k_ses : int

Number of components that are affected to ses related bases. See also [3]

nu1 : float

Class similarity constraint See also [3]

nu2 : float

Session similarity constraint See also [3]

verbose : int

Set verbose to any positive number for verbosity.

References

[4]	R. Serizel, S. Essid, and G. Richard. “Group nonnegative matrix factorisation with speaker and session variability compensation for speaker identification”. In Proc. of 2016 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP), pp. 5470-5474, 2016.

Attributes

clf	(object) Classifier
D	(array) Dictionnary
n_components	(int) Size of the dictionary
dist_ses	(array) Distance between bases related to the same session
dist_cls :	Distance between bases related to the same class
cst	(array) Update constraint computed from dist_ses and dist_cls

Methods

compute_cst()	Compute the update constraints based on the distance between
fit(X_train, y_train[, X_test, dtype, ...])	Fits the model to input training data
mean_frames([X, agreg])	Averages every successive group of agreg rows in the a matrix
predict(X)	Predicts labels from a given matrix using the model classifier
project_data(X[, agreg])	Projects data on the model dictionary
scores(X, y)	Compute classification scores (accurracy and F1-score).
update_D([x_mat, y, alpha_mat, denom, ...])	Updates dictionary

compute_cst()

Compute the update constraints based on the distance between session related bases and the distance between class related bases

fit(X_train, y_train, X_test=array([], dtype=float64), y_test=array([], dtype=float64))

Fits the model to input training data

Parameters:

X_train : array, shape (n_samples, n_features)

Training data matrix

X_test : array, shape (n_samples_test, n_features), optional

Test data matrix Usefull only to check performance during development

y_train : array-like, shape (n_samples/self.agreg,)

Target vector relative to X_train.

y_train : array-like, shape (n_samples_test/self.agreg,)

Target vector relative to X_test.

mean_frames(X=0, agreg=15)

Averages every successive group of agreg rows in the a matrix

Parameters:

X : array, shape (n_samples, n_features)

Matrix to reduce by averaging

agreg : int

Specifies size of the groups to average

Returns:

X_mean: array, shape(n_samples/agreg, n_features)

Averaged matrix

predict(X)

Predicts labels from a given matrix using the model classifier

Parameters:

X : array, shape (n_samples, n_features)

Matrix to project on dictoonary

Returns:

y_pred: array, shape(n_samples/agreg,)

Predicted labels

project_data(X, agreg=1)

Projects data on the model dictionary

Parameters:

X : array, shape (n_samples, n_features)

Matrix to project on dictoonary

agreg : int

Specifies size of the groups to average after projection

Returns:

projections: array, shape(n_samples/agreg, n_components)

Projection matrix

scores(X, y)

Compute classification scores (accurracy and F1-score). on a given dataset.

Parameters:

X_train : array, shape (n_samples, n_features)

Training data matrix

X_test : array, shape (n_samples_test, n_features), optional

Test data matrix Usefull only to check performance during development

y_train : array-like, shape (n_samples/self.agreg,)

Target vector relative to X_train.

y_train : array-like, shape (n_samples_test/self.agreg,)

Target vector relative to X_test.

Returns:

y_pred: array, shape(n_samples/agreg,)

update_D(x_mat=0, y=0, alpha_mat=0, denom=0, num_alpha=0, d_alpha=0, rho_t=0.001, ses=0)

Updates dictionary

Parameters:

x_mat : array shape (n_features, batch_size)

Input data (batch_size = 1 in the stochastic gradient case)

y : array shape (batch_size, )

Labels corresponding to the input data

alpha_mat : array shape (batch_size, n_components)

Projections

d_alpha : array shape (batch_size, n_components)

Gradient of loss with respect to projections

denom : array shape (n_components, )

Gradient denominator

num_alpha : array (batch_size, n_components)

Gradient numerator

rho_t : float

Learning rate

ses : array (batch_size, )

Session labels for the data