bnmf_algs::nmf Namespace Reference

Namespace that contains solver and auxiliary functions for computing Nonnegative Matrix Factorization (NMF) of a matrix.. More...

Functions
template<typename T , typename Real >
std::pair< matrix_t< T >, matrix_t< T > >	nmf (const matrix_t< T > &X, size_t r, Real beta, size_t max_iter=1000)
	Compute nonnegative matrix factorization of a matrix. More...
template<typename Real >
Real	beta_divergence (Real x, Real y, Real beta, double eps=1e-50)
	Compute the \(\beta\)-divergence as defined in [3]. More...
template<typename Tensor >
Tensor::value_type	beta_divergence (const Tensor &X, const Tensor &Y, typename Tensor::value_type beta, double eps=1e-50)
	Return \(\beta\)-divergence between two tensor-like objects as defined in bnmf_algs::vector_t , bnmf_algs::matrix_t , bnmf_algs::tensor_t. More...
template<typename InputIterator1 , typename InputIterator2 >
auto	beta_divergence_seq (InputIterator1 first_begin, InputIterator1 first_end, InputIterator2 second_begin, decltype(*first_begin) beta, double eps=1e-50)
	Compute the \(\beta\)-divergence as defined in [3]. More...

Detailed Description

Namespace that contains solver and auxiliary functions for computing Nonnegative Matrix Factorization (NMF) of a matrix..

Function Documentation

template<typename Real >

Real bnmf_algs::nmf::beta_divergence	(	Real	x,
		Real	y,
		Real	beta,
		double	eps = 1e-50
	)

Compute the \(\beta\)-divergence as defined in [3].

This function computes the \(\beta\)-divergence between two scalars which is given as

\[ d_{\beta}(x|y) = \begin{cases} \frac{1}{\beta(\beta - 1)}(x^{\beta} + (\beta - 1)y^{\beta} - \beta xy^{\beta - 1}), & \beta \in \mathcal{R}\setminus \{0,1\} \\ x\log{\frac{x}{y}} - x + y, & \beta = 1 \\ \frac{x}{y} - \log{\frac{x}{y}} - 1, & \beta = 0 \end{cases} \]

Regular cost functions in NMF can be obtained using certain values of \(\beta\). In particular, \(\beta = 0\) corresponds to Itakuro-Saito divergence, \(\beta = 1\) corresponds to Kullback-Leibler divergence and \(\beta = 2\) corresponds to Euclidean cost (square of Euclidean distance).

Template Parameters

Real	Type of the values whose beta divergence will be computed.

Parameters

x	First value. If \(x=0\) and beta is 0 (IS) or 1 (KL), the terms containing x is not used during IS or KL computation.
y	Second value.
beta	\(\beta\)-divergence parameter.
eps	Epsilon value to prevent division by 0.

Returns

\(\beta\)-divergence between the two scalars.

template<typename Tensor >

Tensor::value_type bnmf_algs::nmf::beta_divergence	(	const Tensor &	X,
		const Tensor &	Y,
		typename Tensor::value_type	beta,
		double	eps = 1e-50
	)

Return \(\beta\)-divergence between two tensor-like objects as defined in bnmf_algs::vector_t , bnmf_algs::matrix_t , bnmf_algs::tensor_t.

Template Parameters

Tensor

Type of the tensor-like object with a compile-time value_type field denoting the type of the entries.

Parameters

X	First tensor-like object (vector/matrix/tensor).
Y	Second tensor-like object (vector/matrix/tensor).
beta	\(\beta\)-divergence parameter.
eps	Epsilon value to prevent division by 0.

Returns

Sum of \(\beta\)-divergence of each pair of corresponding elements in the given two tensor-like objects.

See also

nmf::beta_divergence.

template<typename InputIterator1 , typename InputIterator2 >

auto bnmf_algs::nmf::beta_divergence_seq	(	InputIterator1	first_begin,
		InputIterator1	first_end,
		InputIterator2	second_begin,
		decltype *first_begin	beta,
		double	eps = 1e-50
	)

Compute the \(\beta\)-divergence as defined in [3].

This function computes the \(\beta\)-divergence between each corresponding item in the given two sequences and then returns the summed divergence value.

Template Parameters

InputIterator1	Iterator type of the first sequence.
InputIterator2	Iterator type of the second sequence.

Parameters

first_begin	Beginning of the first sequence.
first_end	End of the first sequence.
second_begin	Beginning of the second sequence.
beta	\(\beta\)-divergence parameter.
eps	Epsilon value to prevent division by 0.

Returns

Sum of \(\beta\)-divergence of each corresponding element in the given two sequences.

See also

nmf::beta_divergence.

template<typename T , typename Real >

std::pair<matrix_t<T>, matrix_t<T> > bnmf_algs::nmf::nmf	(	const matrix_t< T > &	X,
		size_t	r,
		Real	beta,
		size_t	max_iter = 1000
	)

Compute nonnegative matrix factorization of a matrix.

According to the NMF model, nonnegative matrix X is factorized into two nonnegative matrices W and H such that

     X = WH

where X is (m x n), W is (m x r) and H is (r x n) nonnegative matrices. For original NMF paper, see [6] and [7].

Template Parameters

T	Type of the matrix entries.
Real	Type of beta.

Parameters

X	(m x n) nonnegative matrix.
r	Inner dimension of the factorization. Must be positive.
beta	\(\beta\)-divergence parameter. \(\beta = 0\) corresponds to Itakuro-Saito divergence, \(\beta = 1\) corresponds to Kullback-Leibler divergence and \(\beta = 2\) corresponds to Euclidean cost (square of Euclidean distance). Note that beta values different than these values may result in considerably slower convergence.
max_iter	Maximum number of iterations. If set to 0, the algorithm runs until convergence.

Returns

std::pair of W and H matrices.

Todo:

Add SVD initialization. See [2].

Exceptions

std::invalid_argument

if \(X\) is not nonnegative, if r is not positive, epsilon is not positive