%==============================================================================
%    cohesion.m
%    Copyright (C) 2007  Denise M. Wolf, Amoolya H. Singh, singh@embl.de
%
%    This program 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.
%
%    You should have received a copy of the GNU General Public License
%    along with this program.  If not, see <http://www.gnu.org/licenses/>.
%===============================================================================
function [Nspecies_min, Nspecies_thresh, ...
	  Pct_min_over_thresh, Mean_min_over_thresh,...
	  Mean_min_over_min] = ...
    cohesion(n, Matrix, ind, min_g, thresh_g)

%------------------------------------------------------------------------------
%
% [Nspecies_min, Nspecies_thresh, Pct_min_over_thresh,
% Mean_min_over_thresh,...  Mean_min_over_min] = ...
% cohesion(n, Matrix, ind, min_g, thresh_g) calculates
% Pct_min_over_thresh, the minimum percentage of species with at least
% min_g percent of module genes that have over thresh_g percent of
% module genes.  (example: min_g = 5%, thresh_g = 75% )
%
% Input:
%   n, number of genes in module
%   Matrix, datamatrix (phylogenetic profile genes x species)
%   ind, indices of module
%   min_g, minimum percent of genes in module for species to be counted as
%          being above noise level (e.g., 5% )
%   thresh_g, fraction of genes over which we say the module is 'there' (say,
%              75% )
% 
% Output:
%   Nspecies_min, number of species with more than min_g fraction of module
%   Nspecies_thresh, number of species with more than thresh_g fraction of
%                    module
%   Pct_min_over_thresh, % of species with at least min_g fraction of
%                        module that have more than thresh_g fraction of
%                        module (all or none measure)
%   Mean_min_over_thresh, mean % of genes in module that species have if
%                         they have over the minimum (noise) amount.
% 
%------------------------------------------------------------------------------ 

% the percent of module genes in each species
frac_module_InSpecies = 100*sum(Matrix(ind,:))/length(ind); 
% indices for species with more than min_g percent module genes
Ind_species_min = find(frac_module_InSpecies > min_g);  
% number of species with more than min_g module genes (over noise floor)
Nspecies_min = length(Ind_species_min); 

%  indices for species with more than thresh percent of module (most
%  of module present)
Ind_species_thresh = find(frac_module_InSpecies > thresh_g);  

% number of species with more than thresh percent of module (mostly present)
Nspecies_thresh = length(Ind_species_thresh);  

% of the species with any genes (over noise) that have most genes in
% module (this is module coherence)
Pct_min_over_thresh = 100*Nspecies_thresh/Nspecies_min; 

% mean percent of module genes present in module = YES species
Mean_min_over_thresh = mean(frac_module_InSpecies(Ind_species_thresh));

% mean percent of module genes present in module > noise species [also
% related to coherence]
Mean_min_over_min = mean(frac_module_InSpecies(Ind_species_min));

