ageas.Deck

class ageas.Deck(squad: dict, n_dataloader_workers: int = 10, accelerator: str = 'cpu', cuda_devices: list = None)

Bases: Hangar

Sortie deck that trains, evaluates, and explains a squad of units.

Inherits from Hangar and adds operational logic on top of the candidate squad: a Trainer_Maker to launch the correct trainer per model type, a per-unit report ledger, and the debrief() aggregation that combines model-wise explanations weighted by their validation/test metrics.

Variables:

  • squad – Mapping unit_id -> Unit for the active operating units.

  • trainer_maker – Factory that produces trainer-model pairs.

  • n_dataloader_workers – Worker count for prediction/test dataloaders.

  • report – Per-unit {'vali': [], 'test': []} metric ledger.

  • accelerator – Default accelerator ('cpu' or 'cuda').

  • cuda_devices – Resolved GPU device indices (None for CPU).

__init__(squad: dict, n_dataloader_workers: int = 10, accelerator: str = 'cpu', cuda_devices: list = None) → None

Initialize a Deck.

Parameters:

  • squad – Mapping unit_id -> Unit to operate on, typically produced by sortie_generate().

  • n_dataloader_workers – Number of worker processes for the prediction/test dataloaders.

  • accelerator – Default accelerator ('cpu' or 'cuda') the deck will request from each unit at sortie time.

  • cuda_devices – Optional list of GPU device indices to bind. When accelerator='cuda' and this is None, all visible devices are used.

debrief(exp_dataset: torch.utils.data.Dataset = None, operation: str = 'trail', mission: str = 'final', monitor_type: str = 'min', monitor_metric: str = 'vali.CEL', verbose: bool = True, **kwargs) → pandas.DataFrame

Aggregate per-class explanation scores across the squad.

Each unit’s explain method is called on exp_dataset and the resulting per-class score table is weighted by that unit’s metric value (monitor_metric). The weight direction depends on monitor_type: lower-is-better metrics divide by the score, higher-is-better metrics multiply.

Parameters:

  • exp_dataset – Dataset to explain. Forwarded unchanged to every unit’s explain method.

  • operation – Operation name used to look up the metric in unit.report.

  • mission – Mission name (e.g. 'final' or 'fold_1') used inside the operation’s report.

  • monitor_type – 'min' for lower-is-better metrics (divide-by-weight), 'max' for higher-is-better metrics (multiply-by-weight).

  • monitor_metric – Dotted metric name (e.g. 'vali.CEL', 'test.accuracy').

  • verbose – If True, print per-unit weights and the assembled answer.

  • kwargs – Additional keyword arguments forwarded to each unit.model.explain call.

Returns:

The integrated per-class score table. Columns ending in _Std are dropped from the final answer.

make_report(squad: dict = None) → dict

Initialize an empty report ledger for a squad of units.

Parameters:

squad – Mapping unit_id -> Unit for which to allocate report slots. None uses the deck’s current squad.

Returns:

A nested dict {unit_id: {'vali': [], 'test': []}}.

property ops_reports: dict

Aggregate per-operation reports across the entire squad.

Walks the per-unit unit.report ledger and reshapes it into a nested structure:

{operation: {mission: {metric_type: {metric_name: {unit_id: [values]}}}}}

that is convenient for downstream summary plots.

Returns:

The merged report tree described above.

predict(query_dataset: torch.utils.data.Dataset = None, batch_size: int = 10, num_workers: int = 1) → tuple

Ensemble-predict by averaging probabilities across the squad.

Each unit produces softmax outputs on query_dataset which are averaged uniformly across all units in the squad.

Parameters:

  • query_dataset – Dataset to score. Each item must yield (x, y) tuples.

  • batch_size – Batch size for the prediction dataloader.

  • num_workers – Number of dataloader workers.

Returns:

Tuple (all_preds, all_labels) where all_preds is the averaged probability matrix and all_labels is the concatenated label tensor in the same order.

sortie(train_data: torch.utils.data.Dataset, vali_data: torch.utils.data.Dataset, n_classes: int, fea_names: pandas.Index, test_dataset: torch.utils.data.Dataset = None, report: dict = None, save_model: bool = False, save_trainer: bool = False, verbose: bool = True) → dict

Train every unit in the squad on a single fold and collect metrics.

Each unit is “spiked” to verify its accelerator, then trained via the appropriate trainer (Lightning, scikit-learn, or XGBoost). Validation metrics are read from the trainer’s callback metrics and an optional test pass is launched on test_dataset.

Parameters:

  • train_data – Training split for this sortie.

  • vali_data – Validation split for this sortie.

  • n_classes – Number of label classes in the task.

  • fea_names – Feature names (typically gene symbols/Ensembl IDs).

  • test_dataset – Optional held-out test split. If provided, each model is also evaluated on it after training.

  • report – Existing report dict to append to. None uses the deck’s own self.report ledger.

  • save_model – If True, retain the trained model on the unit.

  • save_trainer – If True, retain the trainer object on the unit.

  • verbose – If True, print per-unit training and evaluation traces.

Returns:

The updated report mapping unit_id to lists of validation and test metric snapshots.

squad_update(unit_ids: list) → None

Restrict the squad and report ledger to a subset of unit IDs.

Parameters:

unit_ids – Whitelist of unit IDs to keep. All other units are dropped from both self.squad and self.report.