dimc-toolkit 1.0.0__py3-none-any.whl

dimc/fit.py

@@ -0,0 +1,682 @@
+"""
+Alternating optimization loop, alpha-sensitivity sweep, and full pipeline.
+
+Corresponds to notebook Sections 8, 9b, and 10:
+  8.  Algorithm 1, lines 4-9: the alternating optimization loop
+  9b. Parameter sensitivity sweep for alpha(1)/alpha(2)   (Section 4.4, Fig. 4)
+  10. Full pipeline = Algorithm 1, driven by one plain settings dict
+
+The public entry point is ``fit`` (aliased to ``run_dimc`` for backward
+compatibility with the notebook's naming), matching the requested usage::
+
+    from dimc import fit
+    result = fit(X_views, labels, learning_rate=1e-5, alpha_1=60, alpha_2=60)
+"""
+
+import time
+from typing import Any, Dict, List, Optional, Sequence
+
+import numpy as np
+import torch
+
+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
+from dimc.config import DEFAULT_ALPHA_CANDIDATES, DEFAULT_SETTINGS, SWEEP_MAX_EPOCHS
+from dimc.graph import build_view_graph
+from dimc.initialize import (
+    build_view_decoder,
+    build_view_network,
+    initialize_nmf_factor,
+    pretrain_view_network,
+)
+from dimc.metrics import cluster_representation, compute_ACC, compute_NMI
+from dimc.preprocessing import (
+    load_views,
+    make_missing_masks,
+    split_by_availability,
+    standardize_views,
+)
+from dimc.utils import set_global_seed
+
+
+# ============================================================
+# 8. Algorithm 1, lines 4-9: the alternating optimization loop
+# ============================================================
+
+def _forward_all_views(
+    encoders: Sequence[Any],
+    X_views_t: Sequence[torch.Tensor],
+) -> List[np.ndarray]:
+    """
+    Run every view's current encoder to obtain H(v) for all views
+    (Algorithm 1, line 5: forward propagation).
+
+    Parameters
+    ----------
+    encoders : Sequence[torch.nn.Sequential]
+        Per-view encoder networks.
+    X_views_t : Sequence[torch.Tensor]
+        Per-view input tensors, each shape ``(n_samples, input_dim_v)``.
+
+    Returns
+    -------
+    List[numpy.ndarray]
+        Per-view latent representations ``H(v)``, each shape
+        ``(n_samples, latent_dim)``.
+    """
+    return [enc(X).detach().numpy() for enc, X in zip(encoders, X_views_t)]
+
+
+def _update_codes(
+    U_list: List[np.ndarray],
+    PC: np.ndarray,
+    PI_list: List[np.ndarray],
+    H_complete: List[np.ndarray],
+    H_private: List[np.ndarray],
+    W_list: List[np.ndarray],
+    D_list: List[np.ndarray],
+    alpha_list: List[float],
+) -> tuple:
+    """
+    Algorithm 1, line 6: update PC (Eq. 13) and each P(v)_I (Eq. 14).
+
+    Parameters
+    ----------
+    U_list : List[numpy.ndarray]
+        Per-view basis matrices.
+    PC : numpy.ndarray
+        Current shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Per-view private code matrices.
+    H_complete : List[numpy.ndarray]
+        Per-view DNN latent representations restricted to complete samples.
+    H_private : List[numpy.ndarray]
+        Per-view DNN latent representations restricted to private samples.
+    W_list : List[numpy.ndarray]
+        Per-view affinity matrices.
+    D_list : List[numpy.ndarray]
+        Per-view degree matrices.
+    alpha_list : List[float]
+        Per-view graph-regularization strengths.
+
+    Returns
+    -------
+    PC : numpy.ndarray
+        Updated shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Updated per-view private code matrices.
+    """
+    PC = update_PC(PC, U_list, H_complete, W_list, D_list, alpha_list)
+    PI_list = [update_PI(PI, U, H) for PI, U, H in zip(PI_list, U_list, H_private)]
+    return PC, PI_list
+
+
+def _update_bases(
+    U_list: List[np.ndarray],
+    H_full: List[np.ndarray],
+    obs_idx: List[np.ndarray],
+    PC: np.ndarray,
+    PI_list: List[np.ndarray],
+) -> List[np.ndarray]:
+    """
+    Algorithm 1, line 7: update each U(v) (Eq. 16), using the FULL H(v)
+    and P(v) = [PC, P(v)_I].
+
+    Parameters
+    ----------
+    U_list : List[numpy.ndarray]
+        Per-view basis matrices.
+    H_full : List[numpy.ndarray]
+        Per-view full DNN latent representations, each shape
+        ``(n_samples, latent_dim)``.
+    obs_idx : List[numpy.ndarray]
+        Per-view indices of samples that view observes.
+    PC : numpy.ndarray
+        Current shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Per-view private code matrices.
+
+    Returns
+    -------
+    List[numpy.ndarray]
+        Updated per-view basis matrices.
+    """
+    return [
+        update_U(U, H[idx].T, np.hstack([PC, PI]))
+        for U, H, idx, PI in zip(U_list, H_full, obs_idx, PI_list)
+    ]
+
+
+def _finetune_all_views(
+    encoders: Sequence[Any],
+    X_views_t: Sequence[torch.Tensor],
+    obs_idx: List[np.ndarray],
+    U_list: List[np.ndarray],
+    PC: np.ndarray,
+    PI_list: List[np.ndarray],
+    learning_rate: float,
+) -> List[float]:
+    """
+    Algorithm 1, line 8: fine-tune each view-specific DNN (Eqs. 17-23).
+
+    Parameters
+    ----------
+    encoders : Sequence[torch.nn.Sequential]
+        Per-view encoder networks, modified in place.
+    X_views_t : Sequence[torch.Tensor]
+        Per-view input tensors.
+    obs_idx : List[numpy.ndarray]
+        Per-view indices of samples that view observes.
+    U_list : List[numpy.ndarray]
+        Per-view basis matrices.
+    PC : numpy.ndarray
+        Current shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Per-view private code matrices.
+    learning_rate : float
+        Plain gradient-descent step size for the fine-tune step.
+
+    Returns
+    -------
+    List[float]
+        Per-view MSE reconstruction loss values.
+    """
+    losses = []
+    for v in range(2):
+        P_full = np.hstack([PC, PI_list[v]])
+        target = torch.tensor((U_list[v] @ P_full).T, dtype=torch.float32)
+        losses.append(
+            finetune_view_network(encoders[v], X_views_t[v][obs_idx[v]], target, learning_rate)
+        )
+    return losses
+
+
+def train_dimc(
+    X_views_t: Sequence[torch.Tensor],
+    encoders: Sequence[Any],
+    U_list: List[np.ndarray],
+    PC: np.ndarray,
+    PI_list: List[np.ndarray],
+    split: Dict[str, np.ndarray],
+    graphs: Sequence[Dict[str, np.ndarray]],
+    alpha_list: List[float],
+    learning_rate: float = 1e-2,
+    n_epochs: int = 300,
+    log_every: int = 50,
+) -> tuple:
+    """
+    Run the Algorithm 1, lines 4-9 alternating optimization loop.
+
+    Parameters
+    ----------
+    X_views_t : Sequence[torch.Tensor]
+        Per-view input tensors, each shape ``(n_samples, input_dim_v)``.
+    encoders : Sequence[torch.nn.Sequential]
+        Per-view encoder networks, modified in place during training.
+    U_list : List[numpy.ndarray]
+        Initial per-view basis matrices.
+    PC : numpy.ndarray
+        Initial shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Initial per-view private code matrices.
+    split : Dict[str, numpy.ndarray]
+        Output of ``dimc.preprocessing.split_by_availability``.
+    graphs : Sequence[Dict[str, numpy.ndarray]]
+        Per-view graph dictionaries from ``dimc.graph.build_view_graph``,
+        each containing ``"W"``, ``"D"``, and ``"L"``.
+    alpha_list : List[float]
+        Per-view graph-regularization strengths.
+    learning_rate : float, default=1e-2
+        Learning rate used for the DNN fine-tuning step.
+    n_epochs : int, default=300
+        Number of alternating-optimization iterations.
+    log_every : int, default=50
+        Print reconstruction/graph loss every this many epochs.
+
+    Returns
+    -------
+    U_list : List[numpy.ndarray]
+        Final per-view basis matrices.
+    PC : numpy.ndarray
+        Final shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Final per-view private code matrices.
+    """
+    complete_idx = split["complete_idx"]
+    private_idx = [split["view0_only_idx"], split["view1_only_idx"]]
+    obs_idx = [split["view0_obs_idx"], split["view1_obs_idx"]]
+
+    W_list = [g["W"] for g in graphs]
+    D_list = [g["D"] for g in graphs]
+    L_list = [g["L"] for g in graphs]
+
+    for epoch in range(n_epochs):
+        # line 5: forward propagation -> H(v) for all views
+        H_full = _forward_all_views(encoders, X_views_t)
+        H_complete = [H[complete_idx].T for H in H_full]
+        H_private = [H[idx].T for H, idx in zip(H_full, private_idx)]
+
+        # line 6: update PC (Eq. 13) and each P(v)_I (Eq. 14)
+        PC, PI_list = _update_codes(
+            U_list, PC, PI_list, H_complete, H_private, W_list, D_list, alpha_list
+        )
+
+        # line 7: update each U(v) (Eq. 16), using the FULL H(v) and P(v) = [PC, P(v)_I]
+        U_list = _update_bases(U_list, H_full, obs_idx, PC, PI_list)
+
+        # line 8: fine-tune each view-specific DNN (Eqs. 17-23)
+        losses = _finetune_all_views(encoders, X_views_t, obs_idx, U_list, PC, PI_list, learning_rate)
+
+        if epoch % log_every == 0:
+            recon_loss = sum(losses)
+            graph_loss = sum(
+                graph_regularization_loss(PC, L, alpha)
+                for L, alpha in zip(L_list, alpha_list)
+            )
+            print(f"Epoch {epoch:3d} | Recon: {recon_loss:.4f} | Graph: {graph_loss:.4f}")
+
+    return U_list, PC, PI_list
+
+
+# ============================================================
+# 10. Full pipeline = Algorithm 1, driven by one plain settings dict
+# ============================================================
+
+def _prepare_data(
+    settings: Dict[str, Any],
+    X_views: Optional[Sequence[np.ndarray]],
+    labels: Optional[np.ndarray],
+) -> tuple:
+    """
+    Load (if needed) and standardize the input views, and derive labels
+    if not provided (Section 4.1).
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Full settings dictionary.
+    X_views : Optional[Sequence[numpy.ndarray]]
+        Pre-loaded views, or ``None`` to load from ``settings["fou_path"]``
+        / ``settings["pix_path"]``.
+    labels : Optional[numpy.ndarray]
+        Ground-truth labels, or ``None`` to derive from
+        ``settings["n_classes"]`` / ``settings["samples_per_class"]``.
+
+    Returns
+    -------
+    X_views : List[numpy.ndarray]
+        Standardized views.
+    labels : numpy.ndarray
+        Ground-truth labels.
+    n_samples : int
+        Number of samples (rows) in view 0.
+    """
+    if X_views is None:
+        X_views = load_views([settings["fou_path"], settings["pix_path"]])
+    X_views = standardize_views(X_views)
+    n_samples = X_views[0].shape[0]
+
+    if labels is None:
+        labels = np.repeat(np.arange(settings["n_classes"]), settings["samples_per_class"])
+
+    return X_views, labels, n_samples
+
+
+def _build_and_pretrain_networks(
+    settings: Dict[str, Any],
+    X_views: Sequence[np.ndarray],
+    X_views_t: Sequence[torch.Tensor],
+) -> tuple:
+    """
+    Algorithm 1, line 1: build and pretrain each view-specific DNN
+    (encoder + decoder) by auto-encoding.
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Full settings dictionary.
+    X_views : Sequence[numpy.ndarray]
+        Standardized views (used only for their feature dimensionality).
+    X_views_t : Sequence[torch.Tensor]
+        Torch tensors of the standardized views.
+
+    Returns
+    -------
+    encoders : List[torch.nn.Sequential]
+        Pretrained per-view encoders.
+    decoders : List[torch.nn.Sequential]
+        Pretrained per-view decoders.
+    """
+    encoders = [
+        build_view_network(X.shape[1], latent_dim=settings["latent_dim"]) for X in X_views
+    ]
+    decoders = [
+        build_view_decoder(X.shape[1], latent_dim=settings["latent_dim"]) for X in X_views
+    ]
+
+    for enc, dec, X in zip(encoders, decoders, X_views_t):
+        pretrain_view_network(
+            enc, dec, X,
+            epochs=settings["pretrain_epochs"],
+            learning_rate=settings["pretrain_lr"],
+        )
+
+    return encoders, decoders
+
+
+def _initialize_factors(
+    settings: Dict[str, Any],
+    split: Dict[str, np.ndarray],
+    rng: np.random.RandomState,
+) -> tuple:
+    """
+    Algorithm 1, lines 2-3: initialize U(v), PC (Eq. 7), and P(v)_I randomly.
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Full settings dictionary.
+    split : Dict[str, numpy.ndarray]
+        Output of ``dimc.preprocessing.split_by_availability``.
+    rng : numpy.random.RandomState
+        Random state used for all factor initializations.
+
+    Returns
+    -------
+    U_list : List[numpy.ndarray]
+        Initial per-view basis matrices.
+    PC : numpy.ndarray
+        Initial shared code matrix.
+    PI_list : List[numpy.ndarray]
+        Initial per-view private code matrices.
+    """
+    complete_idx = split["complete_idx"]
+
+    U_list = [
+        initialize_nmf_factor((settings["latent_dim"], settings["latent_k"]), rng)
+        for _ in range(2)
+    ]
+    PC = initialize_nmf_factor((settings["latent_k"], len(complete_idx)), rng)
+    PI_list = [
+        initialize_nmf_factor((settings["latent_k"], len(idx)), rng)
+        for idx in [split["view0_only_idx"], split["view1_only_idx"]]
+    ]
+
+    return U_list, PC, PI_list
+
+
+def _nmf_warmup(
+    settings: Dict[str, Any],
+    encoders: Sequence[Any],
+    X_views_t: Sequence[torch.Tensor],
+    split: Dict[str, np.ndarray],
+    graphs: Sequence[Dict[str, np.ndarray]],
+    U_list: List[np.ndarray],
+    PC: np.ndarray,
+    alpha_list: List[float],
+) -> tuple:
+    """
+    NMF-only warm-up on the complete samples to minimize Eq. (7) before
+    joint training.
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Full settings dictionary.
+    encoders : Sequence[torch.nn.Sequential]
+        Pretrained per-view encoders.
+    X_views_t : Sequence[torch.Tensor]
+        Torch tensors of the standardized views.
+    split : Dict[str, numpy.ndarray]
+        Output of ``dimc.preprocessing.split_by_availability``.
+    graphs : Sequence[Dict[str, numpy.ndarray]]
+        Per-view graph dictionaries.
+    U_list : List[numpy.ndarray]
+        Initial per-view basis matrices.
+    PC : numpy.ndarray
+        Initial shared code matrix.
+    alpha_list : List[float]
+        Per-view graph-regularization strengths.
+
+    Returns
+    -------
+    U_list : List[numpy.ndarray]
+        Warmed-up per-view basis matrices.
+    PC : numpy.ndarray
+        Warmed-up shared code matrix.
+    """
+    complete_idx = split["complete_idx"]
+
+    H0 = encoders[0](X_views_t[0]).detach().numpy()
+    H1 = encoders[1](X_views_t[1]).detach().numpy()
+    H_complete = [H0[complete_idx].T, H1[complete_idx].T]
+    W_list = [g["W"] for g in graphs]
+    D_list = [g["D"] for g in graphs]
+
+    for _ in range(settings["nmf_pretrain_iters"]):
+        PC = update_PC(PC, U_list, H_complete, W_list, D_list, alpha_list)
+        U_list = [update_U(U, H, PC) for U, H in zip(U_list, H_complete)]
+
+    return U_list, PC
+
+
+def _assemble_shared_representation(
+    settings: Dict[str, Any],
+    split: Dict[str, np.ndarray],
+    n_samples: int,
+    PC: np.ndarray,
+    PI_list: List[np.ndarray],
+) -> np.ndarray:
+    """
+    Assemble the full shared representation P by scattering PC and each
+    P(v)_I back into their original sample positions (Section 3, end).
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Full settings dictionary.
+    split : Dict[str, numpy.ndarray]
+        Output of ``dimc.preprocessing.split_by_availability``.
+    n_samples : int
+        Total number of samples.
+    PC : numpy.ndarray
+        Final shared code matrix, restricted to complete samples.
+    PI_list : List[numpy.ndarray]
+        Final per-view private code matrices.
+
+    Returns
+    -------
+    numpy.ndarray
+        Full shared representation, shape ``(latent_k, n_samples)``.
+    """
+    P_shared = np.zeros((settings["latent_k"], n_samples), dtype=np.float32)
+    P_shared[:, split["complete_idx"]] = PC
+    P_shared[:, split["view0_only_idx"]] = PI_list[0]
+    P_shared[:, split["view1_only_idx"]] = PI_list[1]
+    return P_shared
+
+
+def run_dimc(
+    settings: Dict[str, Any],
+    X_views: Optional[Sequence[np.ndarray]] = None,
+    labels: Optional[np.ndarray] = None,
+) -> Dict[str, Any]:
+    """
+    Run the full DIMC pipeline (Algorithm 1) end to end, driven by one
+    plain settings dictionary.
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Full settings dictionary; see ``dimc.config.DEFAULT_SETTINGS``
+        for the expected keys and their meanings.
+    X_views : Optional[Sequence[numpy.ndarray]], default=None
+        Pre-loaded views. If ``None``, views are loaded from
+        ``settings["fou_path"]`` / ``settings["pix_path"]``.
+    labels : Optional[numpy.ndarray], default=None
+        Ground-truth labels. If ``None``, labels are derived from
+        ``settings["n_classes"]`` / ``settings["samples_per_class"]``.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Dictionary with keys ``"ACC"``, ``"NMI"``, ``"encoders"``,
+        ``"decoders"``, ``"U_list"``, ``"PC"``, ``"PI_list"``,
+        ``"P_shared"``, and ``"cluster_labels"``.
+    """
+    t0 = time.time()
+
+    seed = settings["seed"]
+    rng = set_global_seed(seed)
+
+    # ---- data (Section 4.1) ----
+    X_views, labels, n_samples = _prepare_data(settings, X_views, labels)
+
+    # ---- incomplete-view split: D = {X_C, X_I} ----
+    mask_0, mask_1 = make_missing_masks(n_samples, settings["missing_ratio"], settings["mask_seed"])
+    split = split_by_availability(mask_0, mask_1)
+    complete_idx = split["complete_idx"]
+
+    X_views_t = [torch.tensor(X, dtype=torch.float32) for X in X_views]
+
+    # ---- one affinity graph W(v)/L(v) PER VIEW, built from that view's own
+    #      complete samples X(v)_C (Eq. 2, Section 3.2) ----
+    graphs = [build_view_graph(X[complete_idx], settings["p_neighbors"]) for X in X_views]
+
+    # ---- Algorithm 1, line 1: pretrain view-specific DNNs by auto-encoding ----
+    encoders, decoders = _build_and_pretrain_networks(settings, X_views, X_views_t)
+
+    # ---- Algorithm 1, lines 2-3: initialize U(v), PC (Eq. 7) and P(v)_I randomly ----
+    U_list, PC, PI_list = _initialize_factors(settings, split, rng)
+
+    alpha_list = [settings["alpha_1"], settings["alpha_2"]]
+
+    # NMF-only warm-up on the complete samples to minimize Eq. (7) before joint training
+    U_list, PC = _nmf_warmup(settings, encoders, X_views_t, split, graphs, U_list, PC, alpha_list)
+
+    # ---- Algorithm 1, lines 4-9: alternating optimization until convergence ----
+    U_list, PC, PI_list = train_dimc(
+        X_views_t, encoders, U_list, PC, PI_list, split, graphs, alpha_list,
+        learning_rate=settings["learning_rate"],
+        n_epochs=settings["n_epochs"],
+        log_every=settings["log_every"],
+    )
+
+    # ---- assemble shared representation P and cluster (Section 3, end) ----
+    P_shared = _assemble_shared_representation(settings, split, n_samples, PC, PI_list)
+
+    cluster_labels = cluster_representation(P_shared, settings["n_clusters"], seed)
+
+    acc = compute_ACC(labels, cluster_labels)
+    nmi = compute_NMI(labels, cluster_labels)
+    runtime = time.time() - t0
+
+    print(f"ACC={acc:.4f}  NMI={nmi:.4f}  Runtime={runtime:.2f}s")
+
+    return {
+        "ACC": acc,
+        "NMI": nmi,
+        "encoders": encoders,
+        "decoders": decoders,
+        "U_list": U_list,
+        "PC": PC,
+        "PI_list": PI_list,
+        "P_shared": P_shared,
+        "cluster_labels": cluster_labels,
+    }
+
+
+# ============================================================
+# 9b. Parameter sensitivity sweep for alpha(1)/alpha(2)   (Section 4.4, Fig. 4)
+# ============================================================
+# The paper does NOT use one fixed alpha across datasets: Section 4.4 explicitly
+# sweeps alpha(1)/alpha(2) per dataset and picks the values that maximize NMI
+# (Fig. 4 shows NMI rises then falls as alpha grows -- too small under-uses the
+# graph regularizer, too large lets it dominate reconstruction and over-smooth
+# PC, which hurts clustering). alpha=60 is the value the paper found for its
+# own Multiple Features preprocessing; a different fou/pix file (different
+# scaling, different feature statistics) can need a very different alpha.
+# Run this sweep on your own data before trusting a fixed default.
+
+def sweep_alpha(
+    settings: Dict[str, Any],
+    alpha_candidates: Sequence[float],
+    X_views: Optional[Sequence[np.ndarray]] = None,
+    labels: Optional[np.ndarray] = None,
+) -> List[Dict[str, float]]:
+    """
+    Try each alpha value (same alpha for both views, as in Fig. 4) with a
+    reduced epoch budget, and report ACC/NMI for each so you can pick the
+    best one for your data before doing a full run.
+
+    Parameters
+    ----------
+    settings : Dict[str, Any]
+        Base settings dictionary; a copy is modified per candidate alpha.
+    alpha_candidates : Sequence[float]
+        Candidate values to try for both ``alpha_1`` and ``alpha_2``.
+    X_views : Optional[Sequence[numpy.ndarray]], default=None
+        Pre-loaded views, forwarded to ``run_dimc``.
+    labels : Optional[numpy.ndarray], default=None
+        Ground-truth labels, forwarded to ``run_dimc``.
+
+    Returns
+    -------
+    List[Dict[str, float]]
+        One dict per candidate alpha with keys ``"alpha"``, ``"ACC"``,
+        and ``"NMI"``.
+    """
+    sweep_settings = dict(settings)
+    sweep_settings["n_epochs"] = min(settings["n_epochs"], SWEEP_MAX_EPOCHS)
+    sweep_settings["log_every"] = sweep_settings["n_epochs"]  # only log the final epoch
+
+    scores = []
+    for alpha in alpha_candidates:
+        sweep_settings["alpha_1"] = alpha
+        sweep_settings["alpha_2"] = alpha
+        result = run_dimc(sweep_settings, X_views=X_views, labels=labels)
+        scores.append({"alpha": alpha, "ACC": result["ACC"], "NMI": result["NMI"]})
+        print(f"alpha={alpha:<8} -> ACC={result['ACC']:.4f}  NMI={result['NMI']:.4f}")
+
+    best = max(scores, key=lambda s: s["NMI"])
+    print(f"\nBest alpha by NMI: {best['alpha']} (ACC={best['ACC']:.4f}, NMI={best['NMI']:.4f})")
+    return scores
+
+
+def fit(
+    X_views: Optional[Sequence[np.ndarray]] = None,
+    labels: Optional[np.ndarray] = None,
+    **overrides: Any,
+) -> Dict[str, Any]:
+    """
+    Convenience entry point: run the full DIMC pipeline using
+    ``dimc.config.DEFAULT_SETTINGS`` merged with any keyword overrides.
+
+    This matches the requested top-level usage::
+
+        from dimc import fit
+        result = fit(X_views, labels, learning_rate=1e-5, alpha_1=60, alpha_2=60)
+
+    Parameters
+    ----------
+    X_views : Optional[Sequence[numpy.ndarray]], default=None
+        Pre-loaded views. If ``None``, views are loaded from the default
+        (or overridden) ``fou_path`` / ``pix_path`` settings.
+    labels : Optional[numpy.ndarray], default=None
+        Ground-truth labels. If ``None``, labels are derived from the
+        default (or overridden) ``n_classes`` / ``samples_per_class``
+        settings.
+    **overrides : Any
+        Any key from ``dimc.config.DEFAULT_SETTINGS`` to override, e.g.
+        ``learning_rate=1e-5``, ``alpha_1=60``, ``alpha_2=60``.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Same return value as ``run_dimc``.
+    """
+    settings = dict(DEFAULT_SETTINGS)
+    settings.update(overrides)
+    return run_dimc(settings, X_views=X_views, labels=labels)