modularitypruning 1.3.6__py3-none-any.whl → 1.4.1__py3-none-any.whl

modularitypruning/champ_utilities.py

@@ -1,14 +1,16 @@
-from .partition_utilities import all_degrees, in_degrees, out_degrees, membership_to_communities, \
-    membership_to_layered_communities
+import warnings
 from collections import defaultdict
-import numpy as np
-from numpy.random import choice
 from math import floor
 from multiprocessing import Pool, cpu_count
-from scipy.spatial import HalfspaceIntersection
+
+import numpy as np
+from numpy.random import choice
 from scipy.linalg import LinAlgWarning
 from scipy.optimize import linprog, OptimizeWarning
-import warnings
+from scipy.spatial import HalfspaceIntersection
+
+from .partition_utilities import all_degrees, in_degrees, out_degrees, membership_to_communities, \
+    membership_to_layered_communities
 
 
 def get_interior_point(halfspaces, initial_num_sampled=50, full_retry_limit=10):

modularitypruning/leiden_utilities.py

@@ -1,12 +1,10 @@
-from .progress import Progress
 import functools
+from multiprocessing import Pool, cpu_count
+
 import igraph as ig
 import leidenalg
-from math import ceil
-from multiprocessing import Pool, cpu_count
 import numpy as np
-import psutil
-import warnings
+from tqdm import tqdm
 
 LOW_MEMORY_THRESHOLD = 1e9  # 1 GB
 
@@ -50,6 +48,11 @@ def singlelayer_leiden(G, gamma, return_partition=False):
         return tuple(partition.membership)
 
 
+def _wrapped_singlelayer_leiden(args):
+    """Wrapped singlelayer_leiden() for use in multiprocessing.Pool.imap_unordered."""
+    return singlelayer_leiden(*args)
+
+
 def leiden_part(G):
     return leidenalg.RBConfigurationVertexPartition(G)
 
@@ -68,8 +71,6 @@ def split_intralayer_leiden_graph(G_intralayer, layer_membership):
 
     This is needed since leidenalg lacks support for faster multilayer optimization.
 
-    WARNING: Optimization can be EXTREMELY slow! Leidenalg does not properly implement multilayer optimization.
-
     :param G_intralayer: intralayer graph of interest
     :type G_intralayer: igraph.Graph
     :param layer_vec: list of each vertex's layer membership
@@ -77,9 +78,6 @@ def split_intralayer_leiden_graph(G_intralayer, layer_membership):
     :return: list of intralayer networks
     :rtype: list[igraph.Graph]
     """
-    warnings.warn("You are using Leiden multilayer modularity optimization. THIS CAN BE EXTREMELY SLOW! "
-                  "leidenalg's implementation is inefficient, especially when there are many layers.")
-
     # internally use hashable objects for memoization
     return _split_leiden_graph_layers_cached(n=G_intralayer.vcount(), G_es=tuple(G_intralayer.es),
                                              is_directed=G_intralayer.is_directed(),
@@ -108,7 +106,8 @@ def _split_leiden_graph_layers_cached(n, G_es, is_directed, layer_membership):
 def multilayer_leiden(G_intralayer, G_interlayer, layer_vec, gamma, omega, optimiser=None, return_partition=False):
     r"""Run the Leiden modularity maximization algorithm at a single (:math:`\gamma, \omega`) value.
 
-    WARNING: Optimization can be EXTREMELY slow! Leidenalg does not properly implement multilayer optimization.
+    WARNING: Optimization can be EXTREMELY slow for large numbers of layers! Leidenalg does not properly implement
+    multilayer optimization.
 
     :param G_intralayer: intralayer graph of interest
     :type G_intralayer: igraph.Graph
@@ -150,6 +149,11 @@ def multilayer_leiden(G_intralayer, G_interlayer, layer_vec, gamma, omega, optim
         return tuple(intralayer_parts[0].membership)
 
 
+def _wrapped_multilayer_leiden(args):
+    """Wrapped multilayer_leiden() for use in multiprocessing.Pool.imap_unordered."""
+    return multilayer_leiden(*args)
+
+
 def multilayer_leiden_part(G_intralayer, G_interlayer, layer_membership):
     if 'weight' not in G_intralayer.es:
         G_intralayer.es['weight'] = [1.0] * G_intralayer.ecount()
@@ -178,51 +182,29 @@ def repeated_leiden_from_gammas(G, gammas):
     return {sorted_tuple(singlelayer_leiden(G, gamma)) for gamma in gammas}
 
 
-def repeated_parallel_leiden_from_gammas(G, gammas, show_progress=True, chunk_dispatch=True):
+def repeated_parallel_leiden_from_gammas(G, gammas, show_progress=True):
     r"""Runs the Leiden modularity maximization algorithm at each provided :math:`\gamma` value, using all CPU cores.
 
     :param G: graph of interest
     :type G: igraph.Graph
     :param gammas: list of gammas (resolution parameters) to run Leiden at
     :type gammas: list[float]
-    :param show_progress: if True, render a progress bar. This will only work if ``chunk_dispatch`` is also True
+    :param show_progress: if True, render a progress bar
     :type show_progress: bool
-    :param chunk_dispatch: if True, dispatch parallel work in chunks. Setting this to False may increase performance,
-                           but can lead to out-of-memory issues
-    :type chunk_dispatch: bool
     :return: a set of all unique partitions returned by the Leiden algorithm
     :rtype: set of tuple[int]
     """
-
-    pool = Pool(processes=cpu_count())
     total = set()
-
-    chunk_size = len(gammas) // 99
-    if chunk_size > 0 and chunk_dispatch:
-        chunk_params = ([(G, g) for g in gammas[i:i + chunk_size]] for i in range(0, len(gammas), chunk_size))
-    else:
-        chunk_params = [[(G, g) for g in gammas]]
-        chunk_size = len(gammas)
-
-    if show_progress:
-        progress = Progress(ceil(len(gammas) / chunk_size))
-
-    for chunk in chunk_params:
-        for partition in pool.starmap(singlelayer_leiden, chunk):
-            total.add(sorted_tuple(partition))
-
+    pool_chunk_size = max(1, len(gammas) // (cpu_count() * 100))
+    with Pool(processes=cpu_count()) as pool:
+        pool_iterator = pool.imap_unordered(_wrapped_singlelayer_leiden, [(G, g) for g in gammas],
+                                            chunksize=pool_chunk_size)
         if show_progress:
-            progress.increment()
-
-        if psutil.virtual_memory().available < LOW_MEMORY_THRESHOLD:
-            # Reinitialize pool to get around an apparent memory leak in multiprocessing
-            pool.close()
-            pool = Pool(processes=cpu_count())
+            pool_iterator = tqdm(pool_iterator, total=len(gammas))
 
-    if show_progress:
-        progress.done()
+        for partition in pool_iterator:
+            total.add(sorted_tuple(partition))
 
-    pool.close()
     return total
 
 
@@ -232,10 +214,13 @@ def repeated_leiden_from_gammas_omegas(G_intralayer, G_interlayer, layer_vec, ga
 
 
 def repeated_parallel_leiden_from_gammas_omegas(G_intralayer, G_interlayer, layer_vec, gammas, omegas,
-                                                show_progress=True, chunk_dispatch=True):
+                                                show_progress=True):
     """
     Runs leidenalg at each gamma and omega in ``gammas`` and ``omegas``, using all CPU cores available.
 
+    WARNING: Optimization can be EXTREMELY slow for large numbers of layers! Leidenalg does not properly implement
+    multilayer optimization.
+
     :param G_intralayer: intralayer graph of interest
     :type G_intralayer: igraph.Graph
     :param G_interlayer: interlayer graph of interest
@@ -248,44 +233,23 @@ def repeated_parallel_leiden_from_gammas_omegas(G_intralayer, G_interlayer, laye
     :type omegas: list[float]
     :param show_progress: if True, render a progress bar
     :type show_progress: bool
-    :param chunk_dispatch: if True, dispatch parallel work in chunks. Setting this to False may increase performance,
-                           but can lead to out-of-memory issues
-    :type chunk_dispatch: bool
     :return: a set of all unique partitions encountered
     :rtype: set of tuple[int]
     """
     resolution_parameter_points = [(gamma, omega) for gamma in gammas for omega in omegas]
 
-    pool = Pool(processes=cpu_count())
     total = set()
-
-    chunk_size = len(resolution_parameter_points) // 99
-    if chunk_size > 0 and chunk_dispatch:
-        chunk_params = ([(G_intralayer, G_interlayer, layer_vec, gamma, omega)
-                         for gamma, omega in resolution_parameter_points[i:i + chunk_size]]
-                        for i in range(0, len(resolution_parameter_points), chunk_size))
-    else:
-        chunk_params = [[(G_intralayer, G_interlayer, layer_vec, gamma, omega)
-                         for gamma, omega in resolution_parameter_points]]
-        chunk_size = len(gammas)
-
-    if show_progress:
-        progress = Progress(ceil(len(resolution_parameter_points) / chunk_size))
-
-    for chunk in chunk_params:
-        for partition in pool.starmap(multilayer_leiden, chunk):
-            total.add(sorted_tuple(partition))
-
+    pool_chunk_size = max(1, len(resolution_parameter_points) // (cpu_count() * 100))
+    with Pool(processes=cpu_count()) as pool:
+        pool_iterator = pool.imap_unordered(
+            _wrapped_multilayer_leiden,
+            [(G_intralayer, G_interlayer, layer_vec, gamma, omega) for gamma, omega in resolution_parameter_points],
+            chunksize=pool_chunk_size
+        )
         if show_progress:
-            progress.increment()
-
-        if psutil.virtual_memory().available < LOW_MEMORY_THRESHOLD:
-            # Reinitialize pool to get around an apparent memory leak in multiprocessing
-            pool.close()
-            pool = Pool(processes=cpu_count())
+            pool_iterator = tqdm(pool_iterator, total=len(resolution_parameter_points))
 
-    if show_progress:
-        progress.done()
+        for partition in pool_iterator:
+            total.add(sorted_tuple(partition))
 
-    pool.close()
     return total

modularitypruning/louvain_utilities.py

@@ -6,14 +6,16 @@ module ``modularitypruning.louvain_utilities`` now shims single-layer functions
 in ``modularitypruning.leiden_utilities`` (though it still contains the legacy multi-layer functions since they can be
 faster in general -- leidenalg does not efficiently implement multilayer optimization).
 """
-from . import leiden_utilities
-from .leiden_utilities import sorted_tuple, LOW_MEMORY_THRESHOLD
-from .progress import Progress
+import warnings
 from math import ceil
 from multiprocessing import Pool, cpu_count
+
 import numpy as np
 import psutil
-import warnings
+
+from . import leiden_utilities
+from .leiden_utilities import sorted_tuple, LOW_MEMORY_THRESHOLD
+from .progress import Progress
 
 try:
     import louvain  # import louvain if possible

modularitypruning/parameter_estimation.py

@@ -1,8 +1,9 @@
+import leidenalg
+
 from .leiden_utilities import singlelayer_leiden, multilayer_leiden
 from .parameter_estimation_utilities import leiden_part_with_membership, estimate_singlelayer_SBM_parameters, \
     gamma_estimate_from_parameters, omega_function_from_model, estimate_multilayer_SBM_parameters
 from .partition_utilities import in_degrees
-import leidenalg
 
 
 def iterative_monolayer_resolution_parameter_estimation(G, gamma=1.0, tol=1e-2, max_iter=25, verbose=False,

modularitypruning/parameter_estimation_utilities.py

@@ -1,12 +1,14 @@
-from .leiden_utilities import leiden_part_with_membership, sorted_tuple
-from .champ_utilities import CHAMP_2D, CHAMP_3D
-from .partition_utilities import num_communities
+import warnings
+from math import log
+
 import igraph as ig
 import leidenalg
-from math import log
 import numpy as np
 from scipy.optimize import fsolve
-import warnings
+
+from .champ_utilities import CHAMP_2D, CHAMP_3D
+from .leiden_utilities import leiden_part_with_membership, sorted_tuple
+from .partition_utilities import num_communities
 
 
 def estimate_singlelayer_SBM_parameters(G, partition, m=None):
@@ -534,12 +536,25 @@ def prune_to_multilayer_stable_partitions(G_intralayer, G_interlayer, layer_vec,
     parameter estimates are within the provided ``gamma_start``, ``gamma_end``, ``omega_start``, and ``omega_end``
     bounds.
 
+    There are three network layer topology models available, all from Pamfil et al.
+
+    * **"temporal"**: Interlayer edges always connect copies of a node from one layer to the next, often representing
+      interactions that change over time.
+    * **"multilevel"**: Interlayer edges connect a hierarchy of monolayer networks from one layer to the next. This is
+      more general than temporal networks, as nodes can connect arbitrarily to nodes in the next layer. These often
+      represent inclusion relationships, such as cities to counties, counties to states, and states to countries.
+    * **"multiplex"**: Each layer represents a type of interaction, making the entire multilayer network akin to an
+      edge-colored multigraph (each type of edge has its own layer). This model is unique in that there is no natural
+      ordering of layers, and the resulting theory requires some analytical simplifications, making the resulting
+      parameter estimation the least robust of the three models.
+
     See https://doi.org/10.1038/s41598-022-20142-6 for more details.
 
-    NOTE: This method truncates omega estimates to ``omega_end - 1e-3`` in order to properly identify stable partitions
-    with infinite interlayer coupling estimates (e.g. when all membership labels persist across layers). If
-    ``omega_end`` is set too low, such partitions may be incorrectly identified as stable. As such, you should be
-    somewhat wary of the returned partitions with zero community structure differences across layers.
+    NOTE: This method will truncate omega estimates to ``omega_end - 1e-3`` (and raise a warning) if needed to properly
+    identify stable partitions with very large or infinite interlayer coupling estimates (e.g., when all membership
+    labels persist across layers). If ``omega_end`` is set too low, these partitions may be incorrectly identified as
+    stable. Conversely, some partitions with large omega estimates might be misclassified as not stable. Therefore, be
+    cautious of returned partitions with little or no community structure differences across layers.
 
     :param G_intralayer: intralayer graph of interest
     :type G_intralayer: igraph.Graph
@@ -599,6 +614,11 @@ def prune_to_multilayer_stable_partitions(G_intralayer, G_interlayer, layer_vec,
                        omega_start, omega_end)
     domains_with_estimates = domains_to_gamma_omega_estimates(G_intralayer, G_interlayer, layer_vec, domains, model)
 
+    if any(o_est >= omega_end for _, _, g_est, o_est in domains_with_estimates if g_est is not None):
+        warnings.warn(f"We are truncating some omega estimates to your choice of omega_end={omega_end}. You should "
+                      f"check that this accurately captures the high-omega behavior of the partition domains. "
+                      f"Be cautious of partitions with little or no community structure differences across layers!")
+
     # Truncate infinite omega solutions to our maximum omega
     domains_with_estimates = [(polyverts, membership, g_est, min(o_est, omega_end - 1e-3))
                               for polyverts, membership, g_est, o_est in domains_with_estimates

modularitypruning/partition_utilities.py

@@ -1,4 +1,5 @@
 from collections import defaultdict
+
 from sklearn.metrics import adjusted_mutual_info_score, normalized_mutual_info_score
 
 

modularitypruning/plotting.py

@@ -1,12 +1,14 @@
-from .partition_utilities import num_communities, ami
 from collections import defaultdict
 from random import sample, shuffle
-import numpy as np
+
 import matplotlib
-from matplotlib.patches import Polygon
-from matplotlib.collections import PatchCollection
 import matplotlib.pyplot as plt
+import numpy as np
 import seaborn as sbn
+from matplotlib.collections import PatchCollection
+from matplotlib.patches import Polygon
+
+from .partition_utilities import num_communities, ami
 
 
 def plot_adjacency(adj):
@@ -69,7 +71,7 @@ def plot_estimates(gamma_estimates):
                 #           length_includes_head=True, alpha=0.5, zorder=2, **{"overhang": 0.5})
 
 
-def plot_2d_domains(domains, xlim, ylim, flip_axes=False, use_current_axes=False):
+def plot_2d_domains(domains, xlim, ylim, flip_axes=True, use_current_axes=False):
     """Plot partition dominance ranges in the (gamma, omega) plane, using the domains from CHAMP_3D.
 
     Limits output to xlim and ylim dimensions. Note that the plotting here has x=gamma and y=omega.
@@ -91,7 +93,7 @@ def plot_2d_domains(domains, xlim, ylim, flip_axes=False, use_current_axes=False
         patches.append(polygon)
 
     cnorm = matplotlib.colors.Normalize(vmin=0, vmax=len(domains))
-    cmap = matplotlib.cm.get_cmap("Set1")
+    cmap = plt.get_cmap("Set1")
     available_colors = {cmap(cnorm(i)) for i in range(len(domains))}
 
     if len(available_colors) == len(domains):
@@ -207,7 +209,7 @@ def plot_2d_domains_with_num_communities(domains_with_estimates, xlim, ylim, fli
     plt.ylim(ylim)
 
 
-def plot_2d_domains_with_ami(domains_with_estimates, ground_truth, xlim, ylim, flip_axes=False):
+def plot_2d_domains_with_ami(domains_with_estimates, ground_truth, xlim, ylim, flip_axes=True):
     """Plot partition dominance ranges in the (gamma, omega) plane, using the domains from CHAMP_3D and coloring by the
     AMI between the partitions and ground truth.
 

{modularitypruning-1.3.6.dist-info → modularitypruning-1.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: modularitypruning
-Version: 1.3.6
+Version: 1.4.1
 Summary: Pruning tool to identify small subsets of network partitions that are significant from the perspective of stochastic block model inference.
 Home-page: https://github.com/ragibson/ModularityPruning
 Author: Ryan Gibson
@@ -26,6 +26,7 @@ Requires-Dist: igraph
 Requires-Dist: scikit-learn
 Requires-Dist: scipy >=1.7
 Requires-Dist: seaborn
+Requires-Dist: tqdm
 
 # ModularityPruning
 
@@ -46,6 +47,7 @@ https://static-content.springer.com/esm/art%3A10.1038%2Fs41598-022-20142-6/Media
 ).
 
 ## Installation
+
 This project is on [PyPI](https://pypi.org/project/modularitypruning/) and can
 be installed with
 
@@ -60,6 +62,7 @@ Alternatively, you can install it from this repository directly:
     python3 setup.py install
 
 <a name = "Basic Usage"></a>
+
 ## Basic Usage
 
 This package interfaces directly with python-igraph. A simple example of its

modularitypruning-1.4.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+modularitypruning/__init__.py,sha256=U1iz51AVVzHw0aBZeJicxVg_L6TWq5pmv8Ep_bYyySU,238
+modularitypruning/champ_utilities.py,sha256=yRLng9KciNxJst3Ybp24qlRnYvIEIe5Y-ZVsfSijkqc,16350
+modularitypruning/leiden_utilities.py,sha256=kHHYFj30Ezl_YUhgmwEm-vPZ4K7658MqTGegra_4V_8,10360
+modularitypruning/louvain_utilities.py,sha256=duGAK0PlIJvtpo689dNuRNixNXvLIWAPf-5ELGhEHZ4,8233
+modularitypruning/parameter_estimation.py,sha256=n0_VPXa6QvFZqVEKhHSBUrnqQPTLRNGgNLDTsVymYT4,10480
+modularitypruning/parameter_estimation_utilities.py,sha256=teJvq_w1gSjmA2weV9PDKTLN2xgCWgsIQhiY6ZlJ_xU,28152
+modularitypruning/partition_utilities.py,sha256=0hPEftbV6xcYWdusiE65UZG99kqIrALH7Nwo_44KO-Q,957
+modularitypruning/plotting.py,sha256=48yRl0--q1adi415pps1MbTtKtBMQxKVOXoRjPOxu-w,10570
+modularitypruning/progress.py,sha256=XxkEVx8L9BoFnWtvUPg-kWtxUmE1RHqs5p5HPiTExUQ,971
+modularitypruning-1.4.1.dist-info/LICENSE,sha256=eWz3HIQQxg7p1iSpUOUDKdDhGcuMPuVDDlcXf9F12D8,1068
+modularitypruning-1.4.1.dist-info/METADATA,sha256=AYXmtCswKmz9EU7rjS3WugRrMGZt3sA_AoDNq6ASB3I,3422
+modularitypruning-1.4.1.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+modularitypruning-1.4.1.dist-info/top_level.txt,sha256=ZPOx3a-ek0Ge0ZMq-uvbySSaAL9MZ-t23-JkuHZXo9E,18
+modularitypruning-1.4.1.dist-info/RECORD,,

{modularitypruning-1.3.6.dist-info → modularitypruning-1.4.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.3)
+Generator: setuptools (75.2.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

modularitypruning-1.3.6.dist-info/RECORD

@@ -1,14 +0,0 @@
-modularitypruning/__init__.py,sha256=U1iz51AVVzHw0aBZeJicxVg_L6TWq5pmv8Ep_bYyySU,238
-modularitypruning/champ_utilities.py,sha256=VveP8N9CvMODk3dPtVMRfNLji1pktaolA6iNoW6Fy-A,16348
-modularitypruning/leiden_utilities.py,sha256=er_Sjp5b6fUacO-Bfygbk6CiX6J8uj-gKFw-HZWffNA,11820
-modularitypruning/louvain_utilities.py,sha256=Zt58Wl4hgu6-zejdl-N_NW04UC4rbYmSHgpfoGDC2Ws,8231
-modularitypruning/parameter_estimation.py,sha256=EPU5BDDauToPbAdG1lZc9p5Rl_oDqiC7bltfnjs5tg8,10479
-modularitypruning/parameter_estimation_utilities.py,sha256=dRml1ZIB3ctVC7lk4QQRQwwLBldhG92rNIT6kHs0yfQ,26563
-modularitypruning/partition_utilities.py,sha256=Fizqd0JuODL8W4BP2h8iV0WhZMK6HoKjH_QFNVDZkaI,956
-modularitypruning/plotting.py,sha256=Bxu62ueWZRKKoeNVVHy0aXvocKAUgKuj0dZZsnLmL78,10580
-modularitypruning/progress.py,sha256=XxkEVx8L9BoFnWtvUPg-kWtxUmE1RHqs5p5HPiTExUQ,971
-modularitypruning-1.3.6.dist-info/LICENSE,sha256=eWz3HIQQxg7p1iSpUOUDKdDhGcuMPuVDDlcXf9F12D8,1068
-modularitypruning-1.3.6.dist-info/METADATA,sha256=mcEUa7NhV6DfDHPHGHY6J7jv99McahL_R0Py_-jU0fQ,3400
-modularitypruning-1.3.6.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-modularitypruning-1.3.6.dist-info/top_level.txt,sha256=ZPOx3a-ek0Ge0ZMq-uvbySSaAL9MZ-t23-JkuHZXo9E,18
-modularitypruning-1.3.6.dist-info/RECORD,,