Commit 7e99bed0 by Tiago Peixoto

### Add docstrings to clustering module

parent 300589cb
 ... @@ -16,6 +16,14 @@ ... @@ -16,6 +16,14 @@ # You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License # along with this program. If not, see . # along with this program. If not, see . """ clustering -------------- Provides algorithms for calculation of clustering coefficients, aka. transitivity. """ from .. dl_import import dl_import from .. dl_import import dl_import dl_import("import libgraph_tool_clustering") dl_import("import libgraph_tool_clustering") ... @@ -24,22 +32,214 @@ from numpy import * ... @@ -24,22 +32,214 @@ from numpy import * __all__ = ["local_clustering", "global_clustering", "extended_clustering"] __all__ = ["local_clustering", "global_clustering", "extended_clustering"] def local_clustering(g, prop=None): def local_clustering(g, prop=None, undirected=False): r""" Return vertex property containing local clustering coefficients for all vertices. Parameters ---------- g : Graph Graph to be used. prop : PropertyMap or string, optional Vertex property map where results will be stored. If specified, this parameter will also be the return value. undirected : bool, optional Calculate the *undirected* clustering coefficient, if graph is directed (this option has no effect if the graph is undirected). Returns ------- prop : PropertyMap Vertex property containing the clustering coefficients. See Also -------- global_clustering: global clustering coefficient extended_clustering: extended (generalized) clustering coefficient Notes ----- The local clustering coefficient [1]_ :math:c_i is defined as .. math:: c_i = \frac{|\{e_{jk}\}|}{k_i(k_i-1)} :\, v_j,v_k \in N_i,\, e_{jk} \in E where :math:k_i is the out-degree of vertex :math:i, and .. math:: N_i = \{v_j : e_{ij} \in E\} is the set of out-neighbours of vertex :math:i. For undirected graphs the value of :math:c_i is normalized as .. math:: c'_i = 2c_i. The implemented algorithm runs in :math:O(|V|\left< k\right>^3) time, where :math:\left< k\right> is the average out-degree. If enabled during compilation, this algorithm runs in parallel. Examples -------- >>> g = gt.random_graph(1000, lambda: (5,5), seed=42) >>> clust = gt.local_clustering(g) >>> print gt.vertex_average(g, clust) (0.0045633333333333333, 0.00041406305209606802) References ---------- .. [1] D. J. Watts and Steven Strogatz, "Collective dynamics of 'small-world' networks", Nature, vol. 393, pp 440-442, 1998. doi:10.1038/30918 """ if prop == None: if prop == None: prop = g.new_vertex_property("double") prop = g.new_vertex_property("double") libgraph_tool_clustering.extended_clustering(g._Graph__graph, was_directed = g.directed() [_prop("v", g, prop)]) if g.directed() and undirected: g.set_directed(False) try: libgraph_tool_clustering.\ extended_clustering(g._Graph__graph, [_prop("v", g, prop)]) finally: if was_directed and undirected: g.set_directed(True) return prop return prop def global_clustering(g): def global_clustering(g): r""" Return global clustering coefficients for graphs. Parameters ---------- g : Graph Graph to be used. Returns ------- c : tuple of floats Global clustering coefficient and standard deviation (jacknife method) See Also -------- local_clustering: local clustering coefficient extended_clustering: extended (generalized) clustering coefficient Notes ----- The global clustering coefficient [1]_ :math:c is defined as .. math:: c = 3 \times \frac{\text{number of triangles}} {\text{number of connected triples}} The implemented algorithm runs in :math:O(|V|\left< k\right>^3) time, where :math:\left< k\right> is the average (total) degree. If enabled during compilation, this algorithm runs in parallel. Examples -------- >>> g = gt.random_graph(1000, lambda: (5,5), seed=42) >>> print gt.global_clustering(g) (0.0086380072318200073, 0.00044516087903790925) References ---------- .. [1] M. E. J. Newman, "The structure and function of complex networks", SIAM Review, vol. 45, pp. 167-256, 2003 """ c = libgraph_tool_clustering.global_clustering(g._Graph__graph) c = libgraph_tool_clustering.global_clustering(g._Graph__graph) return c return c def extended_clustering(g, props=None, max_depth=3): def extended_clustering(g, props=None, max_depth=3, undirected=False): r""" Return a list of vertex properties containing the extended clustering coefficients for all vertices. Parameters ---------- g : Graph Graph to be used. props : list of PropertyMap objects, optional list of vertex property maps where results will be stored. If specified, this parameter will also be the return value. max_depth : int, optional Maximum clustering order (default: 3). undirected : bool, optional Calculate the *undirected* clustering coefficients, if graph is directed (this option has no effect if the graph is undirected). Returns ------- prop : list of PropertyMap objects List of vertex properties containing the clustering coefficients. See Also -------- local_clustering: local clustering coefficient global_clustering: global clustering coefficient Notes ----- The definition of the extended clustering coefficient :math:c^d_i of order :math:d is defined as .. math:: c^d_i = \frac{\left|\right\{ \{u,v\}; u,v \in N_i | d_{G(V\diagdown \{i\})}(u,v) = d \left\}\right|}{\binom{\left|N_i\right|}{2}}, where :math:d_G(u,v) is the shortest distance from vertex :math:u to :math:v in graph :math:G, and .. math:: N_i = \{v_j : e_{ij} \in E\} is the set of out-neighbours of :math:i. According to the above definition, we have that the traditional local clustering coefficient is recovered for :math:d=1, i.e., :math:c^1_i = c_i. The implemented algorithm runs in :math:O(|V|\left< k\right>^{2+\text{max_depth}}) worst time, where :math:\left< k\right> is the average out-degree. If enabled during compilation, this algorithm runs in parallel. Examples -------- >>> g = gt.random_graph(1000, lambda: (5,5), seed=42) >>> clusts = gt.extended_clustering(g, max_depth=5) >>> for i in xrange(0, 5): ... print gt.vertex_average(g, clusts[i]) ... (0.0045633333333333333, 0.00041406305209606802) (0.027705, 0.0010493633929938454) (0.11730666666666667, 0.00201118990760307) (0.41394666666666663, 0.0030157036105470745) (0.41717499999999996, 0.0030272310298907366) References ---------- .. [1] A. H. Abdo, A. P. S. de Moura, "Clustering as a measure of the local topology of networks", arXiv:physics/0605235v4 """ was_directed = g.directed() if g.directed() and undirected: g.set_directed(False) if props == None: if props == None: props = [] props = [] for i in xrange(0, max_depth): for i in xrange(0, max_depth): props.append(g.new_vertex_property("double")) props.append(g.new_vertex_property("double")) libgraph_tool_clustering.extended_clustering(g._Graph__graph, try: [_prop("v", g, p) for p in props]) libgraph_tool_clustering.\ extended_clustering(g._Graph__graph, [_prop("v", g, p) for p in props]) finally: if was_directed and undirected: g.set_directed(True) return props return props
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!