sage.exec.director

Filename : director.py Description : Short description of the file

Created on 2021-11-21 15:30:43

__author__ = Narenraju Nagarajan __copyright__ = Copyright 2025, Sage __license__ = MIT Licence __version__ = 0.0.1 __maintainer__ = Narenraju Nagarajan __affiliation__ = University of Glasgow __email__ = N/A __status__ = [‘inProgress’, ‘Archived’, ‘inUsage’, ‘Debugging’]

GitHub Repository: https://github.com/nnarenraju/sage

Documentation: NULL

Attributes

opts

Classes

SageDirector

Top-level orchestrator for the Sage pipeline (legacy DataLoader mode).

Functions

parse_args()

Argument parser for directors

Module Contents

parse_args()

Argument parser for directors

Returns:

populated namespace object

Return type:

opts (namespace object)

class SageDirector(opts)

Top-level orchestrator for the Sage pipeline (legacy DataLoader mode).

Provides a step-by-step API to configure, build, train, and evaluate a Sage detection network. Each major concern is handled by a dedicated prepare_* method that can be called individually or via run() for a full end-to-end execution.

This class wraps the legacy sage.factory.legacy training loop that uses PyTorch DataLoader objects. For the modern on-the-fly (OTF) training loop, see sage.factory.training.

Parameters:

opts (argparse.Namespace) – Parsed command-line options from parse_args().

cfg

Pipeline (model + training) configuration.

Type:

BaseConfig

data_cfg

Dataset configuration.

Type:

BaseDataConfig

Network

Instantiated neural network.

Type:

nn.Module

optimiser, scheduler, loss_function

Configured PyTorch training objects.

train_loader, val_loader, aux_loader

Data loaders for training, validation, and auxiliary data.

Type:

DataLoader

checkpoint

Loaded checkpoint state for resuming, or None for a fresh run.

Type:

dict or None

opts

cfg = None

data_cfg = None

Network = None

optimiser = None

scheduler = None

loss_function = None

train_loader = None

val_loader = None

aux_loader = None

checkpoint = None

prepare_configs()

Load and register the dataset and pipeline configurations.

prepare_data(train_fold=None, val_fold=None, balance_params=None)

Prepare dataset objects and DataLoader instances.

Creates the export directory, optionally generates the dataset, and builds training / validation / auxiliary DataLoader objects.

Parameters:

• train_fold (int or None) – Fold indices for cross-validation splits.

• val_fold (int or None) – Fold indices for cross-validation splits.

• balance_params (dict or None) – Optional parameters for class-balancing the DataLoader.

initialise_model()

Instantiate the neural network and optionally load pretrained weights.

If cfg.pretrained is True and cfg.weights_path is set, loads a weights snapshot and optionally freezes layers for transfer learning.

Raises:

ValueError – If cfg.pretrained is True but no valid weights_path is configured, or if the checkpoint file does not exist.

prepare_model_summary()

Optionally print a model summary and write a TensorBoard graph.

Triggered only when opts.summary is True. Uses torchsummary.summary() for a parameter-count table and SummaryWriter to emit a computation graph viewable in TensorBoard.

prepare_optimiser()

Instantiate the optimiser from cfg.optimiser and cfg.optimiser_params.

Sets optimiser to None when no optimiser is configured.

prepare_scheduler()

Instantiate the learning-rate scheduler from cfg.scheduler and cfg.scheduler_params.

Returns:

The configured scheduler, or None if not used.

Return type:

scheduler or None

prepare_loss_function()

Assign cfg.loss_function to loss_function.

prepare_checkpoint()

Load a checkpoint to resume training.

When cfg.resume_from_checkpoint is True, loads the model and optimiser state dictionaries from cfg.checkpoint_path so that training resumes from the saved epoch.

train_model()

Launch the legacy DataLoader-based training loop.

Delegates to sage.factory.legacy.train() with all prepared components (model, optimiser, scheduler, loss, loaders, checkpoint). Updates Network with the best weights returned after training.

test_model()

Run inference over foreground and background test datasets.

Produces trigger files for both jobs (foreground / background) under <export_dir>/TESTING/. Activated only when opts.inference is True.

evaluate_model()

Run the MLGWSC-1 evaluator on the trigger files produced by test_model().

Builds the raw-argument list expected by sage.benchmark.mlgwsc1.evaluator.main() and invokes it to produce clustered triggers and efficiency statistics written to the TESTING sub-directory.

save_results()

Persist final results and artefacts (stub — not yet implemented).

run()

Execute the full training pipeline end-to-end.

Calls all prepare_* methods in order: configs → data → model → summary → optimiser → scheduler → loss → checkpoint → train.

opts