U tdv@sHddlmZddlmZddlmZddlmZmZGddde Z dS) ) _c_leiden)(LinearResolutionParameterVertexPartition) namedtuple)logsqrtc@s,eZdZdZddZeddZejddZeddZejd dZed d Z e jd d Z ed dZ e jddZ eddZ e jddZ eddZ e jddZ eddZ e jddZ ddZd0ddZd1dd Zd2d!d"Zd3d#d$Zd4d%d&Zd5d'd(Zdd)d*d+d,d-d+fd.d/ZdS)6 Optimisera$ Class for doing community detection using the Leiden algorithm. The Leiden algorithm [1] derives from the Louvain algorithm [2]. The Louvain algorithm has an elegant formulation. It consists of two phases: (1) move nodes between communities; (2) aggregate the graph. It then repeats these phases on the aggregate graph. The Leiden algorithm consists of three phases: (1) move nodes; (2) refine communities; (3) aggregate the graph based on the refinement. The Louvain algorithm can lead to arbitrarily badly connected communities, whereas the Leiden algorithm guarantees communities are well-connected. In fact, it converges towards a partition in which all subsets of all communities are locally optimally assigned. Finally, the Leiden algorithm is also much faster, because it relies on a fast local move routine. There is one, rather technical, difference with the original Leiden algorithm. This implementation provides a general optimisation routine for any quality function. There is one aspect of the original Leiden algorithm that cannot be translated well in this framework: when merging subcommunities in the refinement procedure, it does not consider whether they are sufficiently well connected to the rest of the community. This implementation therefore does not guarantee subpartition :math:`\gamma`-density. However, all other guarantees still hold: After each iteration 1. :math:`\gamma`-separation 2. :math:`\gamma`-connectivity After a stable iteration 3. Node optimality 4. Some subsets are locally optimally assigned Asymptotically 5. Uniform :math:`\gamma`-density 6. Subset optimality The optimiser class provides a number of different methods for optimising a given partition. The overall optimisation procedure :func:`optimise_partition` calls either :func:`move_nodes` or :func:`merge_nodes` (which is controlled by :attr:`optimise_routine`) then aggregates the graph and repeats the same procedure. Possible, indicated by :attr:`refine_partition` the partition is refined before aggregating, meaning that subsets of communities are considered for moving around. Which routine is used for the refinement is indicated by :attr:`refine_routine`. For calculating the actual improvement of moving a node (corresponding a subset of nodes in the aggregate graph), the code relies on :func:`~VertexPartition.MutableVertexPartition.diff_move` which provides different values for different methods (e.g. modularity or CPM). The default settings are consistent with the Leiden algorithm. By not doing the refinement, you essentially get the Louvain algorithm with a fast local move. Finally, the Optimiser class provides a routine to construct a :func:`resolution_profile` on a resolution parameter. References ---------- .. [1] Traag, V.A., Waltman. L., Van Eck, N.-J. (2018). From Louvain to Leiden: guaranteeing well-connected communities. `arXiv:1810.08473 `_ .. [2] Blondel, V. D., Guillaume, J.-L., Lambiotte, R., & Lefebvre, E. (2008). Fast unfolding of communities in large networks. Journal of Statistical Mechanics: Theory and Experiment, 10008(10), 6. `10.1088/1742-5468/2008/10/P10008 `_ cCst|_dS)z Create a new Optimiser object N)rZ_new_Optimiser _optimiserselfr L/home/sam/Atlas/atlas_env/lib/python3.8/site-packages/leidenalg/Optimiser.py__init__GszOptimiser.__init__cCs t|jS)a Determine how alternative communities are considered for moving a node for *optimising* a partition. Nodes will only move to alternative communities that improve the given quality function. Notes ------- This attribute should be set to one of the following values * :attr:`leidenalg.ALL_NEIGH_COMMS` Consider all neighbouring communities for moving. * :attr:`leidenalg.ALL_COMMS` Consider all communities for moving. This is especially useful in the case of negative links, in which case it may be better to move a node to a non-neighbouring community. * :attr:`leidenalg.RAND_NEIGH_COMM` Consider a random neighbour community for moving. The probability to choose a community is proportional to the number of neighbours a node has in that community. * :attr:`leidenalg.RAND_COMM` Consider a random community for moving. The probability to choose a community is proportional to the number of nodes in that community. )rZ_Optimiser_get_consider_commsr r r r r consider_commsMszOptimiser.consider_commscCst|j|dSN)rZ_Optimiser_set_consider_commsr r valuer r r rlscCs t|jS)a Determine how alternative communities are considered for moving a node when *refining* a partition. Nodes will only move to alternative communities that improve the given quality function. Notes ------- This attribute should be set to one of the following values * :attr:`leidenalg.ALL_NEIGH_COMMS` Consider all neighbouring communities for moving. * :attr:`leidenalg.ALL_COMMS` Consider all communities for moving. This is especially useful in the case of negative links, in which case it may be better to move a node to a non-neighbouring community. * :attr:`leidenalg.RAND_NEIGH_COMM` Consider a random neighbour community for moving. The probability to choose a community is proportional to the number of neighbours a node has in that community. * :attr:`leidenalg.RAND_COMM` Consider a random community for moving. The probability to choose a community is proportional to the number of nodes in that community. )rZ$_Optimiser_get_refine_consider_commsr r r r r refine_consider_commsrszOptimiser.refine_consider_commscCst|j|dSr)rZ$_Optimiser_set_refine_consider_commsr rr r r rscCs t|jS)a Determine the routine to use for *optimising* a partition. Notes ------- This attribute should be set to one of the following values * :attr:`leidenalg.MOVE_NODES` Use :func:`move_nodes`. * :attr:`leidenalg.MERGE_NODES` Use :func:`merge_nodes`. )rZ_Optimiser_get_optimise_routiner r r r r optimise_routineszOptimiser.optimise_routinecCst|j|dSr)rZ_Optimiser_set_optimise_routiner rr r r rscCs t|jS)a Determine the routine to use for *refining* a partition. Notes ------- This attribute should be set to one of the following values * :attr:`leidenalg.MOVE_NODES` Use :func:`move_nodes`. * :attr:`leidenalg.MERGE_NODES` Use :func:`merge_nodes`. )rZ_Optimiser_get_refine_routiner r r r r refine_routineszOptimiser.refine_routinecCst|j|dSr)rZ_Optimiser_set_refine_routiner rr r r rscCs t|jS)z; boolean: if ``True`` refine partition before aggregation. )rZ_Optimiser_get_refine_partitionr r r r r refine_partitionszOptimiser.refine_partitioncCst|j|dSr)rZ_Optimiser_set_refine_partitionr rr r r rscCs t|jS)zV boolean: if ``True`` consider also moving nodes to an empty community (default). )rZ'_Optimiser_get_consider_empty_communityr r r r r consider_empty_communitysz"Optimiser.consider_empty_communitycCst|j|dSr)rZ'_Optimiser_set_consider_empty_communityr rr r r rscCs t|jS)z Constrain the maximal community size. By default (zero), communities can be of any size. If this is set to a positive integer value, then communities will be constrained to be at most this total size. )rZ_Optimiser_get_max_comm_sizer r r r r max_comm_sizeszOptimiser.max_comm_sizecCs&|dkrtd|t|j|dS)Nrznegative max_comm_size: %s) ValueErrorrZ_Optimiser_set_max_comm_sizer rr r r rs cCst|j|dS)z Set the random seed for the random number generator. Parameters ---------- value The integer seed used in the random number generator N)rZ_Optimiser_set_rng_seedr rr r r set_rng_seedszOptimiser.set_rng_seedNcCshd}d}||kp|dk}|r\tj|j|j|d}||7}|d7}|dkrR|dk}q||k}q||S)a Optimise the given partition. Parameters ---------- partition The :class:`~VertexPartition.MutableVertexPartition` to optimise. n_iterations : int Number of iterations to run the Leiden algorithm. By default, 2 iterations are run. If the number of iterations is negative, the Leiden algorithm is run until an iteration in which there was no improvement. is_membership_fixed: list of bools or None Boolean list of nodes that are not allowed to change community. The length of this list must be equal to the number of nodes. By default (None) all nodes can change community during the optimization. Returns ------- float Improvement in quality function. Examples -------- >>> G = ig.Graph.Famous('Zachary') >>> optimiser = la.Optimiser() >>> partition = la.ModularityVertexPartition(G) >>> diff = optimiser.optimise_partition(partition) or, fixing the membership of some nodes: >>> is_membership_fixed = [False for v in G.vs] >>> is_membership_fixed[4] = True >>> is_membership_fixed[6] = True >>> diff = optimiser.optimise_partition(partition, is_membership_fixed=is_membership_fixed) r)is_membership_fixedr)rZ_Optimiser_optimise_partitionr _partition_update_internal_membership)r partition n_iterationsritrdiffcontinue_iterationdiff_incr r r optimise_partitions '  zOptimiser.optimise_partitionc Cs|sdgt|}d}d}||kp(|dk}|rvt|jdd|D||}||7}|d7}|dkrl|dk}q*||k}q*|D] } | qz|S)a Optimise the given partitions simultaneously. Parameters ---------- partitions List of :class:`~VertexPartition.MutableVertexPartition` layers to optimise. layer_weights List of weights of layers. is_membership_fixed: list of bools or None Boolean list of nodes that are not allowed to change community. The length of this list must be equal to the number of nodes. By default (None) all nodes can change community during the optimization. n_iterations : int Number of iterations to run the Leiden algorithm. By default, 2 iterations are run. If the number of iterations is negative, the Leiden algorithm is run until an iteration in which there was no improvement. Returns ------- float Improvement in quality of combined partitions, see `Notes <#notes-multiplex>`_. .. _notes-multiplex: Notes ----- This method assumes that the partitions are defined for graphs with the same vertices. The connections between the vertices may be different, but the vertices themselves should be identical. In other words, all vertices should have identical indices in all graphs (i.e. node `i` is assumed to be the same node in all graphs). The quality of the overall partition is simply the sum of the individual qualities for the various partitions, weighted by the layer_weight. If we denote by :math:`Q_k` the quality of layer :math:`k` and the weight by :math:`\lambda_k`, the overall quality is then .. math:: Q = \sum_k \lambda_k Q_k. This is particularly useful for graphs containing negative links. When separating the graph in two graphs, the one containing only the positive links, and the other only the negative link, by supplying a negative weight to the latter layer, we try to find relatively many positive links within a community and relatively many negative links between communities. Note that in this case it may be better to assign a node to a community to which it is not connected so that :attr:`consider_comms` may be better set to :attr:`leidenalg.ALL_COMMS`. Besides multiplex graphs where each node is assumed to have a single community, it is also useful in the case of for example multiple time slices, or in situations where nodes can have different communities in different slices. The package includes some special helper functions for using :func:`optimise_partition_multiplex` in such cases, where there is a conversion required from (time) slices to layers suitable for use in this function. See Also -------- :func:`slices_to_layers` :func:`time_slices_to_layers` :func:`find_partition_multiplex` :func:`find_partition_temporal` Examples -------- >>> G_pos = ig.Graph.SBM(100, pref_matrix=[[0.5, 0.1], [0.1, 0.5]], block_sizes=[50, 50]) >>> G_neg = ig.Graph.SBM(100, pref_matrix=[[0.1, 0.5], [0.5, 0.1]], block_sizes=[50, 50]) >>> optimiser = la.Optimiser() >>> partition_pos = la.ModularityVertexPartition(G_pos) >>> partition_neg = la.ModularityVertexPartition(G_neg) >>> diff = optimiser.optimise_partition_multiplex( ... partitions=[partition_pos, partition_neg], ... layer_weights=[1,-1]) rrcSsg|] }|jqSr )r).0rr r r sz:Optimiser.optimise_partition_multiplex..)lenrZ'_Optimiser_optimise_partition_multiplexr r) r Z partitionsZ layer_weightsr rr!r"r#r$rr r r optimise_partition_multiplex0s(S    z&Optimiser.optimise_partition_multiplexcCs.|dkr|j}t|j|j||}||S)a Move nodes to alternative communities for *optimising* the partition. Parameters ---------- partition The partition for which to move nodes. is_membership_fixed: list of bools or None Boolean list of nodes that are not allowed to change community. The length of this list must be equal to the number of nodes. By default (None) all nodes can change community during the optimization. consider_comms If ``None`` uses :attr:`consider_comms`, but can be set to something else. Returns ------- float Improvement in quality function. Notes ----- When moving nodes, the function loops over nodes and considers moving the node to an alternative community. Which community depends on ``consider_comms``. The function terminates when no more nodes can be moved to an alternative community. See Also -------- :func:`Optimiser.move_nodes_constrained` :func:`Optimiser.merge_nodes` Examples -------- >>> G = ig.Graph.Famous('Zachary') >>> optimiser = la.Optimiser() >>> partition = la.ModularityVertexPartition(G) >>> diff = optimiser.move_nodes(partition) N)rrZ_Optimiser_move_nodesr rrr rrrr"r r r move_nodess+zOptimiser.move_nodescCs0|dkr|j}t|j|j|j|}||S)a Move nodes to alternative communities for *refining* the partition. Parameters ---------- partition The partition for which to move nodes. constrained_partition The partition within which we may move nodes. consider_comms If ``None`` uses :attr:`refine_consider_comms`, but can be set to something else. Returns ------- float Improvement in quality function. Notes ----- The idea is constrain the movement of nodes to alternative communities to another partition. In other words, if there is a partition ``P`` which we want to refine, we can then initialize a new singleton partition, and move nodes in that partition constrained to ``P``. See Also -------- :func:`Optimiser.move_nodes` :func:`Optimiser.merge_nodes_constrained` Examples -------- >>> G = ig.Graph.Famous('Zachary') >>> optimiser = la.Optimiser() >>> partition = la.ModularityVertexPartition(G) >>> diff = optimiser.optimise_partition(partition) >>> refine_partition = la.ModularityVertexPartition(G) >>> diff = optimiser.move_nodes_constrained(refine_partition, partition) N)rrZ!_Optimiser_move_nodes_constrainedr rrr rZconstrained_partitionrr"r r r move_nodes_constraineds +z Optimiser.move_nodes_constrainedcCs.|dkr|j}t|j|j||}||S)an Merge nodes for *optimising* the partition. Parameters ---------- partition The partition for which to merge nodes. is_membership_fixed: list of bools or None Boolean list of nodes that are not allowed to change community. The length of this list must be equal to the number of nodes. By default (None) all nodes can change community during the optimization. consider_comms If ``None`` uses :attr:`consider_comms`, but can be set to something else. Returns ------- float Improvement in quality function. Notes ----- This function loop over all nodes once and tries to merge them with another community. Merging in this case implies that a node will never be removed from a community, only merged with other communities. See Also -------- :func:`Optimiser.move_nodes` :func:`Optimiser.merge_nodes_constrained` Examples -------- >>> G = ig.Graph.Famous('Zachary') >>> optimiser = la.Optimiser() >>> partition = la.ModularityVertexPartition(G) >>> diff = optimiser.merge_nodes(partition) N)rrZ_Optimiser_merge_nodesr rrr*r r r merge_nodess*zOptimiser.merge_nodescCs0|dkr|j}t|j|j|j|}||S)ap Merge nodes for *refining* the partition. Parameters ---------- partition The partition for which to merge nodes. constrained_partition The partition within which we may merge nodes. consider_comms If ``None`` uses :attr:`refine_consider_comms`, but can be set to something else. Returns ------- float Improvement in quality function. Notes ----- The idea is constrain the merging of nodes to another partition. In other words, if there is a partition ``P`` which we want to refine, we can then initialize a new singleton partition, and move nodes in that partition constrained to ``P``. See Also -------- :func:`Optimiser.move_nodes_constrained` :func:`Optimiser.merge_nodes` Examples -------- >>> G = ig.Graph.Famous('Zachary') >>> optimiser = la.Optimiser() >>> partition = la.ModularityVertexPartition(G) >>> diff = optimiser.optimise_partition(partition) >>> refine_partition = la.ModularityVertexPartition(G) >>> diff = optimiser.move_nodes_constrained(refine_partition, partition) N)rrZ"_Optimiser_merge_nodes_constrainedr rrr,r r r merge_nodes_constrained/s +z!Optimiser.merge_nodes_constrainedcCs|Sr bisect_value)pr r r ezOptimiser.rgMbP?Fc  szdd} dd} dfdd } t|ts0tdi}g}||td d d g}| |f||||d d | }||||d||d <| |f||||dd | }||||d||d<zd dlm}|tdd}Wnd}YnX|rB|}t||d j ||dj }|d d krR|dd krR|sRt |d|d }nt|d|d }||kr||kr|d d kr|dd kr|st |d|d }n t |d}||d |f|||df||kr| ||f|||d| }||||d||<|dk r6| d|j|dd| ||q|dk rT|| |tdd|DdddS)aI Use bisectioning on the resolution parameter in order to construct a resolution profile. Parameters ---------- graph The graph for which to construct a resolution profile. partition_type The type of :class:`~VertexPartition.MutableVertexPartition` used to find a partition (must support resolution parameters obviously). resolution_range The range of resolution values that we would like to scan. weights If provided, indicates the edge attribute to use as a weight. Returns ------- list of :class:`~VertexPartition.MutableVertexPartition` A list of partitions for different resolutions. Other Parameters ---------------- bisect_func The function used for bisectioning. For the methods currently implemented, this should usually not be altered. min_diff_bisect_value The difference in the value returned by the bisect_func below which the bisectioning stops (i.e. by default, a difference of a single edge does not trigger further bisectioning). min_diff_resolution The difference in resolution below which the bisectioning stops. For positive differences, the logarithmic difference is used by default, i.e. ``diff = log(res_1) - log(res_2) = log(res_1/res_2)``, for which ``diff > min_diff_resolution`` to continue bisectioning. Set the linear_bisection to true in order to use only linear bisectioning (in the case of negative resolution parameters for example, which can happen with negative weights). linear_bisection Whether the bisectioning will be done on a linear or on a logarithmic basis (if possible). number_iterations Indicates the number of iterations of the algorithm to run. If negative (or zero) the algorithm is run until a stable iteration. Examples -------- >>> G = ig.Graph.Famous('Zachary') >>> optimiser = la.Optimiser() >>> profile = optimiser.resolution_profile(G, la.CPMVertexPartition, ... resolution_range=(0,1)) c Ss|D]Z\}}|}|j|}|D](\}}|j||kr(|}|j|}q(||kr|||<qtdd|Dddd}t||ddD]\\}} \}} | | kr||=q|D]\}}||j_qdS)NcSsg|]\}}||jfqSr r0)r&respartr r r r'szHOptimiser.resolution_profile..clean_stepwise..cSs|dS)Nrr xr r r r3r4zFOptimiser.resolution_profile..clean_stepwise..keyr)itemsrqualitysortedzipresolution_parameter) bisect_valuesr5bisectZ best_bisectZ best_qualityZres2Zbisect2Z bisect_listZres1Zv1Zv2r r r clean_stepwises,   z4Optimiser.resolution_profile..clean_stepwisecSs|D]0\}}||j||j|kr||||<q||j|}|}|D]\}}|j||krV|}qV||||<dSr)r;rr<)r@new_resr5Z bisect_partZcurrent_qualityZbest_resr r r ensure_monotonicitysz9Optimiser.resolution_profile..ensure_monotonicityNcsD||fd|i|}d}||dkr@|ks6dkr@|d7}q|S)Nweightsrr)r%)r graphpartition_typerEkwargsrZn_itrnumber_iterationsr r find_partitions z4Optimiser.resolution_profile..find_partitionzIBisectioning only works on partitions with a linear resolution parameter.BisectPartitionrr1r)rFrGrEr?)rr1r)tqdminf)totalg@)rGrEr?F)r?refreshcss|]\}}|jVqdSr)r)r&r5rAr r r 'sz/Optimiser.resolution_profile..cSs|jSr)r?r7r r r r3(r4z.Optimiser.resolution_profile..r9)N) issubclassrAssertionErrorappendrrMfloatpopabsr1rrsumupdateZ set_postfixcloser=r;)r rFrGZresolution_rangerEZ bisect_funcZmin_diff_bisect_valueZmin_diff_resolutionZlinear_bisectionrJrHrBrDrKr@Zstack_res_rangerLrrMprogress current_rangeZdiff_bisect_valueZdiff_resolutionrCr rIr resolution_profile`sH        ""       zOptimiser.resolution_profile)rN)NrN)NN)N)NN)N)__name__ __module__ __qualname____doc__rpropertyrsetterrrrrrrrr%r)r+r-r.r/r]r r r r rsX@               : j 2 1 2 5rN) rZVertexPartitionr collectionsrmathrrobjectrr r r r s