FAQ » History » Version 17
Version 16 (Ivan Damnjanovic, 2011-03-30 04:51 PM) → Version 17/50 (Ivan Damnjanovic, 2011-03-30 04:58 PM)
h1. FAQ
h2. Q1: What is SMALLbox?
*SMALLbox* is an evaluation framework for processing signals using adaptive sparse structured representations. SMALLbox is built within FP7 EU FET project called "SMALL" that is exploring new provably good methods to obtain inherently data-driven sparse models, which are able to cope with large-scale and complicated data. The main focus of research in the area of *sparse representations* is in developing reliable algorithms with provable performance and bounded complexity. There exist many applications for which it was proven beneficial to sparsely represent the data in some transform domain (i.e. "dictionary"). Moreover, the success of sparse models heavily depends on the choice of a “dictionary” to reflect the natural structures of a class of data. *Dictionary learning for sparse representation* deals with inferring such a dictionary from training data and is a key to the extension of sparse models for new exotic types of data.
SMALLbox provides an easy way to evaluate these methods against state-of-the art alternatives in a variety of standard signal processing problems. This is achieved trough a unifying interface that enables a seamless connection between the three types of modules: problems, dictionary learning algorithms and sparse solvers. In addition, it provides interoperability between existing state-of-the-art toolboxes.
As an open source MATLAB toolbox, the SMALLbox can be seen as not only as a evaluation and educational tool, but as a tool for reproducible research in the sparse representations research community.
h2. Q2: How to obtain SMALLbox?
The SMALLbox project is maintained by people at the "Centre for Digital Music at SEECS, Queen Mary University of London":http://www.elec.qmul.ac.uk/digitalmusic/. To access the SMALLbox project page follow the link bellow:
https://code.soundsoftware.ac.uk/projects/smallbox/
If you want to try the latest stable public release please go to *Downloads* section. If you want to check the latest development and to contribute to the project then please first register to soundsoftware.ac.uk following the link in the upper right corner of the page.
The code repository hosted at soundsoftware.ac.uk is using Mercurial distributed version control, so you will need mercurial installed on your system. If you are new to mercurial the easiest way to start is to install EasyMercurial, which you can find at https://code.soundsoftware.ac.uk/projects/easyhg.
To check out SMALLbox repository please hg clone the following URL, or provide this URL to your preferred Mercurial client (e.g. EasyMercurial):
https://code.soundsoftware.ac.uk/hg/smallbox
h2. Q3: How to install SMALLbox?
To install the toolbox run the script *SMALLboxSetup.m* from the MATLAB command prompt and follow the instructions. *SmallboxSetup.m* is in the root SMALLbox directory. The SMALLbox installation involves the automatic download of several existing toolboxes. These are described in Q5. Due to the automatic download of toolboxes you must have an active internet connection.
Please note that within the toolboxes are several MEX components that must be compiled. If you do not already have MEX setup, run "mex -setup" or type "help mex" in the MATLAB command prompt.
Once installed, there are two optional demo functions that can be run. Further information can be found in the README.txt in the main SMALLbox directory.
h2. Q4: What are the Problem, solver, and DL structures in SMALLbox?
There are three main structures in SMALLbox that describe common parts of problem solving using sparse representation and dictionary learning - *Problem*, *DL* and *solver* structures.
The *Problem* structure defines all necessary aspects of a problem to be solved. To be compatible with the SPARCO, it needs to have five fields defined prior to any sparse representation of the data: *A* – a matrix or operator representing dictionary in which signal is sparse, *b* – a vector or matrix representing signal or signals to be represented, *reconstruct* – a function handle to reconstruct the signal from coefficients, *signalSize* – the dimension of the signal, *sizeA* – if matrix A is given as an operator the size of the dictionary needs to be defined in advance. Other fields that further describe the problem, which are useful for either reconstruction of the signal or representation of the results, might be generated by the SPARCO generateProblem function or the SMALLbox problem functions. The new problems implemented in the SMALLbox version 1.0 are: Image De-noising, Automatic Music Transcription and Image Representation using another image as a dictionary. In the case of a dictionary learning problem, fields *A* and *reconstruct* are not defined while generating the problem, but after the dictionary is learned and prior to the sparse representation. In this case, field *b* needs to be given in matrix form to represent the training data and another field *p* defining the number of dictionary elements to be learned needs to be specified.
The structure for dictionary learning - *DL* is a structure that defines dictionary learning algorithm to be used. It is initialised with a utility function *SMALL_init_DL*, which will define five mandatory fields: *toolbox* - a field used to discriminate the API, *name* - the name of dictionary learning function from the particular toolbox, *param* - a field containing parameters for the particular DL technique and in the form given by the toolbox API, *D* - a field where the learned dictionary will be stored, *time* - a field to store learning time. After *toolbox*, *name* and *param* fields are set, the function *SMALL_learn* is called with *Problem* and *DL* structures as inputs. According to the DL.toolbox field, the function calls the DL.name algorithm with its API and outputs learned dictionary D and time spent. The DL.param field contains parameters such as dictionary size, the number of iterations, the error goal or similar depending on the particular algorithm used.
Similar to dictionary learning every instance of the sparse representation needs to be initialised with the *SMALL_init_solver* function. It will define mandatory fields of the *solver* structure: *toolbox* - a field with toolbox name (e.g. sparselab), *name* - the name of solver from the particular toolbox (e.g. SolveOMP), *param* - the parameters in the form given by the toolbox API, *solution* - the output representation, *reconstructed* - the signal reconstructed from solution, *time* - the time spent for sparse representation. With the input parameters of the solver structure set, the *SMALL_solve* function is called with *Problem* and *solver* structure as inputs. The function calls *solver.name* algorithm with API specified by *solver.toolbox* and outputs solution, reconstructed and time fields.
h2. Q5: What is included in SMALLbox?
To enable easy comparison with the existing state-of-the-art algorithms, during the installation procedure SMALLbox checks the Matlab path for existence of the following freely available toolboxes and will automatically download and install them, as required:
- SPARCO (v.1.2) - set of sparse representation problems
- SparseLab (v.2.1) - set of sparse solvers
- Sparsify (v.0.4) - set of greedy and hard thresholding algorithms
- SPGL1 (v.1.7) - large-scale sparse reconstruction solver
- GPSR (v.6.0) - Gradient projection for sparse reconstruction
- KSVD-box (v.13) and OMP-box (v.10) - dictionary learning
- KSVDS-box (v.11) and OMPS-box (v.1) - sparse dictionary learning
In addition there are also implementations of three solvers in the *solver* directory (MP, OMP and PCGP) and our implementation of recursive least square dictionary learning algorithm (RLS-DLA) in *DL* directory.
h2. Q6: How do I contribute?
h2. Q7: I want to add my solver to SMALLbox. How?
h2. Q8: I want to add my dictionary learning algorithm to SMALLbox. How?
h2. Q9: I want to add a new sparse representation problem. How?
h2. Q10: I want to add a new problem for dictionary learning. How?
h2. Q1: What is SMALLbox?
*SMALLbox* is an evaluation framework for processing signals using adaptive sparse structured representations. SMALLbox is built within FP7 EU FET project called "SMALL" that is exploring new provably good methods to obtain inherently data-driven sparse models, which are able to cope with large-scale and complicated data. The main focus of research in the area of *sparse representations* is in developing reliable algorithms with provable performance and bounded complexity. There exist many applications for which it was proven beneficial to sparsely represent the data in some transform domain (i.e. "dictionary"). Moreover, the success of sparse models heavily depends on the choice of a “dictionary” to reflect the natural structures of a class of data. *Dictionary learning for sparse representation* deals with inferring such a dictionary from training data and is a key to the extension of sparse models for new exotic types of data.
SMALLbox provides an easy way to evaluate these methods against state-of-the art alternatives in a variety of standard signal processing problems. This is achieved trough a unifying interface that enables a seamless connection between the three types of modules: problems, dictionary learning algorithms and sparse solvers. In addition, it provides interoperability between existing state-of-the-art toolboxes.
As an open source MATLAB toolbox, the SMALLbox can be seen as not only as a evaluation and educational tool, but as a tool for reproducible research in the sparse representations research community.
h2. Q2: How to obtain SMALLbox?
The SMALLbox project is maintained by people at the "Centre for Digital Music at SEECS, Queen Mary University of London":http://www.elec.qmul.ac.uk/digitalmusic/. To access the SMALLbox project page follow the link bellow:
https://code.soundsoftware.ac.uk/projects/smallbox/
If you want to try the latest stable public release please go to *Downloads* section. If you want to check the latest development and to contribute to the project then please first register to soundsoftware.ac.uk following the link in the upper right corner of the page.
The code repository hosted at soundsoftware.ac.uk is using Mercurial distributed version control, so you will need mercurial installed on your system. If you are new to mercurial the easiest way to start is to install EasyMercurial, which you can find at https://code.soundsoftware.ac.uk/projects/easyhg.
To check out SMALLbox repository please hg clone the following URL, or provide this URL to your preferred Mercurial client (e.g. EasyMercurial):
https://code.soundsoftware.ac.uk/hg/smallbox
h2. Q3: How to install SMALLbox?
To install the toolbox run the script *SMALLboxSetup.m* from the MATLAB command prompt and follow the instructions. *SmallboxSetup.m* is in the root SMALLbox directory. The SMALLbox installation involves the automatic download of several existing toolboxes. These are described in Q5. Due to the automatic download of toolboxes you must have an active internet connection.
Please note that within the toolboxes are several MEX components that must be compiled. If you do not already have MEX setup, run "mex -setup" or type "help mex" in the MATLAB command prompt.
Once installed, there are two optional demo functions that can be run. Further information can be found in the README.txt in the main SMALLbox directory.
h2. Q4: What are the Problem, solver, and DL structures in SMALLbox?
There are three main structures in SMALLbox that describe common parts of problem solving using sparse representation and dictionary learning - *Problem*, *DL* and *solver* structures.
The *Problem* structure defines all necessary aspects of a problem to be solved. To be compatible with the SPARCO, it needs to have five fields defined prior to any sparse representation of the data: *A* – a matrix or operator representing dictionary in which signal is sparse, *b* – a vector or matrix representing signal or signals to be represented, *reconstruct* – a function handle to reconstruct the signal from coefficients, *signalSize* – the dimension of the signal, *sizeA* – if matrix A is given as an operator the size of the dictionary needs to be defined in advance. Other fields that further describe the problem, which are useful for either reconstruction of the signal or representation of the results, might be generated by the SPARCO generateProblem function or the SMALLbox problem functions. The new problems implemented in the SMALLbox version 1.0 are: Image De-noising, Automatic Music Transcription and Image Representation using another image as a dictionary. In the case of a dictionary learning problem, fields *A* and *reconstruct* are not defined while generating the problem, but after the dictionary is learned and prior to the sparse representation. In this case, field *b* needs to be given in matrix form to represent the training data and another field *p* defining the number of dictionary elements to be learned needs to be specified.
The structure for dictionary learning - *DL* is a structure that defines dictionary learning algorithm to be used. It is initialised with a utility function *SMALL_init_DL*, which will define five mandatory fields: *toolbox* - a field used to discriminate the API, *name* - the name of dictionary learning function from the particular toolbox, *param* - a field containing parameters for the particular DL technique and in the form given by the toolbox API, *D* - a field where the learned dictionary will be stored, *time* - a field to store learning time. After *toolbox*, *name* and *param* fields are set, the function *SMALL_learn* is called with *Problem* and *DL* structures as inputs. According to the DL.toolbox field, the function calls the DL.name algorithm with its API and outputs learned dictionary D and time spent. The DL.param field contains parameters such as dictionary size, the number of iterations, the error goal or similar depending on the particular algorithm used.
Similar to dictionary learning every instance of the sparse representation needs to be initialised with the *SMALL_init_solver* function. It will define mandatory fields of the *solver* structure: *toolbox* - a field with toolbox name (e.g. sparselab), *name* - the name of solver from the particular toolbox (e.g. SolveOMP), *param* - the parameters in the form given by the toolbox API, *solution* - the output representation, *reconstructed* - the signal reconstructed from solution, *time* - the time spent for sparse representation. With the input parameters of the solver structure set, the *SMALL_solve* function is called with *Problem* and *solver* structure as inputs. The function calls *solver.name* algorithm with API specified by *solver.toolbox* and outputs solution, reconstructed and time fields.
h2. Q5: What is included in SMALLbox?
To enable easy comparison with the existing state-of-the-art algorithms, during the installation procedure SMALLbox checks the Matlab path for existence of the following freely available toolboxes and will automatically download and install them, as required:
- SPARCO (v.1.2) - set of sparse representation problems
- SparseLab (v.2.1) - set of sparse solvers
- Sparsify (v.0.4) - set of greedy and hard thresholding algorithms
- SPGL1 (v.1.7) - large-scale sparse reconstruction solver
- GPSR (v.6.0) - Gradient projection for sparse reconstruction
- KSVD-box (v.13) and OMP-box (v.10) - dictionary learning
- KSVDS-box (v.11) and OMPS-box (v.1) - sparse dictionary learning
In addition there are also implementations of three solvers in the *solver* directory (MP, OMP and PCGP) and our implementation of recursive least square dictionary learning algorithm (RLS-DLA) in *DL* directory.
h2. Q6: How do I contribute?
h2. Q7: I want to add my solver to SMALLbox. How?
h2. Q8: I want to add my dictionary learning algorithm to SMALLbox. How?
h2. Q9: I want to add a new sparse representation problem. How?
h2. Q10: I want to add a new problem for dictionary learning. How?