WaveLab Architecture

Jonathan Buckheit and David Donoho, Stanford University 1 Version .850 December, 2005

Acknowledgment of Support. This work was partially supported by NSF DMS 92-09130 and 95-05151 (Stanford), by the NASA Astrophysics Data Program (NASA-Ames), ASOR MURI, by DARPA BAA-9804, by NSF KDI, NSF DMS 00-77261, NSF DMS 01-40698 and by other sponsors.

Contents
1 Introduction 2 Scripts 2.1 Script Philosophy . . . . . . . . . . . . . 2.2 Script Architecture . . . . . . . . . . . . 2.2.1 Meta-Routines . . . . . . . . . . 2.2.2 Specialized Tools . . . . . . . . . 2.2.3 Scripting Rules . . . . . . . . . . 2.2.4 Documenting Individual Figures 2.3 Adding New Scripts . . . . . . . . . . . 2.4 Modifying Existing Scripts . . . . . . . . 3 Workouts 3.1 Workouts Philosophy . 3.2 Existing Workouts . . 3.3 Workouts Architecture 3.3.1 Naming . . . . 3.3.2 Script Contents 3.3.3 Meta Routines 4 Books 5 Datasets 5.1 Dataset Philosophy . . . 5.2 Directory Contents . . . 5.3 Dataset Format . . . . . 5.4 Dataset Access . . . . . 5.5 Dataset Documentation 5.6 Synthetic Signals . . . . 5.7 Adding New Datasets . . . . . . . . . . . . . . . . . . . . . . 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 7 7 8 9 9 10 10 11 11 13 13 14 14 14 14 14 15 17 17 18 19 19 20 22 22

4 5.8

CONTENTS Dataset Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 25 25 27 28 29 29 30 31 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 34 34 34 35 37 37 37 38 39 39 41 41 41 41 42

6 Documentation 6.1 Help Headers . . . . . . . 6.2 Documentation Directory 6.3 Workouts Directory . . . . 6.4 TEX Documents . . . . . . 6.4.1 About WaveLab . 6.4.2 Architecture . . . 7 Browsers 8 Utilities 8.1 Graphics . . . . . . 8.2 Random Numbers 8.3 Shaping Vectors . . 8.4 Scripting . . . . . .

9 Source and Build 9.1 Development System 9.2 Shell Tools . . . . . 9.3 Standard Release . . 9.4 Compiling .ps . . . . 9.5 Distribution . . . . .

10 Distribution and Maintenance 10.1 Archive Directory . . . . . . . 10.2 Developer Checklists . . . . . 10.3 WaveLab Account . . . . . . 10.4 Web Page . . . . . . . . . . .

Chapter 1

Introduction
This document describes the architecture of Wavelab version .850. It is designed for users who already have had day-to-day interaction with the package and now need specic details about the architecture of the package, for example to modify components for their own research. For an introduction to Wavelab at an elementary level, see About WaveLab. This document may be accessed via WWW through the Wavelab Home Page. Before beginning, we mention the main components of the Wavelab package, to standardize terminology. First, there are the basic system components: 1. Source. There is source code, in Matlab, C, TEX, Perl. 2. Build. The source code is assembled into a standard release. The current release is .850. 3. Archives. Compressed archives of the standard release available for three platforms, Mac, Unix and PC, which users can download and install on their machines. 4. Web Documents. A web home page (which can be viewed using any web browser) and a series of postscript and pdf les which explain what Wavelab is and how to get it. The URL is http://wwwstat.stanford.edu/ wavelab. Next there are the basic user components of an installed system: 1. Wavelab Main Directory. A subdirectory /Wavelab850 of the Matlab/Toolbox directory, containing the currently released version of Wavelab software, datasets and documentation. 5

CHAPTER 1. INTRODUCTION 2. Scripts. A subdirectory /Wavelab850/Papers/ of /Wavelab850 contains scripts reproducing gures in various articles and technical reports. 3. Workouts. A subdirectory /Wavelab850/Workouts/ of / Wavelab850 contains workouts that exercise various aspects of Wavelab. 4. Documentation. Both pdf and Postscript les available by WWW access. 5. Browsers. High-level tools which give a point-and-click interface to basic wavelet transform features in Wavelab. 6. Datasets. Numerical, acoustic and image data used to illustrate various aspects of wavelet analysis by the scripts and workouts.

The following document describes all these various components from a systems-level point of view. An individual needing to modify Wavelab or add to it would be interested in this information.

Chapter 2

Scripts
We briey describe the contents and architecture of the /Wavelab850/Papers/ subdirectory of Wavelab.

2.1

Script Philosophy

The makeup of /Wavelab850/Papers/ is the whole raison dtre of the Wavee lab package. The idea is that, when doing research in a computational science, one works to develop reproducible knowledge about the results of computational experiments. The /Papers directory is the end product of such an eort. It makes available to researchers around the world, via the Internet, the computations that produced gures which have been published in hardcopy form as technical reports at Stanford University and in forthcoming journal articles. Other researchers can obtain the Matlab code which generated these gures, and can reproduce the calculations that underly the gures. They can, if they wish, modify the calculations by editing the underlying Matlab code. They can use the algorithms on other datasets. They can try their own favorite methods on the same datasets. Our idea is that, when doing research, long before we write an article, we prepare ourselves with the thought that what we do on the computer will ultimately be made available to others, for their inspection, modication, reuse and criticism. This implies several things. First, that the work product which we are aiming to create will be a subdirectory of Wavelab containing a series of scripts that will generate, from scratch, all the gures of the corresponding article. Second, that our work product is not the printed gures that go into the article, but the underlying algorithms and code which generate those gures, and which will be made available to others. 7

CHAPTER 2. SCRIPTS

Thus, it is no good to print a hardcopy of a gure that we see on the screen and save that for photocopying into a nal version of the paper. Once we are happy with a gure we see on the screen, we must save the code that generated the gure, and then edit the code to make it part of a system that automatically reproduces all the gures of an article. The philosophy we are adopting can be traced to Jon Claerbout and Martin Karrenbachs article Electronic Documents Give Reproducible Research New Meaning (http://sepwww.stanford.edu). We especially like a thought of theirs which we paraphrase as follows: A traditionally published article is not the end product of scholarship; it is the advertisement for the scholarship. The working software environment that produced the gures in the article is the actual end product of the scholarship. To work in accordance with the philosophy, we must adopt a discipline of how we structure our computational experiments in Matlab. A benet of this discipline is, hopefully, to avoid the sloppiness and error that are ubiquitous in computational science.

2.2

Script Architecture

The architecture of the /Papers directory is as follows. At present, it contains these subdirectories, recreating gures in published articles:

AdaptDemo - Adapting to Unknown Smoothness via Wavelet Shrinkage AsympDemo - Wavelet Shrinkage: Asymptopia? BlockyDemo - Smooth Wavelet Decompositions with Blocky Coefficient Kernels CorrelDemo - Wavelet Threshold Estimators for Data with Correlated Noise IdealDemo - Ideal Spatial Adaptation via Wavelet Shrinkage MESDemo - Minimum Entropy Segmentation MIPTDemo - Nonlinear Wavelet Transforms based on Median-Interpolaton RiskDemo - Exact Risk Analysis of Wavelet Regression SCDemo - Nonlinear Wavelet Methods for Recovery of Signals, Densities and Spectra from Indirect and Noisy Data CSpinDemo - Translation-Invariant De-Noising TourDemo - Wavelet Shrinkage and W.V.D. -- A Ten-Minute Tour VdLDemo - WaveLab and Reproducible Research These subdirectories have been created following several rules, which should be followed in making future additions.

2.2. SCRIPT ARCHITECTURE 1. Each article gets one subdirectory of /Wavelab850/Papers/.

2. Each subdirectory contains: (a) meta-routines that run the whole gure-generating process, (b) scripts that generate individual gures, and (c) specialized tools, not present in Wavelab proper, for generating the gures. 3. The les in a subdirectory have stylized names, so that the name indicates the function of the le. 4. Stylized names are based on a name and a short prex. The name should be short but descriptive, for example, Adapt for scripts associated with the paper Adapting to Unknown Smoothness via Wavelet Shrinkage and the prex should be a related tag, just two-characters long, for example ad. 5. The subdirectory name reects the name you have chosen, for example /Wavelab850/Papers/Adapt.

2.2.1

Meta-Routines

There are ve meta-routines underlying the gure-generating process in the current script architecture. For example, the Adapt subdirectory contains: AdaptDemo AdaptInit AdaptFig AdaptIntro AdaptCleanup starts the Demonstration, invokes Choices sets up data structures called from Choices help file, explains contents of directories clears all globals created by the demo

Rather than a lengthy blow-by-blow at this point, it is suggested that the user who wants to understand the detailed structure of these scripts pick one of the subdirectories in the current version and inspect these les.

2.2.2

Specialized Tools

There are several tools available in the Utilities directory to help you with writing scripts. For example, when creating a display through several Plot calls, it is preferable to use Wavelab functions like LockAxes and UnLockAxes rather than to use the low-level Matlab routine hold. See Chapter 8 below.

10

CHAPTER 2. SCRIPTS

2.2.3

Scripting Rules

I. One script creates one complete gure, not a series of gures, and not just a subplot of a gure. II. If several scripts need to work with the same variables for example, if you want a variable to be created in one script and then used in later scripts these variables must be made global (see section 4 below). III. No pauses or prints in a script. IV. As far as possible try to use the tools in the Wavelab Utilities directory to perform actions like setting axes. Inspection of existing scripts will help in following these rules. If you obey these rules, then your scripts should be upwardly compatible with script-running engines making more sophisticated use of the Matlab user interface.

2.2.4

Documenting Individual Figures

Each .m le for an individual gure contains a help header which is displayed in the command window at the time the gure is generated in the plot window. This provides a kind of on-line narrative, or caption. Here is an example from Adapt: % % % % % % % % % % %

adfig10 -- Adapt Figure 10: Wavelet Shrinkage of object yBlocks in Haar Basi (Panel a) depicts the noisy object yBlocks, its Haar transform (Panel c), wavelet shrinkage reconstruction using the Haar wavelet (Panel b), and the Haar Transform of the reconstruction (Panel d). The viewer is supposed to notice that in the Haar domain, the noise is spread out among all coefficients, while the signal is concentrated in only a few coefficients. Hence thresholding mostly affects the noise without disturbing the signal.

Note here the format of the rst line of the help header. Adhering to this format helps various automatic documentation features.

2.3. ADDING NEW SCRIPTS

11

2.3

Adding New Scripts

To add new demonstration scripts to /Wavelab850/Papers/, having the same format and eect as AdaptDemo, AsympDemo, BlockyDemo, CorrelDemo, IdealDemo, MESDemo, MIPTDemo, RiskDemo, SCDemo, CSpinDemo, TourDemo and VdlDemo: 1. Decide on a name for your demo and a short prex for les implementing your demo. For example, MyOwnDemo and mo. 2. Create a new subdirectory of /Wavelab850/Papers/. For example, MyOwn. 3. Create the following m-les: MyOwnDemo MyOwnInit MyOwnFig MyOwnIntro MyOwnCleanup starts the Demonstration, invokes Choices sets up data structures called from Choices help file, explains contents of directories clears all globals created by the demo

Suggestion: copy the corresponding les in one of the other subdirectories of /Papers into your new subdirectory, giving them these names; then edit these les to refer to your own new scripts. 4. Create the scripts which implement your demo: mofig1.m, mofig2.m, etc. The scripts need to follow thee rules mentioned above in sections 2.2, 2.3 and 2.4.

2.4

Modifying Existing Scripts

You might want to modify an existing script for several reasons: To try it out on a dierent dataset; To try it out with dierent parameters; To insert a dierent method in place of the existing method, using the same dataset. Our rules for script creation should help make this possible. Some issues to keep in mind:

12

CHAPTER 2. SCRIPTS

First, the script that generates a certain gure might be dependent on computations done in the process of generating earlier gures. Therefore, the script cannot be assumed to work correctly in stand-alone mode. If the script refers to any global variables then, at a minimum, the corresponding Init script has to be run before the indicated script in order to set global variables up. Second, in order to generate a certain eect, it might therefore be necessary to change earlier scripts, not just the script formally associated with the gure you are interested in. The change might have to be in the Init script (to aect global variables), and might possibly have to be in other scripts as well. Third, when a set of scripts has been well-written, it should be necessary only to change the Init script to produce most changes of the type users will want. As a rst example, to modify the examples in AdaptDemo to work at a sample size 512 rather than 2048, you would edit AdaptInit changing the line N=2048 to N=512. This would then aect every later calculation in the demonstration. As a second example, to modify the examples in AdaptDemo to work with Haar wavelets rather than S8, you would edit AdaptInit changing the line QMF Filter = MakeONFilter(Symmlet,8) to QMF Filter = MakeONFilter(Haar). This would then aect every later calculation in the demonstration.

Chapter 3

Workouts
Here we describe the contents and architecture of the /Workouts subdirectory of Wavelab.

3.1

Workouts Philosophy

/Workouts is a subdirectory of /Wavelab850 that is much like Papers in that it contains a variety of subdirectories, each of which contains a sequence of scripts generating gures. However, Workouts is dierent in that its primary motivation is not to reproduce gures in our own articles. Instead, its motivation is for more informal, exploratory purposes, both (a) To release code which produces gures that correspond to no published papers, but instead demonstrate or test various methodologies; and (b) To release code that approximately reproduces gures in articles by other researchers. We use /Workouts informally in our own research group to communicate new ideas, still being prototyped, to others. We also use /Workouts to test out the ideas of others, so that we can understand the ner points of their work and avoid the twin dangers of, on the one hand, gullibility, and, on the other hand, the not invented here syndrome. We believe that by having an organized place for experimental work we will do better work ourselves. 13

14

CHAPTER 3. WORKOUTS

3.2

Existing Workouts

In the current release, version .850, we distribute the following workouts: /BestOrthoBasis /MatchingPursuit Workouts for Best Ortho Basis (Coifman-Wickerhauser) Workouts for Matching Pursuits (Mallat-Zhang)

/MultiFractal

Workouts illustrating some aspects of the Continuous Wavelet Transform "Cartoon Guide to Wavelets"

/Toons

3.3

Workouts Architecture

It is a good idea to follow the same naming practices and le organization as in the directory /Wavelab850/Papers/.

3.3.1

Naming

In the Best Ortho Basis workout, we use lenames like BBFig01.m, BBFig02.m, etc. In the Toons workout we use names like toon0121.m. We try to number gures in an obvious way and to stick with names no longer than eight characters.

3.3.2

Script Contents

Each le should generate one gure, and should avoid the use of clg, figure, print and pause. This is the same set of rules that we adhere to in /Wavelab850/Papers/.

3.3.3

Meta Routines

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

Chapter 4

Books
The Books/Wavetour directory contain a collection of scripts which reproduce the gures in the book of Stephan Mallat, Wavelet Tour of Signal Processing. We are hoping in the future, as part of teaching and research, to develop more scripts reproducing the work of others.

15

16

CHAPTER 4. BOOKS

Chapter 5

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

5.1

Dataset Philosophy

We make available datasets through 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 le system, or if it needs to be stored in some other format, no scripts that use the data for wavelet 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 centralized synthesizer. In this way, a synthetic signal designed for one use in one script automatically becomes available for other purposes. 17

18

CHAPTER 5. DATASETS

5.2

Dataset Directory

The Contents.m le in the 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. % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % Data Readers BrowseImages ImageFig ReadImage ReadSignal Browser for Image Datasets Called by BrowseImages Uniform Interface to Image Datasets Uniform Interface to Signal Datasets

Data Fabricators MakeBrownian MakeFractal MakeSignal Make2dSignal makediag Make Make Make Make Make Fractional Brownian Motions fractal signals artificial signal artificial 2d signal diagonal pattern (used by Make2dSignal)

1-d Signals caruso.asc esca.asc greasy.asc HochNMR.asc laser.asc RaphNMR.asc seismic.asc sunspots.asc transients.asc tweet.asc old recording by Enrico Caruso ESCA spectrum supplied by J.P. Bib\erian recording of the word greasy from Mallat and Zhang NMR Spectrum supplied by Jeff Hoch Time Series competition Laser series NMR Spectrum supplied by Adrian Maudsley standard PROMAX test seismic signal sunspot numbers artificial signal of Mallat and Zhang recording of a bird singing

5.3. DATASET FORMAT % % % % % % % % % % % % % 2-d Images barton.raw canaletto.raw coifman.raw daubechies.raw fingerprint.raw lenna.raw lincoln.raw mriscan.raw phone.raw -

19

painting of seashore compressed by Jan-Olov Stromberg painting of Venice processed by P. Perona and J. Malik photo of R.R. Coifman photo of Ingrid Daubechies someones fingerprint Lenna Honest Abe someones brain someones phone

5.3

Dataset Format

Datasets currently occur in one of two formats: 1. 1-d Signals. Here the le is destined to become a 1-d signal in Wavelab, i.e. an array of n numbers, where n is dyadic. It is stored as a single column of ASCII text, one number per line. The actual le is located in the directory /Wavelab850/Datasets/, with sux .txt. 2. 2-d Images. Here the le is destined to become a 2-d image in Wavelab, i.e. an array of n by n numbers, where n dyadic. Due to rather large size of such arrays (e.g. 512 by 512), they are stored as arrays of bytes, which can be read in raw format using the Matlab I/O routine fread. The actual le is located in the directory /Wavelab850/Datasets/, with sux .raw.

5.4

Dataset Access

Datasets currently are accessed in one of two ways: 1. 1-d Signals. The fragment sig = ReadSignal(Name) causes Wavelab to look in the correct directory, read the corresponding ASCII le into an array, and shape it to the correct format for a 1-d signal. For a list of currently available names, see the documentation on this function. Examples include RaphaelNMR, Sunspots and Caruso.

20

CHAPTER 5. DATASETS 2. 2-d Image. The fragment sig = ReadImage(Name) causes Wavelab to look in the correct directory and read the corresponding raw format le into an n by n matrix. For a list of currently available names, see the documentation on this function. Examples include Daubechies, Canaletto and Fingerprint.

A side eect of the access methods is that the corresponding documentation le of the dataset is displayed on the Matlab console as the le is read.

5.5

Dataset Documentation

Each dataset in the system has a documentation le, with sux .doc. Here is an example of a documentation le for a 1-d signal: 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. Here is an example of a documentation le for a 2-d image: canaletto.raw -- Gray-scale image of Canaletto painting

5.5. DATASET DOCUMENTATION Access Canal = ReadImage(Canaletto); Size 512 by 512 Gray Levels 256

21

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.

22

CHAPTER 5. DATASETS You will notice the following elds in the documentation: 1. Title. A one-line header at the start of the le, giving the lename, and, after two hyphens, descriptive text. 2. Access. A code fragment indicating the stereotyped access method. 3. Size. The size of the signal or image. 4. Gray Levels. Applicable for Images only. 5. Sampling Rate. Applicable for Sounds only. 6. Source. Indication of the original source of the data. 7. Description. Additional description of the data.

5.6

Synthetic Signals

Synthetic data are currently accessed in one of two ways: 1. 1-d Signals. The fragment sig = MakeSignal(Name,n) causes Wavelab to use a built-in formula to generate a synthetic signal of length n in the correct format for a 1-d signal. For a list of currently available names, see the documentation on this function. Examples include Bumps, Doppler and HeaviSine. 2. 2-d Images. The fragment sig = Make2dSignal(Name,n) causes Wavelab use a built-in formula to generate a synthetic image in an n by n matrix. For a list of currently available names, see the documentation on this function. Examples include Circle, StickFigure and Mondrian.

5.7

Adding New Datasets

To add new datasets to Wavelab, do the following: 1. Installation. Place the dataset, in stereotyped format, in the 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).

5.8. DATASET SOURCES

23

2. Documentation. Insert a .doc le in the Datasets directory to explain the dataset. To add a new synthetic signal or image to Wavelab, simply modify the appropriate function, MakeSignal or Make2dSignal, by inserting a new case in the compound if; the new case tests for a new, previously unused name, and contains a formula dening the signal in that case. 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.

5.8

Dataset Sources

We would like to take this opportunity to thank the sources of our datasets. We reprint here from the le THANKS.m in /Wavelab850/Documentation/. % % % % % % % % % % % % % % % Contributors of Data Jean-Paul Bib\erian, Universite de Marseille, Luminy Chris Brislawn, Los Alamos National Labs John Canny, UC Berkeley R.R. Coifman, Yale University Ingrid Daubechies, AT&T Bell Labs Paul Donoho, Chevron Jeffrey Hoch, Rowland Institute Doug Jones, Univ. Illinois Jitendra Malik, UC Berkeley Stephane Mallat, Courant Institute Adrian Maudsley, VA Medical Center, San Francisco Chris Raphael, Stanford University Jan-Olov Stromberg, University of Tromso Zhifeng Zhang, Courant Institute

24

CHAPTER 5. DATASETS

Chapter 6

Documentation
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.

6.1

Help Headers

Each function in the Wavelab system has documentation contained inside the .m le with its Matlab code. This documentation can be accessed on-line by typing help Name where Name is the name of the function. For example, typing help BestBasis gives: function [basis,value] = BestBasis(tree,D) % BestBasis -- Coifman-Wickerhauser Best-Basis Algorithm % Usage % [btree,vtree] = BestBasis(stree,D) % Inputs % stree stat-tree (output by CalcStatTree) % D maximum depth of tree-search % Outputs % btree basis-tree of best basis % vtree value of components of best basis % vtree(1) holds value of best basis % % Description % The best-basis algorithm is used to pick out the best % basis from all the possible bases in the packet table. 25

26 % % % % % % % % % % % % % % % % % % % % % % % % %

CHAPTER 6. DOCUMENTATION Here best means minimizing an additive measure of information, called entropy by Coifman and Wickerhauser. Once the stattree of entropy values is created, BestBasis selects the best basis using the pruning algorithm described in Wickerhausers book. Examples [n,D] = dyadlength(signal); qmf = MakeONFilter(Coiflet,3); wp = WPAnalysis(signal,D, qmf); stree = CalcStatTree(wp,Entropy); [btree,vtree] = BestBasis(stree,D); Algorithm Yale University has filed a patent application for this algorithm. Commercial Development based on this algorithm should be cleared by Yale University. Contact them for licensing information. See Also WPAnalysis, CalcStatTree, CPTour, WPTour References Wickerhauser, M.V.

_Adapted_Wavelet_Analysis_.

AK Peters (1994).

This illustrates the main components of the format we have adopted: a one-line help header, and sections for Usage, Inputs, Outputs, Side Eects, Description, Examples, Algorithm, See Also and References. 1. Header. The rst line of the help header is called the H1 line by the Matlab folks. It is special to Matlab, and to Wavelab. When you use the lookfor command, Matlab examines this line for each .m le in its path to nd text matching the request. When a release of Wavelab is built, these lines are compiled and sorted in alphabetical order to make les 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.

6.2. DOCUMENTATION DIRECTORY

27

2. 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. 3. 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. 4. Outputs. Here, one line per output variable, indicating the name of the variable, the formal data type and the interpretation. 5. Side Eects. Here, indicate any side eects the routine may have (graphics, sound, etc.). Omit if the function has no side eects. 6. Description. Here, describe what the function does in as much detail as possible. 7. Examples. Here, list examples of how the function is called in practice. This eld is optional. 8. Algorithm. Here, describe the algorithm used by the function. This eld is optional. 9. See Also. Here, mention other routines which this routine calls or which call this one, or routines with a special relationship to this function. This eld is optional.

6.2

Documentation Directory

The directory /Wavelab850/Documentation/ contains a variety of information about Wavelab. There are a number of general les, which describe various terms and conditions and goals. The contents of any of these les may be examined by typing its name. % % % % % % ADDINGNEWFEATURES BUGREPORT COPYING DATASTRUCTURES FEEDBACK GETTINGSTARTED How to Add New Features to WaveLab How to report bugs about WaveLab WaveLab Copying Permissions Basic data structures in WaveLab Give feedback about WaveLab Ideas for getting started with WaveLab

28 % % % % % % % % % INSTALLATION LIMITATIONS PAYMENT READING REGISTRATION SUPPORT THANKS VERSION WARRANTY -

CHAPTER 6. DOCUMENTATION Installation of WaveLab WaveLab known limitations No Charge for WaveLab Software Sources for further reading about wavelets WaveLab Registration WaveLab Support Thanks to contributors Part of WaveLab Version v$VERSION$ No Warranty on WaveLab software

In addition, there are several les compiled automatically during the build process: % % % % WLAlphaSynopsisListing WLContentsListing WLFiles WLHelpHeaders -

one-line synopses arranged by function name all Contents.m files listing of all WaveLab files arranged by director listing of all first lines of help headers

To add or modify the rst group of les, very little is required. Simply add new les. The second group of les, being automatically generated at build time, should not ordinarily be modied. Instead, modify the source from which they are automatically compiled. Because of the automatic build process, it is important to maintain the integrity of certain les. These include: Contents les. Every directory should have a Contents.m le. When adding a new function to a directory, be sure to add it to the directorys Contents le as well. H1 Lines of Help documents. Every .m le should contain a help header, and the H1 line of the help header should follow the rules specied above. $VERSION$ marker. Every Contents.m le has, in the H1 line, a description of what the directory contains, as well as a version marker. The text $VERSION$ is replaced, automatically upon build, by the current version number.

6.3

Workouts Directory

Another useful component of the system documentation is the /Workouts directory, which contains more than a hundred scripts that exercise the software in various ways.

6.4. TEX DOCUMENTS

29

The user can look through the graphics generated by this documentation and, upon seeing something interesting, inspect the corresponding script to see how the graphic was created. This gives, in eect, hundreds of working examples of how Wavelab is used. Currently, the /Workouts directory contains four subdirectories: BestOrthoBasis gives examples of the Coifman-Wickerhauser Best Orthogonal Basis paradigm in operation, on both real and synthetic data. MatchingPursuit gives examples of Matching Pursuit in operation, on both real and synthetic data. MultiFractal gives examples of using the continuous wavelet transform tools. Toons gives more than 100 examples of wavelets and time frequency analysis in operation, both in explanatory mode (e.g. showing examples of wavelets and wavelet packets) and in analysis of signals and images.

6.4

TEX Documents

The system also comes with several documents, written in TEX, which function as manuals for system-maintenance people. The le WaveMacros.tex within WaveLab Master/Documentation contains macros that dene the current version of Wavelab, lenames, le sizes, le locations, etc. This le should be modied appropriately for new releases of Wavelab. It is included by all the documents described below.

6.4.1

About WaveLab

About WaveLab helps a new user with installing and getting started with Wavelab. The corresponding pdf and postscript documents are available at: A http://www-stat.stanford.edu/~ wavelab. The source is written in L TEX. It is contained within the About WaveLab folder in WaveLab Master/Documentation. Sections that may need to be changed with a new release are: section 2.2 (the lenames in the sample session), section 2.3 (the Contents.m le), section 2.5 (the le listings of the top-level Wavelab directory), section 2.6 (the startup screen), section 3.1.1 (if Orthogonal/Contents.m changes), section 3.1.4 (update WLAlphaSynopsisListing and WLHelpHeaders.m), section 3.3

30

CHAPTER 6. DOCUMENTATION

(if the browser changes) and section 5 (if any of the les in Documentation are modied). Also, although the version number of Wavelab is generally not hard-coded in this document (through the use of the WLVersion macro), there are certain instances (e.g. in the Contents.m les) that should be manually replaced.

6.4.2

Architecture

You are currently reading the WaveLab Architecture document. It contains system-level information about the Wavelab distribution. The corresponding postscript document is available via http://www-stat.stanford.edu/~ A wavelab. The source is written in L TEX. It is contained within the WaveLab Architecture folder in WaveLab Master/Documentation. Sections that may need to be changed with a new release are: beginning of section 2.2 (list of papers), beginning of section 3.2 (list of workouts), section 4.2 (the Contents.m le), section 3.8 (thanks to dataset contributors), section 5.2 (if any les in Documentation change), section 5.3 (list of workouts), section 7 (if any les in Utilities change)

Chapter 7

Browsers
In the current release of Wavelab, version .850, /Wavelab850/Browsers/ contains two subdirectories, /One-D and /WaveTour. /One-D contains the browser WLBrowser which allows point-and-click access to a number of interesting features in wavelet transforms, compression and denoising. /Wavetour contains the browser WTBrowser which invokes the scripts that reproduce the gures from the book Wavelet Tour of Signal Processing by S. Mallat. We hope to install further browsers and systematize rules for browsers in the future.

31

32

CHAPTER 7. BROWSERS

Chapter 8

Utilities
Several utilities are available in Wavelab mainly for the purpose of centralizing various programming idioms. If Wavelab is ever to be ported to Octave, for example, these allow one to modify only the utilities to the new platform and achieve the desired eect of platform-independent scripts. The current Contents.m le for /Wavelab850/Utilities/ goes as follows: % % % % % % % % % % % % % % % % AppendTitle AutoImage CutDyad GrayImage HitAnyKey ifprint LockAxes MakeTiledFigures PadDyad RegisterPlot ShapeAsRow ShapeLike UnlockAxes versaplot WaitUntil WhiteNoise Utility to Build Title String Automatic Scaling for Image Display Truncate signal to Dyadic length Image display of Gray-scaled digital images Tool for pausing in scripts Conditional printing to postscript file Version-independent axis command Tile the screen with figures Zero-fill signal to Dyadic length Add legend with file name, date, flag Reshape 1d vector as row Reshape first argument like second argument Version-independent axis command Version-independent plot routine Burn up CPU cycles until sec seconds elapse Version-independent white noise generator

The functions of these utilities can currently be classied into the categories: Graphics, Random Numbers, Shaping Arrays and Scripting. 33

34

CHAPTER 8. UTILITIES

8.1

Graphics

There are several graphics utilities. For image display, the basic image command shipped with Matlab does no scaling of its argument, nor any special choice of colormap or axes. AutoImage(img) provides automatic scaling of any image and a simple colormap. For cases where memory constraints are present and the image is a gray-scale digital image taking values between 0 and ngray-1, GrayImage(img,ngray) displays the image on a gray colormap without any special scaling. For Axis control, LockAxes and UnlockAxes provide version-independent axis control. versaplot bundles together axis, subplot, and other commands into a single multi-purpose, version-independent plotting command. MakeTiledFigures is a tool to ll the screen with non-overlapping gures.

8.2

Random Numbers

WhiteNoise(x) is a version-independent Normal(0,1) random number generator. It returns an array shaped like x lled with normally-distributed pseudo-random numbers. Use of this routine avoids warning messages due to the change of conventions among dierent versions of Matlab for generating random numbers.

8.3

Shaping Vectors

Two routines exist to coerce vectors to have the shape expected by various algorithms in Wavelab. Most of those routines were rst written assuming that signals were row vectors, which is inconvenient from some points of view. So now, at the entry of most algorithms, the argument is reshaped as a row vector, and at the end of most algorithms, the result is reshaped to be in the same form as the input had originally. ShapeAsRow(x) reshapes a 1-d vector (row or column) to be a row vector. ShapeLike(x,y) reshapes the rst argument to conform to the shape of its second argument. Two additional routnes, CutDyad and PadDyad either truncate a signal to have dyadic length (i.e. a power of two), or add zeros to the end of it

8.4. SCRIPTING

35

to enforce this restriction. The fast algorithms in Wavelab depend on the length of a signal being a power of two.

8.4

Scripting

There are several routines to help with scripting. AppendTitle tacks on extra information to a title string, such as parameters particular to a particular gure. RegisterPlot allows the tools in /Papers to indicate, in small print at the bottom of the page, the date a plot was created and the .m le that created it. HitAnyKey pauses execution, asking the user to respond with a key stroke. Optionally, it can print the current graphic before continuing. WaitUntil(tics) burns up CPU cycles so that scripts dont run by too quickly.

36

CHAPTER 8. UTILITIES

Chapter 9

Source and Build

This chapter describes how Wavelab source is compiled into archives for distribution.

9.1

Development System

1 The source for Wavelab development has several components in dierent directories: 2 C Source and Compiled C Source les in a directory named MEX/Mex Source inside the WaveLab Master folder. 3 TeX Source in a directory named Documentation inside the WaveLab Master folder. 4 Shell Source in a directory named shell Tools inside the WaveLab Master folder.

9.2

Shell Tools

About a dozen small Shell scripts are programmed, along with master scripts, to assist in the build process. The script InitWaveVars is called by the highlevel scripts to initialize global variables and usually needs to be modied when modications are made to Wavelab; for example, when new directories are added. Here is an up-to-date list of the high-level les: BuildWaveRelease FolderCompare Master Build Compare Folders to Look for Differences 37

38 InitWaveVars List_WL_HelpHeaders ListWavelabFiles RespelWaveLab SearchWavelab -

CHAPTER 9. SOURCE AND BUILD Initialize Build Variables Compile a listing of all Help Headers Compile a Listing of all Files Rename a function throught Wavelab Source Search Wavelab source for function name

These can be used outside of the Master build process; for example, SearchWaveLab may be used to see which Wavelab functions call a certain specic function. Here is an up-to-date listing of the low-level shell Scripts used as part of the build: AlphaHelpListing AlphaSynopsisListing ShowHelpHeader ShowSynopsisLine Build alphabetic Build alphabetic Show help header Extract synopsis

list of all function help headers list of all function synopsis lines without comment markers name from function header

9.3

Standard Release

The Master Build script is BuildWaveRelease which builds a directory WaveLabvers, where vers is replaced by the version supplied as the argument to BuildWaveRelease of Wavelab being built. A complete copy of the Wavelab package is assembled in that directory, which is located according to the BuildDir variable within the InitWaveVars script. BuildWaveRelease then analyzes and processes the les and directories to produce the standard release. The process of building a standard release involves: 1. Appending copyright notices and date-of-modication information to all les in the library; 2. Compiling .mex les as needed; 3. Assembling lists of all lenames into Documentation/WLFiles; 4. Assembling sorted lists of all one-line help headers into Documentation/WLHelpHeaders.m; 5. Assembling sorted lists of all one-line synopses into Documentation/WLAlphaSynopsisListing;

9.4. COMPILING .PS

39

6. Assembling Documentation/WLContentsListing, a listing of all directory contents les, by alphabetical order of the directory name. 7. Adding the Matlab Source les to a zip le. This .zip le is the nal version that will be made available on the WWW sites.

9.4

Compiling .ps

The Documentation directory within WaveLab Master contains one folder for each of the Wavelab documents: About WaveLab and WaveLab ArchiA tecture. These folders contain the L TEX code for the documents, which are compiled into .ps and .pdf les. These .ps and .pdf les are then made available on the WWW sites.

9.5

Distribution

The uniform download process is chosen for Wavelab. By uniform download process we mean that all the users, independent of the platforms they are using, download the le Wavelabvers.zip in which vers is replaced by the version of the Wavelab. Then during the installation process Wavelab will recognize their platform. Therefore, there is no need for releasing dierent les for dierent platforms anymore. The only thing that the distributor should do is just putting the Wavelabvers.zip (which is the result of BuildWaveRelease) on the WWW site.

40

CHAPTER 9. SOURCE AND BUILD

Chapter 10

Distribution and Maintenance

This chapter describes how Wavelab is distributed and maintained.

10.1

Archive Directory

The Archive directory within WaveLab Master is a depository for old versions of the software and documentation.

10.2

Developer Checklists

A collection of les meant to assist developers are kept in the Checklists folder of WaveLab Master. For example, Adding a New WaveLab Folder describes the series of steps that should be followed to add a new top-level directory to Wavelab. We hope that a complete library of such checklists will be developed as Wavelab evolves.

10.3

WaveLab Account

An account named WaveLab is maintained on rgmiller. All members of the Wavelab development team share its password. The account serves several varied purposes: 1. The sub-directory incoming is used as a centralized location to distribute les among members of our development group. 41

42

CHAPTER 10. DISTRIBUTION AND MAINTENANCE 2. The sub-directory public html holds the les used to maintain our Web page. 3. The current version of Wavelab is always present on this account in the sub-directory WaveLab. 4. The sub-directory VersionBuilder holds .mex binaries for the two most popular Unix platforms: Solaris and Linux. If someone runs into problems compiling the Wavelab .mex les using installMEX, we put up an archive of one of these directories for FTP. We do not include these directories with the standard distribution because .mex les tend to take up a relatively large amount of disk space. 5. Feedback questions, comments, suggestions, etc. may be sent to the development team by e-mailing wavelab@stat.stanford.edu. Currently a .forward le in the WaveLab home directory keeps a copy of any e-mail sent in WaveLabs local mailbox as well as forwarding it to all members of the team.

10.4

Web Page

The URL of the Wavelab WWW page is http://www-stat.stanford.edu/ wavelab. The HTML les for the home page are stored in WaveLab Master/Documentation/W The home page is constantly changing and evolving. New versions and updates are always announced on the home page.