function y = gharmmean(x)
%GHARMMEAN Harmonic mean of a grouped sample.
% In some scientific works, once the data have been gathered from a
% population of interest, it is often difficult to get a sense of what
% the data indicate when they are presented in an unorganized fashion.
% Assembling the raw data into a meaningful form, such as a frequency
% distribution, makes the data easier to understand and interpret. It is
% in the context of frequency distributions that the importance of
% conveying in a succinct way numerical information contained in the data
% is encountered.
% So, grouped data is data that has been organized into groups known as
% classes. The raw dataset can be organized by constructing a table
% showing the frequency distribution of the variable (whose values are
% given in the raw dataset). Such a frequency table is often referred to
% as grouped data.
% The harmonic mean is the reciprocal of the arithmetic mean of the
% reciprocals of the evaluated values. It should be employed in averaging
% any rates (value related to any unit:averaging rate metrics). The
% harmonic mean is best used in situations where extreme outliers exist in
% the population. Because the harmonic mean is unintuitive, it is hard to
% see how to apply it in practical situations. Two examples where the
% harmonic mean is absolutely necessary are variable-speed processors and
% load balancing servers.
% According to Jensen (1998), one can define the power mean, p-norm, or
% generalized mean
%
% Mp = [E[x^p]]^(1/p)
%
% which reduces to the harmonic, geometric and arithmetic means for p =
% -1, p -> 0 (eg. 1/2,1/3,1/4,..1/20000,..,1/n) and p = 1, respectively.
% Here, we developed a m-code to calculate the harmonic mean of a grouped
% data.
% One can input the returns or modified vectors n and xout containing the
% frequency counts and the bin locations of the hist m-function, in a
% column form matrix.
%
% Harmonic mean calculation uses the formula,
%
% H = N/Sum(Fi/MCi)
%
% where:
% Fi = class frequency
% MCi = class mark
% N = sample size [sum(Fi)]
%
% Syntax: function y = gharmmean(x)
%
% Inputs:
% x - data matrix (Size of matrix must be n-by-2; absolut frequency=
% column 1, class mark=column 2)
% Outputs:
% y - harmonic mean of the values in x
%
% Example: Suppose we have the next frequency table:
%
% ----------------
% MC F
% ----------------
% 34.5 2
% 44.5 3
% 54.5 11
% 64.5 20
% 74.5 32
% 84.5 25
% 94.5 7
% ----------------
%
% Taken from:
% http://www.emathzone.com/tutorials/basic-statistics/harmonic-mean.html
%
% Where we are interested to get the harmonic mean value.
%
% Data input:
% x = [34.5 2;44.5 3;54.5 11;64.5 20;74.5 32;84.5 25;94.5 7];
%
% Calling on Matlab the function:
% y = gharmmean(x)
%
% Answer is:
%
% y = 69.6010
%
% Created by A. Trujillo-Ortiz, R. Hernandez-Walls,
% O.A. Mancillas-de-la-Torre and S. Alvarez-Borrego*
% Facultad de Ciencias Marinas
% Universidad Autonoma de Baja California
% Apdo. Postal 453
% *Centro de Investigacion Cientifica y de Educacion Superior
% de Ensenada, Carr. Ens-Tij 3918 Zona Playitas
% Ensenada, Baja California
% Mexico.
% atrujo@uabc.edu.mx
%
% Copyright (C) September 24, 2012.
%
% To cite this file, this would be an appropriate format:
% Trujillo-Ortiz, A., R. Hernandez-Walls, O.A. Mancillas-de-la-Torre and
% S. Alvarez-Borrego. (2012). gharmmean:Harmonic mean of a grouped
% sample. [WWW document]. URL http://www.mathworks.com/matlabcentral/
% fileexchange/38441-gharmmean
%
% Reference:
% Agarwal, B. L. (2006), Basic Statistics. 4th Ed. New Age International
% Ltd., Publishers. Daryaganj:New Delhi.
% Jensen, J. L. (1998), Some statistical properties of power averages for
% lognormal samples. Water Resour. Res. 34(9):2415-2418.
%
c = size(x,2);
if c ~= 2
error('stats:gharmmean:BadData','X must have two colums.');
end
mc = x(:,1); %class mark
f = x(:,2); %absolut frequency
n = sum(f); %sample size
y = n/sum(f./mc);
return,