mimisbm 0.1.0__tar.gz

mimisbm-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,21 @@
+name: Lint
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    container:
+      image: python:latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install ruff
+        run: pip install ruff
+      - name: Format check
+        run: ruff format mimisbm
+      - name: Lint
+        run: ruff check mimisbm

mimisbm-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,33 @@
+name: Pages
+
+on:
+  workflow_dispatch:
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+    container:
+      image: python:3.13
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Fix git safe directory
+        run: git config --global --add safe.directory '*'
+      - name: Install system dependencies
+        run: apt-get update && apt-get install -y git
+      - name: Install Python dependencies
+        run: |
+          pip install sphinx furo
+          pip install . --extra-index-url https://download.pytorch.org/whl/cpu
+      - name: Build documentation
+        run: sphinx-build -b html docs/source public
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: public
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

mimisbm-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-to-pypi:
+    runs-on: ubuntu-latest
+    container:
+      image: python:3.13
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Fix git safe directory
+        run: git config --global --add safe.directory '*'
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine setuptools-scm
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: python -m twine upload --verbose dist/*

mimisbm-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: mimisbm
+Version: 0.1.0
+Summary: Mixture of Multilayer Integrator Stochastic Block Model
+Author: Félix Laplante
+Project-URL: Source, https://github.com/felixlaplante0/mimisbm
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: fastkmeanspp
+Requires-Dist: scikit-learn
+
+# 🕸️ MimiSBM
+
+**mimisbm** is a Python package implementing the **Mixture of Multilayer Integrator Stochastic Block Model** proposed by the original authors. It jointly groups nodes into clusters and layers into components, providing a unified framework for identifying shared connectivity patterns across multiple network layers.
+
+---
+
+## ✨ Features
+
+- **Multilayer Clustering**: Jointly identifies node communities and layer components in a single probabilistic framework.
+- **Variational EM**: Efficient inference using a Variational Expectation-Maximization (VEM) algorithm for large-scale networks.
+- **Bayesian Framework**: Supports flexible Dirichlet and Beta priors, allowing for robust structure discovery under different sparsity regimes.
+- **Component-wise SBMs**: Groups layers sharing similar block-model structures into distinct mixture components.
+- **scikit-learn API**: Native `BaseEstimator` and `ClusterMixin` integration with a familiar `fit` / `predict` interface.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install mimisbm
+```
+
+## 🔧 Usage
+
+### Example
+
+```python
+import numpy as np
+from mimisbm import MimiSBM
+
+# Generate a synthetic multilayer adjacency tensor (20 nodes, 5 layers)
+np.random.seed(42)
+N, V = 20, 5
+X = np.random.randint(0, 2, size=(N, N, V))
+
+# Ensure the adjacency matrices are symmetric (undirected)
+for v in range(V):
+    X[..., v] = np.tril(X[..., v], -1) + np.tril(X[..., v], -1).T
+
+# Initialize the model with 3 node clusters and 2 layer components
+model = MimiSBM(n_clusters=3, n_components=2, random_state=42)
+
+# Fit the model to the multilayer network
+model.fit(X)
+
+# Predict node cluster and layer component assignments
+node_labels, layer_labels = model.predict()
+
+print(f"Node clusters: {node_labels}")
+print(f"Layer components: {layer_labels}")
+print(f"Final ELBO: {model.elbo_:.2f}")
+```
+
+---
+
+## 📖 Learn More
+
+For tutorials and detailed API reference, visit the official site:  
+👉 [mimisbm's documentation](https://felixlaplante0.github.io/mimisbm)
+
+### 📚 Citation
+
+If you use MimiSBM in your research, please cite the original authors' paper:
+
+```bibtex
+@article{de2024mixture,
+  title={Mixture of multilayer stochastic block models for multiview clustering},
+  author={De Santiago, Kylliann and Szafranski, Marie and Ambroise, Christophe},
+  journal={arXiv preprint arXiv:2401.04682},
+  year={2024}
+}
+```
+
+For more details, see the corresponding Preprint: https://arxiv.org/abs/2401.04682

mimisbm-0.1.0/README.md

@@ -0,0 +1,74 @@
+# 🕸️ MimiSBM
+
+**mimisbm** is a Python package implementing the **Mixture of Multilayer Integrator Stochastic Block Model** proposed by the original authors. It jointly groups nodes into clusters and layers into components, providing a unified framework for identifying shared connectivity patterns across multiple network layers.
+
+---
+
+## ✨ Features
+
+- **Multilayer Clustering**: Jointly identifies node communities and layer components in a single probabilistic framework.
+- **Variational EM**: Efficient inference using a Variational Expectation-Maximization (VEM) algorithm for large-scale networks.
+- **Bayesian Framework**: Supports flexible Dirichlet and Beta priors, allowing for robust structure discovery under different sparsity regimes.
+- **Component-wise SBMs**: Groups layers sharing similar block-model structures into distinct mixture components.
+- **scikit-learn API**: Native `BaseEstimator` and `ClusterMixin` integration with a familiar `fit` / `predict` interface.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install mimisbm
+```
+
+## 🔧 Usage
+
+### Example
+
+```python
+import numpy as np
+from mimisbm import MimiSBM
+
+# Generate a synthetic multilayer adjacency tensor (20 nodes, 5 layers)
+np.random.seed(42)
+N, V = 20, 5
+X = np.random.randint(0, 2, size=(N, N, V))
+
+# Ensure the adjacency matrices are symmetric (undirected)
+for v in range(V):
+    X[..., v] = np.tril(X[..., v], -1) + np.tril(X[..., v], -1).T
+
+# Initialize the model with 3 node clusters and 2 layer components
+model = MimiSBM(n_clusters=3, n_components=2, random_state=42)
+
+# Fit the model to the multilayer network
+model.fit(X)
+
+# Predict node cluster and layer component assignments
+node_labels, layer_labels = model.predict()
+
+print(f"Node clusters: {node_labels}")
+print(f"Layer components: {layer_labels}")
+print(f"Final ELBO: {model.elbo_:.2f}")
+```
+
+---
+
+## 📖 Learn More
+
+For tutorials and detailed API reference, visit the official site:  
+👉 [mimisbm's documentation](https://felixlaplante0.github.io/mimisbm)
+
+### 📚 Citation
+
+If you use MimiSBM in your research, please cite the original authors' paper:
+
+```bibtex
+@article{de2024mixture,
+  title={Mixture of multilayer stochastic block models for multiview clustering},
+  author={De Santiago, Kylliann and Szafranski, Marie and Ambroise, Christophe},
+  journal={arXiv preprint arXiv:2401.04682},
+  year={2024}
+}
+```
+
+For more details, see the corresponding Preprint: https://arxiv.org/abs/2401.04682

mimisbm-0.1.0/demo.py

@@ -0,0 +1,41 @@
+import numpy as np
+from sklearn.metrics import adjusted_rand_score
+
+from mimisbm._model import MimiSBM
+
+
+def gen_data(N=100, V=20, K=2, Q=2):
+    z = np.random.randint(0, K, N)
+    w = np.random.randint(0, Q, V)
+
+    # Connectivity for component 0 (assortative) and component 1 (disassortative)
+    alphas = np.zeros((K, K, Q))
+    alphas[:, :, 0] = [[0.8, 0.1], [0.1, 0.8]]
+    alphas[:, :, 1] = [[0.1, 0.8], [0.8, 0.1]]
+
+    A = np.zeros((N, N, V))
+    for v in range(V):
+        p_mat = alphas[np.ix_(z, z, [w[v]])].squeeze()
+        # Generate undirected edges without self-loops
+        tri_mask = np.random.rand(N, N) < p_mat
+        A[:, :, v] = np.tril(tri_mask, -1).astype(float)
+        A[:, :, v] += A[:, :, v].T
+
+    return A, z, w
+
+np.random.seed(42)
+
+print("Generating synthetic data...")
+A, true_z, true_w = gen_data()
+
+print("Fitting MimiSBM...")
+model = MimiSBM(n_clusters=2, n_subclusters=2, random_state=42).fit(A)
+pred_z, pred_w = model.predict()
+
+# 3. Evaluate
+node_ari = adjusted_rand_score(true_z, pred_z)
+view_ari = adjusted_rand_score(true_w, pred_w)
+
+print("\nEvaluation Results:")
+print(f"Node ARI: {node_ari:.4f}")
+print(f"View ARI: {view_ari:.4f}")

mimisbm-0.1.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

mimisbm-0.1.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

mimisbm-0.1.0/docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+
+   .. automethod:: __init__

mimisbm-0.1.0/docs/source/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../"))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "mimisbm"
+release = ""
+version = ""
+copyright = "2026, Félix Laplante"
+author = "Félix Laplante"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_typehints_format = "short"
+autodoc_inherit_docstrings = True
+autosummary_generate = True
+add_module_names = False
+napoleon_use_ivar = True
+napoleon_attr_annotations = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]

mimisbm-0.1.0/docs/source/index.rst

@@ -0,0 +1,78 @@
+MimiSBM
+=======
+
+**mimisbm** is a Python package implementing the **Mixture of Multilayer Integrator Stochastic Block Model** proposed by the original authors. It jointly groups nodes into clusters and layers into components, providing a unified framework for identifying shared connectivity patterns across multiple network layers.
+
+Features
+--------
+
+- **Multilayer Clustering**: Jointly identifies node communities and layer components in a single probabilistic framework.
+- **Variational EM**: Efficient inference using a Variational Expectation-Maximization (VEM) algorithm for large-scale networks.
+- **Bayesian Framework**: Supports flexible Dirichlet and Beta priors, allowing for robust structure discovery under different sparsity regimes.
+- **Component-wise SBMs**: Groups layers sharing similar block-model structures into distinct mixture components.
+- **scikit-learn API**: Native ``BaseEstimator`` and ``ClusterMixin`` integration with a familiar ``fit`` / ``predict`` interface.
+
+Installation
+------------
+
+You can install the package via pip:
+
+.. code-block:: bash
+
+   pip install mimisbm
+
+Usage
+-----
+
+Example:
+
+.. code-block:: python
+
+    import numpy as np
+    from mimisbm import MimiSBM
+
+    # Generate a synthetic multilayer adjacency tensor (20 nodes, 5 layers)
+    np.random.seed(42)
+    N, V = 20, 5
+    X = np.random.randint(0, 2, size=(N, N, V))
+
+    # Ensure the adjacency matrices are symmetric (undirected)
+    for v in range(V):
+        X[..., v] = np.tril(X[..., v], -1) + np.tril(X[..., v], -1).T
+
+    # Initialize the model with 3 node clusters and 2 layer components
+    model = MimiSBM(n_clusters=3, n_components=2, random_state=42)
+
+    # Fit the model to the multilayer network
+    model.fit(X)
+
+    # Predict node cluster and layer component assignments
+    node_labels, layer_labels = model.predict()
+
+    print(f"Node clusters: {node_labels}")
+    print(f"Layer components: {layer_labels}")
+    print(f"Final ELBO: {model.elbo_:.2f}")
+
+Citation
+--------
+
+If you use MimiSBM in your research, please cite the original authors' paper:
+
+.. code-block:: bibtex
+
+    @article{de2024mixture,
+      title={Mixture of multilayer stochastic block models for multiview clustering},
+      author={De Santiago, Kylliann and Szafranski, Marie and Ambroise, Christophe},
+      journal={arXiv preprint arXiv:2401.04682},
+      year={2024}
+    }
+
+For more details, see the corresponding Preprint: https://arxiv.org/abs/2401.04682
+
+API Reference
+-------------
+
+.. autoclass:: mimisbm.MimiSBM
+   :members:
+   :undoc-members:
+   :show-inheritance:

mimisbm-0.1.0/mimisbm/__init__.py

@@ -0,0 +1,5 @@
+"""Mixture of Multilayer Integrator Stochastic Block Model."""
+
+from ._model import MimiSBM
+
+__all__ = ["MimiSBM"]

mimisbm-0.1.0/mimisbm/_model.py

@@ -0,0 +1,444 @@
+from numbers import Integral, Real
+from typing import Self
+
+import numpy as np
+from fastkmeanspp import KMeans  # type: ignore
+from scipy.special import betaln, digamma, entr, gammaln, softmax  # type: ignore
+from sklearn.base import BaseEstimator, ClusterMixin  # type: ignore
+from sklearn.utils._param_validation import (  # type: ignore
+    Interval,  # type: ignore
+    StrOptions,  # type: ignore
+    validate_params,  # type: ignore
+)
+from sklearn.utils.validation import check_is_fitted, validate_data  # type: ignore
+
+
+class MimiSBM(ClusterMixin, BaseEstimator):
+    r"""Mixture of Multilayer Integrator Stochastic Block Model (MimiSBM).
+
+    The MimiSBM is a generative model for multilayer networks that identifies mesoscale
+    structures by grouping nodes into clusters and layers into components.
+
+    Each component represents a distinct Stochastic Block Model (SBM) shared by a subset
+    of layers. This model uses a Variational Expectation-Maximization (VEM) algorithm to
+    perform inference and estimation of the posterior distributions.
+
+    Model settings:
+        - `n_clusters`: Number of clusters for the nodes.
+        - `n_components`: Number of mixture components for the layers.
+
+    Prior settings:
+        - `clusters_prior`: Dirichlet prior for the node cluster mixing proportions.
+        - `components_prior`: Dirichlet prior for the layer component mixing
+          proportions.
+        - `adjacency_prior`: Beta prior for the edge probabilities within and
+          between clusters for each component.
+
+    EM settings:
+        - `max_iter`: Maximum number of iterations for the VEM algorithm.
+        - `tol`: Convergence tolerance based on the Evidence Lower Bound (ELBO).
+        - `warm_start`: If True, reuse the responsibilities from the previous fit
+          as initialization.
+
+    Attributes:
+        n_clusters (int): Number of node clusters.
+        n_components (int): Number of layer components.
+        clusters_prior (np.ndarray): Prior parameters for node clusters.
+        components_prior (np.ndarray): Prior parameters for layer components.
+        adjacency_prior (np.ndarray): Prior parameters for edge connections.
+        max_iter (int): Maximum number of iterations for the EM algorithm.
+        tol (float): Tolerance to declare convergence based on the ELBO.
+        warm_start (bool): Whether to reuse the solution of the previous call
+            to fit as initialization.
+        random_state (int | None): Random state for initialization.
+        cluster_responsibilities_ (np.ndarray): Posterior probabilities of node cluster
+            assignments (N, K).
+        component_responsibilities_ (np.ndarray): Posterior probabilities of layer
+            component assignments (V, Q).
+        cluster_posterior_ (np.ndarray): Dirichlet posterior parameters for clusters.
+        component_posterior_ (np.ndarray): Dirichlet posterior parameters for
+            components.
+        adjacency_posterior_ (np.ndarray): Beta posterior parameters for edge
+            connections (2, K, K, Q).
+        elbo_ (float): Evidence Lower Bound of the fitted model.
+        converged_ (bool): True if the algorithm converged, False otherwise.
+
+    Examples:
+        >>> from mimisbm import MimiSBM
+        >>> import numpy as np
+        >>> X = np.random.randint(0, 2, size=(10, 10, 5))
+        >>> model = MimiSBM(n_clusters=2, n_components=2)
+        >>> model.fit(X)
+        >>> node_labels, layer_labels = model.predict()
+    """
+
+    n_clusters: int
+    n_components: int
+    clusters_prior: np.ndarray
+    components_prior: np.ndarray
+    adjacency_prior: np.ndarray
+    max_iter: int
+    tol: float
+    warm_start: bool
+    random_state: int | None
+    cluster_responsibilities_: np.ndarray
+    component_responsibilities_: np.ndarray
+    cluster_posterior_: np.ndarray
+    component_posterior_: np.ndarray
+    adjacency_posterior_: np.ndarray
+    elbo_: float
+    converged_: bool
+
+    @validate_params(
+        {
+            "n_clusters": [Interval(Integral, 1, None, closed="left")],
+            "n_components": [Interval(Integral, 1, None, closed="left")],
+            "clusters_prior": [StrOptions({"jeffreys", "uniform"}), np.ndarray],
+            "components_prior": [StrOptions({"jeffreys", "uniform"}), np.ndarray],
+            "adjacency_prior": [StrOptions({"jeffreys", "uniform"}), np.ndarray],
+            "max_iter": [Interval(Integral, 1, None, closed="left")],
+            "tol": [Interval(Real, 0, None, closed="left")],
+        },
+        prefer_skip_nested_validation=True,
+    )
+    def __init__(
+        self,
+        n_clusters: int = 2,
+        n_components: int = 2,
+        *,
+        clusters_prior: np.ndarray | str = "jeffreys",
+        components_prior: np.ndarray | str = "jeffreys",
+        adjacency_prior: np.ndarray | str = "jeffreys",
+        max_iter: int = 100,
+        tol: float = 1e-4,
+        warm_start: bool = False,
+        random_state: int | None = None,
+    ):
+        r"""Initializes the MimiSBM model with specified design and priors.
+
+        Constructs a mixture of multilayer SBMs with user-defined priors and
+        EM settings. Provides default settings for Bayesian inference and
+        convergence criteria.
+
+        Args:
+            n_clusters (int, optional): Number of clusters for the nodes.
+                Defaults to 2.
+            n_components (int, optional): Number of mixture components for the layers.
+                Defaults to 2.
+            clusters_prior (np.ndarray | str, optional): Dirichlet prior for node
+                clusters. Can be "jeffreys" (0.5), "uniform" (1.0), or a custom array.
+                Defaults to "jeffreys".
+            components_prior (np.ndarray | str, optional): Dirichlet prior for layer
+                components. Defaults to "jeffreys".
+            adjacency_prior (np.ndarray | str, optional): Beta prior for edge
+                probabilities. Defaults to "jeffreys".
+            max_iter (int, optional): Maximum number of VEM iterations. Defaults to 100.
+            tol (float, optional): Convergence tolerance for ELBO. Defaults to 1e-4.
+            warm_start (bool, optional): Whether to reuse responsibilities from a
+                previous fit. Defaults to False.
+            random_state (int | None, optional): Seed for the KMeans initialization.
+                Defaults to None.
+        """
+        self.n_clusters = n_clusters
+        self.n_components = n_components
+        self.clusters_prior = self._init_prior(clusters_prior, n_clusters)
+        self.components_prior = self._init_prior(components_prior, self.n_components)
+        self.adjacency_prior = self._init_prior(adjacency_prior, 2)
+        self.max_iter = max_iter
+        self.tol = tol
+        self.warm_start = warm_start
+        self.random_state = random_state
+
+    @staticmethod
+    def _init_prior(prior: np.ndarray | str, d: int) -> np.ndarray:
+        r"""Initializes the prior parameters for a given dimension.
+
+        Args:
+            prior (np.ndarray | str): The prior specification.
+            d (int): The dimension of the prior vector.
+
+        Returns:
+            np.ndarray: The initialized prior parameters.
+
+        Raises:
+            ValueError: If the provided prior array has an incorrect length.
+        """
+        if prior == "jeffreys":
+            return np.full((d,), 0.5)
+        if prior == "uniform":
+            return np.full((d,), 1.0)
+
+        prior = prior.reshape(-1)
+        if len(prior) != d:
+            raise ValueError(f"Prior must have {d} elements, got {len(prior)}")
+        return prior
+
+    def _init_responsibilities(
+        self, X: np.ndarray, n_clusters: int, axis: tuple[int, ...]
+    ) -> np.ndarray:
+        r"""Initializes responsibilities using KMeans on aggregated adjacency data.
+
+        Args:
+            X (np.ndarray): The multilayer adjacency tensor.
+            n_clusters (int): Number of clusters/components to initialize.
+            axis (tuple[int, ...]): Axis over which to aggregate the tensor.
+
+        Returns:
+            np.ndarray: Initialized responsibilities.
+        """
+        X_agg = X.sum(axis=axis)
+        X_agg = X_agg.reshape(X_agg.shape[0], -1)
+
+        labels = KMeans(
+            n_clusters=n_clusters, random_state=self.random_state
+        ).fit_predict(X_agg)
+
+        responsibilities = np.zeros((labels.shape[0], n_clusters))
+        responsibilities[np.arange(labels.shape[0]), labels] = 1
+        return responsibilities
+
+    def _elbo(self) -> float:
+        r"""Computes the Evidence Lower Bound (ELBO) for the current state.
+
+        The ELBO is used to monitor convergence and as a surrogate for the
+        log-likelihood in the Variational EM algorithm.
+
+        Returns:
+            float: The computed ELBO value.
+        """
+        cluster_entropy = entr(self.cluster_responsibilities_).sum()
+        component_entropy = entr(self.component_responsibilities_).sum()
+
+        cluster_evidence = (
+            gammaln(self.cluster_posterior_).sum()
+            - gammaln(self.cluster_posterior_.sum())
+            - gammaln(self.clusters_prior).sum()
+            + gammaln(self.clusters_prior.sum())
+        )
+
+        component_evidence = (
+            gammaln(self.component_posterior_).sum()
+            - gammaln(self.component_posterior_.sum())
+            - gammaln(self.components_prior).sum()
+            + gammaln(self.components_prior.sum())
+        )
+
+        log_adjacency_posterior = betaln(
+            self.adjacency_posterior_[0], self.adjacency_posterior_[1]
+        )
+        log_adjacency_prior = betaln(self.adjacency_prior[0], self.adjacency_prior[1])
+
+        # Sum over i < j
+        rows, cols = np.tril_indices(self.n_clusters)
+        adjacency_evidence = (
+            log_adjacency_posterior[rows, cols, :] - log_adjacency_prior
+        ).sum()
+
+        evidence = cluster_evidence + component_evidence + adjacency_evidence
+        entropy = cluster_entropy + component_entropy
+
+        return evidence + entropy
+
+    def _m_step(self, X: np.ndarray, X_non: np.ndarray):
+        r"""Performs the M-step of the Variational EM algorithm.
+
+        Updates the posterior parameters of the priors based on the current
+        responsibilities.
+
+        Args:
+            X (np.ndarray): The multilayer adjacency tensor.
+            X_non (np.ndarray): The complement of the adjacency tensor.
+        """
+        self.cluster_posterior_ = (
+            self.clusters_prior + self.cluster_responsibilities_.sum(axis=0)
+        )
+        self.component_posterior_ = (
+            self.components_prior + self.component_responsibilities_.sum(axis=0)
+        )
+
+        weighted_edges = X @ self.component_responsibilities_
+        weighted_non_edges = X_non @ self.component_responsibilities_
+
+        expected_edges = (
+            self.cluster_responsibilities_.T
+            @ weighted_edges.swapaxes(0, 2)
+            @ self.cluster_responsibilities_
+        ).swapaxes(0, 2)
+        expected_non_edges = (
+            self.cluster_responsibilities_.T
+            @ weighted_non_edges.swapaxes(0, 2)
+            @ self.cluster_responsibilities_
+        ).swapaxes(0, 2)
+
+        # Sum over i < j
+        rows, cols = np.diag_indices(self.n_clusters)
+        expected_edges[rows, cols, :] *= 0.5
+        expected_non_edges[rows, cols, :] *= 0.5
+
+        self.adjacency_posterior_ = np.stack(
+            [
+                expected_edges + self.adjacency_prior[0],
+                expected_non_edges + self.adjacency_prior[1],
+            ]
+        )
+
+    def _e_step(self, X: np.ndarray, X_non: np.ndarray):
+        r"""Performs the E-step of the Variational EM algorithm.
+
+        Updates the responsibilities for node clusters and layer components given the
+        current posterior parameters.
+
+        Args:
+            X (np.ndarray): The multilayer adjacency tensor.
+            X_non (np.ndarray): The complement of the adjacency tensor.
+        """
+        digamma_adjacency_posterior = digamma(self.adjacency_posterior_.sum(axis=0))
+        log_edges = digamma(self.adjacency_posterior_[0]) - digamma_adjacency_posterior
+        log_non_edges = (
+            digamma(self.adjacency_posterior_[1]) - digamma_adjacency_posterior
+        )
+
+        expected_component_edges = (
+            self.cluster_responsibilities_
+            @ log_edges.swapaxes(0, 2)
+            @ self.cluster_responsibilities_.T
+        ).swapaxes(0, 2)
+        expected_component_non_edges = (
+            self.cluster_responsibilities_
+            @ log_non_edges.swapaxes(0, 2)
+            @ self.cluster_responsibilities_.T
+        ).swapaxes(0, 2)
+
+        # Sum over i < j
+        component_posterior_evidence = digamma(self.component_posterior_) - digamma(
+            self.component_posterior_.sum()
+        )
+        component_edges_evidence = 0.5 * np.tensordot(
+            X, expected_component_edges, axes=([0, 1], [0, 1])
+        )
+        component_edges_evidence = np.nan_to_num(component_edges_evidence)
+        component_non_edges_evidence = 0.5 * np.tensordot(
+            X_non, expected_component_non_edges, axes=([0, 1], [0, 1])
+        )
+        component_non_edges_evidence = np.nan_to_num(component_non_edges_evidence)
+        self.component_responsibilities_ = softmax(
+            component_posterior_evidence
+            + component_edges_evidence
+            + component_non_edges_evidence,
+            axis=1,
+        )
+
+        # Sum over i != j
+        expected_cluster_edges = np.tensordot(
+            self.component_responsibilities_, log_edges, axes=([1], [2])
+        )
+        expected_cluster_non_edges = np.tensordot(
+            self.component_responsibilities_, log_non_edges, axes=([1], [2])
+        )
+        cluster_posterior_evidence = digamma(self.cluster_posterior_) - digamma(
+            self.cluster_posterior_.sum()
+        )
+
+        cluster_edges_evidence = np.tensordot(
+            X,
+            self.cluster_responsibilities_ @ expected_cluster_edges.swapaxes(1, 2),
+            axes=([1, 2], [1, 0]),
+        )
+        cluster_non_edges_evidence = np.tensordot(
+            X_non,
+            self.cluster_responsibilities_ @ expected_cluster_non_edges.swapaxes(1, 2),
+            axes=([1, 2], [1, 0]),
+        )
+
+        self.cluster_responsibilities_ = softmax(
+            cluster_posterior_evidence
+            + cluster_edges_evidence
+            + cluster_non_edges_evidence,
+            axis=1,
+        )
+
+    def _validate(self, X: np.typing.ArrayLike) -> tuple[np.ndarray, np.ndarray]:
+        r"""Validates the input data and ensures it is in the correct format.
+
+        Checks that the input is a 3D numpy array with appropriate dimension for a
+        multilayer adjacency tensor.
+
+        Args:
+            X (np.typing.ArrayLike): The input data to validate.
+
+        Raises:
+            ValueError: If the input data is not a 3D array.
+
+        Returns:
+            tuple[np.ndarray, np.ndarray]: A tuple containing the validated adjacency
+                tensor and its complement.
+        """
+        X = np.asarray(validate_data(self, X, allow_nd=True, dtype=np.bool))  # type: ignore
+        if X.ndim != 3:  # noqa: PLR2004
+            raise ValueError(f"Input data must be a 3D array, got {X.ndim}D array")
+
+        X |= X.swapaxes(0, 1)
+        rows, cols = np.diag_indices(X.shape[0])
+        X[rows, cols, :] = 0
+        X_non = 1 - X
+        X_non[rows, cols, :] = 0
+
+        return X, X_non
+
+    @validate_params({"X": ["array-like"]}, prefer_skip_nested_validation=True)
+    def fit(self, X: np.typing.ArrayLike) -> Self:
+        r"""Fits the MimiSBM model to the multilayer adjacency tensor.
+
+        Initializes the model responsibilities and iteratively updates them using the
+        VEM algorithm. The process continues until the ELBO converges or the maximum
+        number of iterations is reached.
+
+        Args:
+            X (np.typing.ArrayLike): A 3D numpy array-like representing the multilayer
+                adjacency tensor of shape (N, N, V).
+
+        Returns:
+            Self: The fitted model instance.
+        """
+        X, X_non = self._validate(X)  # type: ignore
+
+        if not (self.warm_start and hasattr(self, "converged_")):
+            self.cluster_responsibilities_ = self._init_responsibilities(
+                X, self.n_clusters, (2,)
+            )
+            self.component_responsibilities_ = self._init_responsibilities(
+                X, self.n_components, (0, 1)
+            )
+
+        old_elbo = -np.inf
+        for _ in range(self.max_iter):
+            self._m_step(X, X_non)
+            self._e_step(X, X_non)
+
+            self.elbo_ = self._elbo()
+            if abs(self.elbo_ - old_elbo) < self.tol:
+                self.converged_ = True
+                return self
+            old_elbo = self.elbo_
+
+        self.converged_ = False
+
+        return self
+
+    def predict(self) -> tuple[np.ndarray, np.ndarray]:
+        r"""Predicts the node clusters and layer components labels.
+
+        Assigns each node and each layer to the cluster/component with the highest
+        probability.
+
+        Returns:
+            tuple[np.ndarray, np.ndarray]: A tuple containing:
+                - node_labels (np.ndarray): Predicted cluster for each node (N,).
+                - layer_labels (np.ndarray): Predicted component for each layer (V,).
+        """
+        check_is_fitted(
+            self, ["cluster_responsibilities_", "component_responsibilities_"]
+        )
+        return self.cluster_responsibilities_.argmax(
+            axis=1
+        ), self.component_responsibilities_.argmax(axis=1)

mimisbm-0.1.0/mimisbm.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: mimisbm
+Version: 0.1.0
+Summary: Mixture of Multilayer Integrator Stochastic Block Model
+Author: Félix Laplante
+Project-URL: Source, https://github.com/felixlaplante0/mimisbm
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: fastkmeanspp
+Requires-Dist: scikit-learn
+
+# 🕸️ MimiSBM
+
+**mimisbm** is a Python package implementing the **Mixture of Multilayer Integrator Stochastic Block Model** proposed by the original authors. It jointly groups nodes into clusters and layers into components, providing a unified framework for identifying shared connectivity patterns across multiple network layers.
+
+---
+
+## ✨ Features
+
+- **Multilayer Clustering**: Jointly identifies node communities and layer components in a single probabilistic framework.
+- **Variational EM**: Efficient inference using a Variational Expectation-Maximization (VEM) algorithm for large-scale networks.
+- **Bayesian Framework**: Supports flexible Dirichlet and Beta priors, allowing for robust structure discovery under different sparsity regimes.
+- **Component-wise SBMs**: Groups layers sharing similar block-model structures into distinct mixture components.
+- **scikit-learn API**: Native `BaseEstimator` and `ClusterMixin` integration with a familiar `fit` / `predict` interface.
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install mimisbm
+```
+
+## 🔧 Usage
+
+### Example
+
+```python
+import numpy as np
+from mimisbm import MimiSBM
+
+# Generate a synthetic multilayer adjacency tensor (20 nodes, 5 layers)
+np.random.seed(42)
+N, V = 20, 5
+X = np.random.randint(0, 2, size=(N, N, V))
+
+# Ensure the adjacency matrices are symmetric (undirected)
+for v in range(V):
+    X[..., v] = np.tril(X[..., v], -1) + np.tril(X[..., v], -1).T
+
+# Initialize the model with 3 node clusters and 2 layer components
+model = MimiSBM(n_clusters=3, n_components=2, random_state=42)
+
+# Fit the model to the multilayer network
+model.fit(X)
+
+# Predict node cluster and layer component assignments
+node_labels, layer_labels = model.predict()
+
+print(f"Node clusters: {node_labels}")
+print(f"Layer components: {layer_labels}")
+print(f"Final ELBO: {model.elbo_:.2f}")
+```
+
+---
+
+## 📖 Learn More
+
+For tutorials and detailed API reference, visit the official site:  
+👉 [mimisbm's documentation](https://felixlaplante0.github.io/mimisbm)
+
+### 📚 Citation
+
+If you use MimiSBM in your research, please cite the original authors' paper:
+
+```bibtex
+@article{de2024mixture,
+  title={Mixture of multilayer stochastic block models for multiview clustering},
+  author={De Santiago, Kylliann and Szafranski, Marie and Ambroise, Christophe},
+  journal={arXiv preprint arXiv:2401.04682},
+  year={2024}
+}
+```
+
+For more details, see the corresponding Preprint: https://arxiv.org/abs/2401.04682

mimisbm-0.1.0/mimisbm.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+demo.py
+pyproject.toml
+.github/workflows/lint.yml
+.github/workflows/pages.yml
+.github/workflows/publish.yml
+docs/Makefile
+docs/make.bat
+docs/source/conf.py
+docs/source/index.rst
+docs/source/_static/.gitkeep
+docs/source/_templates/autosummary/class.rst
+mimisbm/__init__.py
+mimisbm/_model.py
+mimisbm.egg-info/PKG-INFO
+mimisbm.egg-info/SOURCES.txt
+mimisbm.egg-info/dependency_links.txt
+mimisbm.egg-info/requires.txt
+mimisbm.egg-info/top_level.txt

mimisbm-0.1.0/mimisbm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mimisbm-0.1.0/mimisbm.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+scipy
+fastkmeanspp
+scikit-learn

mimisbm-0.1.0/mimisbm.egg-info/top_level.txt

@@ -0,0 +1 @@
+mimisbm

mimisbm-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "mimisbm"
+description = "Mixture of Multilayer Integrator Stochastic Block Model"
+readme = "README.md"
+urls = { "Source" = "https://github.com/felixlaplante0/mimisbm" }
+authors = [{ name = "Félix Laplante" }]
+requires-python = ">=3.10"
+dependencies = ["numpy", "scipy", "fastkmeanspp", "scikit-learn"]
+dynamic = ["version"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+
+[build-system]
+requires = ["setuptools>=42", "setuptools-scm[toml]>=6.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["mimisbm"]
+
+[tool.setuptools_scm]
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+
+[tool.setuptools.package-data]
+mypkg = ["py.typed"]
+
+[tool.ruff]
+lint.select = [
+    "D",   # pydocstyle (docstring conventions)
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "S",   # flake8-bandit (security)
+    "T20", # flake8-print
+    "PT",  # flake8-pytest-style
+    "Q",   # flake8-quotes
+    "RET", # flake8-return
+    "SIM", # flake8-simplify
+    "ARG", # flake8-unused-arguments
+    "ERA", # eradicate (commented code)
+    "PL",  # Pylint
+    "RUF", # Ruff-specific rules
+]
+lint.ignore = ["D417", "PLR0913"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

mimisbm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+