Advanced Biwavelet R Software Package

The advanced biwavelet R package is a modified version of the original biwavelet R package. The advanced biwavelet wavelet package contains additional features such as the cumulative area-wise and arc-wise tests that reduce the number of spurious results arising from the point-wise significance test. This version is the preliminary version and future updates will be made. A brief description of the additional functions found in this package is provided below. A PDF version can be found here. The actual software package can be downloaded by clicking the following link. here

Please Cite: Schulte, J. A.: Statistical Hypothesis Testing in Wavelet Analysis: Theoretical Developments and Applications to India Rainfall, Nonlin. Processes Geophys., https://doi.org/10.5194/npg-2018-55, 2019

Currently, a higher-order wavelet software package is being finalized. The preliminary code can be found here. Because of time constraints, the code has not been fine tuned. However, it is hoped that the upcoming months a better version of the code will be completed. This code is associated wtih the following paper:

Please Cite: Schulte, J., Policielli, F., and Zaitchik, B.: A skewed perspective of the Indian rainfall-El Nino-Southern Oscillation (ENSO) relationship, Hydrol. Earth Syst. Sci., 24, 5473-5489, https://doi.org/10.5194/hess 24 5473 2020, 2020

Brief Description of Functions

check_subset - A simple function that checks whether a contour encloses a hole. This function reduces the number of times the inpolygon function is called by determining if a contour is surrounded by another contour using its minimum and maximum coordinates. This step increasing computational efficiency.

compile_cords - This function determines if a point-wise significance patch is area-wise significant by computing the normalized area of the point-wise significance patch and comparing it to the critical area associated with the geometric significance test. If a point-wise significance patch is deemed geometrically significant (Step 1), then its vertices are stored in two vectors, one for the time vertices and one for the wavelet scale vertices. In Step 2, the normalized area of the point-wise significance patch in question is stored in a vector. Steps 1 and 2 are repeated Npatch times, where Npatch is the number of point-wise significance patches identified at the point-wise significance level in question.

compute_arc_nulldis - Identifies all possible point-wise significance arcs in a point-wise significance matrix (via get_sigarcs) and computes the arc length of the arcs, where arc length is simply the number of data points composing the arcs. The arc lengths are then returned in a single vector.

convert_multisig - Same as convert_sig except that this function operates on a set of point-wise significance levels.

convert_sig - This function extracts the coordinates of the point-wise significance patches from the point-wise significance matrix, which indicates whether a wavelet quantity is point-wise significance at a specified point-wise significance level. After the extraction of the coordinates, the coordinates are passed to compile_cords, which computes the normalized areas of the patches and compares them to the critical level of the geometric significance test. Only the coordinates of those patches that are geometrically significant are returned by complie_cords. If the point-wise significance patch is geometrically significant, then the vertices of the point-wise significance patches get assigned the value of 2 in a new matrix called siggeo. If not geometrically significant, then the vertices retain the default value of 0. All points within the geometrically significant patch get assigned the value of 2 using the cords2matrix function.

cords2matrix - A function that converts a matrix containing 2s at the vertices of geometrically significant point-wise significance patches to a matrix that contains 2s at the vertices and all points enclosed by the contour that defines the point-wise significance patch. This function is a way to convert a polygon represented by a contour into a binary region of interest mask. The function performs a similar task to the MATLAB poly2mask function. An example of what the cords2matrix function does can be in the PDF version of the user guide.

fill_sigholes - This function assigns all points enclosed by a contour representing the boundary of a hole a value of 1, which "fills" in the holes. This step is necessary for the convert_sig function to perform properly.

findholes_fast - computes the number of patches and holes associated with the set of all point-wise significant values

generate_red - A function that generates a realization of red-noise process with a specified lag-1 auto-correlation coefficient.

get_arccrits_coher - Computes the critical levels of the cumulative arc-wise test at a specified point-wise significance levels for wavelet coherence. The critical levels are determined by constructing the null distribution of arc length at each point-wise significance and computing the (1-alpa) percentile of each of the null distributions. The critical arc length associated with each point-wise significance level are returned as a vector.

get_arccrits_power - Computes the critical levels of the cumulative arc-wise test at specified point-wise significance levels for wavelet power. The critical levels are determined by constructing the null distribution of arc length at each point-wise significance and computing the (1-alpa) percentile of each of the null distributions. The critical arc length associated with each point-wise significance level are returned as a vector.

get_areacrits_coher - Computes the critical levels of the cumulative area-wise test for wavelet coherence. The critical levels of the test are determined by computing specified percentiles of the null distribution. This function returns a vector of containing the critical levels of the cumulative area-wise test at each point-wise significance level. The length of the vector is the number of point-wise significance levels used in the implementation of the cumulative area-wise test.

get_areacrits_power - Computes the critical levels of the cumulative area-wise test for wavelet power. The critical level of the test is determined by computing specified percentiles of the null distribution. This function returns a vector of containing the critical levels of the cumulative area-wise test at each point-wise significance level. The length of the vector is the number of point-wise significance levels used in the implementation of the cumulative area-wise test.

get_areanull - Converts a sig matrix (e.g. sigpoint) to a list containing the coordinates of all point-wise significance patches and then computes the normalized areas of all the point-wise significance patches. The function compiles all the normalized areas into a single vector so that it contains elements of the null distribution corresponding to the geometric significance test applied at a specified geometric significance level, csig.level. This function works for wavelet coherence and power analyses.

get_sigarcs - The function loops through each wavelet scale and identifies point-wise significance arcs at each wavelet scale. A point-wise significance arc is a contiguous string of points whose associated wavelet quantities (wavelet power, coherence, etc.) are point-wise significant at the alpha level. They are cross-sections of point-wise significance patches at a wavelet scale in question.

Multisigarc - Same as sigarc except that it has a third dimension to account for multiple point-wise significance levels.

padsig_matrix - pads a significance matrix with zeros.

PHPnull_power - computes the 0- and 1- dimensional persistent homology profiles associated with noise. This is function estimates the critical levels topological signficance test using Monte Carlo methods.

PHP_waveletpower - computes the 0- and 1- dimensional persistent homology profiles associated with a wavelet power spectrum filtered by a nested sequence of point-wise significance sets.

plot.biwavelet_adv - This function is used to plot the results of the cumulative area- and arc-wise tests. It is almost identical to the plot.biwavelet function in the original biwavelet package.

Sigpoint2sigarc - Transforms the sigpoint matrix into a sigarc matrix that is the ratio of normalized arc length to the critical level of the arc-wise test at a single point-wise significance level. If a point-wise significance arc is arc-wise significant, then every point composing the point-wise significance arc is arc-wise significant.

wt_arc - This is the main function that performs the cumulative arc-wise for the wavelet power spectra.

wt_area - This is the main function that performs the cumulative area-wise test for wavelet power spectra.

wtc_arc - This is the main function that performs the cumulative arc-wise test for wavelet coherence.

wtc_area - This is the main function that performs the cumulative area-wise for wavelet coherence.

wtc.multisigs - This function is nearly the same as the wtc.sig function in the original biwavelet package. The only difference is that it computes multiple critical levels of the point-wise test.

Glossary of variables used in the Advanced Biwavelet Package

Anrands - The number of data values that compose the null distribution of arc-length or area.

Arccrit - Critical level of the arcwise associated with a single point-wise significance level.

Areacrit - Critical level of the area-wise test associated with a single point-wise significance level.

Asig.level - Significance level of the arc-length test.

C - A list containing the coordinates of all point-wise significance patches. The length of C is the number of point-wise significance patches at a given point-wise significance level.

Csig.level - Significance level of the cumulative area-wise test.

Multi_areacrit - a vector of critical areas associated with the geometric significance test applied at multiple point-wise significance levels.

Multi_siggeo - A three-dimensional array indicating whether a point in the wavelet domain is cumulative area-wise significant. The third dimension is determined by the number of point-wise significance levels. Entries with values of 2 indicate that the wavelet quantity associated with the point is geometrically significant. A value of 0 indicates that wavelet quantity is not geometrically significant.

Multi_sigpoint - Same as sigpoint except that it has three dimensions to account for multiple point-wise significance levels. The third dimension is determined by the number of point-wise significance levels. Entries with values greater than 1 indicate that the wavelet quantity associated with the point is point-wise significant.

Multi_arccrit - critical levels associated with the cumulative arc-wise test. There is one critical level for each point-wise significance level.

nnull - Length of the noise realizations used to compute the null distributions of normalized arc length or area. Nnull need not equal the length of the input time series. In fact, smaller values of Nnull make the code run faster. As such, the default value of Nnull is 100.

Nrands - The number of iterations used to calculate the critical levels of the point-wise test for wavelet coherence.

nsiglevels - Number of point-wise significance levels.

pcritlevel - Same as pcritlevels but for only a single point-wise significance level.

pcritlevels - A n_scale×n_time×n_sig array containing the critical values associated with the point-wise test. P is equal the number point-wise significance levels used in the implementation of the cumulative area- and arc-wise tests.

psig.level - A vector containing the point-wise significance levels used to implement the area- and arc-wise test. If psig.level has one element, then the cumulative area-wise test reduces to the geometric significance test assessing the area of point-wise significance patches at a single point-wise significance level.

sigarc - A matrix indicating whether a point in the wavelet domain is arc-wise significant. Entries greater than one indicate that wavelet quantity associated with the point is arc-wise significant.

sigarea- A matrix indicating whether a point in the wavelet domain is cumulative area-wise significant. Entries greater than one indicate that the wavelet quantity associated with the point is cumulative area-wise significant. Each entry is the mean of the result of the geometric significance tests performed at each point-wise significance level individually.

sig_atscale - a vector indicating whether wavelet quantities at a fixed wavelet scale and various time points are point-wise significance. Sig_atscale is just a single row of sigpoint.

siggeo - A matrix indicating whether a point in the wavelet domain is geometrically significant. Entries with a value of 2 mean that the wavelet quantity associated with the point is geometrically significant. A value of 0 means that the wavelet quantity is not geometrically significant.

sigpad - The sigpoint matrix with zeros appended to all sides. The appendage ensures that all contours will be enclosed.

sigpoint - A matrix such that the value of each entry is the ratio of a wavelet quantity to the point-wise test critical level at a point in the wavelet domain.

Signull - a point-wise significance matrix associated with a realization of a noise process.