U td@sFdZddlmZddlmZddlmZmZddlm Z ddl m Z ddl m Z ddlmZdd lmZdd lmZdd lmZdd lmZGd ddZGdddeZGdddZGdddeZGdddZGdddeZGdddeZddZd/ddZ d0d!d"Z!d1d#d$Z"d2d%d&Z#d'd(Z$d3d*d+Z%d4d,d-Z&d.S)5z$Classes related to graph clustering.)deepcopy)StringIO) GraphBasecommunity_to_membership) Configuration)UniqueIdGenerator)ClusterColoringPalette)CairoDendrogramDrawer)MatplotlibDendrogramDrawer) Histogram)_get_wrapper_for_width) deprecatedc@seZdZdZd!ddZddZddZd d Zd d Zd dZ ddZ e ddZ e ddZ ddZddZd"ddZd#ddZdd ZdS)$ Clusteringa Class representing a clustering of an arbitrary ordered set. This is now used as a base for L{VertexClustering}, but it might be useful for other purposes as well. Members of an individual cluster can be accessed by the C{[]} operator: >>> cl = Clustering([0,0,0,0,1,1,1,2,2,2,2]) >>> cl[0] [0, 1, 2, 3] The membership vector can be accessed by the C{membership} property: >>> cl.membership [0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2] The number of clusters can be retrieved by the C{len} function: >>> len(cl) 3 You can iterate over the clustering object as if it were a regular list of clusters: >>> for cluster in cl: ... print(" ".join(str(idx) for idx in cluster)) ... 0 1 2 3 4 5 6 7 8 9 10 If you need all the clusters at once as lists, you can simply convert the clustering object to a list: >>> cluster_list = list(cl) >>> print(cluster_list) [[0, 1, 2, 3], [4, 5, 6], [7, 8, 9, 10]] NcCsNt||_t|jdkr4tdd|jDd|_nd|_|rJ|j|dS)zConstructor. @param membership: the membership list -- that is, the cluster index in which each element of the set belongs to. @param params: additional parameters to be stored in this object's dictionary.rcss|]}|dk r|VqdSN.0mrrJ/home/sam/Atlas/atlas_env/lib/python3.8/site-packages/igraph/clustering.py Dsz&Clustering.__init__..N)list _membershiplenmax_len__dict__update)self membershipparamsrrr__init__;s  zClustering.__init__cs2dks|jkrtdfddt|jDS)zReturns the members of the specified cluster. @param idx: the index of the cluster @return: the members of the specified cluster as a list @raise IndexError: if the index is out of boundsrzcluster index out of rangecsg|]\}}|kr|qSrr)rieidxrr Ssz*Clustering.__getitem__..)r IndexError enumeraterrr%rr$r __getitem__KszClustering.__getitem__cCs>ddt|jD}t|jD]\}}|||qt|S)zIterates over the clusters in this clustering. This method will return a generator that generates the clusters one by one.cSsg|]}gqSrrr_rrrr&Zsz'Clustering.__iter__..)rangerr(rappenditer)rclustersr%clusterrrr__iter__UszClustering.__iter__cCs|jS)zQReturns the number of clusters. @return: the number of clusters )rrrrr__len___szClustering.__len__cCs|jdddS)NrN verbositywidthsummaryr3rrr__str__fszClustering.__str__cCs t|j|S)zFReturns a L{Cover} that contains the same clusters as this clustering.)Cover_graphr3rrras_coveriszClustering.as_covercOst||f||S)a5Compares this clustering to another one using some similarity or distance metric. This is a convenience method that simply calls L{compare_communities} with the two clusterings as arguments. Any extra positional or keyword argument is also forwarded to L{compare_communities}.)compare_communities)rotherargskwdsrrr compare_tomszClustering.compare_tocCs|jddS)zReturns the membership vector.N)rr3rrrrvszClustering.membershipcCs t|jS)z:Returns the number of elements covered by this clustering.rrr3rrrn{sz Clustering.ncCs t||SzjReturns the size of a given cluster. @param idx: the cluster in which we are interested. rr)rrrsizeszClustering.sizecsLdgt||jD]}|dk r|d7<q|rHfdd|DSS)Returns the size of given clusters. The indices are given as positional arguments. If there are no positional arguments, the function will return the sizes of all clusters. rNrcsg|] }|qSrrrr%countsrrr&sz$Clustering.sizes..rD)rrAxrrKrsizess zClustering.sizesrcCst||SzReturns the histogram of cluster sizes. @param bin_width: the bin width of the histogram @return: a L{Histogram} object r rNrZ bin_widthrrrsize_histogramszClustering.size_histogramrcCst}tdt|jt|f|d|dkr8|Sttt|}t|d|dd}t| D].\}}d||f|_ td | ||dqh|S) aReturns the summary of the clustering. The summary includes the number of items and clusters, and also the list of members for each of the clusters if the verbosity is nonzero. @param verbosity: determines whether the cluster members should be printed. Zero verbosity prints the number of items and clusters only. @return: the summary of the clustering as a string. z+Clustering with %d elements and %d clustersfiler subsequent_indent[%*d]  ) rprintrrgetvaluestripstrr r(_formatted_cluster_iteratorinitial_indentjoinwraprr7r8outndigitswrapperr%r1rrrr:s"   zClustering.summaryccs$|D]}ddd|DVqdS)aIterates over the clusters and formats them into a string to be presented in the summary., css|]}t|VqdSrr^rmemberrrrrsz9Clustering._formatted_cluster_iterator..Nrarr1rrrr_sz&Clustering._formatted_cluster_iterator)N)r)rN)__name__ __module__ __qualname____doc__r!r*r2r4r;r>rCpropertyrrErHrNrRr:r_rrrrrs"'        rcseZdZdZdZdfdd Zed ddZddZd!d d Z d d Z e d dZ e Z e ddZddZddZddZddZddZddZddZZS)"VertexClusteringaThe clustering of the vertex set of a graph. This class extends L{Clustering} by linking it to a specific L{Graph} object and by optionally storing the modularity score of the clustering. It also provides some handy methods like getting the subgraph corresponding to a cluster and such. @note: since this class is linked to a L{Graph}, destroying the graph by the C{del} operator does not free the memory occupied by the graph if there exists a L{VertexClustering} that references the L{Graph}. Ncs||dkr"tdg||n&t||kr:tdt||||_||_|dk|_|dkrni|_n t ||_dS)a7Creates a clustering object for a given graph. @param graph: the graph that will be associated to the clustering @param membership: the membership list. The length of the list must be equal to the number of vertices in the graph. If C{None}, every vertex is assumed to belong to the same cluster. @param modularity: the modularity score of the clustering. If C{None}, it will be calculated when needed. @param params: additional parameters to be stored in this object. @param modularity_params: arguments that should be passed to L{Graph.modularity} when the modularity is (re)calculated. If the original graph was weighted, you should pass a dictionary containing a C{weight} key with the appropriate value here. Nrz"membership list has invalid length) superr!vcountr ValueErrorr= _modularity_modularity_dirty_modularity_paramsdict)rgraphr modularityr modularity_params __class__rrr!s zVertexClustering.__init__csddlmddfddzt}d}Wntk rHd}YnXd kr^|j|}nJ|rtfd d |j|D}n"tfd d |j|D}td d <fd d |D}|||d |S)aCreates a vertex clustering based on the value of a vertex attribute. Vertices having the same attribute will correspond to the same cluster. @param graph: the graph on which we are working @param attribute: name of the attribute on which the clustering is based. @param intervals: for numeric attributes, you can either pass a single number or a list of numbers here. A single number means that the vertices will be put in bins of that width and vertices ending up in the same bin will be in the same cluster. A list of numbers specify the bin positions explicitly; e.g., C{[10, 20, 30]} means that there will be four categories: vertices with the attribute value less than 10, between 10 and 20, between 20 and 30 and over 30. Intervals are closed from the left and open from the right. @param params: additional parameters to be stored in this object. @return: a new VertexClustering object rbisectcSs|dkr dSt||S)z2Safe integer division that handles None gracefullyN)int)rMyrrr safeintdivsz2VertexClustering.FromAttribute..safeintdivcs|dkr dS||S)z0Safe list bisection that handles None gracefullyNr) intervalsrMrrr safebisectsz2VertexClustering.FromAttribute..safebisectTFNcsg|]}|qSrrrrM)rrrrr&'sz2VertexClustering.FromAttribute..csg|]}|qSrrr)rrrrr&*scsg|] }|qSrrrr"idgenrrr&.s)rr/ TypeErrorvsrfloatr)clsr{ attributerr r,iterableZvecr)rrrrrr FromAttributes&    zVertexClustering.FromAttributecCs t|j|S)zTReturns a L{VertexCover} that contains the same clusters as this clustering.) VertexCoverr=r3rrrr>1szVertexClustering.as_covercCs0|j}||j||dk r,|j|d|S)aReturns a graph where each cluster is contracted into a single vertex. In the resulting graph, vertex M{i} represents cluster M{i} in this clustering. Vertex M{i} and M{j} will be connected if there was at least one connected vertex pair M{(a, b)} in the original graph such that vertex M{a} was in cluster M{i} and vertex M{b} was in cluster M{j}. @param combine_vertices: specifies how to derive the attributes of the vertices in the new graph from the attributes of the old ones. See L{Graph.contract_vertices()} for more details. @param combine_edges: specifies how to derive the attributes of the edges in the new graph from the attributes of the old ones. See L{Graph.simplify()} for more details. If you specify C{False} here, edges will not be combined, and the number of edges between the vertices representing the original clusters will be equal to the number of edges between the members of those clusters in the original graph. @return: the new graph. F) combine_edges)r{copyZcontract_verticesrsimplify)rZcombine_verticesrresultrrr cluster_graph6s   zVertexClustering.cluster_graphcs|jfdd|jDS)wReturns a boolean vector where element M{i} is C{True} iff edge M{i} lies between clusters, C{False} otherwise.cs g|]\}}||kqSrrrZv1Zv2rrrr&Xsz-VertexClustering.crossing..rr{ get_edgelistr3rrrcrossingTs zVertexClustering.crossingcCs|jr|S|jS)zReturns the modularity score)rx_recalculate_modularity_saferwr3rrrr|\szVertexClustering.modularitycCs|jSz*Returns the graph belonging to this objectr=r3rrrr{eszVertexClustering.graphcCs"|jj|jf|j|_d|_|jS)awRecalculates the stored modularity value. This method must be called before querying the modularity score of the clustering through the class member C{modularity} or C{q} if the graph has been modified (edges have been added or removed) since the creation of the L{VertexClustering} object. @return: the new modularity score F)r=r|rryrwrxr3rrrrecalculate_modularityjs z'VertexClustering.recalculate_modularitycCs<z.z|WW Stk r*YW dSXW5d|_XdS)zRecalculates the stored modularity value and swallows all exceptions raised by the modularity function (if any). @return: the new modularity score or C{None} if the modularity function could not be calculated. FN)rxr Exceptionr3rrrrzs z-VertexClustering._recalculate_modularity_safecCs|j||SaGet the subgraph belonging to a given cluster. Precondition: the vertex set of the graph hasn't been modified since the moment the cover was constructed. @param idx: the cluster index @return: a copy of the subgraph r=subgraphr)rrrrs zVertexClustering.subgraphcsfddDS)Gets all the subgraphs belonging to each of the clusters. Precondition: the vertex set of the graph hasn't been modified since the moment the cover was constructed. @return: a list containing copies of the subgraphs csg|]}j|qSrrrclr3rrr&sz.VertexClustering.subgraphs..rr3rr3r subgraphsszVertexClustering.subgraphscCs |}t|}|||S)arReturns the largest cluster of the clustered graph. The largest cluster is a cluster for which no larger cluster exists in the clustering. It may also be known as the I{giant community} if the clustering represents the result of a community detection function. Precondition: the vertex set of the graph hasn't been modified since the moment the cover was constructed. @note: there can be multiple largest clusters, this method will return the copy of an arbitrary one if there are multiple largest clusters. @return: a copy of the largest cluster. )rNrrindex)rssmax_sizerrrgiantszVertexClustering.giantcsddlm}d|krDd|jkrD||fdd|D|d<|dd}|dkrhtt||d<d |krt d r||d <nt |d ||d <d |kr|j |d <|j j ||f||}|S) aL Plots the clustering to the given Cairo context or matplotlib Axes. This is done by calling L{Graph.__plot__()} with the same arguments, but coloring the graph vertices according to the current clustering (unless overridden by the C{vertex_color} argument explicitly). This method understands all the positional and keyword arguments that are understood by L{Graph.__plot__()}, only the differences will be highlighted here: - C{mark_groups}: whether to highlight some of the vertex groups by colored polygons. Besides the values accepted by L{Graph.__plot__} (i.e., a dict mapping colors to vertex indices, a list containing lists of vertex indices, or C{False}), the following are also accepted: - C{True}: all the groups will be highlighted, the colors matching the corresponding color indices from the current palette (see the C{palette} keyword argument of L{Graph.__plot__}. - A dict mapping cluster indices or tuples of vertex indices to color names. The given clusters or vertex groups will be highlighted by the given colors. - A list of cluster indices. This is equivalent to passing a dict mapping numeric color indices from the current palette to cluster indices; therefore, the cluster referred to by element I{i} of the list will be highlighted by color I{i} from the palette. The value of the C{plotting.mark_groups} configuration key is also taken into account here; if that configuration key is C{True} and C{mark_groups} is not given explicitly, it will automatically be set to C{True}. In place of lists of vertex indices, you may also use L{VertexSeq} instances. In place of color names, you may also use color indices into the current palette. C{None} as a color name will mean that the corresponding group is ignored. - C{palette}: the palette used to resolve numeric color indices to RGBA values. By default, this is an instance of L{ClusterColoringPalette}. @see: L{Graph.__plot__()} for more supported keyword arguments. r)default_edge_colors edge_colorcolorcsg|] }|qSrrrZ is_crossingcolorsrrr&sz-VertexClustering.__plot__..paletteN mark_groupsplotting.mark_groups vertex_color)igraph.drawing.colorsrr{edge_attributesrgetrrrinstance&_handle_mark_groups_arg_for_clusteringrr=__plot__)rbackendcontextrArBrrrrrrrs(0       zVertexClustering.__plot__c#s`|jr<|jjd|D]}dfdd|DVqn |D]}ddd|DVq@dS)rgnamerhc3s|]}t|VqdSrrirjnamesrrrsz?VertexClustering._formatted_cluster_iterator..css|]}t|VqdSrrirjrrrrsNr=Zis_namedrrarmrrrr_s   z,VertexClustering._formatted_cluster_iterator)NNNN)NN)NN)rnrorprqZ_default_paletter! classmethodrr>rrrrr|qr{rrrrrrr_ __classcell__rrr~rrss0 % 5     Krsc@sxeZdZdZddZedddZddZd d Zdd d Z dddZ ddZ e ddZ e ddZejddZdS) DendrogramaThe hierarchical clustering (dendrogram) of some dataset. A hierarchical clustering means that we know not only the way the elements are separated into groups, but also the exact history of how individual elements were joined into larger subgroups. This class internally represents the hierarchy by a matrix with n rows and 2 columns -- or more precisely, a list of lists of size 2. This is exactly the same as the original format used by C{igraph}'s C core. The M{i}th row of the matrix contains the indices of the two clusters being joined in time step M{i}. The joint group will be represented by the ID M{n+i}, with M{i} starting from one. The ID of the joint group will be referenced in the upcoming steps instead of any of its individual members. So, IDs less than or equal to M{n} (where M{n} is the number of rows in the matrix) mean the original members of the dataset (with ID from 0 to M{n}), while IDs up from M{n+1} mean joint groups. As an example, take a look at the dendrogram and the internal representation of a given clustering of five nodes:: 0 -+ | 1 -+-+ | 2 ---+-+ <====> [[0, 1], [3, 4], [2, 5], [6, 7]] | 3 -+ | | | 4 -+---+--- cCsNdd|D|_t|j|_|jr>t|jd|jd|_nd|_d|_dS)zmCreates a hierarchical clustering. @param merges: the merge history either in matrix or tuple formatcSsg|] }t|qSr)tuplerpairrrrr&-sz'Dendrogram.__init__..rN)_mergesr_nmergesr_nitems_names)rmergesrrrr!)s  zDendrogram.__init__Nc Cs|dkrt|d}t|}t|}t|D]r\}}|\}}z2||||}} |||| f||<d|| <Wn$tk rtdd|YnX||q,dd|DS)zConverts the matrix representation of a clustering to a tuple representation. @param merges: the matrix representation of the clustering @return: the tuple representation of the clustering Nrz&malformed matrix, subgroup referenced zbefore being created in step %dcSsg|]}|dk r|qSrrrrrrr&Msz.)rr-r(r'rvr.) rrEZ tuple_reprZidxsZrowidxrowr"jZidxiZidxjrrr_convert_matrix_to_tuple_repr5s$    z(Dendrogram._convert_matrix_to_tuple_reprcCs|g}t}tt|j|jD]X}||kr,q|g}|r|}||||jkr^||q2||j ||jq2q|S)aConducts an inorder traversal of the merge tree. The inorder traversal returns the nodes on the last level in the order they should be drawn so that no edges cross each other. @return: the result of the inorder traversal in a list.) setreversedr-rrpopaddr.extendr)rrZ seen_nodesZ node_indexstacklastrrr_traverse_inorderOs   zDendrogram._traverse_inordercCs |jddS)Nr)r7r9r3rrrr;lszDendrogram.__str__newickcCs|dkr|j|j}|jdkr,tt|}n t|j}t||krb|ddt|t|Dt|j|jD]:\}\}}d||||||f||<d||<||<qp|ddSt d|dS) aXFormats the dendrogram in a foreign format. Currently only the Newick format is supported. Example: >>> d = Dendrogram([(2, 3), (0, 1), (4, 5)]) >>> d.format() '((2,3)4,(0,1)5)6;' >>> d.names = list("ABCDEFG") >>> d.format() '((C,D)E,(A,B)F)G;' rNcss|] }dVqdSNrr+rrrrsz$Dendrogram.format..z (%s,%s)%sr;zunsupported format: %r) rrrrr-rrr(rrv)rformatrEZnodeskr"rrrrros      zDendrogram.formatr(cCst}td|j|jf|d|jdks:|dks:|j|krF|Std|ddg|j}|}d}d}d}t|D]6\} } ||| <t| || <|t |t || d7}qzt |d} td|d ||dd} |j} | |jkrdg| }|D]}|dkrd ||<qd |}t |dD]}t||dq(d}| |jkr|j | \}}|| ks|| krrq| d7} ||||}}d \||<||<||kr||}}|||dd ||d}d ||||d<|d7}q@| |7} td ||dq|S) aReturns the summary of the dendrogram. The summary includes the number of leafs and branches, and also an ASCII art representation of the dendrogram unless it is too large. @param verbosity: determines whether the ASCII representation of the dendrogram should be printed. Zero verbosity prints only the number of leafs and branches. @param max_leaf_count: the maximal number of leafs to print in the ASCII representation. If the dendrogram has more leafs than this limit, the ASCII representation will not be printed even if the verbosity is larger than or equal to 1. @return: the summary of the dendrogram as a string. z"Dendrogram, %d elements, %d mergesrSrrrNrrU|)rr-z`%s')rr[rrr\r]rr(r^rrrar-rr.)rr7Zmax_leaf_countrdZ positionsZinorderZdistanceZlevel_distanceZnextpr%elementr8ZmidxZmax_community_idxZ char_arraypositionZchar_strr,Z cidx_incrZid1Zid2Zpos1pos2dashesrrrr:sd              zDendrogram.summarycOsh|dkrt|}nD|dd}|dd}|dkr:td|dkrJtdt|||}|j|f|dS)aDraws the dendrogram on the given Cairo context or matplotlib Axes. Supported keyword arguments are: - C{orientation}: the orientation of the dendrogram. Must be one of the following values: C{left-right}, C{bottom-top}, C{right-left} or C{top-bottom}. Individual elements are always placed at the former edge and merges are performed towards the latter edge. Possible aliases: C{horizontal} = C{left-right}, C{vertical} = C{bottom-top}, C{lr} = C{left-right}, C{rl} = C{right-left}, C{tb} = C{top-bottom}, C{bt} = C{bottom-top}. The default is C{left-right}. matplotlibbboxNrz bbox is required for Cairo plotsz#palette is required for Cairo plots)r rrvr Zdraw)rrrrArBZdrawerrrrrrrs    zDendrogram.__plot__cCs t|jS)z-Returns the performed merges in matrix format)rrr3rrrrszDendrogram.mergescCs|jS)z0Returns the names of the nodes in the dendrogram)rr3rrrrszDendrogram.namescCs|dkrd|_dSt|}t||jkr6td|j|j|j}|d||_t|j|kr|jddt|t|jDdS)z-Sets the names of the nodes in the dendrogramNzmust specify at least %d namescss|] }dVqdSrrr+rrrrsz#Dendrogram.names..)rrrrrvrrr-)ritemsrErrrrs )N)r)rr)rnrorprqr! staticmethodrrr;rr:rrrrrsetterrrrrr s    P  rcsNeZdZdZd fdd Zd ddZeddZejd dZd d Z Z S)VertexDendrogramz[The dendrogram resulting from the hierarchical clustering of the vertex set of a graph.Ncs6t|||_||_|dkr(i|_n t||_dS)aCreates a dendrogram object for a given graph. @param graph: the graph that will be associated to the clustering @param merges: the merges performed given in matrix form. @param optimal_count: the optimal number of clusters where the dendrogram should be cut. This is a hint usually provided by the clustering algorithm that produces the dendrogram. C{None} means that such a hint is not available; the optimal count will then be selected based on the modularity in such a case. @param params: additional parameters to be stored in this object. @param modularity_params: arguments that should be passed to L{Graph.modularity} when the modularity is (re)calculated. If the original graph was weighted, you should pass a dictionary containing a C{weight} key with the appropriate value here. N)rtr!r=_optimal_countryrz)rr{r optimal_countr r}r~rrr!s  zVertexDendrogram.__init__csT|dkr|j}|j}tt|j|||}fdd|D}t|j||jdS)a}Cuts the dendrogram at the given level and returns a corresponding L{VertexClustering} object. @param n: the desired number of clusters. Merges are replayed from the beginning until the membership vector has exactly M{n} distinct elements or until there are no more recorded merges, whichever happens first. If C{None}, the optimal count hint given by the clustering algorithm will be used If the optimal count was not given either, it will be calculated by selecting the level where the modularity is maximal. @return: a new L{VertexClustering} object. Ncsg|] }|qSrrrrrrr&Asz2VertexDendrogram.as_clustering..)r})rr=rurrrrsry)rrEZnum_eltsrrrr as_clustering0s  zVertexDendrogram.as_clusteringcCs|jdk r|jS|j}|dkr&dSd|t|j}}tt|dt|jdD]8}t|j||}|jj|f|j }||krV||}|}qV||_|S)afReturns the optimal number of clusters for this dendrogram. If an optimal count hint was given at construction time, this property simply returns the hint. If such a count was not given, this method calculates the optimal number of clusters by maximizing the modularity along all the possible cuts in the dendrogram. Nrr) rr=rurrr-minrr|ry)rrEZmax_qrstepZmembsrrrrrFs   zVertexDendrogram.optimal_countcCstt|d|_dS)Nr)rrr)rvaluerrrrasc Osnddlm}Gddd|}||jj|}dd|D|_ddt|jD|_tj|||f||}|`|S)zDraws the vertex dendrogram on the given Cairo context or matplotlib Axes See L{Dendrogram.__plot__} for the list of supported keyword arguments.r)AttributeCollectorBasec@seZdZdZdZdS)z6VertexDendrogram.__plot__..VisualVertexBuilderZvertex_N)rnrorpZ _kwds_prefixlabelrrrrVisualVertexBuilderlsrcSsg|] }|jqSr)r)rZvertexrrrr&qsz-VertexDendrogram.__plot__..cSs$g|]\}}|dk r|nt|qSrri)rr%rrrrr&rs)Zigraph.drawing.metamagicrr=rrr(rr) rrrrArBrrZbuilderrrrrres zVertexDendrogram.__plot__)NNN)N) rnrorprqr!rrrrrrrrrr~rrs   rc@s~eZdZdZdddZddZddZd d Zd d Ze d dZ e ddZ ddZ ddZ dddZdddZddZdS) r<a<Class representing a cover of an arbitrary ordered set. Covers are similar to clusterings, but each element of the set may belong to more than one cluster in a cover, and elements not belonging to any cluster are also allowed. L{Cover} instances provide a similar API as L{Clustering} instances; for instance, iterating over a L{Cover} will iterate over the clusters just like with a regular L{Clustering} instance. However, they are not derived from each other or from a common superclass, and there might be functions that exist only in one of them or the other. Clusters of an individual cover can be accessed by the C{[]} operator: >>> cl = Cover([[0,1,2,3], [2,3,4], [0,1,6]]) >>> cl[0] [0, 1, 2, 3] The membership vector can be accessed by the C{membership} property. Note that contrary to L{Clustering} instances, the membership vector will contain lists that contain the cluster indices each item belongs to: >>> cl.membership [[0, 2], [0, 2], [0, 1], [0, 1], [1], [], [2]] The number of clusters can be retrieved by the C{len} function: >>> len(cl) 3 You can iterate over the cover as if it were a regular list of clusters: >>> for cluster in cl: ... print(" ".join(str(idx) for idx in cluster)) ... 0 1 2 3 2 3 4 0 1 6 If you need all the clusters at once as lists, you can simply convert the cover to a list: >>> cluster_list = list(cl) >>> print(cluster_list) [[0, 1, 2, 3], [2, 3, 4], [0, 1, 6]] L{Clustering} objects can readily be converted to L{Cover} objects using the constructor: >>> clustering = Clustering([0, 0, 0, 0, 1, 1, 1, 2, 2, 2]) >>> cover = Cover(clustering) >>> list(clustering) == list(cover) True rcCsXdd|D|_ztdd|jD|_Wntk rDd|_YnXt||j|_dS)aConstructs a cover with the given clusters. @param clusters: the clusters in this cover, as a list or iterable. Each cluster is specified by a list or tuple that contains the IDs of the items in this cluster. IDs start from zero. @param n: the total number of elements in the set that is covered by this cover. If it is less than the number of unique elements found in all the clusters, we will simply use the number of unique elements, so it is safe to leave this at zero. You only have to specify this parameter if there are some elements that are covered by none of the clusters. cSsg|] }t|qSr)rrr1rrrr&sz"Cover.__init__..css|]}|rt|dVqdS)rN)rrrrrrsz!Cover.__init__..rN) _clustersr_nrv)rr0rErrrr!s  zCover.__init__cCs |j|S)z)Returns the cluster with the given index.)r)rrrrrr*szCover.__getitem__cCs t|jS)z)Iterates over the clusters in this cover.)r/rr3rrrr2szCover.__iter__cCs t|jS)z-Returns the number of clusters in this cover.rrr3rrrr4sz Cover.__len__cCs|jdddS)z-Returns a string representation of the cover.rr5r6r9r3rrrr;sz Cover.__str__cCsBddt|jD}t|D] \}}|D]}|||q(q|S)zReturns the membership vector of this cover. The membership vector of a cover covering I{n} elements is a list of length I{n}, where element I{i} contains the cluster indices of the I{i}th item. cSsg|]}gqSrrr+rrrr&sz$Cover.membership..)r-rr(r.)rrr%r1itemrrrrs zCover.membershipcCs|jS)z@Returns the number of elements in the set covered by this cover.)rr3rrrrEszCover.ncCs t||SrFrGr)rrrrHsz Cover.sizecs$|rfdd|DSddDS)rIcsg|]}tj|qSrrrJr3rrr&szCover.sizes..cSsg|] }t|qSrrGrrrrr&sr)rrArr3rrNsz Cover.sizesrcCst||SrOrPrQrrrrRszCover.size_histogramNcCst}tdt||d|dkr.|Sttt|}t|d|dd}t|D].\}}d||f|_ td | ||dq^|S) aReturns the summary of the cover. The summary includes the number of items and clusters, and also the list of members for each of the clusters if the verbosity is nonzero. @param verbosity: determines whether the cluster members should be printed. Zero verbosity prints the number of items and clusters only. @return: the summary of the cover as a string. zCover with %d clustersrSrrUrVrWrYrZ) rr[rr\r]r^r r(r_r`rarbrcrrrr: s  z Cover.summaryccs$|D]}ddd|DVqdS)rgrhcss|]}t|VqdSrrirjrrrr(sz4Cover._formatted_cluster_iterator..Nrlrmrrrr_$sz!Cover._formatted_cluster_iterator)r)r)rN)rnrorprqr!r*r2r4r;rrrrErHrNrRr:r_rrrrr<s9     r<csVeZdZdZdfdd ZddZeddZd d Zd d Z d dZ ddZ Z S)raThe cover of the vertex set of a graph. This class extends L{Cover} by linking it to a specific L{Graph} object. It also provides some handy methods like getting the subgraph corresponding to a cluster and such. @note: since this class is linked to a L{Graph}, destroying the graph by the C{del} operator does not free the memory occupied by the graph if there exists a L{VertexCover} that references the L{Graph}. NcsJ|dkrt|g}tj||d|j|kr@td||_dS)a Creates a cover object for a given graph. @param graph: the graph that will be associated to the cover @param clusters: the list of clusters. If C{None}, it is assumed that there is only a single cluster that covers the whole graph. N)rEzOcluster list contains vertex ID larger than the number of vertices in the graph)r-rurtr!rrvr=)rr{r0r~rrr!7szVertexCover.__init__cs(dd|jDfdd|jDS)rcSsg|] }t|qSr) frozensetrrrrr&Msz(VertexCover.crossing..cs"g|]\}}||qSr) isdisjointrrrrr&Nsrr3rrrrJs zVertexCover.crossingcCs|jSrrr3rrrr{SszVertexCover.graphcCs|j||Srrr)rrrrXs zVertexCover.subgraphcsfddDS)rcsg|]}j|qSrrrr3rrr&ksz)VertexCover.subgraphs..rr3rr3rrcszVertexCover.subgraphscsd|krJd|jkrJ|dkr(ddgnddgfdd |D|d<|d d }|d krntt||d <d |krtd r||d <nt|d ||d <|j j ||f||S)aPlots the cover to the given Cairo context or matplotlib Axes. This is done by calling L{Graph.__plot__()} with the same arguments, but drawing nice colored blobs around the vertex groups. This method understands all the positional and keyword arguments that are understood by L{Graph.__plot__()}, only the differences will be highlighted here: - C{mark_groups}: whether to highlight the vertex clusters by colored polygons. Besides the values accepted by L{Graph.__plot__} (i.e., a dict mapping colors to vertex indices, a list containing lists of vertex indices, or C{False}), the following are also accepted: - C{True}: all the clusters will be highlighted, the colors matching the corresponding color indices from the current palette (see the C{palette} keyword argument of L{Graph.__plot__}. - A dict mapping cluster indices or tuples of vertex indices to color names. The given clusters or vertex groups will be highlighted by the given colors. - A list of cluster indices. This is equivalent to passing a dict mapping numeric color indices from the current palette to cluster indices; therefore, the cluster referred to by element I{i} of the list will be highlighted by color I{i} from the palette. The value of the C{plotting.mark_groups} configuration key is also taken into account here; if that configuration key is C{True} and C{mark_groups} is not given explicitly, it will automatically be set to C{True}. In place of lists of vertex indices, you may also use L{VertexSeq} instances. In place of color names, you may also use color indices into the current palette. C{None} as a color name will mean that the corresponding group is ignored. - C{palette}: the palette used to resolve numeric color indices to RGBA values. By default, this is an instance of L{ClusterColoringPalette}. @see: L{Graph.__plot__()} for more supported keyword arguments. rrrZdimgreysilverZgrey20Zgrey80csg|] }|qSrrrrrrr&sz(VertexCover.__plot__..rNrr) r{rrrrrrrrr=r)rrrrArBrrrrrms$/      zVertexCover.__plot__c#s`|jr<|jjd|D]}dfdd|DVqn |D]}ddd|DVq@dS)rgrrhc3s|]}t|VqdSrrirjrrrrsz:VertexCover._formatted_cluster_iterator..css|]}t|VqdSrrirjrrrrsNrrmrrrr_s   z'VertexCover._formatted_cluster_iterator)N) rnrorprqr!rrrr{rrrr_rrrr~rr+s     HrcsbeZdZdZdfdd ZddZddZd d Zd d Zd dZ ddZ ddZ ddZ Z S)CohesiveBlocksaThe cohesive block structure of a graph. Instances of this type are created by L{Graph.cohesive_blocks()}. See the documentation of L{Graph.cohesive_blocks()} for an explanation of what cohesive blocks are. This class provides a few more methods that make handling of cohesive block structures easier. Ncsj|dks|dks|dkr&|\}}}t||||_||_t|jD]\}}|dkrJd|j|<qJdS)auConstructs a new cohesive block structure for the given graph. If any of I{blocks}, I{cohesion} or I{parent} is C{None}, all the arguments will be ignored and L{Graph.cohesive_blocks()} will be called to calculate the cohesive blocks. Otherwise, these three variables should describe the *result* of a cohesive block structure calculation. Chances are that you never have to construct L{CohesiveBlocks} instances directly, just use L{Graph.cohesive_blocks()}. @param graph: the graph itself @param blocks: a list containing the blocks; each block is described as a list containing vertex IDs. @param cohesion: the cohesion of each block. The length of this list must be equal to the length of I{blocks}. @param parent: the parent block of each block. Negative values or C{None} mean that there is no parent block for that block. There should be only one parent block, which covers the entire graph. @see: Graph.cohesive_blocks() Nr)cohesive_blocksrtr! _cohesion_parentr()rr{blockscohesionparentr%pr~rrr!szCohesiveBlocks.__init__cCs |j|S)z7Returns the cohesion of the group with the given index.rr)rrrrszCohesiveBlocks.cohesioncCs|jddS)z3Returns the list of cohesion values for each group.Nr r3rrr cohesionsszCohesiveBlocks.cohesionscCs6ddlm}ddt|jtt|D}||ddS)a/Returns a new graph that describes the hierarchical relationships between the groups. The new graph will be a directed tree; an edge will point from vertex M{i} to vertex M{j} if group M{i} is a superset of group M{j}. In other words, the edges point downwards. r)GraphcSsg|]}|ddk r|qS)rNrrrrrr&s z,CohesiveBlocks.hierarchy..T)Zdirected)igraphr ziprr-r)rr edgesrrr hierarchys  zCohesiveBlocks.hierarchycCs2d}t|j|jD]\}}||krt||}q|S)z\Finds the maximum cohesion score among all the groups that contain the given vertex.r)r rrr)rr%rrr1rrr max_cohesions  zCohesiveBlocks.max_cohesioncCsHdg|j}t|j|jD]$\}}|D]}t|||||<q*q|S)zvFor each vertex in the graph, returns the maximum cohesion score among all the groups that contain the vertex.r)r=rur rrr)rrrr1r%rrr max_cohesionss zCohesiveBlocks.max_cohesionscCs |j|S)zsReturns the parent group index of the group with the given index or C{None} if the given group is the root.rr)rrrrszCohesiveBlocks.parentcCs|jddS)zjReturns the list of parent group indices for each group or C{None} if the given group is the root.Nrr3rrrparentsszCohesiveBlocks.parentscOszd}d|krtdr.d}n|ddkr.d}|rPddt|D}||d<d|krd||d<tj|||f||S)a-Plots the cohesive block structure to the given Cairo context or matplotlib Axes. Since a L{CohesiveBlocks} instance is also a L{VertexCover}, keyword arguments accepted by L{VertexCover.__plot__()} are also accepted here. The only difference is that the vertices are colored according to their maximal cohesions by default, and groups are marked by colored blobs except the last group which encapsulates the whole graph. See the documentation of L{VertexCover.__plot__()} for more details. FrrTcSsg|]}|ddkr|qS)rrrrrrr&5s z+CohesiveBlocks.__plot__..r)rrr(r rrr)rrrrArBZprepare_groupsrrrrr!s    zCohesiveBlocks.__plot__)NNN)rnrorprqr!rr rrrrrrrrrr~rrs !  rcs|dkrddtDnt|tr0|nt|drt|drz |d}Wntk rhd}YnX|dk rt|trddt|Dq|q|nt|d r|nifd d }|S) aHandles the mark_groups=... keyword argument in plotting methods of clusterings. This is an internal method, you shouldn't need to mess around with it. Its purpose is to handle the extended semantics of the mark_groups=... keyword argument in the C{__plot__} method of L{VertexClustering} and L{VertexCover} instances, namely the feature that numeric IDs are resolved to clusters automatically. Tcss|]\}}||fVqdSrrrrgrouprrrrLsz9_handle_mark_groups_arg_for_clustering..r*r4rNcss|]\}}||fVqdSrrrrrrr[sr2c3s.D]$\}}t|tr|}||fVqdSr) isinstancer)rr clusteringZ group_iterrrcluster_index_resolvergs  zF_handle_mark_groups_arg_for_clustering..cluster_index_resolver)r(rrz iteritemshasattrrr)rrfirstrrrrr>s&       rFcsdd}||||ttkr2td|rdksFdkṙfddttD}|t}|D]@}|d8}|||<|<|||<|<qv|d=|d=fS)aAuxiliary method that takes two community structures either as membership lists or instances of L{Clustering}, and returns a tuple whose two elements are membership lists. This is used by L{compare_communities} and L{split_join_distance}. @param comm1: the first community structure as a membership list or as a L{Clustering} object. @param comm2: the second community structure as a membership list or as a L{Clustering} object. @param remove_none: whether to remove C{None} entries from the membership lists. If C{remove_none} is C{False}, a C{None} entry in either C{comm1} or C{comm2} will result in an exception. If C{remove_none} is C{True}, C{None} values are filtered away and only the remaining lists are compared. cSst|tr|jSt|Sr)rrrr)objrrr _ensure_lists z3_prepare_community_comparison.._ensure_listz2the two membership vectors must be equal in lengthNcs(g|] }|dks |dkr|qSrrrvec1vec2rrr&s z1_prepare_community_comparison..r)rrvr-reverse)comm1comm2 remove_nonerZidxs_to_removerEr"rrr_prepare_community_comparisonss"    r&vicCs(ddl}t|||\}}|j|||S)a Compares two community structures using various distance measures. @param comm1: the first community structure as a membership list or as a L{Clustering} object. @param comm2: the second community structure as a membership list or as a L{Clustering} object. @param method: the measure to use. C{"vi"} or C{"meila"} means the variation of information metric of Meila (2003), C{"nmi"} or C{"danon"} means the normalized mutual information as defined by Danon et al (2005), C{"split-join"} means the split-join distance of van Dongen (2000), C{"rand"} means the Rand index of Rand (1971), C{"adjusted_rand"} means the adjusted Rand index of Hubert and Arabie (1985). @param remove_none: whether to remove C{None} entries from the membership lists. This is handy if your L{Clustering} object was constructed using L{VertexClustering.FromAttribute} using an attribute which was not defined for all the vertices. If C{remove_none} is C{False}, a C{None} entry in either C{comm1} or C{comm2} will result in an exception. If C{remove_none} is C{True}, C{None} values are filtered away and only the remaining lists are compared. @return: the calculated measure. @newfield ref: Reference @ref: Meila M: Comparing clusterings by the variation of information. In: Scholkopf B, Warmuth MK (eds). Learning Theory and Kernel Machines: 16th Annual Conference on Computational Learning Theory and 7th Kernel Workship, COLT/Kernel 2003, Washington, DC, USA. Lecture Notes in Computer Science, vol. 2777, Springer, 2003. ISBN: 978-3-540-40720-1. @ref: Danon L, Diaz-Guilera A, Duch J, Arenas A: Comparing community structure identification. J Stat Mech P09008, 2005. @ref: van Dongen D: Performance criteria for graph clustering and Markov cluster experiments. Technical Report INS-R0012, National Research Institute for Mathematics and Computer Science in the Netherlands, Amsterdam, May 2000. @ref: Rand WM: Objective criteria for the evaluation of clustering methods. J Am Stat Assoc 66(336):846-850, 1971. @ref: Hubert L and Arabie P: Comparing partitions. Journal of Classification 2:193-218, 1985. rN)igraph._igraphr&_igraphZ_compare_communities)r#r$methodr%r r r!rrrr?s(r?cCs&ddl}t|||\}}|j||S)a Calculates the split-join distance between two community structures. The split-join distance is a distance measure defined on the space of partitions of a given set. It is the sum of the projection distance of one partition from the other and vice versa, where the projection number of A from B is if calculated as follows: 1. For each set in A, find the set in B with which it has the maximal overlap, and take note of the size of the overlap. 2. Take the sum of the maximal overlap sizes for each set in A. 3. Subtract the sum from M{n}, the number of elements in the partition. Note that the projection distance is asymmetric, that's why it has to be calculated in both directions and then added together. This function returns the projection distance of C{comm1} from C{comm2} and the projection distance of C{comm2} from C{comm1}, and returns them in a pair. The actual split-join distance is the sum of the two distances. The reason why it is presented this way is that one of the elements being zero then implies that one of the partitions is a subpartition of the other (and if it is close to zero, then one of the partitions is close to being a subpartition of the other). @param comm1: the first community structure as a membership list or as a L{Clustering} object. @param comm2: the second community structure as a membership list or as a L{Clustering} object. @param remove_none: whether to remove C{None} entries from the membership lists. This is handy if your L{Clustering} object was constructed using L{VertexClustering.FromAttribute} using an attribute which was not defined for all the vertices. If C{remove_none} is C{False}, a C{None} entry in either C{comm1} or C{comm2} will result in an exception. If C{remove_none} is C{True}, C{None} values are filtered away and only the remaining lists are compared. @return: the projection distance of C{comm1} from C{comm2} and vice versa in a tuple. The split-join distance is the sum of the two. @newfield ref: Reference @ref: van Dongen D: Performance criteria for graph clustering and Markov cluster experiments. Technical Report INS-R0012, National Research Institute for Mathematics and Computer Science in the Netherlands, Amsterdam, May 2000. @see: L{compare_communities()} with C{method = "split-join"} if you are not interested in the individual projection distances but only the sum of them. rN)r(r&r)Z_split_join_distance)r#r$r%r r r!rrrsplit_join_distances2r+c Cs|rt|d\}}n t|d}g}|rh|}|D]0}t}|D]}|||qD|t|q6t||} |r~| |fS| SdS)a% Calculates the biconnected components of the graph. @param return_articulation_points: whether to return the articulation points as well @return: a L{VertexCover} object describing the biconnected components, and optionally the list of articulation points as well TFN)rZbiconnected_componentsrrrr.sortedr) r{Zreturn_articulation_pointsZtreesZapsr0Zedgelisttreer1Zedge_idrrrr_biconnected_componentss   r.cCst|ft|S)aCalculates the cohesive block structure of the graph. Cohesive blocking is a method of determining hierarchical subsets of graph vertices based on their structural cohesion (i.e. vertex connectivity). For a given graph G, a subset of its vertices S is said to be maximally k-cohesive if there is no superset of S with vertex connectivity greater than or equal to k. Cohesive blocking is a process through which, given a k-cohesive set of vertices, maximally l-cohesive subsets are recursively identified with l > k. Thus a hierarchy of vertex subsets is obtained in the end, with the entire graph G at its root. @return: an instance of L{CohesiveBlocks}. See the documentation of L{CohesiveBlocks} for more information. @see: L{CohesiveBlocks} )rrr)r{rrr_cohesive_blocks#sr/strongcCst|t||S)a Calculates the (strong or weak) connected components for a given graph. @param mode: must be either C{"strong"} or C{"weak"}, depending on the connected components being sought. Optional, defaults to C{"strong"}. @return: a L{VertexClustering} object)rsrconnected_componentsr{moderrr_connected_components6sr4cCstd|j|dS)z4Deprecated alias to L{Graph.connected_components()}.zHGraph.clusters() is deprecated; use Graph.connected_components() instead)r3)r r1r2rrrr@srN)F)r'F)F)F)r0)r0)'rqrriorr(rrZigraph.configurationrZigraph.datatypesrrrZigraph.drawing.cairo.dendrogramr Z$igraph.drawing.matplotlib.dendrogramr Zigraph.statisticsr Zigraph.summaryr Z igraph.utilsr rrsrrr<rrrr&r?r+r.r/r4rrrrrsB          4F m-}5 + . 8