gpse 0.0.2__py3-none-any.whl

gpse/__init__.py

@@ -0,0 +1,11 @@
+"""gpse — Genomic Prediction with Stacking Ensemble for horticultural crops."""
+
+try:
+    from importlib.metadata import version as _get_version
+except ImportError:
+    from importlib_metadata import version as _get_version  # type: ignore[no-redef]
+
+try:
+    __version__ = _get_version("gpse")
+except Exception:
+    __version__ = "unknown"

gpse/batch/__init__.py

@@ -0,0 +1,3 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Batch training: run ``gpse train`` for many traits from one YAML config."""

gpse/batch/cli.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Command-line interface for ``gpse batch``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+_EPILOG = """\
+YAML config schema:
+  defaults:
+    <any gpse train option>: value  # inherited by every trait
+    results_root: /path/to/output   # per-trait output = <results_root>/<name>
+  traits:
+    - name: FT                      # required; becomes --target_trait
+      task_type: classification     # any train option may be overridden
+      n_classes: 3
+      models: [rf_clf, xgboost_clf]
+      results_dir: /custom/output   # optional; overrides results_root
+      enabled: false                # optional; skip this trait
+"""
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    formatter_class=None,
+    prog: str | None = None,
+    help_action=None,
+    parents: list[argparse.ArgumentParser] | None = None,
+) -> int:
+    """Run the GPSE batch training CLI."""
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+    parser = argparse.ArgumentParser(
+        prog=prog or "python -m gpse.batch.cli",
+        description="Train GPSE models for multiple traits from one YAML config.",
+        formatter_class=formatter_class or argparse.RawDescriptionHelpFormatter,
+        epilog=_EPILOG,
+        parents=parents or [],
+    )
+    parser.add_argument(
+        "--config",
+        required=True,
+        help="Path to the YAML batch config file",
+    )
+    parser.add_argument(
+        "--dry_run",
+        action="store_true",
+        help="Print the generated 'gpse train' commands without running them",
+    )
+    args = parser.parse_args(raw_args)
+
+    # Initialize the standard GPSE console logger so batch messages share the
+    # same "[HH:MM:SS] INFO ..." style as `gpse train`. Without this, batch
+    # logs fall back to whatever handler was installed at import time (e.g.
+    # the rich_color_ext box sink pulled in transitively by the logo).
+    from gpse.utils.log_utils import logger_init
+
+    logger_init(log_level=getattr(args, "log_level", "INFO"))
+
+    from gpse.batch.runner import run_batch
+
+    try:
+        return run_batch(args.config, dry_run=args.dry_run)
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gpse/batch/runner.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Batch Training Runner
+=====================
+Loads a YAML batch config and runs ``gpse train`` once per trait.
+
+Config schema::
+
+    defaults:
+      <any gpse train option>: value   # inherited by every trait
+      results_root: /path/to/output    # per-trait output = <results_root>/<name>
+    traits:
+      - name: FT                       # required; becomes --target_trait
+        task_type: classification      # any train option may be overridden
+        n_classes: 3
+        models: [rf_clf, xgboost_clf]
+        results_dir: /custom/output    # overrides results_root
+        enabled: false                 # optional; skip this trait
+"""
+
+from __future__ import annotations
+
+import argparse
+import traceback
+from pathlib import Path
+from typing import Any
+
+import yaml
+from loguru import logger as main_logger
+
+# Keys consumed by the batch runner itself; everything else must be a
+# ``gpse train`` long option and is passed through.
+RESERVED_KEYS = {"name", "enabled", "results_root", "target_trait"}
+
+
+def _train_option_actions() -> dict[str, argparse.Action]:
+    """Map every ``gpse train`` long option name to its argparse action."""
+    from gpse.train.workflow import _build_parser
+
+    parser = _build_parser()
+    actions: dict[str, argparse.Action] = {}
+    for action in parser._actions:
+        for option in action.option_strings:
+            if option.startswith("--"):
+                actions[option[2:]] = action
+    return actions
+
+
+def load_batch_config(config_path: str | Path) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Load and validate the YAML batch config; return (defaults, traits)."""
+    config_path = Path(config_path)
+    if not config_path.exists():
+        raise FileNotFoundError(f"Batch config not found: {config_path}")
+    with open(config_path, encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    if not isinstance(data, dict):
+        raise ValueError(f"Batch config must be a YAML mapping: {config_path}")
+
+    defaults = data.get("defaults") or {}
+    if not isinstance(defaults, dict):
+        raise ValueError("'defaults' must be a mapping of gpse train options")
+
+    traits = data.get("traits")
+    if not isinstance(traits, list) or not traits:
+        raise ValueError("'traits' must be a non-empty list")
+    for index, trait in enumerate(traits, start=1):
+        if not isinstance(trait, dict):
+            raise ValueError(f"traits entry #{index} must be a mapping")
+        name = trait.get("name")
+        if not name or not isinstance(name, str):
+            raise ValueError(f"traits entry #{index} is missing a string 'name'")
+    return defaults, traits
+
+
+def build_trait_argv(
+    defaults: dict[str, Any],
+    trait: dict[str, Any],
+    actions: dict[str, argparse.Action] | None = None,
+) -> list[str]:
+    """Merge defaults with one trait entry and build a ``gpse train`` argv."""
+    actions = actions or _train_option_actions()
+    name = trait["name"]
+
+    if "target_trait" in defaults or "target_trait" in trait:
+        raise ValueError(
+            f"trait '{name}': 'target_trait' is derived from 'name'; do not set it directly"
+        )
+
+    merged = {**defaults, **{k: v for k, v in trait.items() if k not in RESERVED_KEYS}}
+    results_root = trait.get("results_root", defaults.get("results_root"))
+    merged.pop("results_root", None)
+
+    if not merged.get("results_dir"):
+        if not results_root:
+            raise ValueError(
+                f"trait '{name}': define 'results_dir' or set 'results_root' in defaults"
+            )
+        merged["results_dir"] = str(Path(str(results_root)) / name)
+    merged["target_trait"] = name
+
+    argv: list[str] = []
+    for key, value in merged.items():
+        if value is None:
+            continue
+        action = actions.get(key)
+        if action is None:
+            raise ValueError(
+                f"trait '{name}': unknown option '{key}' (not a 'gpse train' flag)"
+            )
+        flag = f"--{key}"
+        if isinstance(action, argparse.BooleanOptionalAction):
+            argv.append(flag if bool(value) else f"--no-{key}")
+        elif isinstance(action, argparse._StoreTrueAction):
+            if bool(value):
+                argv.append(flag)
+        elif action.nargs in ("+", "*"):
+            values = value if isinstance(value, (list, tuple)) else [value]
+            argv.append(flag)
+            argv.extend(str(item) for item in values)
+        else:
+            argv.append(flag)
+            argv.append(str(value))
+    return argv
+
+
+def _format_train_command(argv: list[str]) -> str:
+    """Render a ``gpse train`` argv as a multi-line copy-pasteable command.
+
+    Each flag is grouped with its values on its own line, joined with shell
+    line-continuations, so long paths stay intact instead of wrapping
+    mid-token at the terminal edge.
+    """
+    groups: list[list[str]] = []
+    for token in argv:
+        if token.startswith("--") or not groups:
+            groups.append([token])
+        else:
+            groups[-1].append(token)
+    lines = ["gpse train \\"]
+    lines.extend(f"    {' '.join(group)} \\" for group in groups[:-1])
+    lines.append(f"    {' '.join(groups[-1])}")
+    return "\n".join(lines)
+
+
+def run_batch(config_path: str | Path, dry_run: bool = False) -> int:
+    """Run ``gpse train`` for every enabled trait; return 0 when all succeed."""
+    defaults, traits = load_batch_config(config_path)
+    actions = _train_option_actions()
+
+    runnable = [trait for trait in traits if trait.get("enabled", True)]
+    skipped = [trait["name"] for trait in traits if not trait.get("enabled", True)]
+    if skipped:
+        main_logger.info(f"Skipping disabled traits: {skipped}")
+    if not runnable:
+        main_logger.error("No enabled traits to run")
+        return 1
+
+    main_logger.info(f"Batch training: {len(runnable)} trait(s) from {config_path}")
+    outcomes: list[tuple[str, str]] = []
+    for index, trait in enumerate(runnable, start=1):
+        name = trait["name"]
+        try:
+            argv = build_trait_argv(defaults, trait, actions)
+        except ValueError as exc:
+            main_logger.error(str(exc))
+            outcomes.append((name, "config-error"))
+            continue
+
+        if dry_run:
+            print(f"[{index}/{len(runnable)}] {name}")
+            print(_format_train_command(argv))
+            outcomes.append((name, "dry-run"))
+            continue
+
+        main_logger.info("=" * 70)
+        main_logger.info(f"[{index}/{len(runnable)}] Training trait: {name}")
+        main_logger.info("=" * 70)
+        from gpse.train.cli import main as train_main
+
+        try:
+            exit_code = train_main(argv, prog="gpse train")
+        except SystemExit as exc:
+            exit_code = exc.code if isinstance(exc.code, int) else 1
+        except Exception:
+            main_logger.error(f"Trait {name} failed with an unexpected error:")
+            main_logger.error(traceback.format_exc())
+            exit_code = 1
+
+        if exit_code == 130:
+            main_logger.warning("Batch interrupted by user (Ctrl+C).")
+            outcomes.append((name, "interrupted"))
+            _log_summary(outcomes)
+            return 130
+        outcomes.append((name, "ok" if exit_code == 0 else f"failed({exit_code})"))
+
+    _log_summary(outcomes)
+    return 0 if all(status in {"ok", "dry-run"} for _, status in outcomes) else 1
+
+
+def _log_summary(outcomes: list[tuple[str, str]]) -> None:
+    main_logger.info("=" * 70)
+    main_logger.info("Batch summary:")
+    for name, status in outcomes:
+        main_logger.info(f"  {name}: {status}")
+    main_logger.info("=" * 70)

gpse/cli.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+GPSE Command-Line Interface
+
+This module is intentionally thin: it only defines argument parsers and routes
+the execution flow. Training business logic lives in ``gpse.train``.
+"""
+
+import os
+import sys
+import argparse
+
+# Configure native thread pools before importing modules that may load
+# numpy/scipy/sklearn. BLAS/MKL/OpenMP read these environment variables only
+# when their pools are initialized, so this has to happen at the top.
+_thread_pre_parser = argparse.ArgumentParser(add_help=False)
+_thread_pre_parser.add_argument("--n_jobs", type=int, default=1)
+_thread_pre_args, _ = _thread_pre_parser.parse_known_args()
+_thread_n = str(_thread_pre_args.n_jobs)
+for _env_var in (
+    "OMP_NUM_THREADS",
+    "MKL_NUM_THREADS",
+    "OPENBLAS_NUM_THREADS",
+    "NUMEXPR_NUM_THREADS",
+    "VECLIB_MAXIMUM_THREADS",
+    "BLIS_NUM_THREADS",
+):
+    os.environ[_env_var] = _thread_n
+del _thread_pre_parser, _thread_pre_args, _thread_n, _env_var
+
+# CLI display helpers are imported after thread setup because they can
+# eventually touch package modules that import numerical dependencies.
+from gpse.utils.cli_display import (
+    ULTIMATE_QUESTION,
+    _build_root_parser,
+    _show_logo_for_command,
+    print_easter_egg,
+    show_gpse_logo,
+)
+
+# Shared argparse action: prints the logo before root/subcommand help.
+from gpse.config.constants import _LogoHelpAction
+
+# Prefer rich-formatted help when available; keep argparse as fallback so the
+# CLI still works in minimal environments.
+try:
+    from rich_argparse import RichHelpFormatter
+except ImportError:
+    RichHelpFormatter = argparse.HelpFormatter
+
+# Console is optional. All user-facing error paths below have plain print()
+# fallbacks for environments without rich.
+try:
+    from rich.console import Console
+    _console = Console()
+except ImportError:
+    _console = None
+
+# Common root options are passed into subcommand parsers as parents. This keeps
+# flags such as --version and --log-level consistent across gpse commands.
+_common_parent = argparse.ArgumentParser(add_help=False)
+_common_parent.add_argument(
+    "-v", "--version",
+    action="store_true",
+    help="Show version information and exit",
+)
+_common_parent.add_argument(
+    "-l", "--log-level",
+    default="INFO",
+    choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+    help="Set logging level (default: INFO)",
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """
+    Main entry point for the GPSE CLI.
+
+    argv is injectable for tests and internal calls. When argv is None, the
+    function reads the real command-line arguments from sys.argv.
+    """
+    # Normalize inputs to a list copy so downstream slicing and checks are
+    # stable even when tests pass tuples or other sequences.
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+
+    # Build the lightweight root router. Detailed workflow arguments are
+    # defined inside gpse.convert.cli, gpse.train.cli, and gpse.predict.cli.
+    root_parser = _build_root_parser(
+        formatter_class=RichHelpFormatter,
+        parents=[_common_parent],
+        help_action=_LogoHelpAction,
+    )
+
+    # No subcommand was provided. Show the logo and root help, then fail with
+    # exit code 1 because this is an invalid invocation.
+    if not raw_args:
+        show_gpse_logo()
+        if _console is not None:
+            _console.print("\n[bold red][ERROR] No command provided. Use convert, train, predict, or batch.[/bold red]\n")
+        else:
+            print("\n[ERROR] No command provided. Use convert, train, predict, or batch.\n")
+        root_parser.print_help()
+        return 1
+
+    # Root help is handled by the root parser so the custom help action can
+    # print the logo before the help text.
+    if raw_args[0] in {"-h", "--help"}:
+        root_parser.parse_args(raw_args)
+        return 0
+
+    # Root version delegates to the train CLI because that module owns the
+    # current version display implementation.
+    if raw_args[0] in {"-v", "--version"}:
+        from gpse.train.cli import main as train_main
+
+        return train_main(["--version"], prog="gpse")
+
+    # Easter egg shortcuts are handled before subcommand dispatch, so commands
+    # like `gpse 42` do not get treated as unknown subcommands.
+    if len(raw_args) == 1 and raw_args[0] == "42":
+        print_easter_egg(show_question=False)
+        return 0
+
+    # Also accept the full question, ignoring case and trailing punctuation.
+    joined_args = " ".join(raw_args).strip().lower().rstrip("?!. ")
+    if joined_args == ULTIMATE_QUESTION:
+        print_easter_egg(show_question=True)
+        return 0
+
+    # Split root command from the arguments that belong to the selected
+    # workflow. The workflow modules receive only their own arguments.
+    command = raw_args[0]
+    command_args = raw_args[1:]
+
+    # Convert workflow: import lazily so gpse --help and gpse --version stay
+    # lightweight and do not load workflow dependencies unnecessarily.
+    if command == "convert":
+        # Display the logo before convert/predict help.
+        _show_logo_for_command(command_args)
+
+        from gpse.convert.cli import main as convert_main
+
+        # convert/predict do not own version rendering; route to the shared
+        # version implementation while preserving the command name in prog.
+        if command_args and command_args[0] in {"-v", "--version"}:
+            from gpse.train.cli import main as train_main
+
+            return train_main(["--version"], prog="gpse convert")
+        return convert_main(
+            command_args,
+            formatter_class=RichHelpFormatter,
+            prog="gpse convert",
+            help_action=_LogoHelpAction,
+            parents=[_common_parent],
+        )
+
+    # Train workflow.
+    if command == "train":
+        # Display the logo before convert/predict help.
+        _show_logo_for_command(command_args)
+
+        from gpse.train.cli import main as train_main
+
+        return train_main(
+            command_args,
+            formatter_class=RichHelpFormatter,
+            prog="gpse train",
+            help_action=_LogoHelpAction,
+            parents=[_common_parent],
+        )
+
+    # Predict workflow.
+    if command == "predict":
+        # Display the logo before convert/predict help.
+        _show_logo_for_command(command_args)
+
+        from gpse.predict.cli import main as predict_main
+
+        if command_args and command_args[0] in {"-v", "--version"}:
+            from gpse.train.cli import main as train_main
+
+            return train_main(["--version"], prog="gpse predict")
+        return predict_main(
+            command_args,
+            formatter_class=RichHelpFormatter,
+            prog="gpse predict",
+            help_action=_LogoHelpAction,
+            parents=[_common_parent],
+        )
+
+    # Batch workflow: train many traits from one YAML config.
+    if command == "batch":
+        _show_logo_for_command(command_args)
+
+        from gpse.batch.cli import main as batch_main
+
+        if command_args and command_args[0] in {"-v", "--version"}:
+            from gpse.train.cli import main as train_main
+
+            return train_main(["--version"], prog="gpse batch")
+        return batch_main(
+            command_args,
+            formatter_class=RichHelpFormatter,
+            prog="gpse batch",
+            parents=[_common_parent],
+        )
+
+    # Any other first token is not a supported workflow command.
+    root_parser.error(f"Unknown command: {command}. Use train, convert, predict, or batch.")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gpse/config/__init__.py

@@ -0,0 +1,15 @@
+"""gpse.config — Configuration constants and model data classes."""
+
+from .constants import (
+    ModelConstants,
+    ModelConfig,
+    ClassificationModelConfig,
+    NumpyEncoder,
+)
+
+__all__ = [
+    "ModelConstants",
+    "ModelConfig",
+    "ClassificationModelConfig",
+    "NumpyEncoder",
+]