INSTALLING CHIRPLAB AND CHIRPLABDATASTREAM

1. INTRODUCTION

The code is split into two packages: ChirpLab and ChirpLabDataStream

These packages are collections of Matlab and MEX routines which implement
methods for detecting and estimating highly oscillatory signals in noisy data.
The methods are described in the Thesis 
"Nonparametric Detection and Estimation of Highly Oscillatory Signals",
by Hannes Helgason.

ChirpLabDataStream implements the Two Stage Best Path Test described 
in chapter 4 of the thesis. Once the archive for that code has been unpacked,
check ChirplLabDataStream/README.txt for installation instructions and information
about functions.

2. INSTALLATION

2.1 Requirements

The software requirements

  - tar and gunzip to install the package on Unix-based systems, or zip to
    install the package on Windows.
  - Matlab version 6 or higher.

We have successfully compiled ChirpLab under the following operating systems
and compiler versions:

  - Solaris 9 (SunOS 5.9), cc 5.3
  - Fedora Core 4 Linux, gcc 3.3.6
  - Mac OS X

Compilation on other systems such as Windows should also work just fine.

2.2 Unpacking the archive

To install,

1) Download the compressed archives.

2) Uncompress it at the desired location:

    gunzip -c ChirpLab.tar.gz | tar xfv -

   and

    gunzip -c ChirpLabDataStream.tar.gz | tar xfv -

or use zip if installing under Windows.

This will create a directory tree rooted at ChirpLab/ containing
the source code.

3) Enter the ChirpLab directory:

    cd ChirpLab

4a) Start up MATLAB and run ChirpPath. If the MEX source is not compiled, it
    will be compiled automatically.

4b) You may prefer to compile the MEX source outside MATLAB. To do so type
    "make" in the top ChirpLab directory:

    make

    If this returns errors make sure that your system fulfills the following
    requirements:
      - a C/C++ compiler capable of creating MEX files.
      - GNU make (compilation will not work using non-GNU versions of make).
        On Solaris, aliasing "make" to "gmake" will usually work.
    Some hand editing of the Makefile.include in the top level directory of ChirpLab 
    may be required to set the correct extension for compiled MEX files.

5) Before using ChirpLab, the Matlab paths must be set up. Edit the file
ChirpPath.m and change the variable CHIRPLABPATH to the directory where
ChirpLab is installed. Note that the directory separator character should
be the same as what is normally used on your OS.

(Optional) To permanently add the ChirpLab directories to your
MATLABPATH, you can add the following commands to your Unix profile
For csh-derived shells use:

setenv CHIRPLAB <root directory of ChirpLab>
setenv MATLABPATH ${MATLABPATH}:${CHIRPLAB}/mex/src/Networks:
${CHIRPLAB}/ChirpletTrans:${CHIRPLAB}/Data:${CHIRPLAB}/Data/ForDemos:
${CHIRPLAB}/Networks:${CHIRPLAB}/Utilities:${CHIRPLAB}/Inspiral

For Bourne-shell derived shells use:

CHIRPLAB=<root directory of ChirpLab>; export CHIRPLAB
MATLABPATH= ${MATLABPATH}:${CHIRPLAB}/mex/src/Networks:
${CHIRPLAB}/ChirpletTrans:${CHIRPLAB}/Data:${CHIRPLAB}/Data/ForDemos:
${CHIRPLAB}/Networks:${CHIRPLAB}/Utilities:${CHIRPLAB}/Inspiral

6) To test that ChirpLab is installed properly, start Matlab, set up the paths
using

    ChirpPath

and run the demo script

    FindBPDemo

3. PACKAGES

ChirpletTrans/   --  Functions for the Chirplet Transform.
Data/            --  Directory for storing data from simulations.
Demos/           --  Some examples of using the code.
Documentation/   --  Holds files with documentation for ChirpLab.
Networks/        --  Network flow algorithms for finding the minimum cost to
                     time ratio, shortest path and other related things.
                     Utilities/DisplayChirplets.m can be used to plot the
                     paths. Used for chirp detection.
BPEstimator/     --  Code for implementing the BP Estimator (see chapter 5 in Thesis).
SplineSmoothing/ --  Implementation of a smoothing splines, used in the BP Estimator.
Estimation/      --  Implementation of the estimator based on thresholding in the Best
                     Chirplet Frame, a method introduced by Emmanuel Candes and
                     used in the thesis for comparison with the BP Estimator.
Inspiral/        --  Functions for generating simulated gravitational wave
                     signals.
Utilities/       --  Scripting utilities (for plotting chirplets etc.), code for
                     generating simulated noise and signals.
mex/             --  C/C++ implementations of routines, interfaced with Matlab using mex.


Brief description of the functions in ChirpLabDataStream can be found in that package
in the file ChirpLabDataStream/README.txt