+ j`Rt^RIHt^RIHt^RIt^RIHtH t ^RI H t H t .ROt !RR]P4tRt] !]R4t]P$R 4t]P$R 4t]P$R 4t]P$!R R 7RRl4t] !R4]P$!R R 7R R R^/Rl44tRRltRRltRRltRRltRRlt]]P$R44tR#)zHFunctions for measuring the quality of a partition (into communities). ) defaultdict) combinationsN)is_cover is_partition)argmapnot_implemented_forc6aa]tRt^toRtV3RltRtVtV;t#) NotAPartitionz0Raised if a given collection is not a partition.c4<V RV 2p\SV`V4R#)z' is not a valid partition of the graph N)super__init__)selfG collectionmsg __class__s&&& f/home/luca/screen-checking/.venv/lib/python3.14/site-packages/networkx/algorithms/community/quality.pyr NotAPartition.__init__s! CA3G ) __name__ __module__ __qualname____firstlineno____doc__r __static_attributes____classdictcell__ __classcell__)r __classdict__s@@rr r s:rr cV\W4'dW3#\P!R4h)aDecorator to check that a valid partition is input to a function Raises :exc:`networkx.NetworkXError` if the partition is not valid. This decorator should be used on functions whose first two arguments are a graph and a partition of the nodes of that graph (in that order):: >>> @require_partition ... def foo(G, partition): ... print("partition is valid!") ... >>> G = nx.complete_graph(5) >>> partition = [{0, 1}, {2, 3}, {4}] >>> foo(G, partition) partition is valid! >>> partition = [{0}, {2, 3}, {4}] >>> foo(G, partition) Traceback (most recent call last): ... networkx.exception.NetworkXError: `partition` is not a valid partition of the nodes of G >>> partition = [{0, 1}, {1, 2, 3}, {4}] >>> foo(G, partition) Traceback (most recent call last): ... networkx.exception.NetworkXError: `partition` is not a valid partition of the nodes of G z6`partition` is not a valid partition of the nodes of G)rnx NetworkXErrorr partitions&&r_require_partitionr$s):A!!|  S TTrc.a\V3RlV44#)a2Returns the number of intra-community edges for a partition of `G`. Parameters ---------- G : NetworkX graph. partition : iterable of sets of nodes This must be a partition of the nodes of `G`. The "intra-community edges" are those edges joining a pair of nodes in the same block of the partition. c3b<"TF$pSPV4P4xK& R#5iN)subgraphsize).0blockrs& r (intra_community_edges..Qs&?YEqzz% %%''Ys,/)sumr"sf&rintra_community_edgesr/Bs ?Y? ??rcVP4'd\PM\Pp\P!WVR7P 4#)aReturns the number of inter-community edges for a partition of `G`. according to the given partition of the nodes of `G`. Parameters ---------- G : NetworkX graph. partition : iterable of sets of nodes This must be a partition of the nodes of `G`. The *inter-community edges* are those edges joining a pair of nodes in different blocks of the partition. Implementation note: this function creates an intermediate graph that may require the same amount of memory as that of `G`. ) create_using) is_directedr MultiDiGraph MultiGraphquotient_graphr))rr#MGs&& rinter_community_edgesr7Ts98MMOOB  Q ; @ @ BBrcB\\P!V4V4#)aKReturns the number of inter-community non-edges according to the given partition of the nodes of `G`. Parameters ---------- G : NetworkX graph. partition : iterable of sets of nodes This must be a partition of the nodes of `G`. A *non-edge* is a pair of nodes (undirected if `G` is undirected) that are not adjacent in `G`. The *inter-community non-edges* are those non-edges on a pair of nodes in different blocks of the partition. Implementation note: this function creates two intermediate graphs, which may require up to twice the amount of memory as required to store `G`. )r7r complementr"s&&rinter_community_non_edgesr:ts< !q!19 ==rweight) edge_attrscaaaaaaa a \V\4'g \V4p\SV4'g \SV4hSP 4oS'dj\ SP SR74o \ SPSR74o\S P44oS^8Xd^#^S^,, o MX\ SPSR74;o o\S P44pV^, oS^8Xd^#^V^,, o VVVVV V VV3Rlp\\WQ44#)a1 Returns the modularity of the given partition of the graph. Modularity is defined in [1]_ as .. math:: Q = \frac{1}{2m} \sum_{ij} \left( A_{ij} - \gamma\frac{k_ik_j}{2m}\right) \delta(c_i,c_j) where $m$ is the number of edges (or sum of all edge weights as in [5]_), $A$ is the adjacency matrix of `G`, $k_i$ is the (weighted) degree of $i$, $\gamma$ is the resolution parameter, and $\delta(c_i, c_j)$ is 1 if $i$ and $j$ are in the same community else 0. According to [2]_ (and verified by some algebra) this can be reduced to .. math:: Q = \sum_{c=1}^{n} \left[ \frac{L_c}{m} - \gamma\left( \frac{k_c}{2m} \right) ^2 \right] where the sum iterates over all communities $c$, $m$ is the number of edges, $L_c$ is the number of intra-community links for community $c$, $k_c$ is the sum of degrees of the nodes in community $c$, and $\gamma$ is the resolution parameter. The resolution parameter sets an arbitrary tradeoff between intra-group edges and inter-group edges. More complex grouping patterns can be discovered by analyzing the same network with multiple values of gamma and then combining the results [3]_. That said, it is very common to simply use gamma=1. More on the choice of gamma is in [4]_. The second formula is the one actually used in calculation of the modularity. For directed graphs the second formula replaces $k_c^2$ with $k^{in}_c k^{out}_c$. Parameters ---------- G : NetworkX Graph communities : list or iterable of set of nodes These node sets must represent a partition of G's nodes. weight : string or None, optional (default="weight") The edge attribute that holds the numerical value used as a weight. If None or an edge does not have that attribute, then that edge has weight 1. resolution : float (default=1) If resolution is less than 1, modularity favors larger communities. Greater than 1 favors smaller communities. Returns ------- Q : float The modularity of the partition. Raises ------ NotAPartition If `communities` is not a partition of the nodes of `G`. Examples -------- >>> G = nx.barbell_graph(3, 0) >>> nx.community.modularity(G, [{0, 1, 2}, {3, 4, 5}]) 0.35714285714285715 >>> nx.community.modularity(G, nx.community.label_propagation_communities(G)) 0.35714285714285715 References ---------- .. [1] M. E. J. Newman "Networks: An Introduction", page 224. Oxford University Press, 2011. .. [2] Clauset, Aaron, Mark EJ Newman, and Cristopher Moore. "Finding community structure in very large networks." Phys. Rev. E 70.6 (2004). .. [3] Reichardt and Bornholdt "Statistical Mechanics of Community Detection" Phys. Rev. E 74, 016110, 2006. https://doi.org/10.1103/PhysRevE.74.016110 .. [4] M. E. J. Newman, "Equivalence between modularity optimization and maximum likelihood methods for community detection" Phys. Rev. E 94, 052315, 2016. https://doi.org/10.1103/PhysRevE.94.052315 .. [5] Blondel, V.D. et al. "Fast unfolding of communities in large networks" J. Stat. Mech 10008, 1-12 (2008). https://doi.org/10.1088/1742-5468/2008/10/P10008 r;c <a\V4o\V3RlSPSS ^R744p\V 3RlS44pS'd\V3RlS44MTpVS, S V,V,S ,, #)c3><"TFwrq2S9gKVxK R#5ir'rr*uvwtcomms& rr,=modularity..community_contribution..sX%JrSWi""%J  datadefaultc36<"TFpSV,xK R#5ir'r)r*rB out_degrees& rr,rFs9DqZ]]Dc36<"TFpSV,xK R#5ir'r)r*rB in_degrees& rr,rFs7$QIaLL$rMsetr.edges) communityL_cout_degree_sum in_degree_sumrErdirectedrOmnormrL resolutionr;s & @rcommunity_contribution*modularity..community_contributionsm9~XQWWTW%JXX9D99;C7$77 Qwn4}DtKKKr) isinstancelistrr r2dictrLrOr.valuesdegreemap) r communitiesr;rZdeg_sumr[rWrOrXrYrLs f&ff @@@@@r modularityresj k4 ( (;' ; ' 'A{++}}H!,,f,56 F34  !!# $ 61a4x!%ahhfh&=!>> Yj'')* aK 67A:~LL s)7 88rrWrZcaaaaaaa \V\4'g \V4p\SV4'g\P!R4h\ \ 4o VF*pVF!pVS9gK S V;;,^, uu&K# K, \SPSR74o\SP44oS^8XdR#VVVV VV3Rlo\V3RlV44#)adReturns Shen et al.'s extended modularity for an overlapping cover. Standard modularity assumes each node belongs to exactly one community. Shen et al. [1]_ extend modularity to overlapping communities by discounting each node's contribution by the number of communities it belongs to: .. math:: EQ = \frac{1}{2m} \sum_{i} \sum_{v \in C_i, w \in C_i} \frac{1}{O_v O_w}\!\left[ A_{vw} - \gamma\,\frac{k_v k_w}{2m}\right] where the outer sum runs over communities $C_i$ in the cover, $A_{vw}$ is the (weighted) adjacency, $k_v$ is the (weighted) degree of $v$, $O_v$ is the number of communities to which $v$ belongs, $m$ is the total (weighted) edge count, and $\gamma$ is the resolution parameter. The factor $1 / (O_v O_w)$ discounts contributions from nodes that belong to many communities: a node in 3 communities contributes 1/3 of its modularity share to each. The resolution parameter $\gamma$ is not part of the original Shen definition; it is added for consistency with :func:`~networkx.algorithms.community.quality.modularity`. Setting $\gamma = 1$ recovers Shen's EQ exactly. Implementation uses the equivalent community-sum form .. math:: EQ = \sum_{i}\!\left[\frac{\tilde{L}_{C_i}}{m} - \gamma\!\left(\frac{\tilde{k}_{C_i}}{2m}\right)^{\!2}\right] where $\tilde{L}_{C_i} = \sum_{(v,w) \in L_{C_i}} 1/(O_v O_w)$ is the overlap-discounted intra-community edge count and $\tilde{k}_{C_i} = \sum_{v \in C_i} k_v / O_v$ is the overlap-discounted degree sum. When the cover is actually a partition ($O_v = 1$ for all $v$), $EQ$ reduces to the standard modularity $Q$. Parameters ---------- G : NetworkX Graph An undirected graph. communities : iterable of sets of nodes A cover of `G`'s nodes: every node must appear in at least one set, but sets may overlap. Accepts the output of any NetworkX overlapping community-detection algorithm such as :func:`~networkx.algorithms.community.kclique.k_clique_communities`. weight : string or None, optional (default="weight") Edge attribute holding the numerical edge weight. If None, or if an edge does not have the attribute, that edge has weight 1. resolution : float, optional (default=1) Resolution parameter $\gamma$. As in standard modularity, values smaller than 1 favor larger communities and values greater than 1 favor smaller communities. The degree of overlap in the cover is independent of $\gamma$, since $\gamma$ rescales only the null-model term. Returns ------- EQ : float The extended modularity of the cover. Raises ------ NetworkXError If `communities` is not a valid cover of the nodes of `G` (some node in `G` does not belong to any community). NetworkXNotImplemented If `G` is directed. Shen's formulation is for undirected graphs. Examples -------- On a partition, EQ equals standard modularity (up to floating-point summation order): >>> G = nx.barbell_graph(3, 0) >>> partition = [{0, 1, 2}, {3, 4, 5}] >>> Q = nx.community.modularity(G, partition) >>> EQ = nx.community.overlapping_modularity(G, partition) >>> abs(Q - EQ) < 1e-12 True Evaluate an overlapping cover produced by ``k_clique_communities``. Two K_5 cliques sharing nodes 3 and 4 yield a 2-community cover: >>> G = nx.complete_graph(5) >>> G.add_edges_from(nx.complete_graph(range(3, 8)).edges()) >>> cover = list(nx.community.k_clique_communities(G, 4)) >>> round(nx.community.overlapping_modularity(G, cover), 3) 0.158 See Also -------- modularity is_cover References ---------- .. [1] Shen, H., Cheng, X., Cai, K., & Hu, M. B. (2009). "Detect overlapping and hierarchical community structure in networks." Physica A, 388(8), 1706-1712. https://doi.org/10.1016/j.physa.2008.12.021 .. [2] Lancichinetti, A., Fortunato, S., & Kertesz, J. (2009). "Detecting the overlapping and hierarchical community structure in complex networks." New J. Phys. 11, 033015. (Cover definition.) z4`communities` is not a valid cover of the nodes of Gr>gc <a\V4o\VV3RlSPSS ^R744p\VV3RlS44p^V,S, SVS, ^,,, #)c3x<"TF/wrpVS9gKVSV,SV,,, xK1 R#5ir'r)r*rBrCrDrE memberships& rr,Ioverlapping_modularity..community_contribution..s: AbDy 1B*Q-*Q-/ 0 0As :&:rHc3R<"TFpSV,SV,, xK R#5ir'r)r*rBraris& rr,rjs!@4aq JqM114s$'rP) rS L_c_tilde k_c_tilderErrdrarirZr;s & @rr[6overlapping_modularity..community_contributionsk9~  GGDvqGA  @4@@ 9}w&y77Jq6P)PPPrc34<"TF pS!V4xK R#5ir'rr*cr[s& rr,)overlapping_modularity..>+Q%a((+) r]r^rr r!rintr_rar.r`) rrcr;rZrSnoder[rdraris f&dd @@@@roverlapping_modularityrw s` k4 ( (;' A{ # #UVVS!J Dqy4 A% ! !((&() *F&--/"G!|QQ$ >+> >>rc aa VP4'd^M^pVS0, o \V 3RlVPVR744pVPS,V,p\V 3RlVPS0VR744p VP4'd.V \V3RlVPS VR744, p W6,V,V,V , #)a Let P = [A, B, C, D,...] be a partition, and let P' = [A', B', C, D,...] be the partition obtained by moving the node u from community A to community B, that is where A' = A\{u} and B = B \union {u} The overall change in quality associated with this move is q_delta = constant_potts_mode(G, P') - constant_potts_model(G, P) Throughout the algorithm the quality q_delta will be computed by calculating two intermediate values q_rem and q_add satisfying the property that q_delta = q_rem + q_add The current function is one of a pair of similar functions that compute these values with q_rem = _cpm_delta_partial_eval_remove(G, u, A) q_add = _cpm_delta_partial_eval_add(G, u, B) c3><"TFwrVS9gKVxK R#5ir'r)r*rBrDA_primes& rr,1_cpm_delta_partial_eval_remove..sN$=51gBB$=rGrIc3><"TFwrq2S9gKVxK R#5ir'r)r*_rCrDrzs& rr,r{sQ$@bL$@rGc3@<"TFwrq2S09gKVxK R#5ir'rr*r~rCrDrvs& rr,r{s V)FXQ2PTv+bb)F  r2r.nodesrR) rrvrSrZr; node_weight dir_factor n_A_primeu_wtE_diffrzs &f&&&& @r_cpm_delta_partial_eval_removers4mmoo1J4& GNAGGG$=NNI 774= %D QAGGTFG$@Q QF}}#Vv)FVVV  "Y . 5 >>rc aaVP4'd^M^p\V3RlVPVR744pVPS,V,p\V3RlVPS0VR744p VP4'd.V \V3RlVPSVR744, p WV,V,V,, #)zk One of a pair of partial evaluation functions. See _cpm_delta_partial_eval_remove for more details. c3><"TFwrVS9gKVxK R#5ir'r)r*rBrDrSs& rr,._cpm_delta_partial_eval_add..s J7UQ1 >bb7rGr|c3><"TFwrq2S9gKVxK R#5ir'rr*r~rCrDrSs& rr,rs P!=XQ2ibb!=rGc3@<"TFwrq2S09gKVxK R#5ir'rrs& rr,rsU&E(!tf22&Err) rrvrSrZr;rrn_BrE_Ds &ff&&& r_cpm_delta_partial_eval_addrsmmoo1J Jagg;g7 J JC 774= %D P$f!= P PC}} sUaggifg&EUUU j(3.5 55rcBaaaa\VV3RlS44p\VV3RlS44p\V3RlSPSVR744p\V3RlSPSVR744p W,V^,V,V,, #)c3X<"TFpSPV,S,xK! R#5ir'rr*rBrrs& rr,._quality_delta_cpm_directed..!?,QK((,'*c3X<"TFpSPV,S,xK! R#5ir'rrs& rr,r!?YAGGAJ{++Yrc3><"TFwrq2S9gKVxK R#5ir'rrs& rr,rs=xqRi=rGr|c3><"TFwrq2S9gKVxK R#5ir'r)r*r~rCrD nodes_to_adds& rr,rs :xqR<>O:rGr.rR) rrrSrZr;rn_size comm_sizeE_D_outE_D_ins fff&&f r_quality_delta_cpm_directedrs?,? ?F?Y??I77.rrc3X<"TFpSPV,S,xK! R#5ir'rrs& rr,rrrc3><"TFwrq2S9gKVxK R#5ir'rrs& rr,rs V!CXQ2I~bb!CrGr|r) rrrSrZr;rrrrs f&f&&f r_quality_delta_cpm_undirectedrsS?,? ?F?Y??I V!C V VC f$y0 00rcaaaaaSP4pV'd VVVV3RloM VVVV3Rlo\V3RlV44#)aV Computes the Constant Potts Model, which is a measure of quality of a partition. This is defined in [1]_ as .. math:: Q = \sum_{C \in P} E(C,C) - \gamma n_C^2 Where E(C,C) is the sum of all edge weights within the community C, n_C is the sum of the weights of the nodes in C. \gamma is the resolution parameter. See Notes below for more more detail on resolution parameter. The Constant Potts Model is similar to modularity, but overcomes the so-called resolution limit problem when used in community detection algorithms like leiden and louvain. The Constant Potts Model is used by default in the leiden community detection algorithm Parameters ---------- G : NetworkX Graph communities : list or iterable of sets of nodes These node sets must represent a partition of G's nodes. weight : string or None, optional The edge attribute that holds the numerical value used as a weight. If None or an edge does not have that attribute, then that edge has weight 1. node_weight : string or None, optional The node attribute that holds the numerical value used as a weight. If None or an edge does not have tha attribute, then the node is treated as having weight 1 resolution : float For smaller resolution values, the constant_potts_model will be maximised by a partition consisting of larger communities; for larger resolution values constant_potts_model will be maximised for smaller communities. Returns ------- Q : float The Constant Potts Model value of the partition. Notes ----- The interpretation of the resolution parameter \gamma is explained as follows in page 3 of [1]_: [The Constant Potts Model] tries to maximize the number of internal edges while at the same time keeping relatively small communities. [The resolution, \gamma] balances these two imperatives. In fact, the parameter \gamma acts as the inner and outer edge density threshold. That is, suppose there is a community [C] with [E(C, C)] edges and [n_C] nodes. Then it is better to split it into two communities r and s whenever .. math:: \frac{[E(r,s)]}{2 n_r n_s} < \gamma where [E(r,s)] is the number [or weighted sum] of links between community r and s. This ratio is exactly the density of links between community r and s. So, the link density between communities should be lower than \gamma, while the link density within communities should be higher than \gamma. References ---------- .. [1] V.A. Traag, P. Van Dooren, Y. Nesterov "Narrow scope for resolution-limit-free community detection" c <a\V4o\V3RlSPSS^R744p\VV3RlV44pVSV^,,, #)c3><"TFwrq2S9gKVxK R#5ir'rrAs& rr,Gconstant_potts_model..community_contribution..X #HxqRQUI#HrGrHc3j<"TF(pSPV,PS^4xK* R#5iNrgetr*rvrrs& rr,r\)NIDaggdm'' Q77I03rPrSE_cn_crErrrZr;s& @rr[4constant_potts_model..community_contributionVsXy>D#$774fa7#HCNINNCsAv.. .rc <a\V4o\V3RlSPSS^R744p\VV3RlV44pVSV^,,^, , #)c3><"TFwrq2S9gKVxK R#5ir'rrAs& rr,rcrrGrHc3j<"TF(pSPV,PS^4xK* R#5irrrs& rr,rgrrrPrs& @rr[ras]y>D#$774fa7#HCNINNCsAv.22 2rc34<"TF pS!V4xK R#5ir'rrps& rr,'constant_potts_model..krsrt)r2r.)rrcr;rrZr2r[sf&fff @rconstant_potts_modelrs;n--/K / / 3 3 >+> >>rc/p\V4Fwr4VFpW2V&K K VP4'g=\R\V^444pVP 4'd V^,pM^p\ V4pWw^, ,pVP 4'g V^,p^p Tp VP 4F8p W+^,,W+^,,8Xd V ^, p K/V ^,p K: V \ VP 4, p VP4'dRp W3#W,V, p W3#)aReturns the coverage and performance of a partition of G. The *coverage* of a partition is the ratio of the number of intra-community edges to the total number of edges in the graph. The *performance* of a partition is the number of intra-community edges plus inter-community non-edges divided by the total number of potential edges. This algorithm has complexity $O(C^2 + L)$ where C is the number of communities and L is the number of links. Parameters ---------- G : NetworkX graph partition : sequence Partition of the nodes of `G`, represented as a sequence of sets of nodes (blocks). Each block of the partition represents a community. Returns ------- (float, float) The (coverage, performance) tuple of the partition, as defined above. Raises ------ NetworkXError If `partition` is not a valid partition of the nodes of `G`. Notes ----- If `G` is a multigraph; - for coverage, the multiplicity of edges is counted - for performance, the result is -1 (total number of possible edges is not defined) References ---------- .. [1] Santo Fortunato. "Community Detection in Graphs". *Physics Reports*, Volume 486, Feb 2010, Issue 3--5 pp. 75--174 c3\"TF"wr\V4\V4,xK$ R#5ir')len)r*p1p2s& rr,$partition_quality..s&- ,F&"CGc"g  ,Fs*,g) enumerate is_multigraphr.rr2rrR)rr#node_communityirSrvpossible_inter_community_edgesn total_pairsr/r:ecoverage performances&& rpartition_qualityrns8`N!), D#$4 - ??  ),- ,8A,F- * & ==?? *a / *)*& AA1u+K ==??  >WWY A$ >A$#7 7 !Q & ! % * %  %s177|3H    -HKW   r)rrerwr)r)r;r)r;r)r;rr)r collectionsr itertoolsrnetworkxr -networkx.algorithms.community.community_utilsrrnetworkx.utils.decoratorsrr__all__r!r r$require_partition _dispatchabler/r7r:rerwrrrrrrrrrrs@ $"PA B$$UD-v6@@"CC>>>@X&r9'r9jZ X&R?XR?!R?'!R?j'?T62 B1o?dW!W!r