Skip to content

Task Runners

Base Task Runner

nazuna.task_runners.BaseTaskRunner dataclass

Bases: ABC

Base class for task runners.
Subclasses must follow these rules:

  • A TaskRunner should be runnable on its own with just a TimeSeriesDataManager instance.
  • Calling run() writes result.toml (and other artifacts if any) to out_dir.

Attributes:

  • dm (TimeSeriesDataManager) –

    TimeSeriesDataManager instance (required).

  • device (str = '') –

    Device name for computation (Ex. 'cpu', 'cuda'). If not specified, it will be automatically detected from your environment.

  • name (str = '') –

    Name of this task. Not used when running a task standalone.

  • out_dir (str | Path = '') –

    Output path for this task's artifacts. Defaults to 'out/YYYYmmdd-HHMMSS/task_0/' if not specified.

  • exist_ok (bool = True) –

    Whether to allow the output path to already exist.

  • seed (int = 0) –

    Random seed for reproducibility.

Eval Task Runner

nazuna.task_runners.EvalTaskRunner dataclass

Bases: BaseTaskRunner

Evaluate a model on a specified data range.

Attributes:

  • data_range_eval (tuple[float, float] | None = None) –

    Data range for evaluation as (start, end) ratios (required for EvalTaskRunner; optional for TrainTaskRunner).

  • data_offset_eval (int = 0) –

    Offset for evaluation data.

  • data_rolling_window_eval (int = 4) –

    Rolling window size for computing quartiles for scaling (unused if quartile-based rolling-window scaling is disabled).

  • batch_size_eval (int = 32) –

    Batch size for evaluation.

  • criterion (dict = None) –

    Criterion configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • baseline_model (dict = None) –

    Baseline model configuration. Must have 'cls_path' (str) and 'params' (dict) keys. Required only when the criterion requires a baseline.

  • model (dict = None) –

    Model configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • model_state_path (str | PathLike | IO[bytes] = None) –

    Path to the model state file.

  • dump_pred_data (bool = True) –

    Whether to dump pred_first.npz and pred_last.npz.

Train Task Runner

nazuna.task_runners.TrainTaskRunner dataclass

Bases: EvalTaskRunner

Train a model on a specified data range.

Attributes:

  • data_range_train (tuple[float, float] | None = None) –

    Data range for training as (start, end) ratios (required).

  • data_offset_train (int = 0) –

    Offset for training data.

  • data_rolling_window_train (int = 4) –

    Rolling window size for computing quartiles for scaling (unused if quartile-based rolling-window scaling is disabled).

  • criterion_target (dict = None) –

    Criterion configuration for the training loss. Must have 'cls_path' (str) and 'params' (dict) keys. If not specified, the eval criterion is used for the training loss.

  • batch_sampler (dict = None) –

    Batch sampler configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • optimizer (dict = None) –

    Optimizer configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • lr_scheduler (dict = None) –

    Learning rate scheduler configuration. Optional. Must have 'cls_path' (str) and 'params' (dict) keys.

  • n_epoch (int = 0) –

    Number of training epochs (required).

  • early_stop (bool = False) –

    Whether to enable early stopping. Stops training if evaluation loss does not improve for 5 consecutive epochs.

Diagnostics Task Runner

nazuna.task_runners.DiagnosticsTaskRunner dataclass

Bases: BaseTaskRunner

Diagnose data characteristics such as seasonality.

Attributes:

  • data_range_diag (tuple[float, float] | None = None) –

    Data range for diagnostics as (start, end) ratios (required).

  • period (int | None = None) –

    Seasonal period for STL decomposition (required).

Optuna Task Runner

nazuna.task_runners.OptunaTaskRunner dataclass

Bases: BaseTaskRunner

Search for optimal hyperparameters using Optuna.

Attributes:

  • search_space (dict = None) –

    Search space (required).

  • data_ranges (list = None) –

    List of data range dicts for cross-validation (required). Each dict should have 'train' and 'eval' keys with (start, end) ratio tuples.

  • n_trials (int = 10) –

    Number of Optuna trials to run.

  • direction (str = 'minimize') –

    Optimization direction ('minimize' or 'maximize').

  • data_offset_train (int = 0) –

    Offset for training data.

  • data_rolling_window_train (int = 4) –

    Rolling window size for training data.

  • data_offset_eval (int = 0) –

    Offset for evaluation data.

  • data_rolling_window_eval (int = 4) –

    Rolling window size for evaluation data.

  • batch_size_eval (int = 32) –

    Batch size for evaluation.

  • criterion (dict = None) –

    Criterion configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • model (dict = None) –

    Model configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • batch_sampler (dict = None) –

    Batch sampler configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • optimizer (dict = None) –

    Optimizer configuration (required). Must have 'cls_path' (str) and 'params' (dict) keys.

  • lr_scheduler (dict = None) –

    Learning rate scheduler configuration. Optional. Must have 'cls_path' (str) and 'params' (dict) keys.

  • n_epoch (int = 0) –

    Number of training epochs per trial (required).

  • early_stop (bool = False) –

    Whether to enable early stopping within each trial.