Hyperparameter Optimisation¶

class ExperimentConfig(NamedTuple):
    """Resources bundled for a notebook experiment run.

    Example:
        >>> from tinycta.hyper import ExperimentConfig
        >>> cfg = ExperimentConfig(name="momentum", logger=None, params={"fast": 16, "slow": 64})
        >>> cfg.name
        'momentum'
        >>> cfg.params
        {'fast': 16, 'slow': 64}

        The three config sections are optional and default to ``None``, so a
        config file that omits one is not an error:

        >>> cfg.optuna is None and cfg.data is None
        True

        Being a :class:`~typing.NamedTuple`, it also unpacks positionally:

        >>> name, _logger, params, _optuna, _data = cfg
        >>> name, sorted(params)
        ('momentum', ['fast', 'slow'])
    """

    name: str
    logger: Any
    params: dict[str, Any] | None = None
    optuna: dict[str, Any] | None = None
    data: dict[str, Any] | None = None

@dataclass(frozen=True)
class Study:
    """Frozen wrapper around a completed Optuna study.

    Example:
        >>> import optuna
        >>> from tinycta.hyper import Study
        >>> optuna.logging.set_verbosity(optuna.logging.WARNING)
        >>> s = optuna.create_study(direction="maximize", sampler=optuna.samplers.TPESampler(seed=0))
        >>> s.optimize(lambda trial: trial.suggest_float("x", 0.0, 1.0), n_trials=5)
        >>> study = Study.from_optuna(s)
        >>> study.n_trials, study.n_completed
        (5, 5)
        >>> sorted(study.best_params)
        ['x']

        ``str`` renders the best trial as a report block:

        >>> print(study)  # doctest: +ELLIPSIS
        === Best parameters ===
          x            = 0...
          Sharpe       = 0...
          Completed    = 5 / 5 trials

        A study in which every trial was pruned (each scored a NaN Sharpe) is not an
        error — it reports no best parameters and a NaN best value:

        >>> pruned = optuna.create_study(direction="maximize")
        >>> pruned.optimize(
        ...     lambda trial: (_ for _ in ()).throw(optuna.exceptions.TrialPruned()), n_trials=2
        ... )
        >>> empty = Study.from_optuna(pruned)
        >>> empty.n_completed, empty.best_params
        (0, {})
        >>> print(empty)
        No completed trials — all returned NaN Sharpe.
    """

    best_params: dict[str, Any]
    best_value: float
    n_completed: int
    n_trials: int
    optuna_study: optuna.Study = field(repr=False)

    def __str__(self) -> str:
        """Return a human-readable summary of the best trial."""
        if self.n_completed == 0:
            return "No completed trials — all returned NaN Sharpe."
        lines = ["=== Best parameters ==="]
        for k, v in self.best_params.items():
            lines.append(f"  {k:<12} = {v}")
        lines.append(f"  {'Sharpe':<12} = {self.best_value:.4f}")
        lines.append(f"  {'Completed':<12} = {self.n_completed} / {self.n_trials} trials")
        return "\n".join(lines)

    @classmethod
    def from_optuna(cls, s: optuna.Study) -> Study:
        """Wrap a completed optuna.Study in a frozen Study."""
        n_completed = sum(1 for t in s.trials if t.state == optuna.trial.TrialState.COMPLETE)
        if n_completed == 0:
            best_params, best_value = {}, float("nan")
        else:
            best_params, best_value = s.best_params, s.best_value
        return cls(
            best_params=best_params,
            best_value=best_value,
            n_completed=n_completed,
            n_trials=len(s.trials),
            optuna_study=s,
        )

    def plot(self, output_dir: Path) -> None:
        """Write Optuna visualisation plots to output_dir (HTML, PNG if kaleido available)."""
        output_dir.mkdir(parents=True, exist_ok=True)
        figures = {
            "optuna_history": optuna.visualization.plot_optimization_history(self.optuna_study),
            "optuna_importance": optuna.visualization.plot_param_importances(self.optuna_study),
            "optuna_parallel": optuna.visualization.plot_parallel_coordinate(self.optuna_study),
            "optuna_contour": optuna.visualization.plot_contour(self.optuna_study),
        }
        for name, fig in figures.items():
            fig.write_html(str(output_dir / f"{name}.html"))
            try:
                fig.write_image(str(output_dir / f"{name}.png"), scale=2)
            except (ValueError, ImportError) as exc:
                # PNG export needs the optional `kaleido` backend; skip if unavailable.
                logger.debug(f"Skipping PNG export for {name}: {exc}")