====================================================================
= WAVOS: Wavelet Analysis and Visualization of Oscillatory Signals =
====================================================================
WAVOS 2.3.0(beta)
WAVOS is an open-source MATLAB toolbox designed for exploring
biological oscillators using both discrete and continous wavelets. It
provides user-friendly interfaces to many standard analyses, and
permits batch analyses to be performed on large data sets.
Contents
========
1. Installation
2. Getting started with WAVOS
- GUI interfaces
1) Loading data
2) Selecting denoising/detrending parameters in DWTgui
3) Selecting analysis parameters and views in CWTvis
4) Selecting analysis parameters and analyses in CWTgui
- Command line interface
3. More detailed instructions
4. References
5. Credits and funding acknowledgement
6. List of files
7. Version History
8. License
1. Installation
================
WAVOS requires MATLAB 7.4.0 (R2007a) or higher to run.
To install WAVOS, simply unzip WAVOS to its own directory and add it
to the MATLAB search path. The file "Installation.txt" has
step-by-step instructions on how to do this.
If you are familiar with wavelet analysis, you can dive right in by
typing "WAVOS" at the command line, once WAVOS has been added to the
path.
2.1 Getting started with WAVOS - GUI interfaces
===============================================
WAVOS contains one main interface invoked by entering "WAVOS" at the
command line. This interface allows you to load and orient the data, set
the sample rate, and send the data to one of the three GUIs listed below
via the corresponding button.
- DWTgui: Performs detrending and denoising on data using the discrete
wavelet transform; extremely quick and efficient however it
is relatively inflexible and can only filter specific
wavelengths, depending on the length and sampling rate of
the data. Suitable for preparing data for other
(non-wavelet) analysis methods.
- CWTgui: Performs detailed analysis on data using the Morlet
continuous wavelet transform. Slower than the CWT and it
cannot be used to denoise or detrend the data for use in
other tools, however it provides much more informative
analyses of the data.
- CWTvis: Allows for visualization of several common CWT analyses
prior to beginning full-scale processing. Useful for data
exploration.
These GUIs may also be invoked individually. To analyze data in the MATLAB
workspace, pass it as an argument to the GUI invocation; data in external
files must be loaded from the main WAVOS GUI. WAVOS can import data in
most standard file formats (.mat, .csv, and .xls).
2.1.1 Loading data:
-------------
1. Load a data set using the "Load data" button if needed.
2. Select the correct data orientation, either 1 time series per row
or 1 time series per column in the "Data Orientation" window.
3. Confirm in the status bar at the bottom that the data is loaded
and the correct number of time series has been found.
4. Enter the correct sample rate in the "Sample rate"
2.1.2 Selecting denoising/detrending parameters in DWTgui:
----------------------------------------------------
DWTgui allows you to denoise/detrend the data based upon either
statistical testing, or by selecting specific frequency bands to
remove.
The statistical testing tests against a null hypothesis of white noise
as per Percival and Walden (2000) at the P-level indicated. To
denoise the data by p-value:
1. Enter the desired p-value in the box to the left of the button
"Denoise data by p-value"
2. Press the "Denoise data by p-value" button.
Note that denoising of the data by statistical testing will generally
_not_ detrend it; if you wish to also detrend the data, please use the
level selection dialogue to remove the lowest-frequency components.
Denoising the data by level selection allows you to specify particular
frequency bands to remove or retain for further analysis. To denoise
data by level selection:
1. Select the desired filter length in the pop-up menu to the left of
the "Denoise data by level select" button. See below for
considerations in selecting a filter length.
2. Press the "Denoise data by level select" button.
3. In the resulting popup window, a list of period bands will be
displayed, by default all periods are included. The bottom-most
period band includes all low-frequency components including any
trends in the data. Remove this component to detrend the data.
To remove a period band from the signal, highlight it in the
lefthand column and click "Remove" to move it to the right-hand
column. To restore a period band, highlight it in the right-hand
column and click "Include". When you have selected the desired
period bands, click "Done" to process the data and return to
DWTgui.
IMPORTANT: The sample rate must be set correctly for the correct
periods to be displayed in the frequency band list.
FILTER LENGTH: the separation for frequency bands is not perfect,
short filter lengths permit more "bleed" between frequencies and can
lead to some longer-period signals leaking into shorter-period signals
and vice versa. This problem may be controlled by selecting the
longest filter length feasible that allows access to the period bands
of interest.
When processing is complete, you may select an additional processing
step, or output the data to the desired location (either a MATLAB
variable, a file, or CWTgui).
2.1.3 Selecting analysis parameters and views in CWTvis
-------------------------------------------------------
CWTvis allows for data exploration and tuning of parameters prior to
executing a CWT analysis in CWTgui. When the data is completely
loaded:
1. Select the desired plot type from the popup menu on the left (see
below for descriptions of each)
2. Select analysis options:
- "Gaussian edge correction" applies a corrective term to the
leading and trailing edge of the data to correct for edge effects.
- "Remove edge-affected data" restricts the analysis to only those
points that are not influence by any edge effects.
- "Find ridges with simulated annealing" uses the "Crazy climber"
algorithm of Carmona et. al (1999) to locate ridges rather than
the time-by-time maximum method. This can be extremely slow but
for highly unstable signals can often improve ridge detection.
3. If desired, toggle the "Keep plots updated" button to continuously
update the plot as parameters are changes. This is _not_
recommended for use in conjunction with the "Find ridges with
simulated annealing" option.
4. Press "Draw Plot" if needed, to display the plot.
5. Select other traces within the data set by either clicking the '+'
or '-' buttons to increment or decrement the current trace number,
or enter a specific trace number in the box.
As of version 2.2.1(beta) the following plots are available:
- CWT heatmap: displays the normalized CWT heatmap; lighter colors
indicate higher power at the period and time indicated.
- CWT phases: displays the CWT phase map; white indicates a phase of 0
(peak) while black indicates a phase of pi (trough) for the
signal at the indicated period and time.
- CWT ridges: displays the CWT ridges as identified either by the
"Crazy climber" algorithm (Carmona et. al 1999) or via
time-by-time maximization. Black points indicate the existence
of a strong periodic component having the indicated period at
the indicated time.
- CWT Heatmap + Ridges: Displays the CWT heatmap as well as the CWT ridge
superimposed in blue.
- Data + Period: extracts the period using the selected ridge
location algorithm (see below) and displays it overlaid on the
original data.
- Data + Peak/Trough points: uses the phase extracted from the CWT
ridge using the currently selected ridge extraction algorithm
(see below) to estimate peak and trough times for the cycle.
Overlays a plot with upwards or downwards pointing lines
estimating these times on the original data.
- Data + Period + Peak/Trough points: a combination of the two plots above
- Filtered Data + Amplitude Envelope: Attempts to reconstruct and center
the data within the range of periods specified in the GUI, and plot
it together with the amplitude envelope.
- Data + Period + Amplitude: Estimates the instantaneous amplitude of the
data and plots it along with the original data and instantaneous
period; as above the amplitude will not track any moving baseline
present in the original data.
- Data + Phase: extracts and "unwraps" the phase from the ridge
extracted via the current ridge selection algorithm, and plots
it on top of the current data.
Ridge location algorithms:
- Time-by-time maximization (default): this method looks for the
highest value of the CWT at each particular time point. The method
is fast and robust for signals with relatively smooth period changes.
- Simulated annealing (aka "Crazy climber" method, selected with the
"Find ridges by simulated annealing" checkbox): performs ridge
identification via the "Crazy climber" method as described in
Carmona et. al (1999). This method can be extremely slow, but often
allows for more accurate selection of ridges in signals with rapidly
changing periods.
2.1.4 Selecting analysis parameters and analyses in CWTgui
----------------------------------------------------------
1. Select the desired analysis outputs (see below for a complete list
and description).
2. Select analysis options:
- "Gaussian edge correction" applies a corrective term to the
leading and trailing edge of the data to correct for edge effects.
- "Remove edge-affected data" restricts the analysis to only those
points that are not influence by any edge effects.
- "Find ridges with simulated annealing" uses the "Crazy climber"
algorithm of Carmona et. al (1999) to locate ridges rather than
the time-by-time maximum method. This can be extremely slow but
for highly unstable signals can often improve ridge detection.
3. Press "Do analysis". You will be prompted for a base file name
for the analyses, which will then be saved according to the name
of the analysis, starting with that stem.
As of version 2.2(beta) the following analyses are available:
- Instantaneous Period: extracts the instantaneous period of each data
trace to a single file.
- Instantaneous Phase: extracts the ridge phase (wrapped on an
interval of -pi to pi) for all data to a single file.
- Instantaneous Amplitude: extracts the instantaneous oscillatory
amplitude (roughly 1/2 the peak-to-trough ratio) as determined
by the ridge for all data to a single file.
- Peak times: extracts the time for each peak (as determined by the
CWT ridge) for all data to a single file. IMPORTANT: the
sample rate must be correctly set to extract the correct times.
- Trough times: extracts the time for each trough (as determined by
the CWT ridge) for all data to a single file. IMPORTANT: the
sample rate must be correctly set to extract the correct times.
- Peak-to-trough difference: Estimates the peak-to-trough difference
based upon the estimated peak times and trough times for all
data and saves to a single file. Positive results indicate a
peak-to-trough measure, negative results indicate a
trough-to-peak measure.
- Crossover indices: Returns a list of indexes that the wrapped phase
crosses zero, indicating completion of a half-cycle, and
saves the result to a single file. IMPORTANT: this returns
indexes and not time, this is most often used to extract values
from the data.
- Sync index: Calculates a single sync index using the Rayleigh
statistic for all data. Will only calculate the SI for times
when _all_ traces have available phase data.
If the "Remove edge-affected data" option is selected, then "NaN" will
be used in place of every point that the output is potentially
affected by the edge. Note that for data sets that contain signals
without strong periodicities, this may result in the SI being empty.
2.2 Command line interface
--------------------------
Commonly used command line functions are (as of WAVOS version
2.2.1(beta)):
- Morlet_CWT.m: Performs a Morlet CWT analysis on one or more data
sets, returning a wavelet structure.
- FindCWTridge.m: Uses a specified ridge-finding algorithm to extract
the CWT ridge and related statistics from a wavelet structure
produced by Morlet_CWT.m, producing a wavelet+ridge structure.
- HeatMap.m: Plots a heatmap for either a wavelet or a wavelet+ridge
structure; displays ridges, phases, or signal intensity as a
function of time and period.
- MakeDaubechiesFilter.m: Generates a set of Daubechies filter
coefficients for use in discrete wavelet analysis.
- MODWT.m: Performs a CWT decomposition on one or more data sets,
returns a discrete wavelet structure.
- MakeMRA.m: Converts a discrete wavelet structure to a
multi-resolution analysis, allowing for by-hand filtering or
reconstruction of signals from a DWT analysis.
As of WAVOS version 2.2.1(beta), documentation for most functions is
available in MATLAB through the 'help' command.
3. More detailed instructions
==============================
Please refer to the enclosed .PDF file "WAVOS_guide.pdf" for a
complete and illustrated tutorial.
4. References
===============
- Batschelet, E. 1981. Circular statistics in biology. Academic Press.
- Carmona, R.A., W.L. Hwang, and B. Torresani. 1999. Multiridge
detection and time-frequency reconstruction. Signal Processing, IEEE
Transactions on [see also Acoustics, Speech, and Signal Processing,
IEEE Transactions on] 47, no. 2: 480-492. doi:10.1109/78.740131.
- Daubechies, Ingrid. 1992. Ten lectures on wavelets. Society for
Industrial and Applied Mathematics.
http://portal.acm.org/citation.cfm?id=SERIES9271.130655.
- Goupillaud, P., A. Grossmann, and J. Morlet. 1984. Cycle-octave and
related transforms in seismic signal analysis. Geoexploration 23,
no. 1 (October): 85-102. doi:10.1016/0016-7142(84)90025-5.
- Stephane Mallat. 1999. A Wavelet Tour of Signal Processing. Academic
Press.
- Donald B. Percival, and Andrew T. Walden. 2000. Wavelet Methods for
Time Series Analysis. Cambridge University Press.
- Torrence, Christopher, and Gilbert P. Compo. 1998. A Practical Guide
to Wavelet Analysis. Bulletin of the American Meteorological Society
79, no. 1: 6178.
5. Credits and funding acknowledgement
=======================================
This work has been supported in part by NIH grants GM078993, EB007511,
GM096873-01, and MH63109.
WAVOS versions 1.0(beta) and 1.1(beta) were written by Richard Harang
as part of his graduate work under the supervision of Dr. Guillaume
Bonnet.
WAVOS versions 2.0(beta) and later were written by Richard Harang
under the supervision of Dr. Linda Petzold.
Gaussian edge-correction code contributed by Dr. Guillaume Bonnet.
6. List of files
=================
CWTgui.fig
CWTgui.m
CWTvis.fig
CWTvis.m
Chi2PV_FFT.m
CrazyClimber.m
DWTgui.fig
DWTgui.m
DWTgui_level_select.fig
DWTgui_level_select.m
Filter_DWT.m
FindCWTridge.m
FindPhaseCrossings.m
CWTHeatMap.m
IMODWT_FFT.m
MODWT.m
MODWT_FFT.m
MakeDaubechiesFilter.m
MakeMRA.m
Morlet_CWT.m
OneMOvar_FFT.m
SeriesPV.m
collapseridgesfromcrazyclimber.m
depad_struct.m
documentation
extractridges.m
inverse_morlet_CWT.m
scratch.m
stackplot.m
test.mat
wavelengthbands.m
README.txt
INSTALLATION.txt
GPL.txt
7. Version history
===================
Versions are numbered A.B[.C]; changes in A indicate major releases
that are not mutally compatible, changes in B indicate minor releases
with new or altered functionality but no API change, changes in C
denote minor changes (bug fixes) with no new functionality.
1.0(B): Initial release
1.1(B): Update and bugfix release.
UPDATES:
- CWTgui added
- DWTgui added
- options for zero-embedding time series added
- automatic filtering by p-value added
- "Crazy climber" ridge algorithm added
- inverse_morlet_CWT.m added to reconstruct wavelet portion of
CWT (no scaling functions)
BUG FIXES:
- extractridges.m will no longer get locked in an infinite
loop under certain circumstances
- MODWT_FFT.m will now permit as many levels of decomposition
as should be possible
- depad_struct.m will now throw an error when it attempts to
remove all data
2.0(B): Update release
UPDATES:
- Overhaul of morlet_CWT.m to allow multiple time series to be
processed at once.
- MODWT.m added as main MODWT function, allows multiple time
series to be processed at once, MODWT_FFT demoted to helper
function.
- CWTgui updated to allow batch processing.
- CWTvis added to handle visualization tasks previously
performed by CWTgui
- DWTgui updated to speed batch processing
- Functions updated to use inputParser objects on input, this
breaks backwards compatability, but will allow future
releases to add or change command line options without
breaking script compatability
- Added Gaussian edge correction code (courtesy of
Dr. Guillaume Bonnet)
- Added option to ignore any data potentially tainted by edge
effects
2.1(B): Update+Bugfix release
BUG FIXES:
- Added check for extremely short (4 observations or fewer)
time series in CWTvis and CWTgui
- Indexing error in CWTgui fixed
UPDATES:
- Removal of several excess functions (extractridges,
depad_struct, collapsridgesfromcrazyclimber)
- Updates to inverse_morlet_CWT.m to permit multiple
inversions, updated documentation for inverse_morlet_CWT.m
- Added function to pass data from MATLAB workspace into GUIs
- Changed name of HeatMap.m to CWTHeatMap.m to prevent
conflicts with bioinformatics toolbox
2.2(B): Update+Bugfix release
BUG FIXES:
- Fixed bad reference to handles.sample_rate in
edit_select_data_trace callback.
UPDATES:
- CWTgui can now export data to the MATLAB workspace
- Added visualization options to DWTgui
- Added warning to DWTgui when changing filter length
- Added MRA_plot.m to allow plotting of MRAs from within
DWTgui.
- Added 'CWT+Ridge' plot to CWTHeatmap to superimpose the CWT
ridge on the heatmap.
2.2.1(B): Bug fix release
BUG FIXES:
- Morlet_CWT will now use a reasonable maximum period for circadian
signals (48 hours or less) if no maximum is specified; this
prevents unexpected results in long data sets where large
amplitude changes could look like long-period signals and confuse
the ridge selection algorithm.
- Corrected initialization bug in CWTvis and CWTgui that prevented
changing minimum period until after maximum period had been
changed.
UPDATES:
- Added CWT+Ridge plot to visualization options in CWTvis
- Added amplitude visualization options to CWTvis
- Changed default periods to 6-48, under the assumption that WAVOS
is largely directed at circadian biology users
- Allowed selection of period limits for inverse_morlet_CWT.m,
permitting limited filtering to be done via the Morlet CWT.
2.3.0: Updates and bugfixes
UPDATES:
- New GUI ("WAVOS") that links DWTgui, CWTgui, and CWTvis.
- Data now passes between CWTgui and DWTgui via the WAVOS GUI
- CWT settings now pass between CWTvis and CWTgui via the WAVOS GUI
BUG FIXES:
- Fixed plot formatting in MRA_plot
- Fixed length-zero error in CWT functions
8. License
===========
This file is part of WAVOS.
If you use WAVOS in your research, we ask that you cite it (Richard E Harang,
Guillaume Bonnet and Linda R Petzold; 2012. "WAVOS: a MATLAB toolkit for
wavelet analysis and visualization of oscillatory systems" BMC Research
Notes 2012, 5:163) in any publications that make use of it.
WAVOS is licensed under a modified BSD license, using the template
available at: http://www.opensource.org/licenses/bsd-license.php
Copyright (c) 2011-2012, Regents of the University of California
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Download Latest Version
WAVOS_2.3.1(B).zip (75.7 kB)
