function StuMaxtest(X,t,alpha)
%STUMAXTEST Stuart-Maxwell's Test for Marginal Homogeneity.
% STUMAXTEST performs the Stuart-Maxwell's test for all the marginal
% homogeneity (i.e. across all the categories simultaneously) for each
% of the two sample times (nominal samples). Obviously, it need a square
% KxK table. It is a non-parametric statistical test. The test was
% proposed by Stuart (1955), Maxwell (1970) and Everitt (1977).
% Stuart-Maxwell's test is asymptotically equivalent to the Bhapkar's test
% by a n-times value. This because the Bhapkar's test works with the
% marginal probabilities for category i.
%
% If we have a square table for a variable with K categories for each
% of the two sample times,
%
% Sample time 1
% ----------------------------
% 1 2 . j . K
% ----------------------------
% 1 n_11 n_12 . . . n_1K n_1+
%
% 2 n_21 n_22 . . . n_2K n_2+
% . . . .
% Sample time 2 i . n_ij . n_i+
% . . . . . . .
%
% K n_K1 n_K2 . . . n_KK n_K+
% ----------------------------
% n_+1 n_+2 n_+j n_+K n
%
% the sample difference in marginal totals (+) for category i is,
%
% d_i = n_i+ - n_+i ; i = 1,2,...,K.
%
% Let d = [d_i, d_2,. . ., d_K-1. We do not use d_k because knowing the
% first K-1 values determines d_K.
%
% The sample covariance matrix S of d has elements,
% _
% |
% | s_ii = n_i+ + n_+i - 2n_ii ; for i == j
% s_ij = <
% | s_ij = -(n_ij + n_ji) ; for i ~= j
% |_
%
%
% The Stuart-Maxwell statistic is calculated as:
%
% SM = d*inv(S)*d',
%
% where d' is the transpose of row vector d and matrix inv(S) is the inverse of S.
%
% SM is interpreted as a Chi-squared value with degrees of freedom df equal
% to K - 1. In the case of K = 2, the Stuart-Maxwell statistic and the McNemar
% statistic are identically equal.
%
% The null hypothesis is stated that the proportion of ordinal values in sample
% time 2 is equal to the proportion of ordinal values in sample time 1,
%
% Ho: p_2 = p_1 or p_2 - p_1 = 0.
%
% Syntax: function StuMaxtest(X,t,alpha)
%
% Inputs:
% X - data matrix defined by the KxK observed frequency cells.
% t - desired test [t = 1, one-tail; t = 2, two-tail (default)].
% alpha - significance level (default = 0.05).
%
% Output:
% A table with the SM statistic, number of categories, degrees of
% freedom and the P-values.
%
% Example: From an example given on the Quoc Hung Huynh's thesis. URL address
% http://www.vhml.org/theses/huynhqh/. On the section 6.1 Evaluation of
% Results and Appendix G. From the second demonstration for the character
% that was shown, with the inclusion of FAML tags. Respondents were asked
% to comment on the "expressiveness" of the Talking Head, how "life-like"
% it performed. Participants were shown the Talking Head and asked to rate
% on a scale of one to five how life-like, among others (believable, realistic
% and interesting), the Talking Head appeared. The null hypothesis is stated
% that the proportion of ordinal values in demonstration 2 (with FAML tags)
% is equal to the proportion of ordinal values in demonstration 1 (without
% FAML tags). This indicates that there was no significant increase of ranking
% values for all questions answered. There were 35 participants. Data are on
% the following table:
%
% First demostration variable (before)
% ---------------------------------------
% 1 2 3 4 5
% ---------------------------------------
% 1 0 0 0 0 0
% Second 2 0 4 0 0 0
% demostration 3 1 5 3 0 0
% variable 4 0 2 12 6 0
% (after) 5 1 0 0 1 0
% ---------------------------------------
%
% Data matrix must be:
% X=[0 0 0 0 0;0 4 0 0 0;1 5 3 0 0;0 2 12 6 0;1 0 0 1 0];
%
% Calling on Matlab the function:
% StuMaxtest(X,1,0.05)
%
% Answer is:
%
% Table for the Stuart-Maxwell's test for marginal homogeneity.
% -------------------------------------------------------------------
% SM statistic Number of categories df P
% -------------------------------------------------------------------
% 19.5571 5 4 0.0006
% -------------------------------------------------------------------
% For a selected two-saided test.
% With a given significance of: 0.050
% [If P-value >= alpha, test is not significative. Else, it results significative.]
%
% Created by A. Trujillo-Ortiz, R. Hernandez-Walls and A. Castro-Perez
% Facultad de Ciencias Marinas
% Universidad Autonoma de Baja California
% Apdo. Postal 453
% Ensenada, Baja California
% Mexico.
% atrujo@uabc.mx
% Copyright (C) November 14, 2004.
%
% To cite this file, this would be an appropriate format:
% Trujillo-Ortiz, A., R. Hernandez-Walls and A. Castro-Perez. (2004). StuMaxtest:
% Stuart-Maxwell's Test for Marginal Homogeneity. A MATLAB file. [WWW document]. URL
% http://www.mathworks.com/matlabcentral/fileexchange/loadFile.do?object Id=6367
%
% References:
%
% Agresti, A. (2002), Categorical Data Analysis (2nd ed.). NY: John Wiley & Sons.
% Bhapkar, V.P. (1966), A note on the equivalence of two test criteria for hypotheses
% in categorical data. Journal of the American Statistical Association, 61:228-235.
% Everitt, B. S. (1977), The Analysis of Contingency Tables. London: Chapman & Hall.
% Huynh, Q. H. (2000), A Facial Animation Markup Language (FAML) for the Scripting
% of a Talking Head. Bachelor of Science (Computer Science) (Honours) Thesis.
% School of Computing Curtin University of Technology Perth, Western Australia.
% URL address http://www.vhml.org/theses/huynhqh/
% Maxwell, A. E. (1970), Comparing the classification of subjects by two independent
% judges. British Journal of Psychiatry, 116:651-655.
% Stuart, A. A. (1955), A test for homogeneity of the marginal distributions in a
% two-way classification. Biometrika, 42:412-416.
%
if nargin < 3,
alpha = 0.05; %(default)
elseif (length(alpha)>1),
error('Requires a scalar alpha value.');
elseif ((alpha <= 0) | (alpha >= 1)),
error('Requires 0 < alpha < 1.');
end;
if nargin < 2,
t = 2; %two-tailed test (default)
end;
[r c] = size(X);
if r ~= c,
error('WARNING:Input data matrix must be square (KxK).');
return;
end;
K = r; %number of categories
R = sum(X');
C = sum(X);
%Computation of the K-1 values of the sample difference in marginal frequency totals
%for category i.
D = R-C;
d = D([1:end-1]);
%Calculation of the (K-1)x(K-2)/2 covariances of the elements of d.
s = (R+C)' - 2*diag(X);
s = s([1:end-1]);
s = diag(s);
%Calculation of the K-1 variances of the elements of d.
M = X-diag(diag(X));
L = tril(M);
U = triu(M)';
ss = -(L+U);
ss = ss(1:end-1,1:end-1);
S = ss+s+ss'; %(K-1)x(K-1) matrix of the variances and covariances of the elements of d
SM = d*inv(S)*d'; %Stuart-Maxwell statistic
v = K-1; %degrees of freedom
P = 1-chi2cdf(SM,v); %P-value approximation by an asymptotic Chi-square distribution
if t == 1;
P = P/2;
else t == 2;
P = P;
end;
disp(' ')
disp('Table for the Stuart-Maxwell''s test for marginal homogeneity.')
fprintf('-------------------------------------------------------------------\n');
disp(' SM statistic Number of categories df P ');
fprintf('-------------------------------------------------------------------\n');
fprintf(' %10.4f %10.i %10.i %10.4f\n',[SM,r,v,P].');
fprintf('-------------------------------------------------------------------\n');
if t == 1;
disp('For a selected one-saided test.')
fprintf('With a given significance of: %.3f\n', alpha);
disp('[If P-value >= alpha, test is not significative. Else, it results significative.]')
else t == 2;
disp('For a selected two-saided test.')
fprintf('With a given significance of: %.3f\n', alpha);
disp('[If P-value >= alpha, test is not significative. Else, it results significative.]')
end;
disp(' ')
return;
