Direct Graphical Models  v.1.6.0
DirectGraphicalModels::fex::CSparseDictionary Class Reference

Sparse Dictionary Learning class. More...

#include <SparseDictionary.h>

Inheritance diagram for DirectGraphicalModels::fex::CSparseDictionary:

Public Member Functions

 CSparseDictionary (void)
 
virtual ~CSparseDictionary (void)
 
void train (const Mat &X, word nWords, dword batch=2000, unsigned int nIt=1000, float lRate=SC_LRATE_D, const std::string &fileName=std::string())
 Trains dictionary \(D\). More...
 
void save (const std::string &fileName) const
 Saves dictionary \(D\) into a binary file. More...
 
void load (const std::string &fileName)
 Loads dictionary \(D\) from the file. More...
 
bool empty (void) const
 Checks whether the dictionary has been trained or loaded. More...
 
Mat getDictionary (void) const
 Returns dictionary \(D\). More...
 
int getBlockSize (void) const
 Returns size of the block, i.e. \(\sqrt{sampleLen}\). More...
 
word getNumWords (void) const
 Returns the number words in dictionary \(D\). More...
 

Static Public Member Functions

static Mat getDictionary (const std::string &fileName)
 Returns dictionary \(D\) from file. More...
 
static Mat img2data (const Mat &img, int blockSize, float varianceThreshold=0.0f)
 Converts image into data \(X\). More...
 
static Mat data2img (const Mat &X, CvSize imgSize)
 Converts data \(X\) into an image. More...
 

Protected Types

enum  grad_type { GRAD_D, GRAD_W }
 

Static Protected Member Functions

static void calculate_W (const Mat &X, const Mat &D, Mat &W, float lambda, float epsilon, unsigned int nIt=800, float lRate=SC_LRATE_W)
 Evaluates weighting coefficients matrix \(W\). More...
 
static void calculate_D (const Mat &X, Mat &D, const Mat &W, float gamma, unsigned int nIt=800, float lRate=SC_LRATE_D)
 Evaluates dictionary \(D\). More...
 
static Mat calculateGradient (grad_type gType, const Mat &X, const Mat &D, const Mat &W, float lambda, float epsilon, float gamma)
 Calculates the gradient matrices \(\frac{\partial J(D, W)}{\partial D}\) and \(\frac{\partial J(D, W)}{\partial W}\). More...
 
static float calculateCost (const Mat &X, const Mat &D, const Mat &W, float lambda, float epsilon, float gamma)
 Calculates the value of \(J(D, W)\) function. More...
 

Detailed Description

Sparse Dictionary Learning class.

This class performs the Sparse dictionary learning, i.e. estimation of dictionary words (bases) \(\vec{d}_i\in D\), such that arbitrary data vector \(\vec{x}\) could be represended via a linear combination:

\[ \begin{align} \sum^{nWords}_{i=1} w_{i,j} \cdot \vec{d}_i = \vec{x}_j, & & \forall j \in [0; nSamples), & \text{ or} \\ \vec{w}_j \times D = \vec{x}_j, & & \forall j \in [0; nSamples), & \end{align} \]

where \(D\) is the dictionary.
The implementation is based on Sparse Coding: Autoencoder Interpretation article, where the task of the dictionary learning turns into the following minimization problem:

\[ \text{arg}\,\min\limits_{D,W} J(D, W) = \left\| W \times D - X \right\|^{2}_{2} + \lambda\left\|W\right\|_1 + \gamma\left\|D\right\|^{2}_{2}, \]

where \(D\in\mathbb{R}^{sampleLen \times nWords}\), \(W\in\mathbb{R}^{nWords \times nSamples}\) is the matrix, containing weighting coefficients for every word and every sample and \(X\in\mathbb{R}^{sampleLen \times nSamples}\) contains the training data as row-vectors samples.
In order to minimize \(J(D, W)\) we use the Gradient Descent algorithm.
We also use \(\sum_{i,j}\sqrt{w^{2}_{i,j} + \epsilon}\) in place of \(\left\|W\right\|_1\) to make \(J(D, W)\) differentiable at \(W = 0\).
In order to train the dictionary, one may use the code:

using namespace DirectGraphicalModels;
CSparseCoding *sparseCoding = new CSparseCoding(img);
Mat X = CSparseDictionary::img2data(img, blockSize); // sampleLen = blockSize * blockSize
sparseCoding->train(X, nWords);
sparseCoding->save("dictionary.dic");
Author
Sergey G. Kosov, serge.nosp@m.y.ko.nosp@m.sov@p.nosp@m.roje.nosp@m.ct-10.nosp@m..de

Definition at line 47 of file SparseDictionary.h.

Member Enumeration Documentation

◆ grad_type

Enumerator
GRAD_D 
GRAD_W 

Definition at line 194 of file SparseDictionary.h.

Constructor & Destructor Documentation

◆ CSparseDictionary()

DirectGraphicalModels::fex::CSparseDictionary::CSparseDictionary ( void  )
inline

Definition at line 50 of file SparseDictionary.h.

◆ ~CSparseDictionary()

virtual DirectGraphicalModels::fex::CSparseDictionary::~CSparseDictionary ( void  )
inlinevirtual

Definition at line 51 of file SparseDictionary.h.

Member Function Documentation

◆ calculate_D()

void DirectGraphicalModels::fex::CSparseDictionary::calculate_D ( const Mat &  X,
Mat &  D,
const Mat &  W,
float  gamma,
unsigned int  nIt = 800,
float  lRate = SC_LRATE_D 
)
staticprotected

Evaluates dictionary \(D\).

Finds the \(D\), that minimizes \(J(D, W)\) for the given \(W\):

\[ \text{arg}\,\min\limits_{D} J(D, W) = \left\| W \times D - X \right\|^{2}_{2} + \gamma\left\|D\right\|^{2}_{2}, \]

Parameters
[in]XTraining data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
[in,out]DDictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
[in]WWeighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
[in]gammaRegularisation parameter: \(\gamma\)
[in]nItNumber of iterations
[in]lRateLearning rate parameter, which is charged with the speed of convergence

Definition at line 236 of file SparseDictionary.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ calculate_W()

void DirectGraphicalModels::fex::CSparseDictionary::calculate_W ( const Mat &  X,
const Mat &  D,
Mat &  W,
float  lambda,
float  epsilon,
unsigned int  nIt = 800,
float  lRate = SC_LRATE_W 
)
staticprotected

Evaluates weighting coefficients matrix \(W\).

Finds the \(W\), that minimizes \(J(D, W)\) for the given \(D\):

\[ \text{arg}\,\min\limits_{W} J(D, W) = \left\| W \times D - X \right\|^{2}_{2} + \lambda\sum_{i,j}{\sqrt{w^{2}_{i,j} + \epsilon}} \]

Parameters
[in]XTraining data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
[in]DDictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
[in,out]WWeighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
[in]lambdaRegularisation parameter \(\lambda\)
[in]epsilonL1-regularisation parameter: \(\epsilon\)
[in]nItNumber of iterations
[in]lRateLearning rate parameter, which is charged with the speed of convergence

Definition at line 221 of file SparseDictionary.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ calculateCost()

float DirectGraphicalModels::fex::CSparseDictionary::calculateCost ( const Mat &  X,
const Mat &  D,
const Mat &  W,
float  lambda,
float  epsilon,
float  gamma 
)
staticprotected

Calculates the value of \(J(D, W)\) function.

Parameters
XTraining data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
DDictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
WWeighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
lambdaRegularisation parameter \(\lambda\)
epsilonL1-regularisation parameter: \(\epsilon\)
gammaRegularisation parameter: \(\gamma\)
Returns
The value of \(J(D, W)\) function

Definition at line 274 of file SparseDictionary.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ calculateGradient()

Mat DirectGraphicalModels::fex::CSparseDictionary::calculateGradient ( grad_type  gType,
const Mat &  X,
const Mat &  D,
const Mat &  W,
float  lambda,
float  epsilon,
float  gamma 
)
staticprotected

Calculates the gradient matrices \(\frac{\partial J(D, W)}{\partial D}\) and \(\frac{\partial J(D, W)}{\partial W}\).

This function calculates the gradient matrices:

\[\begin{align} \frac{\partial J(D, W)}{\partial D} &= \frac{2}{nSapmles} \cdot W^\top\times [W \times D - X] + 2\cdot\gamma\cdot D, &\text{ if gType = GRAD_D} \\ \frac{\partial J(D, W)}{\partial W} &= \frac{2}{nSapmles} \cdot [W \times D - X] \times D^\top + \lambda\frac{W}{\sqrt{W^2 + \epsilon}}, &\text{ if gType = GRAD_W} \end{align}\]

Parameters
gTypeGradient type
XTraining data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
DDictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
WWeighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
lambdaRegularisation parameter \(\lambda\)
epsilonL1-regularisation parameter: \(\epsilon\)
gammaRegularisation parameter: \(\gamma\)
Returns
Gradient matrix

Definition at line 250 of file SparseDictionary.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ data2img()

Mat DirectGraphicalModels::fex::CSparseDictionary::data2img ( const Mat &  X,
CvSize  imgSize 
)
static

Converts data \(X\) into an image.

This function performs reverse transformation of img2data() function, thus the code

Mat X = CSparseDictionary::img2data(img, blockSize, 0);
Mat res = CSparseDictionary::data2img(X, img.size());

gives res identical to img.

Parameters
XThe input data \(X\) (depth: 8 or 16 bit)
imgSizeThe size of the image to return
Returns
Resulting image: Mat(size: imgSize; type: CV_8UC1 or CV_16UC1)

Definition at line 193 of file SparseDictionary.cpp.

◆ empty()

bool DirectGraphicalModels::fex::CSparseDictionary::empty ( void  ) const
inline

Checks whether the dictionary has been trained or loaded.

Return values
trueif the dictionary has been trained or loaded
falseotherwise

Definition at line 82 of file SparseDictionary.h.

Here is the caller graph for this function:

◆ getBlockSize()

int DirectGraphicalModels::fex::CSparseDictionary::getBlockSize ( void  ) const
inline

Returns size of the block, i.e. \(\sqrt{sampleLen}\).

Returns
blockSize

Definition at line 103 of file SparseDictionary.h.

Here is the call graph for this function:

◆ getDictionary() [1/2]

Mat DirectGraphicalModels::fex::CSparseDictionary::getDictionary ( void  ) const
inline

Returns dictionary \(D\).

Returns
Dictionary \(D\): Mat(size: nWords x sampleLen; type: CV_32FC1)

Definition at line 87 of file SparseDictionary.h.

Here is the caller graph for this function:

◆ getDictionary() [2/2]

static Mat DirectGraphicalModels::fex::CSparseDictionary::getDictionary ( const std::string &  fileName)
inlinestatic

Returns dictionary \(D\) from file.

Parameters
fileNameFull file name
Returns
Dictionary \(D\): Mat(size: nWords x sampleLen; type: CV_32FC1)

Definition at line 93 of file SparseDictionary.h.

Here is the call graph for this function:

◆ getNumWords()

word DirectGraphicalModels::fex::CSparseDictionary::getNumWords ( void  ) const
inline

Returns the number words in dictionary \(D\).

Returns
nWords

Definition at line 108 of file SparseDictionary.h.

Here is the call graph for this function:

◆ img2data()

Mat DirectGraphicalModels::fex::CSparseDictionary::img2data ( const Mat &  img,
int  blockSize,
float  varianceThreshold = 0.0f 
)
static

Converts image into data \(X\).

This functions generates a set of data samples (blockSize x blockSize patches) from a single image. The extracted pathces are overlapping, thus the maximal number of data samples is: nMaxSamples = (img.width - blockSize + 1) x (img.height - blockSize + 1)

It is recommended to suffle the samples with parallel::shuffleRows() function before training dictionary with train()

Parameters
imgThe input image (1 or 3 channels, 8 or 16 bit image)
blockSizeSize of the quadratic patch

In order to use this calss with fex::CSparseCoding::get() the size of the block should be odd

varianceThresholdThe extracted samples with variance greater or equal to varianceThreshold will be included to \(X\).

If varianceThreshold = 0 all the samples are included, thus nSamples = nMaxSamples

Returns
Data \(X\): Mat(size: nSamples x blockSize^2; type: CV_8UC1 or CV_16UC1)

Definition at line 162 of file SparseDictionary.cpp.

Here is the caller graph for this function:

◆ load()

void DirectGraphicalModels::fex::CSparseDictionary::load ( const std::string &  fileName)

Loads dictionary \(D\) from the file.

Parameters
fileNameFull file name

Definition at line 87 of file SparseDictionary.cpp.

Here is the caller graph for this function:

◆ save()

void DirectGraphicalModels::fex::CSparseDictionary::save ( const std::string &  fileName) const

Saves dictionary \(D\) into a binary file.

Parameters
fileNameFull file name

Definition at line 78 of file SparseDictionary.cpp.

Here is the caller graph for this function:

◆ train()

void DirectGraphicalModels::fex::CSparseDictionary::train ( const Mat &  X,
word  nWords,
dword  batch = 2000,
unsigned int  nIt = 1000,
float  lRate = SC_LRATE_D,
const std::string &  fileName = std::string() 
)

Trains dictionary \(D\).

This function creates and trains new dictionary \(D\) on data \(X\)

Parameters
XTraining data \(X\): Mat(size nSamples x sampleLen; type CV_8UC1 or CV_16UC1)

May be derived from an image with img2data() fucntion

nWordsLength of the dictionary (number of words)
batchThe number of randomly chosen samples from X to be used in every distinct iteration of training

This parameter must be smaller or equal to the number of samples in training data \(X\)

nItNumber of iterations
lRateLearning rate parameter, which is charged with the speed of convergence
fileNamePath and file name to store intermediate dictionaries \(D\) (every 5 iterations). If specified the resulting file name will be the follows: fileName<it/5>.dic

Definition at line 9 of file SparseDictionary.cpp.

Here is the call graph for this function:

The documentation for this class was generated from the following files: