Reference guide

MvVmd{T,S<:Int}

MultiVariable Variational Mode Decompostion 
Return by vmd function.

** Arguments **

• signal::Array{T,2}:signal
• K::S :modes
• signal_d::Array{T,Val{K}}:decomposed signals
• freqs::Array{T,Val{K}}:decomposed spectrums
• samples::S:signal sampled frequency

Vmd{T,S<:Int}

Variational Mode Decompostion 
Return by vmd function.

** Arguments **

• signal::Array{T,1}:signal
• K::S :modes
• signal_d::Array{T,Val{K}}:decomposed signals
• freqs::Array{T,Val{K}}:decomposed spectrums
• samples::S:signal sampled frequency

compare(v::Vmd)

visual compare origin signal and sum of decomposed signal

Multivariate Variational Mode Decomposition

 The function MVMD applies the "Multivariate Variational Mode Decomposition (MVMD)" algorithm to multivariate or multichannel data sets. 
 We have verified this code through simulations involving synthetic and real world data sets containing 2-16 channels. 
 However, there is no reason that it shouldn't work for data with more than 16 channels.
 

 Input and Parameters:
 ---------------------
 signal  - input multivariate signal that needs to be decomposed
 alpha   - the parameter that defines the bandwidth of extracted modes (low value of alpha yields higher bandwidth)
 tau     - time-step of the dual ascent ( pick 0 for noise-slack )
 K       - the number of modes to be recovered
 DC      - true if the first mode is put and kept at DC (0-freq)
 init    - 0 = all omegas start at 0
         - 1 = all omegas start uniformly distributed
         - 2 = all omegas initialized randomly
 tol     - tolerance value for convergence of ADMM


 Output:
 ----------------------
 u       - the collection of decomposed modes
 u_hat   - spectra of the modes
 omega   - estimated mode center-frequencies


 Syntax:
 -----------------------

 [u, u_hat, omega] = MVMD(X, alpha, tau, K, DC, init, tol)
   returns:
			 a 3D matrix 'u(K,L,C)' containing K multivariate modes, each with 'C' number of channels and length 'L', that are 
            computed by applying the MVMD algorithm on the C-variate signal (time-series) X of length L.
    		 - To extract a particular channel 'c' corresponding to all extracted modes, you can use u_c = u(:,:,c).
			 - To extract a particular mode 'k' corresponding to all channels, you can use u_k = u(k,:,:).
			 - To extract a particular mode 'k' corresponding to the channel 'c', you can use u_kc = u(k,:,c).
			 3D matrix 'u_hat(K,L,C)' containing K multivariate modes, each with 'C' number of channels and length 'L', that  
            are computed by applying the MVMD algorithm on the C-variate signal (time-series) X of length L.
			 2D matrix 'omega(N,K)' estimated mode center frequencies
 Usage:
 -----------------------
 	Example 1: Mode Alignment on Synthetic Data
 	T = 1000; t = (1:T)/T;
 	f_channel1 = (cos(2*pi*2*t)) + (1/16*(cos(2*pi*36*t)));  Channel 1 contains 2 Hz and 36Hz tones
 	f_channel2 = (1/4*(cos(2*pi*24*t))) + (1/16*(cos(2*pi*36*t)));  Channel 2 contains 24 Hz and 36Hz tones
 	f = [f_channel1;f_channel2];  Making a bivariate signal
 	[u, u_hat, omega] = MVMD(f, 2000, 0, 3, 0, 1, 1e-7); 
 	Example 2: Real World Data (EEG Data)
 	load('EEG_data.mat');
 	[u, u_hat, omega] = MVMD(data, 2000, 0, 6, 0, 1, 1e-7);
 	Authors: Naveed ur Rehman and Hania Aftab
 	Contact Email: naveed.rehman@comsats.edu.pk

 	Acknowledgments: The MVMD code has been developed by modifying the univariate variational mode decomposition code that has 
                 been made public at the following link. We are also thankful to Dr. Maik Neukrich who helped us in developing a newer faster 
                 version of the code.  
                 https://www.mathworks.com/matlabcentral/fileexchange/44765-variational-mode-decomposition
                 by K. Dragomiretskiy, D. Zosso.
		  
                 

 	Please cite the following papers if you use this code in your work:
   -----------------------------------------------------------------
 
  [1] N. Rehman, H. Aftab, Multivariate Variational Mode Decomposition, arXiv:1907.04509, 2019. 
  [2] K. Dragomiretskiy, D. Zosso, Variational Mode Decomposition, IEEE Transactions on Signal Processing, vol. 62, pp. 531-544, 2014. 
---------- Check for Input Signal              
 Check for getting number of channels from input signal

n_component(v::Vmd,k)

return No k component decomposed signal

n_mode(v::Vmd,k)
return the k mode frequency

vmd(signal;alpha=100, tau=0, K=3, DC=false, init=1, tol=1e-6,samples=100)

Variational Mode Decomposition
Return Vmd

** Argument **

• signal: the time domain signal (1D) to be decomposed
• alpha : the balancing parameter of the data-fidelity constraint
• tau : time-step of the dual ascent ( pick 0 for noise-slack )
• K : the number of modes to be recovered
• DC : true if the first mode is put and kept at DC (0-freq)
• init : 0 = all omegas start at 0 1 = all omegas start uniformly distributed 2 = all omegas initialized randomly
• tol : tolerance of convergence criterion; typically around 1e-6
• sample_frequency : samples frequency(eg:100/s)

** Example **

T = 1000;
t = (1:T)/T;
sample_frequency = 1000;

# center frequencies of components
f_1 = 2;
f_2 = 24;
f_3 = 288;

# modes
v_1 = @. cos(2*pi*f_1*t);
v_2 = @. 1/4*(cos(2*pi*f_2*t));
v_3 = @. 1/16*(cos(2*pi*f_3*t));

# composite signal, including noise
f = v_1 + v_2 + v_3 + 0.1*randn(length(v_1));

# some sample parameters for VMD
alpha = 2000;       # moderate bandwidth constraint
tau = 0;            # noise-tolerance (no strict fidelity enforcement)
K = 3;              # 3 modes
DC = false;             # no DC part imposed
init = 1;           # initialize omegas uniformly
tol = 1e-7;


v = vmd(f ; alpha = alpha,tau = tau,K = K,DC = false,init = 1,tol = tol,sample_frequency = sample_frequency)

# plot original signal and spectrum
plot(v;k = 0)

# plot first decomposed component and spectrum
plot(v;k = 1)

plot(vmd::Vmd;k=1)

visual the decomposed signals and spectrums

** Argument **

• vmd::Vmd : vmd
• k::Int : 0-original signal 1-first component enforcement

plot(vmd::Vmd;k=1)

visual the decomposed signals and spectrums

** Argument **

• vmd::Vmd : vmd
• k::Int : 0-original signal 1-first component enforcement