Examples d’utilisation

Voici quelques exemples d’utilisation du package mvcluster.

Préparer un dataset personnalisé

"""
[EN] prepare_custom_dataset.py - Final Version

This script prepares heterogeneous multi-view (e.g., multi-omics) datasets
for downstream tasks such as clustering or graph-based learning.

It performs robust loading, preprocessing, normalization, graph
construction, and saving of multiple data views into a unified .mat file
format.

==============================
Main Functionalities
==============================

1. Robust Data Loading
----------------------
- Loads CSV files using pandas.
- Tries alternative encodings (utf-8, latin1, windows-1252) if standard
  read fails.
- If no valid columns are found, generates random fallback data to avoid
  crashing.

2. View Preprocessing
---------------------
Each input view (CSV file) undergoes the following steps:
- Categorical columns are converted to numerical using factorization.
- Missing values are imputed using column-wise medians.
- Views with fewer features than `--min_features` are automatically
  augmented by duplicating existing columns.
- If a view has more than 100 features, variance thresholding is applied
  to remove low-variance columns.
- Each view is standardized using `StandardScaler`.

3. Graph Construction
---------------------
- Constructs a symmetric K-Nearest Neighbors (KNN) graph for each view.
- Graphs are binary (1/0 connectivity) and symmetric (A = (A + A.T) / 2).

4. Label Handling (Optional)
----------------------------
- If a label file is provided, it is loaded and encoded using
  `LabelEncoder`.
- Only labels matching the number of samples are retained.

5. Output Generation
---------------------
The final data is saved as a `.mat` file and includes:
- Feature matrices: X_0, X_1, ..., one per view.
- Adjacency matrices: A_0, A_1, ..., one per view.
- View names.
- Original shape information for each view.
- Sample count.
- Feature names (limited to selected columns).
- Encoded labels (optional).

==============================
Command Line Arguments
==============================
--views        : List of CSV files (one per view) [REQUIRED]
--labels       : (Optional) Path to CSV file with sample labels
--data_name    : Output filename (without extension) [REQUIRED]
--k            : Number of neighbors for KNN graph (default: 15)
--min_features : Minimum number of features per view (default: 1)
--output_dir   : Output directory (default: prepared_datasets)

==============================
Typical Usage Example
==============================
python prepare_custom_dataset.py \
    --views view1.csv view2.csv view3.csv \
    --labels labels.csv \
    --data_name my_dataset \
    --k 15 \
    --min_features 2 \
    --output_dir prepared_datasets

==============================
Error Handling and Recommendations
==============================
- Views with <2 features may cause downstream errors with dimensionality
  reduction (e.g., TruncatedSVD).
- Use `--min_features 2` or manually exclude weak views.
- Final `.mat` output is compatible with MATLAB and multi-view clustering
  frameworks.

==============================
Output Example
==============================
View 1/5: transcriptomics
transcriptomics: Selected 45/150 features
Shape: (30, 45), Features: 45
Loaded 3 label classes

=== Successfully saved to prepared_datasets/my_dataset.mat ===
Summary: 5 views, 30 samples


[FR] prepare_custom_dataset.py - Version finale

Ce script prépare des jeux de données hétérogènes multi-vues (ex : multi-
omiques) pour des tâches en aval telles que le clustering ou
l’apprentissage basé sur les graphes.

Il effectue le chargement robuste, le prétraitement, la normalisation,
la construction de graphes et la sauvegarde des vues dans un fichier
unique `.mat`.

==============================
Fonctionnalités principales
==============================

1. Chargement robuste des données
----------------------------------
- Chargement des fichiers CSV avec pandas.
- Essaie plusieurs encodages alternatifs (utf-8, latin1, windows-1252) si
  le chargement échoue.
- Si aucun fichier valide n'est trouvé, des données aléatoires sont
  générées pour éviter l'arrêt du programme.

2. Prétraitement des vues
--------------------------
Chaque vue (fichier CSV) est traitée comme suit :
- Les colonnes catégorielles sont converties en valeurs numériques via la
  factorisation.
- Les valeurs manquantes sont remplacées par la médiane des colonnes.
- Si une vue contient moins de `--min_features`, elle est augmentée
  automatiquement.
- Si une vue contient plus de 100 colonnes, une sélection par variance
  est appliquée.
- Chaque vue est normalisée avec `StandardScaler`.

3. Construction de graphes
---------------------------
- Un graphe de K plus proches voisins (KNN) est construit pour chaque vue.
- Les graphes sont binaires (0/1) et symétrisés (A = (A + A.T)/2).

4. Gestion des étiquettes (facultatif)
---------------------------------------
- Si un fichier de labels est fourni, il est chargé et encodé avec
  `LabelEncoder`.
- Les étiquettes sont conservées uniquement si elles correspondent au
  nombre d’échantillons.

5. Génération de la sortie
---------------------------
Le fichier final au format `.mat` contient :
- Les matrices de caractéristiques : X_0, X_1, ..., une par vue.
- Les matrices d’adjacence : A_0, A_1, ..., une par vue.
- Les noms des vues.
- Les dimensions d’origine de chaque vue.
- Le nombre total d’échantillons.
- Les noms des variables (colonnes sélectionnées).
- Les étiquettes encodées (si présentes).

==============================
Arguments en ligne de commande
==============================
--views        : Liste de fichiers CSV (une par vue) [OBLIGATOIRE]
--labels       : (Facultatif) Fichier CSV contenant les labels
--data_name    : Nom du fichier de sortie (sans extension) [OBLIGATOIRE]
--k            : Nombre de voisins pour le graphe KNN (défaut : 15)
--min_features : Nombre minimal de colonnes par vue (défaut : 1)
--output_dir   : Répertoire de sortie (défaut : prepared_datasets)

==============================
Exemple d'utilisation
==============================
python prepare_custom_dataset.py \
    --views vue1.csv vue2.csv vue3.csv \
    --labels labels.csv \
    --data_name mon_dataset \
    --k 15 \
    --min_features 2 \
    --output_dir prepared_datasets

==============================
Conseils et gestion des erreurs
==============================
- Les vues avec moins de 2 colonnes peuvent provoquer des erreurs avec
  TruncatedSVD.
- Utilisez `--min_features 2` ou excluez manuellement ces vues.
- Le fichier `.mat` final est compatible avec MATLAB et les frameworks
  de clustering multi-vues.

==============================
Exemple de sortie
==============================
Vue 1/5 : transcriptomics
transcriptomics : 45/150 variables sélectionnées
Forme : (30, 45), Variables : 45
3 classes de labels chargées

=== Sauvegarde réussie vers prepared_datasets/mon_dataset.mat ===
Résumé : 5 vues, 30 échantillons
"""


import argparse
import numpy as np
import scipy.io
import pandas as pd
import os
import warnings
from sklearn.neighbors import kneighbors_graph
from sklearn.preprocessing import StandardScaler, LabelEncoder
from sklearn.feature_selection import VarianceThreshold

# Configure logging
warnings.filterwarnings('once')
pd.set_option('display.max_columns', 10)


def robust_read_file(filepath: str) -> pd.DataFrame:
    """Read data file with multiple fallback strategies."""
    try:
        df = pd.read_csv(filepath, header=0, index_col=None)

        if df.shape[1] == 0:
            encodings = ['utf-8', 'latin1', 'windows-1252']
            for enc in encodings:
                try:
                    df = pd.read_csv(filepath, encoding=enc)
                    if df.shape[1] > 0:
                        break
                except Exception:
                    continue

        if df.shape[1] == 0:
            raise ValueError("No columns detected")

        return df

    except Exception as e:
        warnings.warn(f"Failed to read {filepath}: {str(e)}")
        return pd.DataFrame({'feature': np.random.rand(30)})


def preprocess_view(df: pd.DataFrame, view_name: str,
                    min_features: int) -> np.ndarray:
    """Preprocess a single view."""
    cat_cols = df.select_dtypes(exclude=np.number).columns
    for col in cat_cols:
        df[col] = pd.factorize(df[col])[0]

    if df.isna().any().any():
        df = df.fillna(df.median())

    X = df.values.astype(np.float32)

    if X.shape[1] < min_features:
        warnings.warn(
            f"Augmenting {view_name} from {X.shape[1]} "
            f"to {min_features} features"
        )
        X = np.hstack([X] + [X[:, [0]] *
                             (min_features - X.shape[1])])

    if X.shape[1] > 100:
        selector = VarianceThreshold(threshold=0.1)
        try:
            X = selector.fit_transform(X)
            print(
                f"{view_name}: Selected {X.shape[1]}/"
                f"{selector.n_features_in_} features"
            )
        except Exception as e:
            print(f"Feature selection failed for {view_name}: {str(e)}")

    if X.shape[0] > 1:
        X = StandardScaler().fit_transform(X)

    return X


def save_heterogeneous_data(output_path: str, data: dict):
    """Specialized saver for heterogeneous data."""
    save_data = {}
    for i, (x, a) in enumerate(zip(data['Xs'], data['As'])):
        save_data[f'X_{i}'] = x
        save_data[f'A_{i}'] = a

    save_data.update({
        'view_names': np.array(data['view_names'], dtype=object),
        'n_samples': data['n_samples'],
        'original_shapes': np.array(
            [x.shape for x in data['Xs']], dtype=object
        )
    })

    if 'labels' in data:
        save_data['labels'] = data['labels']

    scipy.io.savemat(output_path, save_data)


def main():
    parser = argparse.ArgumentParser(
        description="Multi-omics data preprocessor"
    )
    parser.add_argument("--views", nargs="+", required=True,
                        help="Input files")
    parser.add_argument("--labels", help="Label file")
    parser.add_argument("--data_name", required=True, help="Output name")
    parser.add_argument("--k", type=int, default=10,
                        help="k for KNN graph")
    parser.add_argument("--min_features", type=int, default=2,
                        help="Min features")
    parser.add_argument("--output_dir", default="prepared_datasets",
                        help="Output dir")

    args = parser.parse_args()
    os.makedirs(args.output_dir, exist_ok=True)
    output_path = os.path.join(args.output_dir,
                               f"{args.data_name}.mat")

    view_data = []
    print("\n=== Processing Views ===")

    for i, view_path in enumerate(args.views):
        view_name = os.path.splitext(os.path.basename(view_path))[0]
        print(f"\nView {i + 1}/{len(args.views)}: {view_name}")

        try:
            df = robust_read_file(view_path)
            X = preprocess_view(df, view_name, args.min_features)

            print(f"\n>>> First 10 rows of {view_name} after preprocessing:")
            print(pd.DataFrame(X).head(10))

            A = kneighbors_graph(X, n_neighbors=args.k,
                                 mode='connectivity')
            A = 0.5 * (A + A.T)  # type: ignore # Symmetrize
            A.data[:] = 1        # Binary weights

            view_data.append({
                'X': X,
                'A': A,
                'name': view_name,
                'features': df.columns.tolist()[:X.shape[1]]
            })

            print(f"  Shape: {X.shape}, "
                  f"Features: {len(view_data[-1]['features'])}")

        except Exception as e:
            warnings.warn(f"Failed to process {view_name}: {str(e)}")
            continue

    results = {
        'Xs': [vd['X'] for vd in view_data],
        'As': [vd['A'] for vd in view_data],
        'view_names': [vd['name'] for vd in view_data],
        'n_samples': view_data[0]['X'].shape[0] if view_data else 0,
        'feature_names': [vd['features'] for vd in view_data]
    }

    if args.labels and os.path.exists(args.labels):
        try:
            labels = pd.read_csv(args.labels).squeeze()
            if len(labels) == results['n_samples']:  # type: ignore
                results['labels'] = LabelEncoder().fit_transform(labels)
                print(f"\nLoaded {len(np.unique(results['labels']))} "
                      "label classes")
        except Exception as e:
            warnings.warn(f"Label loading failed: {str(e)}")

    try:
        save_heterogeneous_data(output_path, results)
        print(f"\n=== Successfully saved to {output_path} ===")
        print(f"Summary: {len(view_data)} views, "
              f"{results['n_samples']} samples")
    except Exception as e:
        print(f"\n!!! Final save failed: {str(e)}")
        print("Possible solutions:")
        print("1. Install hdf5storage: pip install hdf5storage")
        print("2. Reduce feature dimensions using PCA")
        print("3. Save in a different format (e.g., HDF5)")


if __name__ == "__main__":
    main()

Comparer les méthodes

"""
compare_methods.py

Compares multiple multiview clustering algorithms
on the same dataset using clustering metrics (NMI, ARI, ACC).

Steps:
    1. Load and preprocess a multi-view dataset.
    2. Apply multiple clustering algorithms to generate labels.
    3. Compute and display evaluation metrics.
    4. Optionally visualize clusters from each method.

Usage:
    python compare_methods.py

Dependencies:
    - mvclustlib.algorithms.*
    - mvclustlib.utils.metrics
    - mvclustlib.utils.plot
"""

Évaluer avec des métriques

"""
evaluate_with_metrics.py

Computes clustering quality metrics (NMI, ARI, ACC) for a selected multiview
clustering algorithm on a benchmark dataset.

Steps:
    1. Run a clustering method on a dataset.
    2. Compare predicted labels against ground truth.
    3. Compute and print evaluation metrics.

Usage:
    python evaluate_with_metrics.py

Dependencies:
    - mvclustlib.algorithms.lmgec
    - mvclustlib.utils.metrics
"""

Visualiser les clusters

"""
[EN]
This script loads and visualizes multi-view clustering results from custom
multi-view datasets stored in .mat files. It supports various common .mat file
formats for multi-view data with adjacency and feature matrices, optionally
including ground truth cluster labels.

Main features and workflow:

1. Data Loading:
   - Supports .mat formats with keys such as 'X_i'/'A_i', 'X1', 'features',
     'views', and special cases like 'fea', 'W', and 'gnd'.
   - Handles sparse and dense matrices and converts them as needed.
   - Returns a list of (adjacency matrix, feature matrix) tuples for each view,
     along with optional ground truth labels.

2. Data Preprocessing:
   - Normalizes adjacency matrices and preprocesses feature matrices.
   - Supports tf-idf option disabled here and beta parameter usage.
   - Converts sparse matrices to dense format where necessary.

3. Clustering:
   - Uses the LMGEC (Localized Multi-View Graph Embedding Clustering) model
     for clustering.
   - Automatically determines the number of clusters from labels or defaults
     to 3 if no labels are provided.
   - Embedding dimension is set as clusters + 1.

4. Visualization:
   - Visualizes predicted clusters and, if available, ground truth clusters.
   - Uses PCA for dimensionality reduction before plotting.

5. Command-Line Interface:
   - Requires a path to the .mat dataset.
   - Optional flag to run without ground truth labels.

Dependencies:
- mvcluster package (cluster, utils.plot, utils.preprocess modules)
- numpy, scipy, scikit-learn, argparse, warnings

Usage example:
    python visualize_mvclusters.py --data_file path/to/data.mat
    python visualize_mvclusters.py --data_file path/to/data.mat --no_labels

[FR]
Ce script charge et visualise les résultats de clustering multi-vues à partir
de jeux de données multi-vues personnalisés au format .mat. Il supporte
plusieurs formats .mat communs avec matrices d’adjacence et matrices de
caractéristiques, incluant éventuellement des étiquettes de vérité terrain.

Fonctionnalités principales et déroulement :

1. Chargement des données :
- Supporte les formats .mat avec clés telles que 'X_i'/'A_i', 'X1', 'features',
'views', et cas spéciaux comme 'fea', 'W' et 'gnd'.
- Gère les matrices creuses (sparse) et denses en les convertissant si besoin.
- Retourne une liste de tuples
(matrice d’adjacence, matrice de caractéristiques)
pour chaque vue, ainsi que les étiquettes de vérité terrain optionnelles.

2. Prétraitement des données :
- Normalise les matrices d’adjacence et prépare les matrices
de caractéristiques.
- Supporte l’option tf-idf désactivée ici et l’usage du paramètre beta.
- Convertit les matrices creuses en matrices denses si nécessaire.

3. Clustering :
- Utilise le modèle LMGEC (Localized Multi-View Graph Embedding Clustering)
pour le clustering.
- Détermine automatiquement le nombre de clusters à partir des étiquettes,
ou utilise 3 clusters par défaut si aucune étiquette n’est fournie.
- La dimension d’embedding est fixée à clusters + 1.

4. Visualisation :
- Visualise les clusters prédits et, si disponibles, les clusters de vérité
terrain.
- Utilise l’ACP (PCA) pour réduire la dimension avant affichage.

5. Interface en ligne de commande :
- Nécessite le chemin vers le fichier .mat.
- Option pour exécuter sans étiquettes de vérité terrain.

Dépendances :
- Package mvcluster (modules cluster, utils.plot, utils.preprocess)
- numpy, scipy, scikit-learn, argparse, warnings

Exemples d’utilisation :
    python visualize_mvclusters.py --data_file chemin/vers/data.mat
    python visualize_mvclusters.py --data_file chemin/vers/data.mat --no_labels
"""


import argparse
import os
import sys
import numpy as np
import warnings
from sklearn.preprocessing import StandardScaler
from scipy.io import loadmat
from scipy.sparse import issparse, coo_matrix

# Add the parent directory to the import path
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

try:
    from mvcluster.cluster import LMGEC
    from mvcluster.utils.plot import visualize_clusters
    from mvcluster.utils.preprocess import preprocess_dataset
except ImportError as e:
    raise ImportError(f"Failed to import required modules: {e}")


def load_custom_mat(path):
    """
    Load .mat file supporting multiple multiview formats.

    Args:
        path (str): Path to the .mat file

    Returns:
        tuple: (list of (A, X) tuples, labels array or None)

    Raises:
        ValueError: If the file structure is unsupported
    """
    mat = loadmat(path)
    Xs, As = [], []
    # Try to get labels (optional)
    labels = None
    for label_key in ['labels', 'label', 'gt', 'ground_truth']:
        if label_key in mat:
            labels = mat[label_key].squeeze()
            break

    # Try X_0/A_0 format
    i = 0
    while f"X_{i}" in mat and f"A_{i}" in mat:
        X = mat[f"X_{i}"]
        A = mat[f"A_{i}"].astype(np.float32)
        if issparse(X):
            X = X.toarray()
        if issparse(A):
            A = A.toarray()
        Xs.append(X)
        As.append(A)
        i += 1
    if Xs:
        return list(zip(As, Xs)), labels

    # Try X1 format (with identity adjacency)
    i = 1
    while f"X{i}" in mat:
        X = mat[f"X{i}"]
        if issparse(X):
            X = X.toarray()
        A = np.eye(X.shape[0], dtype=np.float32)
        Xs.append(X)
        As.append(A)
        i += 1
    if Xs:
        return list(zip(As, Xs)), labels

    # Try features/views format
    for key in ["features", "views", "data"]:
        if key in mat:
            value = mat[key]
            try:
                if isinstance(value, coo_matrix):
                    X = value.toarray()
                    A = np.eye(X.shape[0], dtype=np.float32)
                    return [(A, X)], labels
                elif value.shape == (1,):
                    # Handle cell array format
                    for view in value[0]:
                        X = view.toarray() if issparse(view) else view
                        A = np.eye(X.shape[0], dtype=np.float32)
                        Xs.append(X)
                        As.append(A)
                else:
                    # Handle matrix directly
                    X = value.toarray() if issparse(value) else value
                    A = np.eye(X.shape[0], dtype=np.float32)
                    Xs.append(X)
                    As.append(A)
                if Xs:
                    return list(zip(As, Xs)), labels
            except Exception as e:
                warnings.warn(f"Failed to process key '{key}': {str(e)}")
                continue
            # New case for wiki.mat format with 'fea', 'W', and 'gnd' keys
    if "fea" in mat and "W" in mat:
        X = mat["fea"]
        A = mat["W"].astype(np.float32)
        Xs.append(X)
        As.append(A)
        if "gnd" in mat:
            labels = mat["gnd"].squeeze()
            if labels.ndim != 1:
                labels = labels.ravel()
            if not isinstance(labels, np.ndarray):
                labels = np.array(labels)
        return list(zip(As, Xs)), labels

    raise ValueError(
        "Unsupported .mat structure. Expected formats:\n"
        "1. X_0/A_0, X_1/A_1,...\n"
        "2. X1, X2,... (with identity adjacency)\n"
        "3. 'features' or 'views' key with data"
    )


def main():
    """Main function to run the visualization pipeline."""
    parser = argparse.ArgumentParser(
        description="Visualize multiview clustering results."
    )
    parser.add_argument(
        "--data_file",
        type=str,
        required=True,
        help="Path to the .mat multiview dataset"
    )
    parser.add_argument(
        "--no_labels",
        action="store_true",
        help="Run even if dataset has no ground truth labels"
    )
    args = parser.parse_args()

    # Configuration parameters
    temperature = 1.0
    beta = 1.0
    max_iter = 10
    tolerance = 1e-7

    # Load and preprocess data
    views, labels = load_custom_mat(args.data_file)

    if labels is None and not args.no_labels:
        raise ValueError(
            "Dataset must include 'labels' for visualization. "
            "Use --no_labels to run without ground truth."
        )

    # Process each view
    processed_views = []
    for A, X in views:
        # Convert to dense arrays if sparse
        if issparse(A):
            A = A.toarray()  # type: ignore
        if issparse(X):
            X = X.toarray()

        # Ensure proper dimensions
        A = np.asarray(A, dtype=np.float32)
        X = np.asarray(X, dtype=np.float32)

        if X.ndim == 1:
            X = X.reshape(-1, 1)
        if A.ndim != 2 or A.shape[0] != A.shape[1]:
            A = np.eye(X.shape[0], dtype=np.float32)

        # Preprocess
        norm_adj, feats = preprocess_dataset(A, X, tf_idf=False, beta=int(beta))  # noqa: E501
        if issparse(feats):
            feats = feats.toarray()
        processed_views.append((np.asarray(norm_adj), np.asarray(feats)))

    # Create feature matrices for each view
    Hs = []
    for S, X in processed_views:
        if X.ndim < 2:
            X = X.reshape(-1, 1)
        if S.ndim < 2:
            S = S.reshape(-1, 1)

        # Standardize features
        H = StandardScaler(with_std=False).fit_transform(S @ X)
        Hs.append(H)

    # Cluster the data
    k = len(np.unique(labels)) if labels is not None else 3
    model = LMGEC(
        n_clusters=k,
        embedding_dim=k + 1,
        temperature=temperature,
        max_iter=max_iter,
        tolerance=tolerance,
    )
    pred_labels = model.fit_predict(Hs)  # type: ignore

    # Visualize results
    X_concat = np.hstack([X for _, X in processed_views])
    visualize_clusters(
        X_concat, pred_labels, method='pca',
        title='Predicted Clusters (LMGEC)'
    )

    if labels is not None:
        visualize_clusters(
            X_concat, labels, method='pca',
            title='Ground Truth Clusters'
        )


if __name__ == "__main__":
    # Suppress runtime warnings about imports
    warnings.filterwarnings("ignore", category=RuntimeWarning)
    main()

Ajuster les hyperparamètres

import argparse
import itertools
import os
from typing import List, Tuple, Optional

import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
import pandas as pd

from sklearn.preprocessing import StandardScaler
from sklearn.metrics import normalized_mutual_info_score as nmi
from sklearn.metrics import adjusted_rand_score as ari
from scipy.io import loadmat

from mvcluster.cluster.lmgec import LMGEC
from mvcluster.utils.metrics import clustering_accuracy, clustering_f1_score
from mvcluster.utils.preprocess import preprocess_dataset


def load_custom_mat(path: str) -> Tuple[List[Tuple[np.ndarray, np.ndarray]], Optional[np.ndarray]]:  # noqa: E501
    """
    Load various possible .mat file formats with views and labels.
    Returns:
        views: list of (A, X) tuples
        labels: ndarray or None
    """
    from scipy.sparse import issparse

    mat = loadmat(path)
    Xs, As = [], []
    labels = None
    if "labels" in mat:
        labels = mat["labels"].squeeze()
    elif "label" in mat:
        labels = mat["label"].squeeze()
    if labels is not None and labels.ndim != 1:
        labels = labels.ravel()
    if labels is not None and not isinstance(labels, np.ndarray):
        labels = np.array(labels)

    i = 0
    while f"X_{i}" in mat and f"A_{i}" in mat:
        Xs.append(mat[f"X_{i}"])
        As.append(mat[f"A_{i}"].astype(np.float32))
        i += 1
    if Xs:
        return list(zip(As, Xs)), labels

    i = 1
    while f"X{i}" in mat:
        X = mat[f"X{i}"]
        A = np.eye(X.shape[0], dtype=np.float32)
        Xs.append(X)
        As.append(A)
        i += 1
    if Xs:
        return list(zip(As, Xs)), labels

    for key in ("features", "views"):
        if key in mat:
            value = mat[key]

            if issparse(value):
                # Cas : une seule matrice sparse (1 vue)
                A = np.eye(value.shape[0], dtype=np.float32)
                return [(A, value)], labels

            if isinstance(value, np.ndarray) and value.ndim == 2:
                # Cas : une seule matrice dense (1 vue)
                A = np.eye(value.shape[0], dtype=np.float32)
                return [(A, value)], labels

            try:
                # Cas : plusieurs vues stockées dans un array de shape (1, n)
                raw_views = value[0]
                for view in raw_views:
                    if issparse(view):
                        view = view.tocsr()
                    A = np.eye(view.shape[0], dtype=np.float32)
                    Xs.append(view)
                    As.append(A)
                return list(zip(As, Xs)), labels
            except Exception as e:
                raise ValueError(f"Unsupported format under key '{key}': {e}")


    if "fea" in mat and "W" in mat:  # noqa :303
        X = mat["fea"]
        A = mat["W"].astype(np.float32)
        Xs.append(X)
        As.append(A)
        if "gnd" in mat:
            labels = mat["gnd"].squeeze()
            if labels.ndim != 1:
                labels = labels.ravel()
            if not isinstance(labels, np.ndarray):
                labels = np.array(labels)
        return list(zip(As, Xs)), labels

    raise ValueError("Unsupported .mat file structure. Expected known keys.")

def run_once(views, labels, dim, temp, beta, max_iter, tol):  # noqa : 302
    """
    Run a single LMGEC clustering evaluation with detailed
    output and flake8 compliance.

    Args:
        views (List[Tuple[np.ndarray, np.ndarray]]): List of (A, X) views.
        labels (np.ndarray): Ground truth cluster labels.
        dim (int): Embedding dimension.
        temp (float): Temperature parameter.
        beta (float): Graph regularization coefficient.
        max_iter (int): Maximum number of iterations.
        tol (float): Tolerance for convergence.

    Returns:
        dict: Dictionary of evaluation metrics.
    """
    if labels is None:
        raise ValueError("Ground truth labels are required.")

    views_proc = []
    print("\n[ÉTAPE] Prétraitement des vues")
    for idx, (A, X) in enumerate(views):
        A_norm, X_proc = preprocess_dataset(A, X, beta=beta)
        if hasattr(X_proc, "toarray"):
            X_proc = X_proc.toarray()
        print(
            f"  → Vue {idx + 1}: A ({A.shape}), X ({X.shape}) → "
            f"A_norm ({A_norm.shape}), X_proc ({X_proc.shape})"
        )
        views_proc.append((A_norm, X_proc))

    print("\n[ÉTAPE] Calcul des embeddings (H = S @ X)")
    Hs = []
    for idx, (S, X) in enumerate(views_proc):
        H = S @ X
        if isinstance(H, np.matrix):
            print(f"  [AVERTISSEMENT] Vue {idx + 1} est un np.matrix → conversion en ndarray")  # noqa: E501
            H = np.asarray(H)
        H_scaled = StandardScaler(with_std=False).fit_transform(H)
        print(
            f"  → H_{idx + 1} = S @ X : {H.shape}, "
            f"après normalisation : {H_scaled.shape}"
        )
        Hs.append(H_scaled)

    print("\n[ÉTAPE] Entraînement du modèle LMGEC")
    model = LMGEC(
        n_clusters=len(np.unique(labels)),
        embedding_dim=dim,
        temperature=temp,
        max_iter=max_iter,
        tolerance=tol,
    )
    model.fit(Hs)
    pred = model.labels_
    print(f"  → Clustering terminé en {len(model.loss_history_)} itérations")

    metrics = {
        "acc": clustering_accuracy(labels, pred),
        "nmi": nmi(labels, pred),
        "ari": ari(labels, pred),
        "f1": clustering_f1_score(labels, pred, average="macro"),
    }
    print(
        f"[SCORE] ACC: {metrics['acc']:.4f}, "
        f"NMI: {metrics['nmi']:.4f}, "
        f"ARI: {metrics['ari']:.4f}, "
        f"F1: {metrics['f1']:.4f}"
    )

    return metrics


def main(args):
    views, labels = load_custom_mat(args.data_file)
    if labels is None:
        raise ValueError("Labels not found in dataset.")
    if args.n_clusters != len(np.unique(labels)):
        print(
            f"[WARN] --n_clusters ({args.n_clusters}) ≠ nb unique labels ({len(np.unique(labels))})"  # noqa: E501
        )

    temperatures = [0.1, 0.5, 1.0, 2.0, 10.0, 20.0]
    betas = [1.0, 2.0]
    embedding_dims = [3, 4, 5]

    results = []
    for temp, beta, dim in itertools.product(temperatures, betas, embedding_dims):  # noqa: E501
        print("\n" + "=" * 60)
        print(f"[TEST] Température={temp}, β={beta}, dim={dim}")
        metrics = run_once(
            views,
            labels,
            dim=dim,
            temp=temp,
            beta=beta,
            max_iter=args.max_iter,
            tol=args.tolerance,
        )
        metrics.update(temperature=temp, beta=beta, embedding_dim=dim)
        results.append(metrics)

    df = pd.DataFrame(results)
    df.to_csv("hyperparam_results.csv", index=False)

    print("\n[TOP CONFIGS PAR NMI]")
    print(df.sort_values("nmi", ascending=False).head())

    os.makedirs("plots", exist_ok=True)
    for metric in ("nmi", "ari", "acc", "f1"):
        plt.figure(figsize=(8, 5))
        sns.lineplot(
            data=df,
            x="temperature",
            y=metric,
            hue="embedding_dim",
            style="beta",
            markers=True,
        )
        plt.title(f"{metric.upper()} vs Température")
        plt.grid(True)
        plt.tight_layout()
        plt.savefig(f"plots/{metric}_vs_temperature.png")
        plt.close()


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--data_file", type=str, required=True)
    parser.add_argument("--n_clusters", type=int, required=True)
    parser.add_argument("--max_iter", type=int, default=50)
    parser.add_argument("--tolerance", type=float, default=1e-7)
    args = parser.parse_args()
    main(args)

Benchmark custom

"""
[EN]
Benchmark the LMGEC clustering algorithm on a custom multi-view dataset
stored in .mat format.

This script performs the following steps:

1. Load the multi-view dataset from a .mat file, where data is organized
   as pairs of adjacency matrices (A_i) and feature matrices (X_i) for
   each view, plus optional ground truth labels.

2. Preprocess each view by normalizing adjacency matrices and preparing
   feature matrices, converting sparse formats to dense if necessary.

3. Run the LMGEC clustering algorithm multiple times (specified by the
   'runs' parameter) with given hyperparameters, fitting the model on
   the preprocessed feature representations.

4. Evaluate clustering performance using metrics including Accuracy,
   Normalized Mutual Information (NMI), Adjusted Rand Index (ARI),
   F1 score, final loss value, and runtime.

5. Aggregate and print the average and standard deviation of these metrics
   over all runs to assess the algorithm’s stability and performance.

Command-line arguments allow flexible configuration of the dataset path,
number of clusters, number of runs, and algorithm-specific hyperparameters
such as temperature, beta (preprocessing), maximum iterations, and
convergence tolerance.

The script depends on external modules from the mvcluster package for the
LMGEC implementation, metrics, and preprocessing utilities.

Usage example:
    python benchmark_custom_lmgec.py --data_file path/to/data.mat
    --n_clusters 3 --runs 5 --temperature 1.0 --beta 1.0

[FR]
Évaluation de l'algorithme de clustering LMGEC sur un jeu de données
multi-vues personnalisé au format .mat.

Ce script réalise les étapes suivantes :

1. Chargement du jeu de données multi-vues depuis un fichier .mat, où les
   données sont organisées en paires de matrices d’adjacence (A_i) et
   matrices de caractéristiques (X_i) pour chaque vue, ainsi que les
   étiquettes de vérité terrain optionnelles.

2. Prétraitement de chaque vue en normalisant les matrices d’adjacence et
   en préparant les matrices de caractéristiques, en convertissant les
   formats creux en denses si nécessaire.

3. Exécution de l’algorithme de clustering LMGEC plusieurs fois (paramètre
   'runs') avec les hyperparamètres spécifiés, en ajustant le modèle sur
   les représentations prétraitées.

4. Évaluation de la performance du clustering à l’aide de métriques telles
   que la précision (Accuracy), l’information mutuelle normalisée (NMI),
   l’indice de Rand ajusté (ARI), le score F1, la valeur finale de la perte,
   et le temps d’exécution.

5. Agrégation et affichage de la moyenne et de l’écart-type de ces métriques
   sur toutes les exécutions pour mesurer la stabilité et l’efficacité de
   l’algorithme.

Les arguments en ligne de commande permettent de configurer le chemin du jeu
de données, le nombre de clusters, le nombre d’exécutions, ainsi que des
hyperparamètres spécifiques tels que la température, beta (prétraitement),
le nombre maximal d’itérations, et la tolérance de convergence.

Le script dépend de modules externes du package mvcluster pour
l’implémentation de LMGEC, les métriques et les outils de prétraitement.

Exemple d’utilisation :
    python benchmark_custom_lmgec.py --data_file chemin/vers/data.mat
    --n_clusters 3 --runs 5 --temperature 1.0 --beta 1.0

"""


import argparse
import time
import sys
import os

sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

import numpy as np  # noqa: E402
import scipy.io  # noqa: E402
from sklearn.preprocessing import StandardScaler  # noqa: E402, E501
from sklearn.metrics import adjusted_rand_score, normalized_mutual_info_score  # noqa: E402, E501

from mvcluster.cluster.lmgec import LMGEC  # noqa: E402
from mvcluster.utils.metrics import clustering_accuracy, clustering_f1_score  # noqa: E402, E501
from mvcluster.utils.preprocess import preprocess_dataset  # noqa: E402


def load_custom_mat(path):
    """Load .mat file with keys: X_0, A_0, X_1, A_1, ..., labels."""
    mat = scipy.io.loadmat(path)
    Xs, As = [], []
    i = 0
    while f"X_{i}" in mat and f"A_{i}" in mat:
        Xs.append(mat[f"X_{i}"])
        As.append(mat[f"A_{i}"].astype(np.float32))
        i += 1
    labels = mat["labels"].squeeze() if "labels" in mat else None
    return As, Xs, labels


def run_custom_lmgec_experiment(
    file_path,
    n_clusters,
    beta=1.0,
    temperature=1.0,
    max_iter=10,
    tolerance=1e-7,
    runs=5,
):
    As, Xs, labels = load_custom_mat(file_path)
    views = list(zip(As, Xs))
    for i, (A, X) in enumerate(views):
        norm_adj, feats = preprocess_dataset(A, X, beta=beta)
        if hasattr(feats, "toarray"):
            feats = feats.toarray()
        views[i] = (norm_adj, feats)

    metrics = {m: [] for m in ["acc", "nmi", "ari", "f1", "loss", "time"]}
    for _ in range(runs):
        start = time.time()
        Hs = [
            StandardScaler(with_std=False).fit_transform(S @ X) for S, X in views]  # noqa: E501

        model = LMGEC(
            n_clusters=n_clusters,
            embedding_dim=n_clusters + 1,
            temperature=temperature,
            max_iter=max_iter,
            tolerance=tolerance,
        )
        model.fit(Hs)

        duration = time.time() - start
        preds = model.labels_

        metrics["time"].append(duration)
        metrics["acc"].append(clustering_accuracy(labels, preds))
        metrics["nmi"].append(
            normalized_mutual_info_score(labels, preds)  # type: ignore
        )  # type: ignore
        metrics["ari"].append(adjusted_rand_score(labels, preds))  # noqa: E501
        metrics["f1"].append(
            clustering_f1_score(labels, preds, average="macro")  # type: ignore
        )  # type: ignore
        metrics["loss"].append(model.loss_history_[-1])

    print("\n=== Averaged Metrics over", runs, "runs ===")
    for key in metrics:
        mean = np.mean(metrics[key])
        std = np.std(metrics[key])
        print(f"{key.upper()}: {mean:.4f} ± {std:.4f}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="Benchmark LMGEC on a custom multi-view dataset"
    )
    parser.add_argument(
        "--data_file",
        type=str,
        required=True,
        help="Path to .mat file containing X_i, A_i, labels",
    )
    parser.add_argument(
        "--n_clusters",
        type=int,
        required=True,
        help="Number of clusters in ground truth",
    )
    parser.add_argument(
        "--runs", type=int, default=5, help="Number of runs to average metrics"
    )
    parser.add_argument(
        "--temperature",
        type=float,
        default=1.0,
        help="Temperature parameter for LMGEC",
    )
    parser.add_argument(
        "--beta", type=float, default=1.0,
        help="Beta for graph-feature preprocessing"
        )
    parser.add_argument("--max_iter", type=int, default=10)
    parser.add_argument("--tolerance", type=float, default=1e-7)

    args = parser.parse_args()

    run_custom_lmgec_experiment(
        file_path=args.data_file,
        n_clusters=args.n_clusters,
        beta=args.beta,
        temperature=args.temperature,
        max_iter=args.max_iter,
        tolerance=args.tolerance,
        runs=args.runs,
    )