melite 0.1.11__py3-none-any.whl

melite/__init__.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""MELITE — multi-model selection, cross-validation and export toolkit.
+
+Public API
+----------
+The following symbols are part of the stable public API:
+
+    from melite import Config
+    from melite import load_dataset
+    from melite import ResultManager
+    from melite import plot_cv_distributions
+    from melite import predict
+    from melite import __version__
+"""
+
+import logging
+
+from .config import Config
+from .load_dataset import load_dataset
+from .result_manager import ResultManager
+from .plot_metrics import plot_cv_distributions
+from .predict import predict
+from .version import __version__
+
+__all__ = [
+    "Config",
+    "load_dataset",
+    "ResultManager",
+    "plot_cv_distributions",
+    "predict",
+    "__version__",
+]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

melite/cli.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Unified CLI entry point for MELITE.
+
+This module provides the ``melite`` command registered in ``pyproject.toml``
+under ``[project.scripts]``. It exposes two subcommands:
+
+- ``melite run`` — execute the full benchmarking pipeline.
+- ``melite export`` — retrain a selected model and export a ``.pkl`` artifact.
+
+Global flags (``--verbose``, ``--config``, ``--version``) are available to
+all subcommands via argparse parent parsers.
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from .version import __version__
+
+__all__ = ["main"]
+
+logger = logging.getLogger(__name__)
+
+
+def _global_parser() -> argparse.ArgumentParser:
+    """Return a parent parser with shared flags for all subcommands."""
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable progress logging (INFO level).",
+    )
+    parent.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Path to a user TOML configuration file. Overrides defaults.",
+    )
+    return parent
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    global_parent = _global_parser()
+
+    parser = argparse.ArgumentParser(
+        prog="melite",
+        description="MELITE — multi-model selection, cross-validation and export toolkit.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        parents=[global_parent],
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"MELITE {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    subparsers.required = True
+
+    # ------------------------------------------------------------------ #
+    # melite run
+    # ------------------------------------------------------------------ #
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run the full benchmarking pipeline.",
+        description="Run grid search and cross-validation over all configured datasets and models.",
+        parents=[global_parent],
+    )
+    run_parser.add_argument(
+        "--smoke",
+        action="store_true",
+        help=(
+            "Lightweight mode: single-value grids and 3-fold CV. "
+            "Results are not benchmark-quality."
+        ),
+    )
+
+    # ------------------------------------------------------------------ #
+    # melite export
+    # ------------------------------------------------------------------ #
+    export_parser = subparsers.add_parser(
+        "export",
+        help="Export a selected model from results.csv.",
+        description="Retrain a selected model on all available data and save a .pkl artifact.",
+        parents=[global_parent],
+    )
+    export_parser.add_argument(
+        "--row",
+        type=int,
+        default=None,
+        metavar="INDEX",
+        help="Row index from results.csv to export without interactive prompt.",
+    )
+    export_parser.add_argument(
+        "--csv",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Path to results CSV file. Defaults to output/results.csv.",
+    )
+    export_parser.add_argument(
+        "--outdir",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="Destination directory for the .pkl artifact. Defaults to output/.",
+    )
+    export_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Override smoke-mode export guard. Use with caution.",
+    )
+
+    return parser
+
+
+def _configure_logging(verbose: bool) -> None:
+    level = logging.INFO if verbose else logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(levelname)s:%(name)s:%(message)s",
+    )
+
+
+def _run(args: argparse.Namespace) -> None:
+    from .main import Main
+    Main(smoke=args.smoke, user_config=args.config).run()
+
+
+def _export(args: argparse.Namespace) -> None:
+    from .config import Config
+    from .export_best_model import Finalizer
+
+    config = Config(user_config=args.config)
+    csv_path = args.csv or Path(config.PATHS["OUTPUT"]) / "results.csv"
+    outdir = args.outdir or Path(config.PATHS["OUTPUT"])
+    Finalizer(csv_path, outdir, config, row_index=args.row,
+              force=getattr(args, "force", False)).run()
+
+
+def main() -> None:
+    """Entry point for the ``melite`` CLI command.
+
+    Registered in ``pyproject.toml`` as::
+
+        [project.scripts]
+        melite = "melite.cli:main"
+
+    Parses arguments, configures logging, and dispatches to the appropriate
+    subcommand handler (``_run`` or ``_export``).
+
+    Notes
+    -----
+    The ``--verbose`` flag sets the root logger to ``INFO`` level, which
+    exposes progress messages from all ``melite.*`` modules. Without it,
+    only ``WARNING`` and above are shown.
+    """
+    parser = _build_parser()
+    args = parser.parse_args()
+    _configure_logging(args.verbose)
+
+    if args.command == "run":
+        _run(args)
+    elif args.command == "export":
+        _export(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

melite/config.py

@@ -0,0 +1,263 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Configuration loader for MELITE.
+
+Reads ``melite/config_default.toml`` as the base configuration.
+An optional user-supplied TOML file can override any key via deep merge.
+Hyperparameter grids are defined here in Python — they are developer-facing
+and not expected to change between runs.
+
+The :class:`Config` object is the single entry point for all runtime
+settings. It is designed to be instantiated without filesystem side effects;
+call :meth:`Config.setup` explicitly from pipeline entry points.
+"""
+
+import os
+import random
+import tomllib
+from pathlib import Path
+
+import numpy as np
+from sklearn.model_selection import ParameterGrid
+
+__all__ = ["Config"]
+
+# Path to the default configuration file bundled with the package
+_DEFAULT_CONFIG = Path(__file__).parent / "config_default.toml"
+
+
+def _load_toml(path: Path) -> dict:
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Merge *override* into *base* recursively. Override wins on conflict."""
+    result = base.copy()
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+class Config:
+    """Configuration container for MELITE.
+
+    Loads defaults from ``melite/config_default.toml``. If *user_config* is
+    provided, its values are merged over the defaults — user values win and
+    missing keys fall back to defaults.
+
+    Parameters
+    ----------
+    smoke : bool, optional
+        If ``True``, use reduced CV settings and single-value hyperparameter
+        grids for lightweight runs. Default is ``False``.
+    user_config : pathlib.Path or None, optional
+        Path to a user-supplied TOML file. Only the keys present in this file
+        override the defaults. Default is ``None``.
+
+    Attributes
+    ----------
+    SMOKE : bool
+        Whether the instance was created in smoke mode.
+    PATHS : dict
+        Dictionary with keys ``"INPUT"``, ``"DATASET"``, and ``"OUTPUT"``
+        mapping to the corresponding directory paths as strings.
+    RESULTS_FILE : str
+        Full path to the TXT results file (``output/results.txt`` by default).
+    RANDOM_STATE : int
+        Global random seed. Default is ``42``.
+    REDUCTION_TYPES : list of str
+        Reduction methods to benchmark (e.g. ``["PCA", "UMAP"]``).
+    REDUCTION_LEVELS : list of int
+        Variance retention levels to benchmark (e.g. ``[70, 75, 80, 85, 90, 95]``).
+    ACTIVE_MODELS : list of str
+        Model keys to include in the benchmark (e.g. ``["svc", "rf", "xgb"]``).
+    CV_CONFIG : dict
+        Cross-validation settings with keys ``n_splits``, ``n_repeats``, and
+        ``random_state``.
+    PARAM_GRID : list of dict
+        Raw hyperparameter grid definitions, one entry per model configuration.
+    PARAM_GRID_BY_MODEL : dict
+        Compiled :class:`~sklearn.model_selection.ParameterGrid` objects keyed
+        by model name (``"svc"``, ``"rf"``, ``"xgb"``).
+
+    Examples
+    --------
+    Default configuration:
+
+    >>> cfg = Config()
+    >>> cfg.RANDOM_STATE
+    42
+
+    Smoke mode with a user override:
+
+    >>> cfg = Config(smoke=True, user_config=Path("my_config.toml"))
+    >>> cfg.CV_CONFIG["n_splits"]
+    3
+    """
+
+    def __init__(
+        self,
+        smoke: bool = False,
+        user_config: Path | None = None,
+    ):
+        self.SMOKE = smoke
+
+        # Load and merge configuration
+        cfg = _load_toml(_DEFAULT_CONFIG)
+        if user_config is not None:
+            user_cfg = _load_toml(Path(user_config))
+            cfg = _deep_merge(cfg, user_cfg)
+
+        # Paths
+        self.PATHS = {
+            "INPUT":   cfg["paths"]["input"],
+            "DATASET": cfg["paths"]["dataset"],
+            "OUTPUT":  cfg["paths"]["output"],
+        }
+        self.RESULTS_FILE = os.path.join(self.PATHS["OUTPUT"], "results.txt")
+
+        # Benchmark settings
+        self.RANDOM_STATE     = cfg["benchmark"]["random_state"]
+        self.REDUCTION_TYPES  = cfg["benchmark"]["reduction_types"]
+        self.REDUCTION_LEVELS = cfg["benchmark"]["levels"]
+        self.ACTIVE_MODELS    = cfg["models"]["active"]
+
+        # Cross-validation
+        cv_section = cfg["cv_smoke"] if smoke else cfg["cv"]
+        self.CV_CONFIG = {
+            "n_splits":     cv_section["n_splits"],
+            "n_repeats":    cv_section["n_repeats"],
+            "random_state": self.RANDOM_STATE,
+        }
+
+        # Hyperparameter grids — developer-facing, defined in Python
+        self.PARAM_GRID = self._build_param_grid()
+        self.PARAM_GRID_BY_MODEL = self._group_param_grid_by_model()
+
+    # ------------------------------------------------------------------ #
+    # Hyperparameter grids
+    # ------------------------------------------------------------------ #
+
+    def _build_param_grid(self) -> list:
+        if self.SMOKE:
+            return [
+                {
+                    "model": ["svc"],
+                    "kernel": ["linear"],
+                    "C": [1],
+                },
+                {
+                    "model": ["rf"],
+                    "n_estimators": [50],
+                    "max_depth": [5],
+                    "max_features": ["sqrt"],
+                    "min_samples_split": [2],
+                    "min_samples_leaf": [1],
+                },
+                {
+                    "model": ["xgb"],
+                    "n_estimators": [20],
+                    "learning_rate": [0.1],
+                    "max_depth": [3],
+                    "subsample": [0.8],
+                    "colsample_bytree": [1.0],
+                    "gamma": [0],
+                    "reg_alpha": [0],
+                    "reg_lambda": [1],
+                },
+            ]
+        return [
+            {
+                "model": ["svc"],
+                "kernel": ["poly"],
+                "C": [0.01, 0.1, 1, 10],
+                "coef0": [0.0, 0.1, 0.02, 0.6, 0.8, 1],
+                "gamma": [0.001, 0.002, 0.004, 0.008, 0.01, 0.02, 0.04, 0.08, 0.1, 0.2],
+                "degree": [3, 4, 5],
+            },
+            {
+                "model": ["svc"],
+                "kernel": ["rbf"],
+                "C": [0.01, 0.02, 0.1, 0.2, 1, 2, 10, 20],
+                "gamma": [0.001, 0.002, 0.004, 0.008, 0.01, 0.02, 0.04, 0.08, 0.1, 0.2],
+            },
+            {
+                "model": ["rf"],
+                "n_estimators": [200, 400, 800],
+                "max_depth": [None, 10, 20, 30, 40],
+                "max_features": ["sqrt", "log2"],
+                "min_samples_split": [2, 5],
+                "min_samples_leaf": [1, 2],
+            },
+            {
+                "model": ["xgb"],
+                "n_estimators": [300, 400, 600],
+                "learning_rate": [0.01, 0.05, 0.1],
+                "max_depth": [4, 6, 8],
+                "subsample": [0.7, 0.85],
+                "colsample_bytree": [0.7, 1.0],
+                "gamma": [0, 0.01, 1, 5],
+                "reg_alpha": [0, 0.5],
+                "reg_lambda": [1, 2],
+            },
+        ]
+
+    def _group_param_grid_by_model(self) -> dict:
+        grids: dict = {}
+        for entry in self.PARAM_GRID:
+            model = entry["model"][0]
+            grids.setdefault(model, []).append(
+                {k: v for k, v in entry.items() if k != "model"}
+            )
+        return {m: ParameterGrid(g) for m, g in grids.items()}
+
+    # ------------------------------------------------------------------ #
+    # Public accessors
+    # ------------------------------------------------------------------ #
+
+    def get_cv_config(self) -> dict:
+        """Return the cross-validation configuration dictionary.
+
+        Returns
+        -------
+        dict
+            Dictionary with keys ``n_splits``, ``n_repeats``, and
+            ``random_state``.
+        """
+        return self.CV_CONFIG
+
+    def get_param_grid(self, model: str) -> ParameterGrid:
+        """Return the compiled hyperparameter grid for a given model.
+
+        Parameters
+        ----------
+        model : str
+            Model key. One of ``"svc"``, ``"rf"``, or ``"xgb"``.
+
+        Returns
+        -------
+        sklearn.model_selection.ParameterGrid
+            Iterable of hyperparameter combinations for the requested model.
+        """
+        return self.PARAM_GRID_BY_MODEL[model]
+
+    def setup(self) -> None:
+        """Create output directories and set random seeds.
+
+        This method must be called once from the pipeline entry point before
+        any data is loaded or models are trained. It is intentionally separated
+        from ``__init__`` so that :class:`Config` can be instantiated in tests
+        without creating directories or modifying global random state.
+
+        Notes
+        -----
+        Directories are created with ``exist_ok=True``, so calling ``setup``
+        multiple times is safe.
+        """
+        for path in self.PATHS.values():
+            os.makedirs(path, exist_ok=True)
+        random.seed(self.RANDOM_STATE)
+        np.random.seed(self.RANDOM_STATE)

melite/config_default.toml

@@ -0,0 +1,25 @@
+# MELITE default configuration
+# Copy this file and pass it with --config to override any of these values.
+# Only the keys you include in your custom file will be overridden.
+
+[paths]
+input   = "raw/"
+dataset = "data/"
+output  = "output/"
+
+[benchmark]
+reduction_types = ["PCA", "UMAP"]
+levels          = [70, 75, 80, 85, 90, 95]
+random_state    = 42
+
+[cv]
+n_splits = 10
+n_repeats = 5
+
+[cv_smoke]
+n_splits = 3
+n_repeats = 1
+
+[models]
+# Active models to benchmark. Remove any entry to skip that model.
+active = ["svc", "rf", "xgb"]