FAQ » History » Version 40

Luis Figueira, 2012-06-20 06:39 PM
adde citing information

1 1 Ivan Damnjanovic
h1. FAQ
2 1 Ivan Damnjanovic
3 1 Ivan Damnjanovic
h2. Q1: What is SMALLbox?
4 1 Ivan Damnjanovic
5 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.
6 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. 
7 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.
8 1 Ivan Damnjanovic
9 3 Ivan Damnjanovic
h2. Q2: How to obtain SMALLbox?
10 2 Ivan Damnjanovic
11 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:
12 9 Ivan Damnjanovic
13 9 Ivan Damnjanovic
https://code.soundsoftware.ac.uk/projects/smallbox/
14 9 Ivan Damnjanovic
15 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.
16 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):
17 1 Ivan Damnjanovic
18 1 Ivan Damnjanovic
https://code.soundsoftware.ac.uk/hg/smallbox
19 38 Luis Figueira
20 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.
21 9 Ivan Damnjanovic
22 1 Ivan Damnjanovic
23 3 Ivan Damnjanovic
h2. Q3: How to install SMALLbox?
24 1 Ivan Damnjanovic
25 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.
26 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.
27 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.
28 1 Ivan Damnjanovic
29 39 Luis Figueira
For more detailed instructions regarding SMALLbox installation, please refer to the following [[InstallationGuide|page]].
30 39 Luis Figueira
31 1 Ivan Damnjanovic
32 3 Ivan Damnjanovic
h2. Q4: What are the Problem, solver, and DL structures in SMALLbox?
33 1 Ivan Damnjanovic
34 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.
35 13 Ivan Damnjanovic
36 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.
37 16 Ivan Damnjanovic
38 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. 
39 16 Ivan Damnjanovic
40 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.
41 13 Ivan Damnjanovic
42 1 Ivan Damnjanovic
43 3 Ivan Damnjanovic
h2. Q5: What is included in SMALLbox?
44 1 Ivan Damnjanovic
45 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:
46 17 Ivan Damnjanovic
-	SPARCO (v.1.2) - set of sparse representation problems
47 17 Ivan Damnjanovic
-	SparseLab (v.2.1) - set of sparse solvers
48 17 Ivan Damnjanovic
-	Sparsify (v.0.4) - set of greedy and hard thresholding algorithms
49 17 Ivan Damnjanovic
-	SPGL1 (v.1.7) - large-scale sparse reconstruction solver
50 17 Ivan Damnjanovic
-	GPSR (v.6.0) - Gradient projection for sparse reconstruction
51 17 Ivan Damnjanovic
-	KSVD-box (v.13) and OMP-box (v.10) - dictionary learning
52 17 Ivan Damnjanovic
-	KSVDS-box (v.11) and OMPS-box (v.1) - sparse dictionary learning
53 17 Ivan Damnjanovic
54 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. 
55 1 Ivan Damnjanovic
56 3 Ivan Damnjanovic
h2. Q6: How do I contribute?
57 1 Ivan Damnjanovic
58 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. 
59 18 Ivan Damnjanovic
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.
60 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):
61 18 Ivan Damnjanovic
62 18 Ivan Damnjanovic
https://code.soundsoftware.ac.uk/hg/smallbox
63 19 Ivan Damnjanovic
There are three ways how you can contribute your code to SMALLbox:
64 28 Ivan Damnjanovic
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.
65 21 Ivan Damnjanovic
66 26 Ivan Damnjanovic
> For example you have toolbox called *my_dummy_toolbox* and it is available at *my_dummy_url*. You should add the following lines to *SMALLboxSetup.m* script and of course change the parts in bold letters:
67 26 Ivan Damnjanovic
> > % check if toolbox is already installed (assuming that your toolbox have setup file, but any other script that is unique to your toolbox will do.
68 1 Ivan Damnjanovic
> >
69 26 Ivan Damnjanovic
> > if ~exist(' *my_dummy_toolbox_setup.m*','file')
70 26 Ivan Damnjanovic
> >
71 26 Ivan Damnjanovic
> > > fprintf('\n ******************************************************************');
72 1 Ivan Damnjanovic
> > >
73 26 Ivan Damnjanovic
> > > fprintf('\n\n Initialising *My_dummy_toolbox* Setup');
74 1 Ivan Damnjanovic
> > > 
75 1 Ivan Damnjanovic
> > > try
76 26 Ivan Damnjanovic
> > > > % setting up the path where toolbox will be installed
77 26 Ivan Damnjanovic
> > > >
78 26 Ivan Damnjanovic
> > > > *my_dummy_toolbox_path* =[SMALL_path,FS,'toolboxes',FS,' *my_dummy_toolbox* '];
79 26 Ivan Damnjanovic
> > > >
80 26 Ivan Damnjanovic
> > > > %setting up the url of the file to be downloaded
81 26 Ivan Damnjanovic
> > > >
82 26 Ivan Damnjanovic
> > > > *my_dummy_toolbox_zip*='http:// *my_dummy_url*/ *my_dummy_toolbox.zip*';
83 26 Ivan Damnjanovic
> > > >
84 26 Ivan Damnjanovic
> > > > fprintf('\n\n Downloading toolbox, please be patient\n\n');
85 26 Ivan Damnjanovic
> > > > 
86 26 Ivan Damnjanovic
> > > > unzip( *my_dummy_toolbox_zip*, *my_dummy_toolbox_path*);
87 26 Ivan Damnjanovic
> > > > 
88 26 Ivan Damnjanovic
> > > > % generate the path for the toolbox and add it to the MATLAB search path
89 26 Ivan Damnjanovic
> > > >
90 26 Ivan Damnjanovic
> > > > *my_dummy_toolbox_p*=genpath( *my_dummy_toolbox_path*);
91 26 Ivan Damnjanovic
> > > > 
92 26 Ivan Damnjanovic
> > > > addpath( *my_dummy_toolbox_p*);
93 26 Ivan Damnjanovic
> > > > 
94 26 Ivan Damnjanovic
> > > > % go to the installation directory and run the setup script if needed (e.g. there are mex files that needs to be compiled)
95 26 Ivan Damnjanovic
> > > > 
96 26 Ivan Damnjanovic
> > > > cd([ *my_dummy_toolbox_path*]);
97 26 Ivan Damnjanovic
> > > >
98 26 Ivan Damnjanovic
> > > > try
99 26 Ivan Damnjanovic
> > > >> *my_dummy_toolbox_setup.m*;
100 26 Ivan Damnjanovic
> > > >>
101 26 Ivan Damnjanovic
> > > >> fprintf('\n *My_dummy_toolbox* Installation Successful!\n');
102 26 Ivan Damnjanovic
> > > > catch
103 26 Ivan Damnjanovic
> > > >> warning('*My_dummy_toolbox* setup failed');
104 26 Ivan Damnjanovic
> > > > end
105 20 Ivan Damnjanovic
> > > catch
106 26 Ivan Damnjanovic
> > > > fprintf('\n *My_dummy_toolbox* Installation Failed\n');
107 23 Ivan Damnjanovic
> > > end
108 26 Ivan Damnjanovic
> > >
109 26 Ivan Damnjanovic
> > > % return to the SMALL root directory
110 26 Ivan Damnjanovic
> > >
111 26 Ivan Damnjanovic
> > > cd(SMALL_path);
112 26 Ivan Damnjanovic
> > else
113 26 Ivan Damnjanovic
> >> fprintf('\n ******************************************************************');
114 26 Ivan Damnjanovic
> > >
115 26 Ivan Damnjanovic
> >> fprintf('\n\n *My_dummy_toolbox* is already installed');
116 24 Ivan Damnjanovic
> > end
117 26 Ivan Damnjanovic
> 
118 26 Ivan Damnjanovic
> Once you made this changes, you should also follow the steps in Q7, Q8 and Q9 to integrate your API with *SMALLbox* API.
119 27 Ivan Damnjanovic
>
120 27 Ivan Damnjanovic
 
121 28 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.
122 1 Ivan Damnjanovic
123 28 Ivan Damnjanovic
> Make a folder in *toolboxes* directory, add your files and commit to the repository. If your toolbox needs setup (e.g. mex files need to be compiled), add the lines in the *SMALLboxSetup.m* script  and of course change the parts in bold letters:
124 27 Ivan Damnjanovic
> > *my_dummy_toolbox_path* =[SMALL_path,FS,'toolboxes',FS,' *my_dummy_toolbox* '];
125 27 Ivan Damnjanovic
> >
126 27 Ivan Damnjanovic
> > cd([*my_dummy_toolbox_path*]);
127 27 Ivan Damnjanovic
> >
128 27 Ivan Damnjanovic
> > try
129 27 Ivan Damnjanovic
> > >
130 27 Ivan Damnjanovic
> > > *my_dummy_toolbox_setup.m*;
131 27 Ivan Damnjanovic
> > >
132 27 Ivan Damnjanovic
> > > fprintf('\n *My_dummy_toolbox* Installation Successful!\n');
133 27 Ivan Damnjanovic
> > >
134 27 Ivan Damnjanovic
> > catch
135 27 Ivan Damnjanovic
> > > warning('*My_dummy_toolbox* setup failed');
136 27 Ivan Damnjanovic
> > end
137 27 Ivan Damnjanovic
> >
138 1 Ivan Damnjanovic
> > cd(SMALL_path);
139 27 Ivan Damnjanovic
> 
140 28 Ivan Damnjanovic
> If setup is not needed for your toolbox, no changes are required and the SMALLbox setup script will automatically generate the path for your toolbox.
141 27 Ivan Damnjanovic
> Once you made this changes, you should also follow the steps in Q7, Q8 and Q9 to integrate your API with *SMALLbox* API.
142 28 Ivan Damnjanovic
143 28 Ivan Damnjanovic
c) I want to develop solver/DL algorithm/problem through the SMALLbox project. 
144 1 Ivan Damnjanovic
145 29 Ivan Damnjanovic
> If you want to develop your algorithms within the project and use SMALLbox API then put your scripts in dedicated folders ( *DL*, *solvers* and *Problems* ) and make sure you are using following API:
146 1 Ivan Damnjanovic
>
147 30 Ivan Damnjanovic
> SMALL solver API: 
148 30 Ivan Damnjanovic
>
149 30 Ivan Damnjanovic
> >*y = my_dummy_solver(A, b, n, params, AT );*
150 30 Ivan Damnjanovic
> >
151 30 Ivan Damnjanovic
> >where *y* is the solution, *A* is the dictionary to be used, *b* is signal or matrix of signals to be represented, n is size of the signal, *params* are the parameters needed and *AT* is the dictionary transpose if it is given in implicit form.
152 1 Ivan Damnjanovic
> 
153 30 Ivan Damnjanovic
> SMALL dictionary learning API: 
154 30 Ivan Damnjanovic
> >
155 30 Ivan Damnjanovic
> >*D = my_dummy_DL(X, param);*
156 30 Ivan Damnjanovic
> >
157 30 Ivan Damnjanovic
> >where *D* is the learned dictionary, *X* is the matrix with training vectors as its columns and param is a structure with parameters that you algorithm is using. 
158 30 Ivan Damnjanovic
>
159 30 Ivan Damnjanovic
> SMALL problem API: 
160 30 Ivan Damnjanovic
> >
161 30 Ivan Damnjanovic
> >*Problem=my_dummy_problem(varargin);*
162 30 Ivan Damnjanovic
> >
163 31 Ivan Damnjanovic
> >where *Problem* is the structure with fields as explained in *Q4*.
164 29 Ivan Damnjanovic
165 29 Ivan Damnjanovic
166 31 Ivan Damnjanovic
h2. Q7: I want to add my solver API to SMALLbox. How?
167 3 Ivan Damnjanovic
168 33 Ivan Damnjanovic
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 (follow the steps in *Q6*). For example, one has a function called *my_dummy_solver*, to be used in the SMALLbox, with the following API call:
169 1 Ivan Damnjanovic
170 34 Ivan Damnjanovic
> y= *my_dummy_solver* (size_y, dictionary, signal, error_goal, iter_num);
171 33 Ivan Damnjanovic
172 34 Ivan Damnjanovic
A name needs to be defined for your toolbox in order to differentiate your API from other toolboxes. Using the example name *my_dummy_toolbox* the following line needs to be inserted to the if statement in the *SMALL_solve.m* script:
173 33 Ivan Damnjanovic
174 34 Ivan Damnjanovic
> elseif strcmpi(solver.toolbox,' *my_dummy_toolbox* ')
175 33 Ivan Damnjanovic
>
176 33 Ivan Damnjanovic
>>y =eval([solver.name,'(n,A,b,',solver.param,');']);
177 33 Ivan Damnjanovic
178 34 Ivan Damnjanovic
To test the function, the *SMALL_solver_test.m* script from the *examples* directory can be modified as follows:
179 33 Ivan Damnjanovic
>
180 33 Ivan Damnjanovic
>SMALL.Problem = generateProblem(6, 'P', 6, 'm', 270,'n',1024, 'show');
181 33 Ivan Damnjanovic
>
182 33 Ivan Damnjanovic
>i=1;
183 34 Ivan Damnjanovic
>
184 33 Ivan Damnjanovic
>SMALL.solver(i)=SMALL_init_solver;
185 33 Ivan Damnjanovic
>
186 34 Ivan Damnjanovic
>SMALL.solver(i).toolbox=' *my_dummy_toolbox* ';
187 33 Ivan Damnjanovic
>
188 34 Ivan Damnjanovic
>SMALL.solver(i).name=' *my_dummy_solver* ';
189 33 Ivan Damnjanovic
>
190 34 Ivan Damnjanovic
> % In the following string all parameters except matrix, measurement vector and size of solution need to be specified. If you are not sure which parameters are needed for particular solver type "help <Solver name>" in MATLAB command line
191 33 Ivan Damnjanovic
>
192 33 Ivan Damnjanovic
> SMALL.solver(i).param='1e-14, 200';
193 33 Ivan Damnjanovic
>
194 33 Ivan Damnjanovic
> SMALL.solver(i)=SMALL_solve(SMALL.Problem, SMALL.solver(i));
195 33 Ivan Damnjanovic
 
196 31 Ivan Damnjanovic
h2. Q8: I want to add my dictionary learning algorithm API to SMALLbox. How?
197 3 Ivan Damnjanovic
198 35 Ivan Damnjanovic
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 (follow the steps in *Q6*). For example, one has a function called *my_dummy_DL*, to be used in the SMALLbox, with the following API call:
199 35 Ivan Damnjanovic
200 35 Ivan Damnjanovic
> D= *my_dummy_DL* (TrainingMatrix, params);
201 37 Ivan Damnjanovic
>
202 37 Ivan Damnjanovic
>where *D* is learned dictionary, *TrainingMatrix' is matrix that has training signals as its columns and *params* is structure with parameters needed for learning (e.g. initial dictionary, stopping criteria etc.)
203 35 Ivan Damnjanovic
204 35 Ivan Damnjanovic
A name needs to be defined for your toolbox in order to differentiate your API from other toolboxes. Using the example name *my_dummy_toolbox* the following line needs to be inserted to the if statement in the *SMALL_learn.m* script:
205 35 Ivan Damnjanovic
206 35 Ivan Damnjanovic
> elseif strcmpi(solver.toolbox,' *my_dummy_toolbox* ')
207 35 Ivan Damnjanovic
>
208 1 Ivan Damnjanovic
>>D =eval([DL.name,'(X,param);']);
209 36 Ivan Damnjanovic
210 36 Ivan Damnjanovic
You can then try to modify any of Image denoising example scripts to test your algorithm against the ones provided.
211 3 Ivan Damnjanovic
212 31 Ivan Damnjanovic
h2. Q9: I want to add a new problem. How? 
213 1 Ivan Damnjanovic
214 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).
215 40 Luis Figueira
216 40 Luis Figueira
h2. Q10: Citing SMALLbox
217 40 Luis Figueira
218 40 Luis Figueira
Please cite SMALLbox using the following: 
219 40 Luis Figueira
220 40 Luis Figueira
<pre>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.</pre>
221 40 Luis Figueira
222 40 Luis Figueira
Also put a footnote to the URL of the project for people to get the code:
223 40 Luis Figueira
224 40 Luis Figueira
<pre>http://code.soundsoftware.ac.uk/projects/smallbox</pre>