From 6ce76e5df88a65e1aece92393ae7804d5a50e97c Mon Sep 17 00:00:00 2001
From: David <dgleich@stanford.edu>
Date: Fri, 15 May 2009 22:39:55 -0700
Subject: [PATCH] Added examples to dirclustercoeffs.m

---
 Contents.m           |  2 --
 dirclustercoeffs.m   | 30 ++++++++++++++++++++++++++----
 test/test_examples.m |  6 ++++++
 3 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/Contents.m b/Contents.m
index 442f87e..ebce84c 100644
--- a/Contents.m
+++ b/Contents.m
@@ -42,8 +42,6 @@
 % Write demo code
 % Fix mlintrpt errors
 % Update copyright info everywhere
-% Examples for dirclustercoeffs
-% Documentation for dirclustercoeffs
 % Implement bipartite matching
 
 % Future todos
diff --git a/dirclustercoeffs.m b/dirclustercoeffs.m
index 32f85ee..911fea5 100644
--- a/dirclustercoeffs.m
+++ b/dirclustercoeffs.m
@@ -2,11 +2,30 @@
 % DIRCLUSTERCOEFFS Compute clustering coefficients for a directed graph
 %
 % cc=dirclustercoeffs(A) returns the directed clustering coefficients
-% (which are identical to the clustering coefficients on an undirected
-% graph.
+% (which generalize the clustering coefficients of an undirected graph, 
+% and so calling this function on an undirected graph will produce the same
+% answer as clustercoeffs, but less efficiently.)
+%
+% This function implements the algorithm from Fagiolo, Phys Rev. E. 76
+% 026107 (doi:10:1103/PhysRevE.76.026107).  
+%
+% [cc,cccyc,ccmid,ccin,ccout,nf]=dirclusteringcoeffs(A) returns different 
+% components of the clustering coefficients corresponding to cycles,
+% middles, in triangles, and out triangles.  See the manuscript for a 
+% description of the various types of triangles counted in the above
+% metrics.
+%
+% See also CLUSTERCOEFFS
+%
+% Example:
+%   load_gaimc_graph('celegans'); % load the C elegans nervous system network
+%   cc=dirclustercoeffs(A);
+%   [maxval maxind]=max(cc)
+%   labels(maxind) % most clustered vertex in the nervous system
 
 % History
 % 2008-04-22: Initial coding
+% 2009-05-15: Documentation and example
 
 if ~exist('normalized','var') || isempty(normalized), normalized=true; end
 if ~exist('weighted','var') || isempty(weighted), weighted=true; end
@@ -37,9 +56,12 @@
 if nargout>4, ccout=zeros(n,1); end
 if nargout>5, nf=zeros(n,1); end
 % precompute degrees
-for v=1:n, for rpi=rp(v):rp(v+1)-1, w=ci(rpi); 
+for v=1:n, 
+    for rpi=rp(v):rp(v+1)-1, 
+        w=ci(rpi); 
         if v==w, continue; else degs(w)=degs(w)+1; degs(v)=degs(v)+1; end
-end, end        
+    end
+end
 ew=1; ew2=1;
 for v=1:n
     % setup counts for the different cycle types
diff --git a/test/test_examples.m b/test/test_examples.m
index 6971ed6..0b3e58a 100644
--- a/test/test_examples.m
+++ b/test/test_examples.m
@@ -20,6 +20,12 @@
 fprintf('%s',labels{lax}); 
 for i=path; fprintf(' --> %s', labels{i}); end, fprintf('\n');
 
+%% dirclustercoeffs
+load_gaimc_graph('celegans'); % load the C elegans nervous system network
+cc=dirclustercoeffs(A);
+[maxval maxind]=max(cc)
+labels(maxind) % most clustered vertex in the nervous system
+
 %% mst_prim
 load_gaimc_graph('airports'); % A(i,j) = negative travel time
 A = -A; % convert to travel time.