deepal6 1.0.0__py3-none-any.whl

deepal6/__init__.py

@@ -0,0 +1,56 @@
+"""
+DeepAL6 — Deep Active Learning Library
+======================================
+A flexible, research-grade active learning framework supporting 6 query
+strategies compared against a random baseline, for both tabular and image
+domains.
+
+Strategies
+----------
+- Random      : Uniform random draw (baseline)
+- Entropy     : Highest predictive entropy H[y|x]
+- Margin      : Smallest top-2 class probability gap
+- BALD        : Mutual information I[y;θ|x,D] via MC Dropout
+- CoreSet     : Greedy k-center covering in embedding space
+- BADGE       : Gradient embeddings + k-means++ diversity
+
+Quickstart
+----------
+    from deepal6 import ActiveLearner, TabularDataModule
+
+    data = TabularDataModule(X_train, y_train, X_test, y_test)
+    learner = ActiveLearner(data, strategy="BALD")
+    results = learner.run(initial_size=50, batch_size=20, n_rounds=20)
+    learner.plot(results)
+"""
+
+import deepal6.strategies.query  # registers all 6 strategies into STRATEGIES dict
+from deepal6.learner import ActiveLearner
+from deepal6.data.tabular import TabularDataModule
+from deepal6.data.image import ImageDataModule
+from deepal6.strategies.registry import STRATEGIES, list_strategies
+from deepal6.config import ALConfig
+from deepal6.exceptions import (
+    DeepALError,
+    ConfigurationError,
+    DataError,
+    StrategyError,
+    ModelError,
+)
+
+__version__ = "1.0.0"
+__author__ = "Bob Philip Aila — AIMS Rwanda"
+
+__all__ = [
+    "ActiveLearner",
+    "TabularDataModule",
+    "ImageDataModule",
+    "STRATEGIES",
+    "list_strategies",
+    "ALConfig",
+    "DeepALError",
+    "ConfigurationError",
+    "DataError",
+    "StrategyError",
+    "ModelError",
+]

deepal6/config.py

@@ -0,0 +1,203 @@
+"""
+deepal.config
+-------------
+ALConfig is the single source of truth for all experiment hyper-parameters.
+Every parameter has a sensible default drawn from the thesis experiments.
+All values are validated on construction so errors surface early.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+from deepal6.exceptions import ConfigurationError
+from deepal6.strategies.registry import STRATEGIES
+
+
+@dataclass
+class ALConfig:
+    """
+    Configuration for an active learning experiment.
+
+    Parameters
+    ----------
+    strategy : str or list of str
+        Query strategy name(s). One of:
+        'Random', 'Entropy', 'Margin', 'BALD', 'CoreSet', 'BADGE'.
+        Pass a list to run multiple strategies in one experiment.
+        Default: all 6 strategies.
+    initial_size : int
+        Number of samples in the initial labeled set L0.
+        The draw is always stratified (equal class proportions) to
+        prevent the random baseline from winning by luck.
+        Default: 50.
+    batch_size : int
+        Number of samples queried from the pool per AL round.
+        Smaller batches (10–20) favour uncertainty strategies;
+        larger batches (50+) favour diversity strategies (CoreSet, BADGE).
+        Default: 20.
+    n_rounds : int
+        Maximum number of active learning rounds.
+        Total labelling budget = initial_size + n_rounds * batch_size.
+        Default: 20.
+    n_seeds : int
+        Number of independent runs per strategy (different random seeds).
+        Mean ± std across seeds is reported.  ≥3 recommended for publication.
+        Default: 5.
+    train_epochs : int
+        Epochs to train at each AL round.
+        Default: 50 (tabular) — ImageDataModule overrides to 10.
+    lr : float
+        Adam learning rate.  Default: 1e-3 (tabular), 1e-4 (image).
+    weight_decay : float
+        L2 regularisation strength.  Default: 1e-4.
+    dropout_rate : float
+        Dropout probability used in both CreditNet and ResNet-18 head.
+        Also controls MC Dropout stochasticity for BALD.
+        Default: 0.3.
+    mc_passes : int
+        Number of stochastic forward passes for BALD.
+        Higher = lower variance estimate, higher cost.
+        Default: 20.
+    train_batch_size : int
+        Mini-batch size used during model training (not AL batch size).
+        Default: 32.
+    device : str or None
+        'cuda', 'cpu', or None (auto-detect).  Default: None.
+    seed : int
+        Base random seed.  Each of the n_seeds runs uses seed+i.
+        Default: 42.
+    verbose : bool
+        Print per-round metrics during the experiment.  Default: True.
+    save_checkpoints : bool
+        Save the best model checkpoint per strategy per seed.
+        Default: False.
+    checkpoint_dir : str
+        Directory for checkpoints (only used if save_checkpoints=True).
+        Default: './checkpoints'.
+    extra_strategy_kwargs : dict
+        Extra keyword arguments forwarded to specific strategy functions.
+        E.g., {'mc_passes': 30} overrides the top-level mc_passes for BALD.
+        Default: {}.
+
+    Examples
+    --------
+    # Single strategy, quick experiment
+    cfg = ALConfig(strategy='BALD', initial_size=30, batch_size=10, n_rounds=15)
+
+    # Compare all strategies with publication-quality settings
+    cfg = ALConfig(n_seeds=5, train_epochs=50)
+
+    # Image domain — fewer epochs, lower LR, larger batches
+    cfg = ALConfig(strategy=['BALD', 'CoreSet', 'Random'],
+                   train_epochs=10, lr=1e-4, batch_size=20)
+    """
+
+    strategy: Any = field(default_factory=lambda: list(STRATEGIES.keys()))
+    initial_size: int = 50
+    batch_size: int = 20
+    n_rounds: int = 20
+    n_seeds: int = 5
+    train_epochs: int = 50
+    lr: float = 1e-3
+    weight_decay: float = 1e-4
+    dropout_rate: float = 0.3
+    mc_passes: int = 20
+    train_batch_size: int = 32
+    device: Optional[str] = None
+    seed: int = 42
+    verbose: bool = True
+    save_checkpoints: bool = False
+    checkpoint_dir: str = "./checkpoints"
+    extra_strategy_kwargs: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        self._validate()
+
+    def _validate(self):
+        """Validate all parameters; raise ConfigurationError with clear message."""
+        # Normalise strategy to list
+        if isinstance(self.strategy, str):
+            self.strategy = [self.strategy]
+
+        unknown = [s for s in self.strategy if s not in STRATEGIES]
+        if unknown:
+            raise ConfigurationError(
+                f"Unknown strategy name(s): {unknown}.\n"
+                f"Available strategies: {list(STRATEGIES.keys())}.\n"
+                f"Tip: strategy names are case-sensitive. "
+                f"Use deepal.list_strategies() to see all options."
+            )
+
+        if self.initial_size < 2:
+            raise ConfigurationError(
+                f"initial_size must be at least 2 (got {self.initial_size}). "
+                f"You need at least one sample per class for a meaningful start."
+            )
+
+        if self.batch_size < 1:
+            raise ConfigurationError(
+                f"batch_size must be >= 1 (got {self.batch_size}). "
+                f"Typical values: 10–50."
+            )
+
+        if self.n_rounds < 1:
+            raise ConfigurationError(
+                f"n_rounds must be >= 1 (got {self.n_rounds})."
+            )
+
+        if self.n_seeds < 1:
+            raise ConfigurationError(
+                f"n_seeds must be >= 1 (got {self.n_seeds}). "
+                f"Use n_seeds >= 3 for statistically meaningful results."
+            )
+
+        if self.train_epochs < 1:
+            raise ConfigurationError(
+                f"train_epochs must be >= 1 (got {self.train_epochs})."
+            )
+
+        if not (0.0 < self.lr < 1.0):
+            raise ConfigurationError(
+                f"lr={self.lr} looks suspicious. Typical range: 1e-5 to 1e-2."
+            )
+
+        if not (0.0 <= self.dropout_rate < 1.0):
+            raise ConfigurationError(
+                f"dropout_rate must be in [0, 1) (got {self.dropout_rate})."
+            )
+
+        if self.mc_passes < 1:
+            raise ConfigurationError(
+                f"mc_passes must be >= 1 (got {self.mc_passes}). "
+                f"BALD typically uses 20–50 passes."
+            )
+
+        if self.device not in (None, "cpu", "cuda"):
+            raise ConfigurationError(
+                f"device must be None, 'cpu', or 'cuda' (got '{self.device}')."
+            )
+
+    @property
+    def total_budget(self) -> int:
+        """Maximum number of labeled samples at end of experiment."""
+        return self.initial_size + self.n_rounds * self.batch_size
+
+    def summary(self) -> str:
+        """Human-readable parameter summary."""
+        lines = [
+            "=" * 55,
+            "  ALConfig — Experiment Parameters",
+            "=" * 55,
+            f"  Strategies     : {self.strategy}",
+            f"  Initial size   : {self.initial_size}",
+            f"  Batch size     : {self.batch_size}",
+            f"  Rounds         : {self.n_rounds}",
+            f"  Seeds          : {self.n_seeds}",
+            f"  Total budget   : {self.total_budget} labels",
+            f"  Train epochs   : {self.train_epochs}",
+            f"  LR / dropout   : {self.lr} / {self.dropout_rate}",
+            f"  MC passes      : {self.mc_passes} (BALD)",
+            f"  Device         : {self.device or 'auto'}",
+            "=" * 55,
+        ]
+        return "\n".join(lines)

deepal6/data/__init__.py

@@ -0,0 +1,5 @@
+from deepal6.data.base import BaseDataModule
+from deepal6.data.tabular import TabularDataModule
+from deepal6.data.image import ImageDataModule
+
+__all__ = ["BaseDataModule", "TabularDataModule", "ImageDataModule"]

deepal6/data/base.py

@@ -0,0 +1,119 @@
+"""
+deepal.data.base
+----------------
+Abstract base class for all DataModules.
+
+A DataModule wraps your dataset and exposes a standard interface that all
+query strategies use:
+    - predict_proba(model, indices, mc_passes=1)
+    - get_embeddings(model, indices)
+    - get_gradient_embeddings(model, indices)
+    - labels          : np.ndarray of all training labels
+    - n_train         : total pool size
+"""
+
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class BaseDataModule(ABC):
+    """
+    Abstract interface every DataModule must implement.
+
+    Subclass this to add support for new data types (e.g. text, graphs).
+    """
+
+    @property
+    @abstractmethod
+    def labels(self) -> np.ndarray:
+        """Full array of training labels (length = n_train)."""
+        ...
+
+    @property
+    @abstractmethod
+    def n_train(self) -> int:
+        """Total number of training samples in the pool."""
+        ...
+
+    @abstractmethod
+    def predict_proba(
+        self,
+        model,
+        indices,
+        mc_passes: int = 1,
+    ) -> np.ndarray:
+        """
+        Predict class probabilities for the given pool indices.
+
+        Parameters
+        ----------
+        model : nn.Module
+            Trained PyTorch model.
+        indices : array-like of int
+            Global indices into the training pool.
+        mc_passes : int
+            1  → standard deterministic inference, shape (N,).
+            >1 → MC Dropout passes, shape (mc_passes, N).
+
+        Returns
+        -------
+        np.ndarray of float in (0, 1).
+        """
+        ...
+
+    @abstractmethod
+    def get_embeddings(self, model, indices) -> np.ndarray:
+        """
+        Extract penultimate-layer embeddings for the given indices.
+
+        Returns
+        -------
+        np.ndarray, shape (len(indices), embedding_dim).
+        """
+        ...
+
+    @abstractmethod
+    def get_gradient_embeddings(self, model, indices) -> np.ndarray:
+        """
+        Compute gradient embeddings (∇_{θ_last} BCE) for BADGE.
+
+        Returns
+        -------
+        np.ndarray, shape (len(indices), n_last_weights).
+        """
+        ...
+
+    @abstractmethod
+    def train_model(self, model, labeled_idx, config) -> None:
+        """
+        Train model in-place on the current labeled set.
+
+        Parameters
+        ----------
+        model : nn.Module
+        labeled_idx : list of int
+        config : ALConfig
+        """
+        ...
+
+    @abstractmethod
+    def evaluate(self, model) -> dict:
+        """
+        Evaluate model on the held-out test set.
+
+        Returns
+        -------
+        dict with keys: 'accuracy', 'auc', 'bal_acc', 'recall', 'ece'.
+        """
+        ...
+
+    @abstractmethod
+    def build_model(self, config) -> "nn.Module":
+        """
+        Construct and return a fresh model (reset weights each AL round).
+
+        Parameters
+        ----------
+        config : ALConfig
+        """
+        ...