dimc-toolkit 1.0.0__tar.gz

dimc_toolkit-1.0.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: dimc-toolkit
+Version: 1.0.0
+Summary: Deep Incomplete Multi-view Clustering (DIMC): A Python implementation of graph-regularized deep semantic mapping for clustering incomplete multi-view data.
+Author: Suchibrata Patra
+Project-URL: Homepage, https://github.com/suchibrata/dimc-toolkit
+Project-URL: Repository, https://github.com/suchibrata/dimc-toolkit
+Project-URL: Documentation, https://github.com/suchibrata/dimc-toolkit
+Project-URL: Issues, https://github.com/suchibrata/dimc-toolkit/issues
+Keywords: deep learning,multi-view clustering,incomplete multi-view clustering,deep semantic mapping,graph regularization,representation learning,matrix factorization,unsupervised learning,machine learning,pytorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: torch>=2.0
+Requires-Dist: tqdm>=4.66
+Dynamic: license-file

dimc_toolkit-1.0.0/dimc/__init__.py

@@ -0,0 +1,13 @@
+from dimc.fit import fit, run_dimc, sweep_alpha, train_dimc
+from dimc.config import DEFAULT_ALPHA_CANDIDATES, DEFAULT_SETTINGS
+
+__all__ = [
+    "fit",
+    "run_dimc",
+    "sweep_alpha",
+    "train_dimc",
+    "DEFAULT_SETTINGS",
+    "DEFAULT_ALPHA_CANDIDATES",
+]
+
+

dimc_toolkit-1.0.0/dimc/algorithms/__init__.py

@@ -0,0 +1,23 @@
+"""
+Multiplicative update rules for the DIMC alternating optimization
+(Algorithm 1, lines 4-9 / Eqs. 13, 14, 16, and the graph-regularization
+loss of Eq. 3/6).
+
+Re-exports the individual update functions so callers can do either::
+
+    from dimc.algorithms import update_PC, update_PI, update_U
+    from dimc.algorithms.update_graph import update_PC
+"""
+
+from dimc.algorithms.update_graph import update_PC, graph_regularization_loss
+from dimc.algorithms.update_weights import update_PI
+from dimc.algorithms.update_W import update_U
+from dimc.algorithms.update_H import finetune_view_network
+
+__all__ = [
+    "update_PC",
+    "graph_regularization_loss",
+    "update_PI",
+    "update_U",
+    "finetune_view_network",
+]

dimc_toolkit-1.0.0/dimc/algorithms/update_H.py

@@ -0,0 +1,50 @@
+"""
+View-specific DNN fine-tuning step, producing the updated H(v) (Eqs. 17-23).
+
+Eq. (17): min_{W_v,b_v} || H(v) - U(v) P(v) ||_F^2
+This is exactly reconstruction of the NMF target U(v)P(v) by the DNN
+output H(v), so a plain MSE gradient step implements Eqs. (18)-(23)
+(backprop derives the same gradient as Eq. 20-23 automatically).
+"""
+
+import torch
+import torch.nn as nn
+
+
+def finetune_view_network(
+    encoder: nn.Sequential,
+    X: torch.Tensor,
+    target: torch.Tensor,
+    learning_rate: float = 1e-2,
+) -> float:
+    """
+    One gradient-descent step of Eq. (17) via backpropagation (Eqs. 18-23).
+
+    Parameters
+    ----------
+    encoder : torch.nn.Sequential
+        The view-specific encoder network, modified in place.
+    X : torch.Tensor
+        Input data for the samples this view observes, shape
+        ``(n_obs, input_dim)``.
+    target : torch.Tensor
+        Reconstruction target ``U(v) P(v)``, shape ``(n_obs, latent_dim)``.
+    learning_rate : float, default=1e-2
+        Plain gradient-descent step size.
+
+    Returns
+    -------
+    float
+        The MSE loss value before the gradient step is applied.
+    """
+    loss_fn = nn.MSELoss()
+    H = encoder(X)
+    loss = loss_fn(H, target)
+
+    encoder.zero_grad()
+    loss.backward()
+    with torch.no_grad():
+        for p in encoder.parameters():
+            p -= learning_rate * p.grad
+
+    return loss.item()

dimc_toolkit-1.0.0/dimc/algorithms/update_W.py

@@ -0,0 +1,42 @@
+"""
+Multiplicative update rule for U(v), the per-view NMF basis matrix (Eq. 16).
+
+Named ``update_W`` to match the requested package layout; note that in the
+paper's own notation this updates U(v) (the basis matrix), not the graph
+affinity matrix W(v) -- that construction lives in ``dimc.graph``.
+"""
+
+import numpy as np
+
+from dimc.config import EPS
+
+
+def update_U(
+    U: np.ndarray,
+    H_full: np.ndarray,
+    P_full: np.ndarray,
+) -> np.ndarray:
+    """
+    Eq. (16):
+      U(v)_ij <- U(v)_ij * (H(v) P(v)^T)_ij / (U(v) P(v) P(v)^T)_ij
+    where H(v) = [H(v)_C, H(v)_I] and P(v) = [PC, P(v)_I] (Eq. 15).
+
+    Parameters
+    ----------
+    U : numpy.ndarray
+        Current basis matrix for this view, shape ``(latent_dim, latent_k)``.
+    H_full : numpy.ndarray
+        Full DNN latent representation for all samples this view observes,
+        shape ``(latent_dim, n_obs)``.
+    P_full : numpy.ndarray
+        Concatenated code matrix ``[PC, P(v)_I]``, shape
+        ``(latent_k, n_obs)``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Updated basis matrix ``U(v)``, same shape as the input ``U``.
+    """
+    numerator = H_full @ P_full.T
+    denominator = U @ (P_full @ P_full.T) + EPS
+    return U * (numerator / denominator)

dimc_toolkit-1.0.0/dimc/algorithms/update_graph.py

@@ -0,0 +1,87 @@
+"""
+Multiplicative update rule for PC (the shared/graph-regularized code
+matrix, Eq. 13) and the graph-regularization loss term (Eq. 3/6).
+
+Model, per view v:  H(v) = [H(v)_C ; H(v)_I]  ~=  U(v) [PC ; P(v)_I]
+PC is shared across all views and is graph-regularized per view (Eq. 6);
+P(v)_I is private to view v and carries no graph term.
+"""
+
+from typing import List
+
+import numpy as np
+
+from dimc.config import EPS
+
+
+def update_PC(
+    PC: np.ndarray,
+    U_list: List[np.ndarray],
+    H_complete_list: List[np.ndarray],
+    W_list: List[np.ndarray],
+    D_list: List[np.ndarray],
+    alpha_list: List[float],
+) -> np.ndarray:
+    """
+    Eq. (13):
+      PC_ij <- PC_ij * [ sum_v ( U(v)^T H(v)_C + alpha(v) PC W(v) )_ij ]
+                        --------------------------------------------
+                        [ sum_v ( U(v)^T U(v) PC + alpha(v) PC D(v) )_ij ]
+
+    Parameters
+    ----------
+    PC : numpy.ndarray
+        Current shared code matrix, shape ``(latent_k, n_complete)``.
+    U_list : List[numpy.ndarray]
+        Per-view basis matrices ``U(v)``, each shape
+        ``(latent_dim, latent_k)``.
+    H_complete_list : List[numpy.ndarray]
+        Per-view DNN latent representations restricted to complete
+        samples, each shape ``(latent_dim, n_complete)``.
+    W_list : List[numpy.ndarray]
+        Per-view affinity matrices, each shape
+        ``(n_complete, n_complete)``.
+    D_list : List[numpy.ndarray]
+        Per-view degree matrices, each shape
+        ``(n_complete, n_complete)``.
+    alpha_list : List[float]
+        Per-view graph-regularization strengths.
+
+    Returns
+    -------
+    numpy.ndarray
+        Updated shared code matrix ``PC``, same shape as the input.
+    """
+    numerator = np.zeros_like(PC)
+    denominator = np.zeros_like(PC) + EPS
+
+    for U, H_C, W, D, alpha in zip(U_list, H_complete_list, W_list, D_list, alpha_list):
+        numerator += U.T @ H_C + alpha * (PC @ W)
+        denominator += (U.T @ U) @ PC + alpha * (PC @ D)
+
+    return PC * (numerator / denominator)
+
+
+def graph_regularization_loss(
+    PC: np.ndarray,
+    L: np.ndarray,
+    alpha: float,
+) -> float:
+    """
+    Eq. (3)/(6): alpha * trace(PC L PC^T), the local-invariance penalty.
+
+    Parameters
+    ----------
+    PC : numpy.ndarray
+        Shared code matrix, shape ``(latent_k, n_complete)``.
+    L : numpy.ndarray
+        Graph Laplacian for this view, shape ``(n_complete, n_complete)``.
+    alpha : float
+        Graph-regularization strength for this view.
+
+    Returns
+    -------
+    float
+        The scalar regularization loss value.
+    """
+    return alpha * np.trace(PC @ L @ PC.T)

dimc_toolkit-1.0.0/dimc/algorithms/update_weights.py

@@ -0,0 +1,39 @@
+"""
+Multiplicative update rule for P(v)_I, the private (per-view,
+incomplete-sample) code matrix (Eq. 14).
+"""
+
+import numpy as np
+
+from dimc.config import EPS
+
+
+def update_PI(
+    PI: np.ndarray,
+    U: np.ndarray,
+    H_private: np.ndarray,
+) -> np.ndarray:
+    """
+    Eq. (14):
+      P(v)_I_ij <- P(v)_I_ij * (U(v)^T H(v)_I)_ij / (U(v)^T U(v) P(v)_I)_ij
+    (no graph term for the private/incomplete-view code)
+
+    Parameters
+    ----------
+    PI : numpy.ndarray
+        Current private code matrix for this view, shape
+        ``(latent_k, n_private)``.
+    U : numpy.ndarray
+        Basis matrix for this view, shape ``(latent_dim, latent_k)``.
+    H_private : numpy.ndarray
+        DNN latent representation restricted to this view's private
+        (view-only-observed) samples, shape ``(latent_dim, n_private)``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Updated private code matrix ``P(v)_I``, same shape as the input.
+    """
+    numerator = U.T @ H_private
+    denominator = (U.T @ U) @ PI + EPS
+    return PI * (numerator / denominator)

dimc_toolkit-1.0.0/dimc/config.py

@@ -0,0 +1,84 @@
+"""
+Configuration constants and default settings for the DIMC package.
+
+This module centralizes every numeric/string constant that appeared as a
+literal in the original notebook (the "Multiple Features" experiment from
+Section 4.1(ii) of the paper), plus the small numerical-stability constant
+used throughout the multiplicative-update rules.
+
+Nothing here changes the meaning of any constant -- values are copied
+verbatim from the notebook's ``settings`` dict and the ``_EPS`` constant
+used in the update rules.
+"""
+
+from typing import Any, Dict
+
+# ============================================================
+# Numerical stability
+# ============================================================
+# Used in every multiplicative-update denominator (Eqs. 13, 14, 16) to
+# avoid division by zero when a denominator term is exactly 0.
+EPS: float = 1e-10
+
+# ============================================================
+# Default experiment settings
+# ============================================================
+# Defaults below reproduce the paper's "Multiple Features" experiment
+# (Section 4.1(ii) and Fig. 4(b)): 10 classes x 200 samples, 76-D Fourier
+# coefficients + 240-D pixel-average views, missing ratio (ISR) 0.2.
+#
+# IMPORTANT about alpha_1 / alpha_2: the paper does NOT claim alpha=60 works
+# for any fou/pix file -- it is the value THEY found by two-fold cross
+# validation on THEIR exact preprocessing (Section 4.3, Fig. 4b). The graph
+# term grows with alpha and with how similar/dense your own data's k-NN
+# graph turns out to be; too high overpowers reconstruction and over-smooths
+# PC, which can make clustering much worse, not better (confirmed by
+# sweep_alpha below). Run the sweep once on your own data and use its best
+# alpha instead of trusting 60 blindly.
+DEFAULT_SETTINGS: Dict[str, Any] = {
+    # data (Section 4.1(ii): Multiple Features dataset)
+    "fou_path": "/Users/suchibrata/Desktop/ISI_PLP/multiple_features/mfeat-fou",
+    "pix_path": "/Users/suchibrata/Desktop/ISI_PLP/multiple_features/mfeat-pix",
+    "n_classes": 10,
+    "samples_per_class": 200,
+
+    # missing-view simulation: incomplete sample ratio (ISR), Section 4.3
+    "missing_ratio": 0.20,
+    "mask_seed": 1,
+
+    # affinity graph (Eq. 2): p nearest neighbors per view
+    "p_neighbors": 10,
+
+    # architecture (Section 3.3): latent_dim = DNN output size, latent_k = NMF rank
+    "latent_dim": 64,
+    "latent_k": 10,
+    "n_clusters": 10,
+
+    # auto-encoder pretraining (Algorithm 1, line 1)
+    "pretrain_epochs": 700,
+    "pretrain_lr": 1e-3,
+
+    # NMF warm-up before joint training (Algorithm 1, line 2 / Eq. 7)
+    "nmf_pretrain_iters": 200,
+
+    # alternating optimization (Algorithm 1, lines 4-9)
+    # starting point only -- see the alpha sweep below before trusting this
+    "alpha_1": 1,
+    "alpha_2": 1,
+    "learning_rate": 1e-5,
+    "n_epochs": 500,
+    "log_every": 50,
+
+    # reproducibility
+    "seed": 42,
+}
+
+# ============================================================
+# Alpha-sensitivity sweep defaults
+# ============================================================
+# The candidate alpha values used in the notebook's Step 1 sweep.
+DEFAULT_ALPHA_CANDIDATES = [1, 10, 100, 1000, 10000]
+
+# Sweep runs use a reduced epoch budget so multiple alpha values can be
+# tried quickly (Section 4.4 / Fig. 4 does exactly this per-dataset).
+SWEEP_MAX_EPOCHS: int = 100

dimc_toolkit-1.0.0/dimc/datasets/__init__.py

@@ -0,0 +1,5 @@
+"""Dataset loading utilities for the DIMC package."""
+
+from dimc.datasets.load_dataset import load_views
+
+__all__ = ["load_views"]

dimc_toolkit-1.0.0/dimc/datasets/load_dataset.py

@@ -0,0 +1,13 @@
+"""
+Dataset loading utilities.
+
+The single implementation of view-loading lives in
+``dimc.preprocessing.load_views`` (Section 1 of the notebook, "Data
+loading"). This module re-exports it under the requested
+``dimc/datasets/load_dataset.py`` path so there is exactly one
+implementation rather than a duplicate.
+"""
+
+from dimc.preprocessing import load_views
+
+__all__ = ["load_views"]