add logging + toy data + fix tuto

Author: quentinblampey

.gitignore

@@ -1,5 +1,6 @@
 # Other
 .DS_Store
+sandbox/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

customics/__init__.py

@@ -1,6 +1,12 @@
 import importlib.metadata
+import logging
 
+from ._logging import configure_logger
 from . import datasets, metrics
+from .utils import get_common_samples, get_sub_omics_df, toy_dataset
 from .model import CustOMICS
 
 __version__ = importlib.metadata.version("customics")
+
+log = logging.getLogger("customics")
+configure_logger(log)

customics/_logging.py

@@ -0,0 +1,38 @@
+import logging
+
+log = logging.getLogger(__name__)
+
+
+class ColorFormatter(logging.Formatter):
+    grey = "\x1b[38;20m"
+    blue = "\x1b[36;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+
+    prefix = "[%(levelname)s] (%(name)s)"
+    suffix = "%(message)s"
+
+    FORMATS = {
+        logging.DEBUG: f"{grey}{prefix}{reset} {suffix}",
+        logging.INFO: f"{blue}{prefix}{reset} {suffix}",
+        logging.WARNING: f"{yellow}{prefix}{reset} {suffix}",
+        logging.ERROR: f"{red}{prefix}{reset} {suffix}",
+        logging.CRITICAL: f"{bold_red}{prefix}{reset} {suffix}",
+    }
+
+    def format(self, record):
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def configure_logger(log: logging.Logger):
+    log.setLevel(logging.INFO)
+
+    consoleHandler = logging.StreamHandler()
+    consoleHandler.setFormatter(ColorFormatter())
+
+    log.addHandler(consoleHandler)
+    log.propagate = False

customics/explain/shap.py

@@ -1,5 +1,7 @@
 """SHAP-based explainability utilities for customics models."""
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 import pandas as pd

customics/metrics/classification.py

@@ -90,7 +90,7 @@ def multi_classification_evaluation(
         )
         plt.xlabel("Predicted Labels")
         plt.ylabel("True Labels")
-        plt.savefig(filename + ".png")
+        plt.savefig(str(filename) + ".png")
         plt.clf()
     return scores
 

customics/model.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from pathlib import Path
 
 import numpy as np
 import pandas as pd
@@ -885,7 +886,7 @@ def stratify(
     # Serialisation
     # ---------------------------------------------------------------------- #
 
-    def save(self, path: str) -> None:
+    def save(self, path: str | Path) -> None:
         """Save the model architecture config and trained weights to *path*.
 
         The checkpoint contains the five parameter dicts needed to reconstruct
@@ -909,11 +910,15 @@ def save(self, path: str) -> None:
             "history": self.history,
             "_is_fitted": self._is_fitted,
         }
+
+        checkpoint_path = Path(path)
+        checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
+
         torch.save(checkpoint, path)
-        logger.info("Model saved to %s", path)
+        logger.info(f"Model saved to {path}")
 
     @classmethod
-    def load(cls, path: str, device: torch.device | None = None) -> CustOMICS:
+    def load(cls, path: str | Path, device: torch.device | None = None) -> CustOMICS:
         """Load a model previously saved with [save](api/train/#customics.CustOMICS.save).
 
         Parameters
@@ -945,5 +950,5 @@ def load(cls, path: str, device: torch.device | None = None) -> CustOMICS:
         model.history = checkpoint.get("history", [])
         model._is_fitted = checkpoint.get("_is_fitted", True)
         model.to(device)
-        logger.info("Model loaded from %s", path)
+        logger.info(f"Model loaded from {path}")
         return model

customics/utils.py

@@ -2,6 +2,7 @@
 
 import os
 
+import numpy as np
 import pandas as pd
 import seaborn as sns
 from sklearn.model_selection import KFold, train_test_split
@@ -10,6 +11,36 @@
 sns.set_palette("muted")
 sns.set_context("notebook", font_scale=1.5, rc={"lines.linewidth": 2.5})
 
+# ---------------------------------------------------------------------------
+# Toy dataset loader
+# ---------------------------------------------------------------------------
+
+
+def toy_dataset() -> tuple[dict[str, pd.DataFrame], pd.DataFrame]:
+    """Load toy multi-omics dataset from GitHub.
+
+    Returns
+    -------
+    tuple of (dict, pd.DataFrame)
+        - dict: Multi-omics dictionary (source name → DataFrame).
+        - DataFrame: Clinical metadata with sample IDs as index.
+    """
+    PREFIX = "https://raw.githubusercontent.com/prism-oncology/customics/refs/heads/main/data"
+
+    omics_df = {
+        "protein": pd.read_csv(f"{PREFIX}/toy_data/protein.txt", sep="\t", index_col=0).T,
+        "gene_exp": pd.read_csv(f"{PREFIX}/toy_data/gene_exp.txt", sep="\t", index_col=0).T,
+        "methyl": pd.read_csv(f"{PREFIX}/toy_data/methyl.txt", sep="\t", index_col=0).T,
+    }
+
+    clinical_df = pd.read_csv(f"{PREFIX}/toy_data/labels.txt", sep="\t", index_col=1, header=0)
+
+    rng = np.random.default_rng(42)
+    clinical_df["OS"] = rng.integers(0, 2, size=len(clinical_df))  # 0 = censored, 1 = event
+    clinical_df["OS.time"] = rng.integers(200, 3000, size=len(clinical_df))  # days
+
+    return omics_df, clinical_df
+
 
 # ---------------------------------------------------------------------------
 # Sample alignment

customics/visualization.py

@@ -1,9 +1,12 @@
 """Visualisation helpers for trained customics models."""
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 import numpy as np
+import pandas as pd
 import seaborn as sns
 from sklearn.manifold import TSNE
 
@@ -167,7 +170,7 @@ def save_plot_score(filename: str, z: np.ndarray, y: np.ndarray, title: str, sho
     show : bool
         If True, display the plot interactively after saving.
     """
-    tsne = TSNE(n_components=2, verbose=0, perplexity=40, n_iter=300)
+    tsne = TSNE(n_components=2, verbose=0, perplexity=40)
     embedding = tsne.fit_transform(z)
     df = pd.DataFrame({"targets": y, "x-axis": embedding[:, 0], "y-axis": embedding[:, 1]})
     sns.scatterplot(
@@ -179,7 +182,7 @@ def save_plot_score(filename: str, z: np.ndarray, y: np.ndarray, title: str, sho
     )
     plt.title(title)
     plt.legend(bbox_to_anchor=(1.5, 1.1), loc=2, borderaxespad=0.0)
-    plt.savefig(filename + ".png", bbox_inches="tight")
+    plt.savefig(str(filename) + ".png", bbox_inches="tight")
     if show:
         plt.show()
     plt.clf()

docs/getting_started.md

@@ -39,96 +39,6 @@ Choose one of the following, depending on your needs:
     uv sync --dev
     ```
 
-## Usage
-`CustOmics` provides a simple, scikit-learn–style `API` through the customics package. Below is a complete example showing how to train, evaluate, and interpret a multi-omics model:
-
-#### 1. Prepare your data
-`omics_train`: *dict mapping source name → pd.DataFrame (samples × features)*<br>
-`clinical_df`: *pd.DataFrame with columns for labels, event indicator, and survival time.*
-
-
-``` python
-import torch
-import pandas as pd
-from customics import CustOMICS
-
-omics_train = {
-    "rna":   pd.read_csv("rna_train.csv",   index_col=0),
-    "cnv":   pd.read_csv("cnv_train.csv",   index_col=0),
-    "methyl": pd.read_csv("methyl_train.csv", index_col=0),
-}
-clinical_df = pd.read_csv("clinical.csv", index_col=0)
-```
-
-#### 2. Configure the model
-
-``` python
-source_params = {
-    "rna":   {"input_dim": 5000, "hidden_dim": [1024, 512], "latent_dim": 128, "norm": True, "dropout": 0.2},
-    "cnv":   {"input_dim": 2000, "hidden_dim": [512, 256],  "latent_dim": 128, "norm": True, "dropout": 0.2},
-    "methyl":{"input_dim": 8000, "hidden_dim": [1024, 512], "latent_dim": 128, "norm": True, "dropout": 0.2},
-}
-central_params = {"hidden_dim": [512, 256], "latent_dim": 128, "norm": True, "dropout": 0.2, "beta": 1}
-classif_params = {"n_class": 5, "lambda": 5.0, "hidden_layers": [128, 64], "dropout": 0.2}
-surv_params    = {"lambda": 1.0, "dims": [64, 32], "activation": "SELU",
-                  "l2_reg": 1e-2, "norm": True, "dropout": 0.2}
-train_params   = {"switch": 10, "lr": 1e-3}
-
-device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-```
-
-#### 3. Train
-
-``` python
-model = CustOMICS(
-    source_params=source_params,
-    central_params=central_params,
-    classif_params=classif_params,
-    surv_params=surv_params,
-    train_params=train_params,
-    device=device,
-)
-model.fit(
-    omics_train=omics_train,
-    clinical_df=clinical_df,
-    label="PAM50",       # classification target column
-    event="OS",          # survival event column (0/1)
-    surv_time="OS.time", # survival time column
-    omics_val=omics_val, # optional validation set
-    batch_size=32,
-    n_epochs=30,
-    verbose=True,
-)
-```
-
-#### 4. Evaluate
-Classification metrics (Accuracy, F1, AUC, …)
-
-``` python
-metrics = model.evaluate(
-    omics_test, clinical_df,
-    label="PAM50", event="OS", surv_time="OS.time",
-    task="classification",
-)
-# Survival concordance index
-ci = model.evaluate(
-    omics_test, clinical_df,
-    label="PAM50", event="OS", surv_time="OS.time",
-    task="survival",
-)
-```
-
-#### 4. Visualise & explain
-
-``` python
-model.plot_loss()
-model.plot_representation(omics_train, clinical_df, label="PAM50",
-                          filename="latent_space", title="t-SNE of latent space")
-model.stratify(omics_train, clinical_df, event="OS", surv_time="OS.time")
-model.explain(sample_ids, omics_train, clinical_df,
-              source="rna", subtype="Her2", label="PAM50")
-```
-
 ## Next steps
 
 See our main tutorial [here](tutorials/usage) for more details, or our [API](api/train/).