modularitypruning 1.3.5__tar.gz → 1.4.0__tar.gz

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: modularitypruning
-Version: 1.3.5
+Version: 1.4.0
 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
 

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/modularitypruning.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: modularitypruning
-Version: 1.3.5
+Version: 1.4.0
 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
 

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/modularitypruning.egg-info/SOURCES.txt

@@ -11,8 +11,10 @@ tests/test_champ_coefficients_3D.py
 tests/test_champ_usage_2D.py
 tests/test_champ_usage_3D.py
 tests/test_deprecated_louvain_names.py
+tests/test_documentation_examples.py
 tests/test_monolayer_parameter_estimation.py
 tests/test_multiplex_parameter_estimation.py
+tests/test_parallel_leiden_performance.py
 tests/test_temporal_multilevel_parameter_estimation.py
 utilities/__init__.py
 utilities/champ_utilities.py

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/modularitypruning.egg-info/requires.txt

@@ -6,3 +6,4 @@ igraph
 scikit-learn
 scipy>=1.7
 seaborn
+tqdm

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/setup.py

@@ -9,7 +9,7 @@ with open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
 
 setup(
     name='modularitypruning',
-    version='1.3.5',
+    version='1.4.0',
     package_dir={'modularitypruning': 'utilities'},
     packages=['modularitypruning'],
     url='https://github.com/ragibson/ModularityPruning',
@@ -34,5 +34,5 @@ setup(
     ],
     python_requires='>=3.8, <4',
     install_requires=['leidenalg', 'matplotlib', "numpy", 'psutil', 'igraph',
-                      "scikit-learn", "scipy>=1.7", 'seaborn']
+                      "scikit-learn", "scipy>=1.7", 'seaborn', 'tqdm']
 )

modularitypruning-1.4.0/tests/test_documentation_examples.py

@@ -0,0 +1,265 @@
+"""
+This set of tests checks that the examples from the documentation still work correctly.
+
+Sometimes this is simply checking that the code produces the intended output or runs without errors.
+"""
+from modularitypruning import prune_to_stable_partitions, prune_to_multilayer_stable_partitions
+from modularitypruning.champ_utilities import CHAMP_2D, CHAMP_3D
+from modularitypruning.leiden_utilities import (repeated_parallel_leiden_from_gammas,
+                                                repeated_parallel_leiden_from_gammas_omegas)
+from modularitypruning.parameter_estimation_utilities import domains_to_gamma_omega_estimates, ranges_to_gamma_estimates
+from modularitypruning.partition_utilities import num_communities
+from modularitypruning.plotting import (plot_2d_domains_with_estimates, plot_2d_domains, plot_2d_domains_with_ami,
+                                        plot_2d_domains_with_num_communities, plot_estimates, plot_multiplex_community)
+from random import seed, random
+import igraph as ig
+import matplotlib.pyplot as plt
+import numpy as np
+import unittest
+
+
+class TestDocumentationExamples(unittest.TestCase):
+    def test_basic_singlelayer_example(self):
+        """
+        Taken verbatim from basic_example.rst.
+
+        Like a lot of our other tests, this is stochastic but appears incredibly stable.
+        """
+        # get Karate Club graph in igraph
+        G = ig.Graph.Famous("Zachary")
+
+        # run leiden 1000 times on this graph from gamma=0 to gamma=2
+        partitions = repeated_parallel_leiden_from_gammas(G, np.linspace(0, 2, 1000))
+
+        # prune to the stable partitions from gamma=0 to gamma=2
+        stable_partitions = prune_to_stable_partitions(G, partitions, 0, 2)
+
+        intended_stable_partition = [(0, 0, 0, 0, 1, 1, 1, 0, 2, 2, 1, 0, 0, 0, 2, 2, 1,
+                                      0, 2, 0, 2, 0, 2, 3, 3, 3, 2, 3, 3, 2, 2, 3, 2, 2)]
+        self.assertEqual(stable_partitions, intended_stable_partition)
+
+    @staticmethod
+    def generate_basic_multilayer_network():
+        """This is taken verbatim from basic_multilayer_example.rst."""
+        num_layers = 3
+        n_per_layer = 30
+        p_in = 0.5
+        p_out = 0.05
+        K = 3
+
+        # layer_vec holds the layer membership of each node
+        # e.g. layer_vec[5] = 2 means that node 5 resides in layer 2 (the third layer)
+        layer_vec = [i // n_per_layer for i in range(n_per_layer * num_layers)]
+        interlayer_edges = [(n_per_layer * layer + v, n_per_layer * layer + v + n_per_layer)
+                            for layer in range(num_layers - 1)
+                            for v in range(n_per_layer)]
+
+        # set up a community vector with
+        #   three communities in layer 0 (each of size 10)
+        #   three communities in layer 1 (each of size 10)
+        #   one community in layer 2 (of size 30)
+        comm_per_layer = [[i // (n_per_layer // K) if layer < num_layers - 1 else 0
+                           for i in range(n_per_layer)] for layer in range(num_layers)]
+        comm_vec = [item for sublist in comm_per_layer for item in sublist]
+
+        # randomly connect nodes inside each layer with undirected edges according to
+        # within-community probability p_in and between-community probability p_out
+        intralayer_edges = [(u, v) for v in range(len(comm_vec)) for u in range(v + 1, len(comm_vec))
+                            if layer_vec[v] == layer_vec[u] and (
+                                    (comm_vec[v] == comm_vec[u] and random() < p_in) or
+                                    (comm_vec[v] != comm_vec[u] and random() < p_out)
+                            )]
+
+        # create the networks in igraph. By Pamfil et al.'s convention, the interlayer edges
+        # of a temporal network are directed (representing the "one-way" nature of time)
+        G_intralayer = ig.Graph(intralayer_edges)
+        G_interlayer = ig.Graph(interlayer_edges, directed=True)
+
+        return G_intralayer, G_interlayer, layer_vec
+
+    def test_basic_multilayer_example(self):
+        """
+        This is taken verbatim from basic_multilayer_example.rst.
+
+        For simplicity and re-use, the network generation is encapsulated in generate_basic_multilayer_network().
+        """
+        n_per_layer = 30  # from network generation code
+        G_intralayer, G_interlayer, layer_vec = self.generate_basic_multilayer_network()
+
+        # run leidenalg on a uniform 32x32 grid (1024 samples) of gamma and omega in [0, 2]
+        gamma_range = (0, 2)
+        omega_range = (0, 2)
+        leiden_gammas = np.linspace(*gamma_range, 32)
+        leiden_omegas = np.linspace(*omega_range, 32)
+
+        parts = repeated_parallel_leiden_from_gammas_omegas(G_intralayer, G_interlayer, layer_vec,
+                                                            gammas=leiden_gammas, omegas=leiden_omegas)
+
+        # prune to the stable partitions from (gamma=0, omega=0) to (gamma=2, omega=2)
+        stable_parts = prune_to_multilayer_stable_partitions(G_intralayer, G_interlayer, layer_vec,
+                                                             "temporal", parts,
+                                                             *gamma_range, *omega_range)
+
+        # check all 3-partition stable partitions closely match ground truth communities
+        for membership in stable_parts:
+            if num_communities(membership) != 3:
+                continue
+
+            most_common_label = []
+            for chunk_idx in range(6):  # check most common label of each community (10 nodes each)
+                counts = {i: 0 for i in range(max(membership) + 1)}
+                for chunk_label in membership[10 * chunk_idx:10 * (chunk_idx + 1)]:
+                    counts[chunk_label] += 1
+                most_common_label.append(max(counts.items(), key=lambda x: x[1])[0])
+
+            # check these communities look like the intended ground truth communities for the first layer
+            #   [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2]
+            self.assertNotEqual(most_common_label[0], most_common_label[1])
+            self.assertNotEqual(most_common_label[1], most_common_label[2])
+
+        # at least one partition has the last layer mostly in one community and another splits it into multiple
+        unified_final_layer_count = 0
+        split_final_layer_count = 0
+        for membership in stable_parts:
+            count_final_layer = {i: 0 for i in range(max(membership) + 1)}
+            for label in membership[-n_per_layer:]:
+                count_final_layer[label] += 1
+            most_common_label_final_layer, most_common_label_count = max(count_final_layer.items(),
+                                                                         key=lambda x: x[1])
+            proportion_final_layer_having_same_label = most_common_label_count / n_per_layer
+
+            if proportion_final_layer_having_same_label > 0.9:
+                unified_final_layer_count += 1
+            elif proportion_final_layer_having_same_label < 0.5:
+                split_final_layer_count += 1
+
+        self.assertGreater(unified_final_layer_count, 0)
+        self.assertGreater(split_final_layer_count, 0)
+
+    def test_plot_estimates_example(self):
+        """
+        This is taken (almost) verbatim from plotting_examples.rst.
+
+        The first call to plt.rc() has usetex=False (instead of True) to avoid requiring a full LaTeX installation.
+        """
+        # get Karate Club graph in igraph
+        G = ig.Graph.Famous("Zachary")
+
+        # run leiden 100K times on this graph from gamma=0 to gamma=2 (takes ~2-3 seconds)
+        partitions = repeated_parallel_leiden_from_gammas(G, np.linspace(0, 2, 10 ** 5))
+
+        # run CHAMP to obtain the dominant partitions along with their regions of optimality
+        ranges = CHAMP_2D(G, partitions, gamma_0=0.0, gamma_f=2.0)
+
+        # append gamma estimate for each dominant partition onto the CHAMP domains
+        gamma_estimates = ranges_to_gamma_estimates(G, ranges)
+
+        # plot gamma estimates and domains of optimality
+        plt.rc('text', usetex=False)
+        plt.rc('font', family='serif')
+        plot_estimates(gamma_estimates)
+        plt.title(r"Karate Club CHAMP Domains of Optimality and $\gamma$ Estimates", fontsize=14)
+        plt.xlabel(r"$\gamma$", fontsize=14)
+        plt.ylabel("Number of communities", fontsize=14)
+
+    def test_plot_2d_domains_examples(self):
+        """
+        This is taken (almost) verbatim from plotting_examples.rst.
+
+        The first call to plt.rc() has usetex=False (instead of True) to avoid requiring a full LaTeX installation.
+
+        The documentation explicitly shows plot_2d_domains_with_estimates() and describes other, similar functions
+            * plot_2d_domains()
+            * plot_2d_domains_with_ami()
+            * plot_2d_domains_with_num_communities()
+        As such, we test them all here.
+        """
+        G_intralayer, G_interlayer, layer_vec = self.generate_basic_multilayer_network()
+        # run leiden on a uniform grid (10K samples) of gamma and omega (takes ~3 seconds)
+        gamma_range = (0.5, 1.5)
+        omega_range = (0, 2)
+        parts = repeated_parallel_leiden_from_gammas_omegas(G_intralayer, G_interlayer, layer_vec,
+                                                            gammas=np.linspace(*gamma_range, 100),
+                                                            omegas=np.linspace(*omega_range, 100))
+
+        # run CHAMP to obtain the dominant partitions along with their regions of optimality
+        domains = CHAMP_3D(G_intralayer, G_interlayer, layer_vec, parts,
+                           gamma_0=gamma_range[0], gamma_f=gamma_range[1],
+                           omega_0=omega_range[0], omega_f=omega_range[1])
+
+        # append resolution parameter estimates for each dominant partition onto the CHAMP domains
+        domains_with_estimates = domains_to_gamma_omega_estimates(G_intralayer, G_interlayer, layer_vec,
+                                                                  domains, model='temporal')
+
+        # plot resolution parameter estimates and domains of optimality
+        plt.rc('text', usetex=False)
+        plt.rc('font', family='serif')
+        plot_2d_domains_with_estimates(domains_with_estimates, xlim=omega_range, ylim=gamma_range)
+        plt.title(r"CHAMP Domains and ($\omega$, $\gamma$) Estimates", fontsize=16)
+        plt.xlabel(r"$\omega$", fontsize=20)
+        plt.ylabel(r"$\gamma$", fontsize=20)
+        plt.gca().tick_params(axis='both', labelsize=12)
+        plt.tight_layout()
+
+        # same plotting code, but with plot_2d_domains()
+        plt.rc('text', usetex=False)
+        plt.rc('font', family='serif')
+        plot_2d_domains(domains, xlim=omega_range, ylim=gamma_range)
+        plt.title(r"CHAMP Domains", fontsize=16)
+        plt.xlabel(r"$\omega$", fontsize=20)
+        plt.ylabel(r"$\gamma$", fontsize=20)
+        plt.gca().tick_params(axis='both', labelsize=12)
+        plt.tight_layout()
+
+        # same plotting code, but with plot_2d_domains_with_ami()
+        plt.rc('text', usetex=False)
+        plt.rc('font', family='serif')
+        ground_truth_partition = ([0] * 10 + [1] * 10 + [2] * 10) * 2 + [0] * 30
+        plot_2d_domains_with_ami(domains_with_estimates, ground_truth=ground_truth_partition,
+                                 xlim=omega_range, ylim=gamma_range)
+        plt.title(r"CHAMP Domains, Colored by AMI with Ground Truth", fontsize=16)
+        plt.xlabel(r"$\omega$", fontsize=20)
+        plt.ylabel(r"$\gamma$", fontsize=20)
+        plt.gca().tick_params(axis='both', labelsize=12)
+        plt.tight_layout()
+
+        # same plotting code, but with plot_2d_domains_with_num_communities()
+        plt.rc('text', usetex=False)
+        plt.rc('font', family='serif')
+        plot_2d_domains_with_num_communities(domains_with_estimates, xlim=omega_range, ylim=gamma_range)
+        plt.title(r"CHAMP Domains, Colored by Number of Communities", fontsize=16)
+        plt.xlabel(r"$\omega$", fontsize=20)
+        plt.ylabel(r"$\gamma$", fontsize=20)
+        plt.gca().tick_params(axis='both', labelsize=12)
+        plt.tight_layout()
+        plt.close()  # closing all these figures instead of showing
+
+    def test_plot_multiplex_community(self):
+        """
+        This is taken (almost) verbatim from plotting_examples.rst.
+
+        The first call to plt.rc() has usetex=False (instead of True) to avoid requiring a full LaTeX installation.
+        """
+        num_layers = 3
+        layer_vec = [i // 71 for i in range(num_layers * 71)]
+        membership = [1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1,
+                      1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2,
+                      2, 2, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+                      0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2,
+                      2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1,
+                      1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 2, 2, 2,
+                      2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2]
+
+        plt.rc('text', usetex=False)
+        plt.rc('font', family='serif')
+        ax = plot_multiplex_community(np.array(membership), np.array(layer_vec))
+        ax.set_xticks(np.linspace(0, num_layers, 2 * num_layers + 1))
+        ax.set_xticklabels(["", "Advice", "", "Coworker", "", "Friend", ""], fontsize=14)
+        plt.title(f"Multiplex Communities", fontsize=14)
+        plt.ylabel("Node ID", fontsize=14)
+        plt.close()  # closing this these figures instead of showing
+
+
+if __name__ == "__main__":
+    seed(0)
+    unittest.main()

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/tests/test_multiplex_parameter_estimation.py

@@ -49,10 +49,10 @@ class TestMultiplexParameterEstimation(unittest.TestCase):
                                                                                   model='multiplex')
 
         # check we converged close to the ground truth "correct" values
-        # the multiplex omega estimation seems less accurate than in other models, perhaps due to
-        # the copying probability approximation
-        self.assertLess(abs(true_gamma - gamma), 0.05)
-        self.assertLess(abs(true_omega - omega), 0.15)
+        # the multiplex parameter estimation is much less robust and less accurate than in other models,
+        # perhaps due to the copying probability approximation
+        self.assertLess(abs(true_gamma - gamma), 0.1)
+        self.assertLess(abs(true_omega - omega), 0.2)
 
     def test_multiplex_SBM_correct_convergence_varying_copying_probabilty(self):
         for eta in [0.25, 0.5, 0.75, 0.9]:

modularitypruning-1.4.0/tests/test_parallel_leiden_performance.py

@@ -0,0 +1,146 @@
+from .shared_testing_functions import generate_connected_ER, generate_multilayer_intralayer_SBM
+from modularitypruning.leiden_utilities import (repeated_leiden_from_gammas, repeated_parallel_leiden_from_gammas,
+                                                repeated_leiden_from_gammas_omegas,
+                                                repeated_parallel_leiden_from_gammas_omegas)
+from multiprocessing import Pool, cpu_count
+from random import seed
+from time import time, sleep
+import functools
+import igraph as ig
+import numpy as np
+import psutil
+import unittest
+import warnings
+
+# this set of tests ensures that we achieve >= 75% parallel performance compared to perfect scaling of
+# single-threaded jobs to multiple cores (with no memory contention). This threshold will be decreased in
+# determine_target_parallelization_speedup() if the background CPU utilization exceeds 20%.
+PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING = 0.75
+
+
+def mock_calculation(_):
+    """A mock calculation that provides enough work to make serialization overhead negligible."""
+    return sum(range(10 ** 7))
+
+
+@functools.lru_cache(maxsize=1)
+def determine_target_parallelization_speedup(num_calculations=32):
+    """
+    Calculate the parallelization speedup on mock_calculation to benchmark our implementation against.
+
+    This performs
+      * ``num_calculations`` function calls in the single-threaded case, and
+      * ``num_calculations * cpu_count()`` calls in the multi-processed case
+
+    Due in part to frequency scaling and simple memory contention, leidenalg over multiple processes (completely
+    outside of Python or multiprocessing.Pool) seems to run at around (90% * core count) speedup on modern systems when
+    hyper-threading is disabled.
+    """
+    global PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING
+
+    sleep(5)  # sleep to increase stability of the CPU utilization check
+    cpu_utilization = psutil.cpu_percent()
+    if cpu_utilization > 20:
+        PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING = 0.5
+        warnings.warn(f"System CPU utilization is non-negligible during parallel performance test! "
+                      f"Dropping performance scaling target to 50%.")
+
+    start_time = time()
+    _ = [mock_calculation(i) for i in range(num_calculations)]
+    base_duration = time() - start_time
+
+    num_pool_calculations = num_calculations * cpu_count()
+    with Pool(processes=cpu_count()) as pool:
+        pool.map(mock_calculation, range(cpu_count()))  # force pool initialization and basic burn-in
+
+        start_time = time()
+        pool.map(mock_calculation, range(num_pool_calculations))
+        pool_duration = time() - start_time
+
+    return num_pool_calculations / num_calculations * base_duration / pool_duration
+
+
+class TestParallelLeidenPerformance(unittest.TestCase):
+    @staticmethod
+    def run_singlelayer_graph_parallelization(G, gammas):
+        target_speedup = determine_target_parallelization_speedup()
+
+        start_time = time()
+        _ = repeated_leiden_from_gammas(G, gammas)
+        duration = time() - start_time
+
+        pool_gammas = np.linspace(min(gammas), max(gammas), len(gammas) * cpu_count())
+        start_time = time()
+        _ = repeated_parallel_leiden_from_gammas(G, pool_gammas)
+        pool_duration = time() - start_time
+
+        speedup = len(pool_gammas) / len(gammas) * duration / pool_duration
+        return speedup / target_speedup
+
+    @staticmethod
+    def run_multilayer_graph_parallelization(G_intralayer, G_interlayer, layer_membership, gammas, omegas):
+        target_speedup = determine_target_parallelization_speedup()
+
+        start_time = time()
+        _ = repeated_leiden_from_gammas_omegas(G_intralayer, G_interlayer, layer_membership, gammas, omegas)
+        duration = time() - start_time
+
+        pool_gammas = np.linspace(min(gammas), max(gammas), int(len(gammas) * np.sqrt(cpu_count())))
+        pool_omegas = np.linspace(min(omegas), max(omegas), int(len(omegas) * np.sqrt(cpu_count())))
+        start_time = time()
+        _ = repeated_parallel_leiden_from_gammas_omegas(
+            G_intralayer, G_interlayer, layer_membership, pool_gammas, pool_omegas
+        )
+        pool_duration = time() - start_time
+
+        speedup = len(pool_gammas) * len(pool_omegas) / len(gammas) / len(omegas) * duration / pool_duration
+        return speedup / target_speedup
+
+    def test_tiny_singlelayer_graph_many_runs(self):
+        """Single-threaded equivalent is 25k runs on G(n=34, m=78)."""
+        G = ig.Graph.Famous("Zachary")
+        gammas = np.linspace(0.0, 4.0, 25000)
+        parallelization = self.run_singlelayer_graph_parallelization(G, gammas)
+        self.assertGreater(parallelization, PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING)
+
+    def test_larger_singlelayer_graph_few_runs(self):
+        """Single-threaded equivalent is 50 runs on G(n=10000, m=40000)."""
+        G = generate_connected_ER(n=10000, m=40000, directed=False)
+        gammas = np.linspace(0.0, 2.0, 50)
+        parallelization = self.run_singlelayer_graph_parallelization(G, gammas)
+        self.assertGreater(parallelization, PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING)
+
+    def test_tiny_multilayer_graph_many_runs(self):
+        """Single-threaded equivalent is 10k runs on G(n=50, m=150)."""
+        G_intralayer, layer_membership = generate_multilayer_intralayer_SBM(
+            copying_probability=0.9, p_in=0.8, p_out=0.2, first_layer_membership=[0] * 5 + [1] * 5, num_layers=5
+        )
+        interlayer_edges = [(10 * layer + v, 10 * layer + v + 10)
+                            for layer in range(5 - 1) for v in range(10)]
+        G_interlayer = ig.Graph(interlayer_edges, directed=True)
+
+        gammas = np.linspace(0.0, 2.0, 100)
+        omegas = np.linspace(0.0, 2.0, 100)
+        parallelization = self.run_multilayer_graph_parallelization(G_intralayer, G_interlayer,
+                                                                    layer_membership, gammas, omegas)
+        self.assertGreater(parallelization, PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING)
+
+    def test_larger_multilayer_graph_few_runs(self):
+        """Single-threaded equivalent is 49 runs on approximately G(n=2500, m=15000)."""
+        G_intralayer, layer_membership = generate_multilayer_intralayer_SBM(
+            copying_probability=0.9, p_in=0.15, p_out=0.05, first_layer_membership=[0] * 50 + [1] * 50, num_layers=25
+        )
+        interlayer_edges = [(100 * layer + v, 100 * layer + v + 100)
+                            for layer in range(25 - 1) for v in range(100)]
+        G_interlayer = ig.Graph(interlayer_edges, directed=True)
+
+        gammas = np.linspace(0.0, 2.0, 7)
+        omegas = np.linspace(0.0, 2.0, 7)
+        parallelization = self.run_multilayer_graph_parallelization(G_intralayer, G_interlayer,
+                                                                    layer_membership, gammas, omegas)
+        self.assertGreater(parallelization, PERFORMANCE_TARGET_RELATIVE_TO_PERFECT_SCALING)
+
+
+if __name__ == "__main__":
+    seed(0)
+    unittest.main()

{modularitypruning-1.3.5 → modularitypruning-1.4.0}/utilities/leiden_utilities.py

@@ -1,12 +1,11 @@
-from .progress import Progress
 import functools
 import igraph as ig
 import leidenalg
 from math import ceil
 from multiprocessing import Pool, cpu_count
+from tqdm import tqdm
 import numpy as np
 import psutil
-import warnings
 
 LOW_MEMORY_THRESHOLD = 1e9  # 1 GB
 
@@ -50,6 +49,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 +72,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 +79,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 +107,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 +150,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 +183,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 +215,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 +234,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-1.3.5 → modularitypruning-1.4.0}/utilities/parameter_estimation_utilities.py

@@ -534,12 +534,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 +612,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-1.3.5 → modularitypruning-1.4.0}/utilities/plotting.py

@@ -18,7 +18,7 @@ def plot_estimates(gamma_estimates):
     """Plot partition dominance ranges with gamma estimates.
 
     :param gamma_estimates: gamma estimates as returned from
-        :meth:`~modularitypruning.plotting.ranges_to_gamma_estimates`
+        :meth:`~modularitypruning.parameter_estimation_utilities.ranges_to_gamma_estimates`
     """
 
     ax = plt.gca()
@@ -69,7 +69,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 +91,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 +207,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.