ageas.n_iter_extraction

ageas.n_iter_extraction(hangar: Hangar, operation_name: str = 'extraction', accelerator: str = 'cpu', cuda_devices: list = None, query_dataset=None, test_dataset=None, exp_dataset=None, max_extraction_iter: int = 1, extract_top_n: int = 10, use_gene_names: bool = True, seed: int = 42, verbose: bool = None, selection_args: dict = None, explain_args: dict = None) → tuple

N-iteration extraction of top regulatory factors per class.

Each iteration runs n_kfold_selection(), debriefs the surviving deck to obtain per-class explanation scores, prunes outlier features, and feeds the trimmed dataset back into the next iteration. The per-iteration explanations are L1-aggregated and the top-N factors per class are ranked across iterations.

Parameters:

  • hangar – Source hangar from which the operating squad is generated.

  • operation_name – Operation name under which per-iteration reports are stored.

  • accelerator – Accelerator hint forwarded to selection ('cpu' or 'cuda').

  • cuda_devices – Optional GPU device indices.

  • query_dataset – Required dataset that drives selection and (by default) the explanation pass.

  • test_dataset – Optional held-out test dataset.

  • exp_dataset – Optional explanation dataset. Defaults to test_dataset when provided, otherwise query_dataset.

  • max_extraction_iter – Number of extraction iterations.

  • extract_top_n – Number of top factors to retain per class in the final ranking.

  • use_gene_names – If True, the returned table uses adata.var['name'] as the index instead of feature IDs.

  • seed – Random seed forwarded to selection.

  • verbose – If True, emit per-iteration progress logs.

  • selection_args – Extra keyword arguments forwarded to n_kfold_selection().

  • explain_args – Extra keyword arguments forwarded to debrief().

Returns:

(top_factors, final_exp). top_factors is the per-class ranked factor table (with an Outlier_Iter column flagging held-out features), and final_exp is the L1-normalised integrated explanation table.