Looking for the latest version? Download WAVOS_2.3.1(B).zip (75.7 kB)
Home
Name Modified Size Downloads / Week Status
Totals: 2 Items   98.8 kB 5
readme.txt 2012-04-19 23.1 kB 11 weekly downloads
WAVOS_2.3.1(B).zip 2012-04-19 75.7 kB 44 weekly downloads
==================================================================== = 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: 61­­78. 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.
Source: readme.txt, updated 2012-04-19