FAQ » History » Version 46

Luis Figueira, 2012-06-25 10:04 AM
added link to doc

1 1 Ivan Damnjanovic
h1. FAQ
2 1 Ivan Damnjanovic
3 43 Luis Figueira
{{>toc}}
4 42 Luis Figueira
5 1 Ivan Damnjanovic
h2. Q1: What is SMALLbox?
6 1 Ivan Damnjanovic
7 16 Ivan Damnjanovic
*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.
8 2 Ivan Damnjanovic
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. 
9 2 Ivan Damnjanovic
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.
10 1 Ivan Damnjanovic
11 3 Ivan Damnjanovic
h2. Q2: How to obtain SMALLbox?
12 2 Ivan Damnjanovic
13 9 Ivan Damnjanovic
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:
14 9 Ivan Damnjanovic
15 9 Ivan Damnjanovic
https://code.soundsoftware.ac.uk/projects/smallbox/
16 9 Ivan Damnjanovic
17 38 Luis Figueira
If you want to try the latest stable public release please go to *Downloads* section. If you want to check the latest development you can obtain it from the project's code repository. It is hosted at soundsoftware.ac.uk, and 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.
18 10 Ivan Damnjanovic
To check out SMALLbox repository please hg clone the following URL, or provide this URL to your preferred Mercurial client (e.g. EasyMercurial):
19 1 Ivan Damnjanovic
20 1 Ivan Damnjanovic
https://code.soundsoftware.ac.uk/hg/smallbox
21 38 Luis Figueira
22 38 Luis Figueira
If you want to to contribute to the project then please first register to soundsoftware.ac.uk following the link in the upper right corner of the page.
23 9 Ivan Damnjanovic
24 1 Ivan Damnjanovic
25 3 Ivan Damnjanovic
h2. Q3: How to install SMALLbox?
26 1 Ivan Damnjanovic
27 12 Ivan Damnjanovic
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.
28 12 Ivan Damnjanovic
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.
29 12 Ivan Damnjanovic
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.
30 1 Ivan Damnjanovic
31 39 Luis Figueira
For more detailed instructions regarding SMALLbox installation, please refer to the following [[InstallationGuide|page]].
32 39 Luis Figueira
33 1 Ivan Damnjanovic
34 3 Ivan Damnjanovic
h2. Q4: What are the Problem, solver, and DL structures in SMALLbox?
35 1 Ivan Damnjanovic
36 13 Ivan Damnjanovic
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.
37 13 Ivan Damnjanovic
38 1 Ivan Damnjanovic
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.
39 16 Ivan Damnjanovic
40 16 Ivan Damnjanovic
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. 
41 16 Ivan Damnjanovic
42 16 Ivan Damnjanovic
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.
43 13 Ivan Damnjanovic
44 46 Luis Figueira
For more information please refer to section 3 (Design approach to SMALLbox Overview) of the SMALLbox documentation (https://code.soundsoftware.ac.uk/documents/33).
45 1 Ivan Damnjanovic
46 3 Ivan Damnjanovic
h2. Q5: What is included in SMALLbox?
47 1 Ivan Damnjanovic
48 17 Ivan Damnjanovic
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:
49 17 Ivan Damnjanovic
-	SPARCO (v.1.2) - set of sparse representation problems
50 17 Ivan Damnjanovic
-	SparseLab (v.2.1) - set of sparse solvers
51 17 Ivan Damnjanovic
-	Sparsify (v.0.4) - set of greedy and hard thresholding algorithms
52 17 Ivan Damnjanovic
-	SPGL1 (v.1.7) - large-scale sparse reconstruction solver
53 17 Ivan Damnjanovic
-	GPSR (v.6.0) - Gradient projection for sparse reconstruction
54 17 Ivan Damnjanovic
-	KSVD-box (v.13) and OMP-box (v.10) - dictionary learning
55 17 Ivan Damnjanovic
-	KSVDS-box (v.11) and OMPS-box (v.1) - sparse dictionary learning
56 17 Ivan Damnjanovic
57 17 Ivan Damnjanovic
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. 
58 1 Ivan Damnjanovic
59 3 Ivan Damnjanovic
h2. Q6: How do I contribute?
60 1 Ivan Damnjanovic
61 18 Ivan Damnjanovic
If you want to contribute to the project then please first register to soundsoftware.ac.uk following the link in the upper right corner of the page. 
62 44 Luis Figueira
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 
63 44 Luis Figueira
64 44 Luis Figueira
https://code.soundsoftware.ac.uk/projects/easyhg
65 44 Luis Figueira
66 18 Ivan Damnjanovic
To check out SMALLbox repository please hg clone the following URL, or provide this URL to your preferred Mercurial client (e.g. EasyMercurial):
67 26 Ivan Damnjanovic
68 1 Ivan Damnjanovic
https://code.soundsoftware.ac.uk/hg/smallbox
69 44 Luis Figueira
70 27 Ivan Damnjanovic
There are three ways how you can contribute your code to SMALLbox:
71 27 Ivan Damnjanovic
72 44 Luis Figueira
a) I have a toolbox that I maintain myself and it is available at my repository, but I want SMALLbox users to be able to use it within SMALLbox.
73 30 Ivan Damnjanovic
 
74 30 Ivan Damnjanovic
b) I have a toolbox that I would like to incorporate into SMALLbox and to make it maintained and developed through the SMALLbox project.
75 30 Ivan Damnjanovic
76 31 Ivan Damnjanovic
c) I want to develop solver/DL algorithm/problem through the SMALLbox project. 
77 35 Ivan Damnjanovic
78 35 Ivan Damnjanovic
h2. Q7: I want to add my solver API to SMALLbox. How?
79 35 Ivan Damnjanovic
80 45 Luis Figueira
To introduce a new sparse representation algorithm to the SMALLbox, the file containing the code for the algorithm needs to be put into the MATLAB path.
81 1 Ivan Damnjanovic
82 44 Luis Figueira
 h2. Q8: I want to add my dictionary learning algorithm API to SMALLbox. How?
83 1 Ivan Damnjanovic
84 45 Luis Figueira
To introduce a new dictionarylearning algorithm to the SMALLbox, the file containing the code for the algorithm needs to be put into the MATLAB path. 
85 45 Luis Figueira
86 31 Ivan Damnjanovic
h2. Q9: I want to add a new problem. How? 
87 1 Ivan Damnjanovic
88 32 Ivan Damnjanovic
Assuming that your script that generates the problem is in the path (follow the steps in *Q6*), you just need to make sure that it generates *Problem* sturctures with the fileds explained in *Q4*. If you want to reconstruct the signal from the solution then you should also provide the recontruction function (follow the examples provided in the SMALLbox documentation and also in the *Problems* directory).
89 40 Luis Figueira
90 40 Luis Figueira
h2. Q10: Citing SMALLbox
91 40 Luis Figueira
92 40 Luis Figueira
Please cite SMALLbox using the following: 
93 40 Luis Figueira
94 41 Luis Figueira
> Ivan Damnjanovic, Matthew E. P. Davies, and Mark D. Plumbley, “SMALLbox - an evaluation framework for sparse representations and dictionary learning algorithms,” in Proc. LVA/ICA’10, 2010, pp. 418–425.
95 40 Luis Figueira
96 40 Luis Figueira
Also put a footnote to the URL of the project for people to get the code:
97 40 Luis Figueira
98 40 Luis Figueira
<pre>http://code.soundsoftware.ac.uk/projects/smallbox</pre>