% FUNCTION:         ADTestMag
% VERSION:          [Wrapper Standalone Version] V2.8
% COMPATIBLE with Matlab version 2017b or later
% REQUIREMENTS: "Statistics and Machine Learning" Matlab Toolbox installed
% TOOLBOX: "Magnitude Complexity Toolbox" within SERA Project
% DOCUMENT: "READ_ME_App_2A_v2_Description_ADTestMag.docx" 
% --------------------------------------------------------------------------------------------------------
% Test performed for the distribution of a given dataset (time-series)
% the distributions to be tested are Exponential and Weibull
% ------------------------------------------------------------------------------------------------------
% OVERVIEW: This Application is a Matlab function which performs the 
% Anderson-Darling (AD) test for testing the null hypothesis whether a given 
% set of magnitudes, follows the Exponential or Weibull distribution. Please 
% check also to the "ADTestMag_wrapper" and "ADTestMag_Plot" scripts 
% for a specific application (scenario) and plotting results.
% -----------------------------------------------------------------------------------------------------
% AUTHORS: K. Leptokaropoulos, and P. Urban  
% last updated: 07/2019, within SERA PROJECT, EU Horizon 2020 R&I
% programme under grant agreement No.730900
% CURRENT VERSION: v2.8        ****   [Wrapper Standalone Version]
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
% PLEASE refer to the accompanying document:
%                                                              "READ_ME_App_2A_v2_Description_ADTestMag.docx" 
% for description of the Application and its requirements.
% ------------------------------------------------------------------------------------------------------
% DESCRIPTION:
% This function performs the Anderson-Darling test (e.g. Anderson & Darling, 
% 1954; Marsaglia & Marsaglia, 2004) for testing the Null Hypothesis, H0, that
% a given set of magnitudes, follows the exponential or the weibull distribution 
% This is accomplished as a function on minimum magnitude, therefore, multiple 
% results are produced (iteration process). The corresponing p-values for the H0 
% is the main output of the program. Before applying the AD test, the magnitude 
% values are randomized within their round-off interval, following the formula 
% introduced by Lasocki and Papadimitriou, 2006.
% -----------------------------------------------------------------------------------------------------
% ITERATION PROCESS:
% The AD test is perform with an iteration process for a variety of magnitude 
% ranges. First the funstion is executed for magnitudes M, with Mmin<M<M1
% where M1 is the higher Magnitude in the selected Catalog. Then, the process
% is repeated for Mmin+EPS<M<M1, then for Mmin+2*EPS<M<M1, etc till
% Mmax<M<M1. Please see INPUT section for reference to the symbols.
% -----------------------------------------------------------------------------------------------------
% INPUT: The function takes as input any matlab vector (input parameter "M").
%           The input data can be uploaded by the use of "ADTestMag_wrapper"
%           script, from an ASCII file (e.g. *.txt). Such file should contain a vector
%           (raw or column) of the Data that the User wishes to process. The User
%           is afterwards requested to enter values for some additional parameters.
%                Input Parameters Overview:
%                --- M: Time-Series (e.g. Magnitude) vector, read i.e. from an ASCII 
%                     file.
%                --- EPS: Round-off interval, i.e. minimum non-zero difference of
%                     the input data. It also corresponds to step for calculations 
%                     (AD test iterations process)
%                --- MTdistribution: The User is requested to define the selected 
%                     parameter distribution for which the null hypothesis is to be 
%                     tested. Possible values: 'exp' for 'Exponential' and 'weibul' for
%                     'Weibull' distribution. 
%                --- Mmin: Corresponds to the minumum input vector value (e.g. 
%                     magnitude) for which the AD test is performed (cut-off value). 
%                     For the magnitude case, it is recommended (yet, not restricted)
%                     to be equal to the catalog completeness threshold, Mc (if known).
%                --- Mmax: Corresponds to the maximum input vector value (e.g. 
%                     magnitude) to be considered as minimum thresohold for the 
%                     AD test to be performed. The maximum value is the one for 
%                     which the number of events with M>=Mmax is greater than 
%                     4 (i. e. the minimum possible sample for ADTestMag function 
%                     exectution). The function automatically finds this value when the 
%                     User sets a higher one.
%                --- trials: Number of randomization realizations (trials) perfomed  
%                     in order to diminish the influence of magnitude randomization 
%                    on the resulting p-value. Recommended value: 100. 
% ------------------------------------------------------------------------------------------------------
% OUTPUT:
%                 --- Output Report with parameters used and results 
%                                      ('Output_ADTestMag.txt file')
%                 --- Output Parameters:
%                        * P - The average of the p-values obtained by the defined
%                                 number of trials performed (also exists within the 
%                                 output structure 'pval')
%                        * S - The corresponding standard deviation of the
%                                 p-values obtained by the defined number of trials
%                        * pval - Structure with the vectors of p-values obtained by the
%                                defined number of trials for each minimum magnitude. 
%                                The structure also contais parameters 'P' and 'mmin'. 
%                          [NOTE: histograms of such p-values indicate that their 
%                          distribution is not normal, neither even symmetric 
%                          for a large number of cases]
%                        * mmin - vector with the minimum magnitudes to which 
%                                   the aforementioned output parameters correspond 
%                                   (also exists within the output structure 'pval')
%                        * NN - vector with number of events corresponding to 
%                                  each mmin value.
%                        * bval - b-value corresponding to each set defined by the 
%                                     aforementioned mmin values
%                 --- Output Figures:
%                 ____ [after running the auxiliary "ADTestMag_Plot" script] _____ 
%                 -     Figure with average p-value (P parameter) as a function of
%                        mmin, together with a histogram of the events count per 
%                        magnitude bin. The 0.05 significance level is plotted as well
% -------------------------------------------------------------------------------------------------------
% REFERENCES:
% -- Lasocki S. and E. E,  Papadimitriou (2006), "Magnitude distribution 
% complexity revealed in seismicity from Greece", J. Geophys. Res., 
% 111, B11309, doi:10.1029/2005JB003794.
% -- Anderson T. W., and D. A. Darling, (1954), "A test of goodness of fit", 
% J. Amer. Stat. Assoc., 49, 765-769.
% -- Marsaglia, G., and J. Marsaglia (2004), "Evaluating the Anderson-Darling
% distribution", J. Stat. Soft., 9, 1-5.
% ------------------------------------------------------------------------------------------------------
% LICENSE 
%     This is free software: you can redistribute it and/or modify it under 
%     the terms of the GNU General Public License as published by the
%     Free Software Foundation, either version 3 of the License, or 
%     (at your option) any later version.
% 
%     This program is distributed in the hope that it will be useful, but 
%     WITHOUT ANY WARRANTY; without even the implied warranty 
%     of MERCHANTABILITY or FITNESS FOR A PARTICULAR
%     PURPOSE. See the GNU General Public License for more details.
% ----------------------------------------------------------------------------------

function [pval,mmin,NN,P,S,bval]=ADTestMag_V2_8(M,EPS,MTdistribution,Mmin,Mmax,trials)
mkdir Outputs_ADTestMag

% Constrain mangitude limits within data range 
if Mmin<min(M);Mmin=min(M);end
if Mmax>max(M);Mmax=max(M);end

% INPUT PARAMETERS ARE SPECIFIED AS FUNCTION ARGUMENTS
M=round(M/EPS)*EPS;
Mmin=floor(Mmin/EPS)*EPS;MMax=ceil(max(M)/EPS)*EPS;
Rp=round(-log10(EPS));
mags=Mmin:EPS:MMax;mags=round(mags/EPS)*EPS;
N=find(abs(mags-Mmax)<EPS/2);

% magnitude distribution to be tested
if strcmp(MTdistribution,'exp')==1;MTdist='Exponential';
elseif strcmp(MTdistribution,'weibul')==1;MTdist='Weibull';
end

% Anderson-Darling Test for exponentiality
% Loop for different magnitudes
for j=1:N

mmin(j)=Mmin+(j-1)*EPS;%mmin=round(mmin/EPS)*EPS;
m=M(M>=mmin(j)-EPS/2);  %  numel(m)
if numel(m)<4;warning(['insufficient events number for M>',num2str(mmin(j)-EPS)]);
    N=j-1;mmin=mmin(1:N);Merr=1;break
else
    Merr=0;cou=0;
for i=1:trials
[beta]=beta_AK_UT_Mbin(mmin(j),m,Rp);
[m_corr]=korekta(m,mmin(j),EPS,beta);

Mag=m_corr-min(m)+EPS/2;

[h1 p1]=adtest(Mag,'Distribution',MTdistribution);
h(i)=h1;p(i,j)=p1;

if p1<=0.0005+eps;cou=cou+1;else, cou=0;end
if cou==2;p(i:trials,j)=0.0005;break;end

end

end
NN(j)=numel(m);bval(j)=beta/log(10);sb(j)=bval(j)/sqrt(NN(j));
P(j)=mean(p(:,j));
S(j)=std(p(:,j));  % p-values are not normally distributed!!
clear b
end

% creating results for the report
for j=1:N
pval(j).p=p(:,j);
pval(j).mmin=mmin(j);
pval(j).P=P(j);
end

for i=1:length(P);
    if P(i)<0.05;h_decision{i,1}='rejected';
    else h_decision{i,1}='not_rejected';
    end
end
%h_decision=h_decision';

RES=[mmin' NN' bval' P' S']
%SAVE OUTPUTS
cd Outputs_ADTestMag
SaveOuts(EPS,Mmin,Mmax,trials,RES,h_decision,MTdist,Merr)
%saveas(gcf,'Exponentiality_Output.jpg')
%print(gcf,'Exponentiality_Output.jpeg','-djpeg','-r300')
cd ../

end

%% ******************************************************************
% *************************** FUNCTIONS ***************************
% ****-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-****
%% --------------------------------------------------------------------------------------
function [beta]=beta_AK_UT_Mbin(Mmin,m,Rp)
%
%   m - magnitude vector
%   Mmin - completeness magitude threshold
%   beta - beta value. b(G-R)=beta/log(10)
%   Rp - Rounding precision, (1 - one decimal, 2 - two decimals, etc)
beta=1/(mean(m)-(Mmin-0.5*10^(-Rp)));
end

%% --------------------------------------------------------------------------------------
%   % Magnitude randomization
%
function [m_corr]=korekta(m,Mmin,EPS,beta)
%
%   m - magnitude vector
%   Mmin - completeness magitude threshold
%   beta - beta value. b(G-R)=beta/log(10)
% EPS - magnitude round-off interval
%
% m_corr - randomized magnitude vector
%
F1=1-exp(-beta*(m-Mmin-0.5*EPS));
F2=1-exp(-beta*(m-Mmin+0.5*EPS));
u=rand(size(m));
w=u.*(F2-F1)+F1;
m_corr=Mmin-log(1-w)./beta;
end
%% --------------------------------------------------------------------------------------------------------
% --------------------------------------- SAVE OUTPUTS in the report file ---------------------------------------
% Save Outputs
function SaveOuts(EPS,Mmin,Mmax,trials,RES,h_decision,MTdist,Merr)
% ---- Save *.txt file with Parameters Report ----
%cd Outputs/
fid=fopen('REPORT_ADTestMag.txt','w');
fprintf(fid,['PARAMETERS & RESULTS from DISTRIBUTION TESTING (created on ', datestr(now),')\n']);
fprintf(fid,'------------------------------------------------------------------------------------\n');
fprintf(fid,['<Round-off interval              >: ', num2str(EPS),'\n']);
fprintf(fid,['<Data Distribution tested        >: ', MTdist,'\n']);
fprintf(fid,['<Data Range for Analysis         >: ', num2str(Mmin), ' to ', num2str(Mmax),'\n']);
fprintf(fid,['<Number of randomization trials  >: ', num2str(trials),'\n']);
fprintf(fid,'------------------------------------------------------------------------------------\n');

fprintf(fid,['Mmin    N    b-value   mean(p)    std(p)    Decision for H0 \n']);
fprintf(fid,['                       from ',num2str(trials),' trials    (0.05 significance)\n']);
for j=1:size(RES,1);
fprintf(fid,['%5.2f %6d  %5.3f    %5.4f     %5.3f      %s  \n'],RES(j,:),h_decision{j});
end
if Merr==1;fprintf(fid,['insufficient events number for M>',num2str(RES(j,1))]);end

fclose(fid);

%saveas()

% Save Output Structure
%  prompt={'\fontsize{12} Please enter output file name:'};
%  name='Extract Output Structure';
%     numlines=1;
%     defaultanswer={'Tdata.mat'};
%   opts.Interpreter='tex';
%   answer=inputdlg(prompt,name,numlines,defaultanswer,opts);
% save(char(answer),'Tdata')
% cd ../

end




