function [marginalev,gainev,mutualev,gamma]=MIG_simple(fig,bin,resc_flag)
%
% Matlab function used to calculate and partition the spatial information in a
% regular lattice such as a photographic image. 
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
% Written by Raphael Proulx (UQTR) & Lael Parrott (UBC)
% 
% 2006 - 2014
%
% Available for download from http://complexity.ok.ubc.ca 
%
% NOTE ON USE OF MIG_SIMPLE.M:
%
% MIG_simple.m calls two other functions that should be placed in the same
% sub-directory as MIG_simple.m - histmulti5.m and entropy.m
%
% entropy.m is included with this download (see end of file).
%
% histmulti5.m, written by Hans Olsson, can be downloaded from Matlab
% Central at:
% http://www.mathworks.com/matlabcentral/fileexchange/297-hist/content/hist
% /histmulti5.m
%
% The MIG_simple.m function is provided by the
% authors as is and for academic purposes only.  Any use of this function
% in an academic work should be properly acknowledged.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% HOW TO USE
%
% INPUTS fig, bin, resc_flag
%
% fig: Regular 2D lattice (image) to analyse.  (Note: The lattice must have 
% variable type "double" or the hist function gives errors.  To convert
% integer or other variable types to double, use Matlab's "double" function.)
%
% bin: Values in 'fig' are rescaled to an integer between one and bin.
%
% resc_flag: If resc_flag = 0, the values in fig are NOT rescaled before being binned.
%            If resc_flag = 1 (default), the values in fig ARE first rescaled [0-1].
%
% OUTPUTS marginalev, gainev, mutualev, gamma: 
%
% marginalev (ME): marginal or Shannon entropy of the lattice, scaled
% between 0 (ordered) and 1 (random).  This is an aspatial entropy value.
%
% gainev (MIG): mean information gain, scaled between 0 and 1.  This is the
% information gained by including the spatial information in the lattice.
% It is equal to the joint entropy (entropy of 4 coordinate combinations of
% pixels in the image) minus the marginal entropy.  i.e., the difference
% between spatial and aspatial entropy of the image.
%
% mutualev: Mean mutual information (MMI) - this is the information shared
% between the spatial and aspatial entropies, also normalized between 0 and
% 1.  0 = ordered or random lattice; values increase with spatial
% autocorrelation in the lattice (see Proulx and Parrott, 2008. Ecological
% Indicators 8 : 270-284.)
%
% gamma: a convex complexity function which attains its maximum at an
% intermediate value between order and disorder [0-.25].  Can be used to
% identify the value of MIG for which complexity is maximal. 
% (see Proulx and Parrott, 2008. Ecological Indicators 8 : 270-284.)
% 
%
%
% EXAMPLE:
%
% y=rand(1000,1000);
% z=ones(1000,1000);
%[marginalev,gainev,mutualev,gamma]=MIG_simple(z,10,0)
%
%marginalev =
%
 %    0
%
%
%gainev =
%
     %0
%
%
%mutualev =
%
%     0
%
%
%gamma =
%
 %    0
%
%[marginalev,gainev,mutualev,gamma]=MIG_simple(y,10,0)
%
%marginalev =
%
%    1.0000
%
%
%gainev =
%
%    0.9993
%
%
%mutualev =
%
 %  7.2349e-04
%
%
%gamma =
%
 %  7.2296e-04
% 
% TO USE MIG_SIMPLE TO ANALYSE AN IMAGE FILE:
% 
% im_c=imread('filename'); % read in the image
% im_c=double(im_c); % transform it into double format
% [marginalev,gainev,mutualev,gamma]=MIG_simple(im_c(:,:,1),10,1) % call the function for one of the colour bands in the image
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

sz=size(fig);
li=sz(1,1); co=sz(1,2);

if (nargin<3); resc_flag=1; end;

% Note that here the scaling is relative to the minimum and maximum values
% in the lattice.  The code could be modified to use a predefined min and
% max in the case where a series of lattices are being compared.

if resc_flag == 1;
fig = (fig-min(fig(:)))/(range(fig(:)));
fig = ceil(fig*bin);

fdz = (fig == 0); % Attribute the zeros to bin=1.
fig(fdz) = 1;
end

im1=fig; im1(:,1)=[]; im1(1,:)=[]; im1=im1(:);   % coordinate (i+1,j+1)
im2=fig; im2(:,co)=[]; im2(li,:)=[]; im2=im2(:); % coordinate (i,j)
im3=fig; im3(:,co)=[]; im3(1,:)=[]; im3=im3(:);  % coordinate (i+1,j)
im4=fig; im4(li,:)=[]; im4(:,1)=[]; im4=im4(:);  % coordinate (i,j+1)

% Calculate normalized marginal, gain, and mutual information

marginal=hist(im2,bin)'; marginal=entropy(marginal);
joint=histmulti5([im4 im3 im2 im1],ones(1,4)*bin); joint=joint(:); joint=entropy(joint);

gain=joint-marginal; gainev=gain/(log(bin^4)-log(bin));
mutual=(4*marginal)-joint; mutualev=mutual/((4*log(bin))-log(bin));

marginalev=marginal/log(bin);

% Calculate gamma, a convex complexity function (minimal if uniform or random, maximal if at intermediate values)

gamma=gainev*mutualev;

return


function e=entropy(x)
%ENTROPY   Entropy of a distribution.
%    E=ENTROPY(X) computes the entropy of the
%    distribution X.

error(nargchk(1,1,nargin));
if nargout>1, error('Too many output arguments'), end

for j=1:size(x,2);
  x(:,j)=x(:,j)./sum(x(:,j));
  x2=x(find(x(:,j)),j);
  e(:,j)=sum(-x2.*log(x2));
end