Merge pull request #58 from zengfung/dev

Organize API documentation + Fix bug in SIWT + Improve unit test

docs/src/api/acwt.md

@@ -5,6 +5,7 @@ Modules = [ACWT]
 ```
 
 ## Transforms on 1 Signal
+### Public API
 ```@docs
 ACWT.acdwt
 ACWT.acdwt!
@@ -21,6 +22,7 @@ ACWT.iacwpd!
 ```
 
 ## Transforms on Multiple Signals
+### Public API
 ```@docs
 ACWT.acdwtall
 ACWT.iacdwtall
@@ -31,6 +33,7 @@ ACWT.iacwpdall
 ```
 
 ## Utilities
+### Private API
 ```@docs
 ACWT.autocorr
 ACWT.pfilter
@@ -40,6 +43,7 @@ ACWT.make_acreverseqmfpair
 ```
 
 ## Single Step Transforms
+### Private API
 ```@docs
 ACWT.acdwt_step
 ACWT.acdwt_step!

docs/src/api/bestbasis.md

@@ -5,6 +5,7 @@ Modules = [BestBasis]
 ```
 
 ## Cost functions and computations
+### Public API
 ```@docs
 BestBasis.CostFunction
 BestBasis.LSDBCost
@@ -15,17 +16,23 @@ BestBasis.NormCost
 BestBasis.DifferentialEntropyCost
 BestBasis.ShannonEntropyCost
 BestBasis.LogEnergyEntropyCost
-BestBasis.coefcost
 BestBasis.tree_costs
 ```
 
+### Private API
+```@docs
+BestBasis.coefcost
+```
+
 # Best Basis Tree Selection
+### Private API
 ```@docs
 BestBasis.bestbasis_treeselection
 BestBasis.delete_subtree!
 ```
 
 ## Best basis computation
+### Public API
 ```@docs
 BestBasis.BestBasisType
 BestBasis.LSDB

docs/src/api/denoising.md

@@ -5,6 +5,7 @@ Modules = [Denoising]
 ```
 
 ## Shrinking Types and Constructors
+### Public API
 ```@docs
 Denoising.RelErrorShrink
 Denoising.SureShrink
@@ -13,18 +14,21 @@ Wavelets.Threshold.VisuShrink
 ```
 
 ## Threshold Determination and Noise Estimation
+### Public API
 ```@docs
 Wavelets.Threshold.noisest
 Denoising.relerrorthreshold
 ```
 
 ## Denoising Functions
+### Public API
 ```@docs
 Wavelets.Threshold.denoise
 Denoising.denoiseall
 ```
 
 ## Helper Functions for Threshold Determination and Noise Estimation
+### Private API
 ```@docs
 Denoising.surethreshold
 Denoising.orth2relerror

docs/src/api/dwt.md

@@ -5,6 +5,7 @@ Modules = [DWT]
 ```
 
 ## Transforms on 1 Signal
+### Public API
 ```@docs
 Wavelets.Transforms.wpt
 Wavelets.Transforms.wpt(::AbstractArray{T,2}, ::OrthoFilter, ::Integer; ::Bool) where T<:Number
@@ -21,6 +22,7 @@ DWT.iwpd!
 ```
 
 ## Transforms on Multiple Signals
+### Public API
 ```@docs
 DWT.dwtall
 DWT.idwtall
@@ -31,6 +33,7 @@ DWT.iwpdall
 ```
 
 ## Single Step Transforms
+### Private API
 ```@docs
 DWT.dwt_step
 DWT.dwt_step!

docs/src/api/ldb.md

@@ -5,6 +5,7 @@ Modules = [LDB]
 ```
 
 ## Energy Maps
+### Public API
 ```@docs
 LDB.EnergyMap
 LDB.TimeFrequency
@@ -14,6 +15,7 @@ LDB.energy_map
 ```
 
 ## Discriminant Measures
+### Public API
 ```@docs
 LDB.DiscriminantMeasure
 LDB.ProbabilityDensityDM
@@ -24,10 +26,15 @@ LDB.HellingerDistance
 LDB.LpDistance
 LDB.EarthMoverDistance
 LDB.discriminant_measure
+```
+
+### Private API
+```@docs
 LDB.pairwise_discriminant_measure
 ```
 
 ## Computation of Discriminant Powers
+### Public API
 ```@docs
 LDB.DiscriminantPower
 LDB.BasisDiscriminantMeasure
@@ -37,6 +44,7 @@ LDB.discriminant_power
 ```
 
 ## Feature Extraction and Transformation
+### Public API
 ```@docs
 LDB.LocalDiscriminantBasis
 LDB.fit!

docs/src/api/swt.md

@@ -5,6 +5,7 @@ Modules = [SWT]
 ```
 
 ## Transforms on 1 Signal
+### Public API
 ```@docs
 SWT.sdwt
 SWT.sdwt!
@@ -21,6 +22,7 @@ SWT.iswpd!
 ```
 
 ## Transforms on Multiple Signals
+### Public API
 ```@docs
 SWT.sdwtall
 SWT.isdwtall
@@ -31,6 +33,7 @@ SWT.iswpdall
 ```
 
 ## Single Step Transforms
+### Private API
 ```@docs
 SWT.sdwt_step
 SWT.sdwt_step!

docs/src/api/utils.md

@@ -5,6 +5,7 @@ Modules = [Utils]
 ```
 
 ## Useful wavelet/signal utilities
+### Public API
 ```@docs
 Wavelets.Util.maxtransformlevels
 Utils.getbasiscoef
@@ -17,6 +18,7 @@ Utils.finestdetailrange
 ```
 
 ## Tree traversing functions
+### Public API
 ```@docs
 Wavelets.Util.isvalidtree(::AbstractMatrix,::BitVector)
 Wavelets.Util.maketree
@@ -28,6 +30,7 @@ Utils.gettreelength
 ```
 
 ## Metrics
+### Public API
 ```@docs
 Utils.relativenorm
 Utils.psnr
@@ -36,6 +39,7 @@ Utils.ssim
 ```
 
 ## Dataset generation
+### Public API
 ```@docs
 Utils.ClassData
 Utils.duplicatesignals
@@ -44,6 +48,7 @@ Utils.generateclassdata
 ```
 
 ## Miscellaneous
+### Private API
 ```@docs
 Utils.main2depthshift
 ```

docs/src/api/visualizations.md

@@ -4,14 +4,24 @@
 Modules = [Visualizations]
 ```
 
-## Public API
-```@autodocs
-Modules = [Visualizations]
-Private = false
+## Display multiple signals
+### Public API
+```@docs
+Visualizations.wiggle
+Visualizations.wiggle!
 ```
 
-## Private API
-```@autodocs
-Modules = [Visualizations]
-Public = false
+### Display best basis nodes
+### Public API
+```@docs
+Visualizations.plot_tfbdry
+Visualizations.plot_tfbdry!
+Visualizations.plot_tfbdry2
+Visualizations.plot_tfbdry2!
+```
+
+## Utils
+### Private API
+```@docs
+Visualizations.treenodes_matrix
 ```

src/mod/SIWT.jl

@@ -21,7 +21,7 @@ include("siwt/siwt_utls.jl")
 include("siwt/siwt_one_level.jl")
 include("siwt/siwt_bestbasis.jl")
 
-"""
+@doc raw"""
     siwpd(x, wt[, L, d])
 
 Computes the Shift-Invariant Wavelet Packet Decomposition originally developed by Cohen, Raz
@@ -32,10 +32,27 @@ Computes the Shift-Invariant Wavelet Packet Decomposition originally developed b
 - `x::AbstractVector{T} where T<:AbstractFloat`: 1D-signal.
 - `wt::OrthoFilter`: Wavelet filter.
 - `L::S where S<:Integer`: (Default: `maxtransformlevels(x)`) Number of transform levels.
-- `d::S where S<:Integer`: (Default: `L`) Depth of shifted transform for each node.
+- `d::S where S<:Integer`: (Default: `L`) Depth of shifted transform for each node. Value of
+  `d` must be strictly less than or equal to `L`.
 
 # Returns
 - `ShiftInvariantWaveletTransformObject` containing node and tree details.
+
+# Examples
+```julia
+using Wavelets, WaveletsExt
+
+# Setup
+x = generatesignals(:heavysine)
+wt = wavelet(WT.haar)
+
+# SIWPD
+siwpd(x, wt)        
+siwpd(x, wt, 4)     # level 4 decomposition, where each decomposition has 4 levels of shifted decomposition.
+siwpd(x, wt, 4, 2)  # level 4 decomposition, where each decomposition has 2 levels of shifted decomposition.
+```
+
+**See also:** [`isiwpd`](@ref), [`siwpd_subtree!`](@ref)
 """
 function siwpd(x::AbstractVector{T}, 
                 wt::OrthoFilter, 
@@ -70,6 +87,8 @@ Runs the recursive computation of Shift-Invariant Wavelet Transform (SIWT) at ea
 # Keyword Arguments
 - `signalNorm::T₂ where T₂<:AbstractFloat`: (Default: `norm(siwtObj.Nodes[(0,0,0)].Value)`) 
   Signal Euclidean-norm.
+
+**See also:** [`isiwpd_subtree!`](@ref)
 """
 function siwpd_subtree!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂},
                         index::NTuple{3,T₁},
@@ -116,7 +135,7 @@ function siwpd_subtree!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T
     return nothing
 end
 
-"""
+@doc raw"""
     isiwpd(siwtObj)
 
 Computes the Inverse Shift-Invariant Wavelet Packet Decomposition originally developed by
@@ -128,6 +147,23 @@ Cohen, Raz & Malah.
 
 # Returns
 - `Vector{T₂}`: Reconstructed signal.
+
+# Examples
+```julia
+using Wavelets, WaveletsExt
+
+# Setup
+x = generatesignals(:heavysine)
+wt = wavelet(WT.haar)
+
+# SIWPD
+siwtObj = siwpd(x, wt)
+
+# ISIWPD
+isiwpd(siwtObj)
+```
+
+**See also:** [`siwpd`](@ref), [`isiwpd_subtree!`](@ref)
 """
 function isiwpd(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂}) where
                {N, T₁<:Integer, T₂<:AbstractFloat}
@@ -150,6 +186,8 @@ node `index`.
 - `index::NTuple{3,T₁} where T₁<:Integer`: Index of current node to be decomposed.
 - `h::Vector{T₃} where T₃<:AbstractFloat`: High pass filter.
 - `g::Vector{T₃} where T₃<:AbstractFloat`: Low pass filter.
+
+**See also:** [`siwpd_subtree!`](@ref)
 """
 function isiwpd_subtree!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂},
                          index::NTuple{3,T₁},
@@ -162,7 +200,7 @@ function isiwpd_subtree!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T
 
     # --- Base Case ---
     # If node has no children, return
-    hasNoChildren = !(hasNonShiftedChildren && hasShiftedChildren)
+    hasNoChildren = !(hasNonShiftedChildren || hasShiftedChildren)
     if hasNoChildren
         return nothing
     end
@@ -183,8 +221,8 @@ function isiwpd_subtree!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T
 
     isiwpd_subtree!(siwtObj, child1Index, h, g)
     isiwpd_subtree!(siwtObj, child2Index, h, g)
-
-    isiwpd_step!(siwtObj, index, child1Index, child2Index, h, g)
+    
+    isidwt_step!(siwtObj, index, child1Index, child2Index, h, g)
 
     delete_node!(siwtObj, child1Index)
     delete_node!(siwtObj, child2Index)

src/mod/siwt/siwt_bestbasis.jl

@@ -7,6 +7,23 @@ the best basis tree.
 # Arguments
 - `siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂} where {N, T₁<:Integer,
   T₂<:AbstractFloat}`: SIWT object.
+
+# Examples
+```julia
+using Wavelets, WaveletsExt
+
+# Setup
+x = generatesignals(:heavysine)
+wt = wavelet(WT.haar)
+
+# SIWPD
+siwtObj = siwpd(x, wt)
+
+# Best basis tree
+bestbasistree!(siwtObj)
+```
+
+**See also:** [`bestbasis_treeselection!`](@ref), [`isvalidtree`](@ref)
 """
 function bestbasistree!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂}) where
                        {N, T₁<:Integer, T₂<:AbstractFloat}
@@ -27,6 +44,8 @@ Recursive call to select the best basis tree based on the Shannon entropy cost o
 - `siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂} where {N, T₁<:Integer,
   T₂<:AbstractFloat}`: SIWT object.
 - `index::NTuple{3,T₁} where T₁<:Integer`: Node index for subtree selection.
+
+**See also:** [`bestbasistree!`](@ref),
 """
 function bestbasis_treeselection!(siwtObj::ShiftInvariantWaveletTransformObject{N,T₁,T₂},
                                   index::NTuple{3,T₁}) where