def _compute_spectral_decomp(matrix):
- """Solve eigenalue problem."""
- lambdas, v = la.eig(matrix.toarray())
+ """Solve eigenalue problem for symmetric matrix."""
+ lambdas, v = la.eigh(matrix.toarray())
vinv = la.inv(v.real)
return lambdas.real, v.real, vinv
@@ -366,14 +366,20 @@ Source code for pygenstability.constructors
[docs]class constructor_continuous_combinatorial(Constructor):
r"""Constructor for continuous combinatorial Markov Stability.
- The quality matrix is:
+ This implementation follows equation (16) in [1]_. The quality matrix is:
.. math::
- F(t) = \Pi\exp(-Lt)
+ F(t) = \Pi\exp(-tL/<d>)
- where :math:`L=D-A` is the combinatorial Laplacian and :math:`\Pi=\mathrm{diag}(\pi)`,
+ where :math:`<d>=(\boldsymbol{1}^T D \boldsymbol{1})/N` is the average degree,
+ :math:`L=D-A` is the combinatorial Laplacian and :math:`\Pi=\mathrm{diag}(\pi)`,
with null model :math:`v_1=v_2=\pi=\frac{\boldsymbol{1}}{N}`.
+
+ References:
+ .. [1] Lambiotte, R., Delvenne, J.-C., & Barahona, M. (2019). Random Walks, Markov
+ Processes and the Multiscale Modular Organization of Complex Networks.
+ IEEE Trans. Netw. Sci. Eng., 1(2), p. 76-90.
"""
[docs] @_limit_numpy
@@ -406,11 +412,11 @@ Source code for pygenstability.constructors
[docs]class constructor_continuous_normalized(Constructor):
r"""Constructor for continuous normalized Markov Stability.
- The quality matrix is:
+ This implementation follows equation (10) in [1]_. The quality matrix is:
.. math::
- F(t) = \Pi\exp(-Lt)
+ F(t) = \Pi\exp(-tL)
where :math:`L=D^{-1}(D-A)` is the random-walk normalized Laplacian and
:math:`\Pi=\mathrm{diag}(\pi)` with null model :math:`v_1=v_2=\pi=\frac{d}{2M}`.
@@ -448,12 +454,12 @@ Source code for pygenstability.constructors
[docs]class constructor_signed_modularity(Constructor):
"""Constructor of signed modularity.
- This implementation is equation (18) of [1]_, where quality is the adjacency matrix and
+ This implementation is equation (18) of [2]_, where quality is the adjacency matrix and
the null model is the difference between the standard modularity null models based on
positive and negative degree vectors.
References:
- .. [1] Gomez, S., Jensen, P., & Arenas, A. (2009). Analysis of community structure in
+ .. [2] Gomez, S., Jensen, P., & Arenas, A. (2009). Analysis of community structure in
networks of correlated data. Physical Review E, 80(1), 016114.
"""
@@ -491,16 +497,20 @@ Source code for pygenstability.constructors
[docs]class constructor_signed_combinatorial(Constructor):
r"""Constructor for continuous signed combinatorial Markov Stability.
- The quality matrix is:
+ This implementation follows equation (19) in [3]_. The quality matrix is:
.. math::
- F(t) = \exp(-Lt)^T\exp(-Lt)
+ F(t) = \exp(-tL)^T\exp(-tL)
where :math:`L=D_{\mathrm{abs}}-A` is the signed combinatorial Laplacian,
:math:`D_{\mathrm{abs}}=\mathrm{diag}(d_\mathrm{abs})` the diagonal matrix of absolute node
strengths :math:`d_\mathrm{abs}`, and the associated null model is given by
:math:`v_1=v_2=\boldsymbol{0}`, where :math:`\boldsymbol{0}` is the vector of zeros.
+
+ References:
+ .. [3] Schaub, M., Delvenne, J.-C., Lambiotte, R., & Barahona, M. (2019). Multiscale
+ dynamical embeddings of complex networks. Physical Review E, 99(6), 062308.
"""
[docs] def prepare(self, **kwargs):
@@ -535,7 +545,8 @@ Source code for pygenstability.constructors
where :math:`I` denotes the identity matrix, :math:`M(\alpha)` is the transition matrix of a
random walk with teleportation and damping factor :math:`0\le \alpha < 1`, and
:math:`\Pi=\mathrm{diag}(\pi)` for the associated null model :math:`v_1=v_2=\pi` given by the
- eigenvector solving :math:`\pi M(\alpha) = \pi`, which is related to PageRank.
+ eigenvector solving :math:`\pi M(\alpha) = \pi`, which is related to PageRank. See [1]_ for
+ details.
The transition matrix :math:`M(\alpha)` is given by
@@ -552,7 +563,9 @@ Source code for pygenstability.constructors
[docs] @_limit_numpy
def prepare(self, **kwargs):
"""Prepare the constructor with non-scale dependent computations."""
- assert self.exp_comp_mode == "expm"
+ assert (
+ self.exp_comp_mode == "expm"
+ ), 'exp_comp_mode="expm" is required for "constructor_directed"'
alpha = kwargs.get("alpha", 0.8)
n_nodes = self.graph.shape[0]
diff --git a/_modules/pygenstability/optimal_scales.html b/_modules/pygenstability/optimal_scales.html
index 853b0cb..45ebca1 100644
--- a/_modules/pygenstability/optimal_scales.html
+++ b/_modules/pygenstability/optimal_scales.html
@@ -231,7 +231,12 @@ Source code for pygenstability.optimal_scales
)
shape_w = (output_shape[0], output_shape[1], kernel_size, kernel_size)
# pylint: disable=unsubscriptable-object
- strides_w = (stride * A.strides[0], stride * A.strides[1], A.strides[0], A.strides[1])
+ strides_w = (
+ stride * A.strides[0],
+ stride * A.strides[1],
+ A.strides[0],
+ A.strides[1],
+ )
A_w = as_strided(A, shape_w, strides_w)
# Return the result of pooling
@@ -255,7 +260,7 @@ Source code for pygenstability.optimal_scales
basin_radius (int): radius of basin around local minima of the pooled diagonal
Returns:
- result dictionary with two new keys: 'selected_partitions' and 'block_detection_curve'
+ result dictionary with two new keys: 'selected_partitions' and 'block_nvi'
References:
.. [1] D. J. Schindler, J. Clarke, and M. Barahona, 'Multiscale Mobility Patterns and
@@ -272,23 +277,21 @@ Source code for pygenstability.optimal_scales
diagonal = np.diag(nvi_tt_pooled)[: len(nvi_t)]
# smooth diagonal with moving window
- block_detection_curve = np.roll(
+ block_nvi = np.roll(
np.asarray(pd.Series(diagonal).rolling(window=window_size, win_type="triang").mean()),
-int(window_size / 2),
)
- results["block_detection_curve"] = block_detection_curve
+ results["block_nvi"] = block_nvi
# find local minima on diagonal of pooled NVI(s,s')
- basin_centers, _ = find_peaks(-block_detection_curve, height=-max_nvi)
+ basin_centers, _ = find_peaks(-block_nvi, height=-max_nvi)
# add robust scales located in large 0 margins
- not_nan_ind = np.argwhere(~np.isnan(block_detection_curve)).flatten()
+ not_nan_ind = np.argwhere(~np.isnan(block_nvi)).flatten()
if (
np.count_nonzero(
- np.around(
- block_detection_curve[not_nan_ind[0] : not_nan_ind[0] + 2 * basin_radius + 1], 5
- )
+ np.around(block_nvi[not_nan_ind[0] : not_nan_ind[0] + 2 * basin_radius + 1], 5)
)
== 0
):
@@ -296,9 +299,7 @@ Source code for pygenstability.optimal_scales
if (
np.count_nonzero(
- np.around(
- block_detection_curve[not_nan_ind[-1] - 2 * basin_radius : not_nan_ind[-1] + 1], 5
- )
+ np.around(block_nvi[not_nan_ind[-1] - 2 * basin_radius : not_nan_ind[-1] + 1], 5)
)
== 0
):
diff --git a/_modules/pygenstability/plotting.html b/_modules/pygenstability/plotting.html
index a8f6046..a3b4969 100644
--- a/_modules/pygenstability/plotting.html
+++ b/_modules/pygenstability/plotting.html
@@ -229,6 +229,7 @@ Source code for pygenstability.plotting
[docs]def plot_scan(
all_results,
+ figsize=(6, 5),
scale_axis=True,
figure_name="scan_results.pdf",
use_plotly=False,
@@ -239,6 +240,7 @@ Source code for pygenstability.plotting
Args:
all_results (dict): results of pygenstability scan
+ figsize (tuple): matplotlib figure size
scale_axis (bool): display scale of scale index on scale axis
figure_name (str): name of matplotlib figure
use_plotly (bool): use matplotlib or plotly backend
@@ -252,7 +254,9 @@ Source code for pygenstability.plotting
if use_plotly:
return plot_scan_plotly(all_results, live=live, filename=plotly_filename)
- return plot_scan_plt(all_results, scale_axis=scale_axis, figure_name=figure_name)
+ return plot_scan_plt(
+ all_results, figsize=figsize, scale_axis=scale_axis, figure_name=figure_name
+ )
[docs]def plot_scan_plotly( # pylint: disable=too-many-branches,too-many-statements,too-many-locals
@@ -461,7 +465,11 @@ Source code for pygenstability.plotting
for optimal_scale_id in selected_scales:
plot_single_partition(
- graph, all_results, optimal_scale_id, edge_color=edge_color, edge_width=edge_width
+ graph,
+ all_results,
+ optimal_scale_id,
+ edge_color=edge_color,
+ edge_width=edge_width,
)
plt.savefig(f"{folder}/scale_{optimal_scale_id}{ext}", bbox_inches="tight")
if show: # pragma: no cover
@@ -469,7 +477,12 @@ Source code for pygenstability.plotting
[docs]def plot_communities(
- graph, all_results, folder="communities", edge_color="0.5", edge_width=0.5, ext=".pdf"
+ graph,
+ all_results,
+ folder="communities",
+ edge_color="0.5",
+ edge_width=0.5,
+ ext=".pdf",
):
"""Plot the community structures at each scale in a folder.
@@ -592,7 +605,7 @@ Source code for pygenstability.plotting
"""Plot stability."""
ax.plot(
scales,
- all_results["block_detection_curve"],
+ all_results["block_nvi"],
"-",
lw=2.0,
c="C4",
@@ -600,7 +613,7 @@ Source code for pygenstability.plotting
)
ax.plot(
scales[all_results["selected_partitions"]],
- all_results["block_detection_curve"][all_results["selected_partitions"]],
+ all_results["block_nvi"][all_results["selected_partitions"]],
"o",
lw=2.0,
c="C4",
@@ -618,9 +631,10 @@ Source code for pygenstability.plotting
ax2.axvline(scale, ls="--", color="C4")
-[docs]def plot_scan_plt(all_results, scale_axis=True, figure_name="scan_results.svg"):
+[docs]def plot_scan_plt(all_results, figsize=(6, 5), scale_axis=True, figure_name="scan_results.svg"):
"""Plot results of pygenstability with matplotlib."""
scales = _get_scales(all_results, scale_axis=scale_axis)
+ plt.figure(figsize=figsize)
gs = gridspec.GridSpec(3, 1, height_ratios=[0.5, 1.0, 0.5])
gs.update(hspace=0)
axes = []
@@ -654,7 +668,7 @@ Source code for pygenstability.plotting
_plot_number_comm(all_results, ax=ax3, scales=scales)
axes.append(ax3)
- if "block_detection_curve" in all_results:
+ if "block_nvi" in all_results:
ax4 = plt.subplot(gs[2, 0])
_plot_optimal_scales(all_results, ax=ax4, scales=scales, ax1=ax1, ax2=ax2)
axes.append(ax4)
diff --git a/_modules/pygenstability/pygenstability.html b/_modules/pygenstability/pygenstability.html
index b6902bf..8a53b64 100644
--- a/_modules/pygenstability/pygenstability.html
+++ b/_modules/pygenstability/pygenstability.html
@@ -341,6 +341,7 @@ Source code for pygenstability.pygenstability
log_scale=True,
scales=None,
n_tries=100,
+ with_all_tries=False,
with_NVI=True,
n_NVI=20,
with_postprocessing=True,
@@ -375,6 +376,8 @@ Source code for pygenstability.pygenstability
log_scale (bool): use linear or log scales for scales
scales (array): custom scale vector, if provided, it will override the other scale arguments
n_tries (int): number of generalized Markov Stability optimisation evaluations
+ with_all_tries (bools): store all partitions with stability values found in different
+ optimisation evaluations
with_NVI (bool): compute NVI(t) between generalized Markov Stability optimisations
at each scale t
n_NVI (int): number of randomly chosen generalized Markov Stability optimisations
@@ -399,10 +402,13 @@ Source code for pygenstability.pygenstability
- 'number_of_communities': number of communities at each scale
- 'stability': value of stability cost function at each scale
- 'community_id': community node labels at each scale
+ - 'all_tries': all community node labels with stability values found in different
+ optimisation evaluations at each scale (included if with_all_tries==True)
- 'NVI': NVI(t) at each scale
- 'ttprime': NVI(t,tprime) matrix
- - 'block_detection_curve': block detection curve (included if with_optimal_scales==True)
+ - 'block_nvi': block NVI curve (included if with_optimal_scales==True)
- 'selected_partitions': selected partitions (included if with_optimal_scales==True)
+
"""
method = _check_method(method)
run_params = _get_params(locals())
@@ -447,6 +453,9 @@ Source code for pygenstability.pygenstability
if with_NVI:
_compute_NVI(communities, all_results, pool, n_partitions=min(n_NVI, n_tries))
+ if with_all_tries:
+ all_results["all_tries"].append(results)
+
save_results(all_results, filename=result_file)
if with_postprocessing:
diff --git a/constructors.html b/constructors.html
index b84bdca..ecc9aec 100644
--- a/constructors.html
+++ b/constructors.html
@@ -282,13 +282,24 @@
class pygenstability.constructors.constructor_continuous_combinatorial(graph, with_spectral_gap=False, exp_comp_mode='spectral', **kwargs)[source]#
Constructor for continuous combinatorial Markov Stability.
-The quality matrix is:
+This implementation follows equation (16) in [1]. The quality matrix is:
-\[F(t) = \Pi\exp(-Lt)\]
+\[F(t) = \Pi\exp(-tL/<d>)\]
-where \(L=D-A\) is the combinatorial Laplacian and \(\Pi=\mathrm{diag}(\pi)\),
+
where \(<d>=(\boldsymbol{1}^T D \boldsymbol{1})/N\) is the average degree,
+\(L=D-A\) is the combinatorial Laplacian and \(\Pi=\mathrm{diag}(\pi)\),
with null model \(v_1=v_2=\pi=\frac{\boldsymbol{1}}{N}\).
+References
+
The constructor calls the prepare method upon initialisation.
- Parameters:
@@ -312,10 +323,10 @@
-
class pygenstability.constructors.constructor_continuous_normalized(graph, with_spectral_gap=False, exp_comp_mode='spectral', **kwargs)[source]#
Constructor for continuous normalized Markov Stability.
-The quality matrix is:
+This implementation follows equation (10) in [1]. The quality matrix is:
-\[F(t) = \Pi\exp(-Lt)\]
+\[F(t) = \Pi\exp(-tL)\]
where \(L=D^{-1}(D-A)\) is the random-walk normalized Laplacian and
\(\Pi=\mathrm{diag}(\pi)\) with null model \(v_1=v_2=\pi=\frac{d}{2M}\).
@@ -342,13 +353,13 @@
class pygenstability.constructors.constructor_signed_modularity(graph, with_spectral_gap=False, exp_comp_mode='spectral', **kwargs)[source]#
Constructor of signed modularity.
-This implementation is equation (18) of [1], where quality is the adjacency matrix and
+
This implementation is equation (18) of [2], where quality is the adjacency matrix and
the null model is the difference between the standard modularity null models based on
positive and negative degree vectors.
References
where \(L=D_{\mathrm{abs}}-A\) is the signed combinatorial Laplacian,
\(D_{\mathrm{abs}}=\mathrm{diag}(d_\mathrm{abs})\) the diagonal matrix of absolute node
strengths \(d_\mathrm{abs}\), and the associated null model is given by
\(v_1=v_2=\boldsymbol{0}\), where \(\boldsymbol{0}\) is the vector of zeros.
+References
+
The constructor calls the prepare method upon initialisation.
- Parameters:
@@ -422,7 +441,8 @@
where \(I\) denotes the identity matrix, \(M(\alpha)\) is the transition matrix of a
random walk with teleportation and damping factor \(0\le \alpha < 1\), and
\(\Pi=\mathrm{diag}(\pi)\) for the associated null model \(v_1=v_2=\pi\) given by the
-eigenvector solving \(\pi M(\alpha) = \pi\), which is related to PageRank.
+eigenvector solving \(\pi M(\alpha) = \pi\), which is related to PageRank. See [1] for
+details.
The transition matrix \(M(\alpha)\) is given by
diff --git a/index.html b/index.html
index 0a954e3..aab4d22 100644
--- a/index.html
+++ b/index.html
@@ -272,7 +272,7 @@ Using the codepygenstability/optimal_scales.py. To reduce noise, e.g., one can increase the parameter values for block_size and window_size. The optimal network partitions can then be plotted given a NetworkX nx_graph.
-results = pgs.identify_optimal_scales(results, block_size=10, window_size=5)
+results = pgs.identify_optimal_scales(results, kernel_size=10, window_size=5)
pgs.plot_optimal_partitions(nx_graph, results)
@@ -301,7 +301,7 @@ Graph-based data clusteringpygenstability.data_clustering.py module. Given a sample-by-feature matrix X, one can apply graph-based data clustering as follows:
clustering = pgs.DataClustering(
- graph_method="cknn",
+ graph_method="cknn-mst",
k=5,
constructor="continuous_normalized")
@@ -313,7 +313,7 @@ Graph-based data clusteringclustering.plot_scan()
-We currently support $k$-Nearest Neighbor (kNN) and Continuous $k$-Nearest Neighbor (CkNN) [10] graph constructions (specified by graph_method) and k refers to the number of neighbours considered in the construction. See documentation for a list of all parameters. All functionalities of PyGenStability including plotting and scale selection are also available for data clustering. For example, given two-dimensional coordinates of the data points one can plot the optimal partitions directly:
+We currently support $k$-Nearest Neighbor (kNN) and Continuous $k$-Nearest Neighbor (CkNN) [10] graph constructions (specified by graph_method) augmented with the minimum spanning tree to guarentee connectivity, where k refers to the number of neighbours considered in the construction. See documentation for a list of all parameters. All functionalities of PyGenStability including plotting and scale selection are also available for data clustering. For example, given two-dimensional coordinates of the data points one can plot the optimal partitions directly:
# plot robust partitions
clustering.plot_robust_partitions(x_coord=x_coord,y_coord=y_coord)
@@ -331,14 +331,16 @@ Contributors
Cite#
Please cite our paper if you use this code in your own work:
-@article{pygenstability,
- author = {Arnaudon, Alexis and Schindler, Dominik J. and Peach, Robert L. and Gosztolai, Adam and Hodges, Maxwell and Schaub, Michael T. and Barahona, Mauricio},
- title = {PyGenStability: Multiscale community detection with generalized Markov Stability},
- publisher = {arXiv},
- year = {2023},
- doi = {10.48550/ARXIV.2303.05385},
- url = {https://arxiv.org/abs/2303.05385}
-}
+@article{pygenstability,
+ author = {Arnaudon, Alexis and Schindler, Dominik J. and Peach, Robert L. and Gosztolai, Adam and Hodges, Maxwell and Schaub, Michael T. and Barahona, Mauricio},
+ title = {Algorithm 1044: PyGenStability, a Multiscale Community Detection Framework with Generalized Markov Stability},
+ journal = {ACM Trans. Math. Softw.},
+ volume = {50},
+ number = {2},
+ pages = {15:1–15:8}
+ year = {2024},
+ doi = {10.1145/3651225}
+}
The original paper for Markov Stability can also be cited as:
@@ -401,7 +403,7 @@ ReferencesReturns:
-‘selected_partitions’ and ‘block_detection_curve’
+‘selected_partitions’ and ‘block_nvi’
- Return type:
result dictionary with two new keys
diff --git a/plotting.html b/plotting.html
index 0a55b9d..024b0a3 100644
--- a/plotting.html
+++ b/plotting.html
@@ -202,12 +202,13 @@
Plotting functions.
-
-pygenstability.plotting.plot_scan(all_results, scale_axis=True, figure_name='scan_results.pdf', use_plotly=False, live=True, plotly_filename='scan_results.html')[source]#
+pygenstability.plotting.plot_scan(all_results, figsize=(6, 5), scale_axis=True, figure_name='scan_results.pdf', use_plotly=False, live=True, plotly_filename='scan_results.html')[source]#
Plot results of pygenstability with matplotlib or plotly.
- Parameters:
all_results (dict) – results of pygenstability scan
figsize (tuple) – matplotlib figure size
scale_axis (bool) – display scale of scale index on scale axis
figure_name (str) – name of matplotlib figure
use_plotly (bool) – use matplotlib or plotly backend
-
-pygenstability.plotting.plot_scan_plt(all_results, scale_axis=True, figure_name='scan_results.svg')[source]#
+pygenstability.plotting.plot_scan_plt(all_results, figsize=(6, 5), scale_axis=True, figure_name='scan_results.svg')[source]#
Plot results of pygenstability with matplotlib.
diff --git a/pygenstability.html b/pygenstability.html
index 6028fff..85790a7 100644
--- a/pygenstability.html
+++ b/pygenstability.html
@@ -211,7 +211,7 @@
the user via the constructor module.
-
-pygenstability.pygenstability.run(graph=None, constructor='linearized', min_scale=-2.0, max_scale=0.5, n_scale=20, log_scale=True, scales=None, n_tries=100, with_NVI=True, n_NVI=20, with_postprocessing=True, with_ttprime=True, with_spectral_gap=False, exp_comp_mode='spectral', result_file='results.pkl', n_workers=4, tqdm_disable=False, with_optimal_scales=True, optimal_scales_kwargs=None, method='louvain', constructor_kwargs=None)[source]#
+pygenstability.pygenstability.run(graph=None, constructor='linearized', min_scale=-2.0, max_scale=0.5, n_scale=20, log_scale=True, scales=None, n_tries=100, with_all_tries=False, with_NVI=True, n_NVI=20, with_postprocessing=True, with_ttprime=True, with_spectral_gap=False, exp_comp_mode='spectral', result_file='results.pkl', n_workers=4, tqdm_disable=False, with_optimal_scales=True, optimal_scales_kwargs=None, method='louvain', constructor_kwargs=None)[source]#
This is the main function to compute graph clustering across scales with Markov Stability.
This function needs a graph object as an adjacency matrix encoded with scipy.csgraph.
The default settings will provide a fast and generic run with linearized Markov Stability,
@@ -232,6 +232,8 @@
log_scale (bool) – use linear or log scales for scales
scales (array) – custom scale vector, if provided, it will override the other scale arguments
n_tries (int) – number of generalized Markov Stability optimisation evaluations
with_all_tries (bools) – store all partitions with stability values found in different
+optimisation evaluations
with_NVI (bool) – compute NVI(t) between generalized Markov Stability optimisations
at each scale t
n_NVI (int) – number of randomly chosen generalized Markov Stability optimisations
@@ -258,9 +260,14 @@
’number_of_communities’: number of communities at each scale
’stability’: value of stability cost function at each scale
’community_id’: community node labels at each scale
+- ’all_tries’: all community node labels with stability values found in different
optimisation evaluations at each scale (included if with_all_tries==True)
+
+’NVI’: NVI(t) at each scale
’ttprime’: NVI(t,tprime) matrix
’block_detection_curve’: block detection curve (included if with_optimal_scales==True)
’block_nvi’: block NVI curve (included if with_optimal_scales==True)
’selected_partitions’: selected partitions (included if with_optimal_scales==True)