sparsearch.tex

SparseLab is a Matlab software package designed to find sparse solutions to systems of linear equati

      TFDecompEx       Time Frequency Decomposition
\end{verbatim}

Each example is documented on the SparseLab website and can be run
by running the correspondingly named .m file in each directory.

%-------------------------------------------------------------------------------
\section[Examples Philosophy]{Examples Philosophy}
\label{wophilo}

{\tt /Examples} is a subdirectory of /\WLName\ that is much like {\tt Papers} in that it contains a
variety of subdirectories, each of which contains a sequence of scripts generating figures.
However, {\tt Examples} is different in that its primary motivation is {\it not} to reproduce
figures in our own articles.  Instead, its motivation is for more informal, exploratory purposes


%-------------------------------------------------------------------------------
\section[Existing Examples]{Existing Examples}
\label{woexist}

In the current release, version \WLVersion, we distribute the
following Examples:

\begin{verbatim}
 /nnfEx            Non-negative Matrix Factorization

 /reconstrutionEx  Signal Reconstruction

 /RegEx            Model Selection in Regression

 /TFDecompEx       Time Frequency Decomposition
 \end{verbatim}

%-------------------------------------------------------------------------------
\section[Examples Architecture]{Examples Architecture}
\label{woarch}

It is a good idea to follow the same naming practices and file organization
as in the directory \PaperDir.

\subsection{Naming}

In the Regression example,  we use the filenames {\tt RegEx01.m},
{\tt RegEx02.m} after the name of the example directory for the main
script. We try to number figures in an obvious way and to stick with
names no longer than eight characters.

\subsection{Script Contents}

Each file should generate one figure, and should avoid the use of {\tt clg},
{\tt figure}, {\tt print} and {\tt pause}.  This is the same set of rules that
we adhere to in \PaperDir.

\subsection{Meta Routines}

By following the above rules it is easy to write wrapper code to print all
figures or to cycle through all figures.  Such wrapper code typically has
suggestive names like {\tt BBPrintAllFigs} or {\tt BBShowAllFigs}.

%=============================================
%                Chapter 5
%=============================================
\chapter[Datasets]{Datasets}
\label{dasec}

The scripts we have just discussed make use of  several datasets, which are
made available in the directory \DataDir. In this chapter we describe the
architecture of our dataset library.

%---------------------------------------------------------
\section[Dataset Philosophy]{Dataset Philosophy}
\label{daphilo}

We make available datasets through {\it centralized readers}. The idea is that
the knowledge of how to access a dataset should be concentrated in a single
place, and that the access to any dataset should be made in a stereotyped way,
through a simple function call, not through explicit input and output routines.

In this way, if a dataset is available in the system because it has been used
for one script, it automatically becomes available throughout the system for
any other purpose one would wish, without others needing to know the format or
location of the data.

If, in the future, the dataset needs to be moved to some other location in the
file system, or if it needs to be stored in some other format, no scripts that
use the data for demonstrations will need to change.  Instead, one
changes only the code implementing the access method rather than the scripts
which want to use the dataset.

(The alternative is, of course, that any such changes in the future require
rewriting all existing scripts!)

The same philosophy applies for datasets which are synthetic -- those created by
\Matlab\ formulas.  They are accessed in a stereotyped way through access to a
{\it centralized synthesizer}.  In this way, a synthetic signal designed for
one use in one script automatically becomes available for other purposes.

%---------------------------------------------------------
\section[Directory Contents]{Dataset Directory}
\label{daformat}

The \Contents\ file in the {\tt Datasets} directory contains the
following information. It shows that there are several tools for accessing
data, 1-d datasets and 2-d datasets.

It is possible that at some time in the future, we will also have 3-d datasets
(probably movies) or collections of still images.

\begin{verbatim}
%          Data Fabricators
%
%   MakeBlocks        -   Make artificial blocky signal
%   MakeBumps         -   Make artificial bump signal
%   MakeMatrix        -   Make artificial random matrix
%
%
\end{verbatim}

%---------------------------------------------------------
\section[Dataset Documentation]{Dataset Documentation}
\label{dadoc}

Each dataset in the system has a documentation file, with suffix \dotdoc.
Here is an example of a documentation file for a 1-d signal:

\begin{verbatim}
caruso.asc -- Digital signal of Caruso singing

Access
    Enrico = ReadSignal('Caruso');

Size
    50,000 by 1

Sampling Rate
    8192 Hz

Description
    In MATLAB, the command sound(Enrico,8192) will play this sound
    back at the right pitch.

Source
    Obtained by anonymous FTP from the xwplw package
    developed by R.R. Coifman and Fazal Majid at Yale University.
    You can get this X-windows adapted waveform analysis
    package by anonymous FTP to math.yale.edu.
\end{verbatim}

Here is an example of a documentation file for a 2-d image:
\begin{verbatim}
canaletto.raw -- Gray-scale image of Canaletto painting

Access
    Canal = ReadImage('Canaletto');

Size
    512 by 512

Gray Levels
    256

Description
    This image was used in an article by P. Perona and J. Malik,
    "Scale-Space Filtering by Anisotropic Diffusions," IEE PAMI.

Source
    Obtained from John Canny and Jitendra Malik, of EECS at
    U.C. Berkeley.
\end{verbatim}

\pagebreak
You will notice the following fields in the documentation:
\begin{enumerate}
\item {\it Title}. A one-line header at the start of the file, giving the
filename, and, after two hyphens, descriptive text.

\item {\it Access}. A code fragment indicating the stereotyped access method.

\item {\it Size}. The size of the signal or image.

\item {\it Gray Levels}. Applicable for Images only.

\item {\it Sampling Rate}. Applicable for Sounds only.

\item {\it Source}. Indication of the original source of the data.

\item {\it Description}. Additional description of the data.
\end{enumerate}

%---------------------------------------------------------
\section[Adding New Datasets]{Adding New Datasets}
\label{daadd}

To add new datasets to \WaveLab, do the following:

\begin{itemize}
\item[1.] {\it Installation.}  Place the dataset, in stereotyped format, in the
{\tt Datasets} directory.  Modify one of the existing access functions to read
in the dataset. (You can, in a pinch, place the dataset elsewhere, or keep it
in a nonstandard format).

\item[2.] {\it Documentation.}  Insert a \dotdoc\ file in the {\tt Datasets}
directory to explain the dataset.
\end {itemize}

To add a new synthetic matrix type to \WaveLab, simply modify the
function {\tt MakeMatrix}, by inserting a new case in the ``compound
if''; the new case tests for a new, previously unused name, and
contains a formula defining the signal in that case. Add a separate
function, similar to {\tt UniformSphericalMatrix} for example, with
the build instructions. It is best if the formula is designed to
work the same way the other formulas work -- to produce an output at
any given signal length or image extent.

%-----------------------------------------------------------------
\section[Dataset Sources]{Dataset Sources}
\label{dasource}

We would like to take this opportunity to thank the sources of our datasets.
We reprint here from the file {\tt THANKS.m} in \DocDir.
\begin{verbatim}
%  Contributors of Data
%       Yaakov Tsaig
\end{verbatim}

%=============================================
%                Chapter 6
%=============================================
\chapter[Documentation]{Documentation}
\label{docsec}

There has been extensive concern for the documentation of the code in \WaveLab.  We try to use all
the features of \Matlab\ as well as other features to produce a coherent, understandable system.

%---------------------------------------------------------
\section[Help Headers]{Help Headers}
\label{dochelp}

Each function in the \WaveLab\ system has documentation contained
inside the \dotm\ file with its \Matlab\ code. This documentation
can be accessed on-line by typing {\tt help Name} where {\tt Name}
is the name of the function. For example, typing {\tt help SolveMP}
gives:

\begin{verbatim}
% SolveMP: Matching Pursuit (non-orthogonal)
% Usage
%   [sol iters activationHist] = SolveMP(A, b, maxIters, NoiseLevel, verbose)
% Input
%   A           dictionary (dxn matrix), rank(A) = min(d,n) by assumption
%   y           data vector, length d.
%   maxIters    number of atoms in the decomposition
%   NoiseLevel  estimated norm of noise, default noiseless, i.e. 1e-5
%   verbose     1 to print out detailed progress at each iteration, 0 for
%               no output (default)
% Outputs
%    sol             solution of MP
%    iters           number of iterations performed
%    activationHist  Array of indices showing elements entering
%                    the solution set
% Description
%   SolveMP implements the greedy pursuit algorithm to estimate the
%   solution of the sparse approximation problem
%      min ||x||_0 s.t. A*x = y
% See Also
%   SolveOMP
% References
%   Matching Pursuit With Time-Frequency Dictionaries (1993) Mallat, Zhang
%   IEEE Transactions on Signal Processing
%\end{verbatim}

This illustrates the main components of the format we have adopted: a one-line
{\it help header}, and sections for {\it Usage}, {\it Inputs}, {\it Outputs},
{\it Side Effects}, {\it Description}, {\it Examples}, {\it Algorithm}, {\it
See Also} and {\it References}.

\begin{itemize}
\item[1.] {\it Header}. The first line of the help header is called the {\tt
H1} line by the \Matlab\ folks. It is special to \Matlab, and to \WaveLab.
When you use the {\tt lookfor} command,  \Matlab\ examines this line for each
\dotm\ file in its path to find text matching the request. When a release of
\WaveLab\ is built, these lines are compiled and sorted in alphabetical order to
make files in the documentation directory. Format: a percent sign, a single
blank, the name of the function, a blank followed by double hyphens and a
blank, and a short description of the function.  The description should contain
as many helpful keywords as possible.

\item[2.] {\it Usage}. Here, indicate the calling prototype.  Format: the
output argument(s) (enclosed within square brackets if there is more than one
output argument), an equals sign, the function name followed by the input
argument(s) enclosed within parentheses.  Optional input arguments are enclosed
within square brackets.

\item[3.] {\it Inputs}.  Here, one line per input variable, indicating the name
of the variable, the formal data type and the interpretation. Also, indicate if
the input is optional by enclosing it within square brackets.

\item[4.] {\it Outputs}.  Here, one line per output variable, indicating the
name of the variable, the formal data type and the interpretation.

\item[5.] {\it Side Effects}.  Here, indicate any side effects the routine may