Skip to content

Training and model wrappers

train_common trains and evaluates one fold. Every model subclasses one of the wrappers: MLWrapper for classical models, DLPredictionWrapper for PyTorch Lightning models and ImputationWrapper for imputation models.

icu_benchmarks.models.train

Functions:

Name Description
train_common

Common wrapper to train all benchmarked models.

persist_shap_data

Persist shap values to disk.

train_common

train_common(data: dict[str, dict[str, DataFrame]], log_dir: Path, eval_only: bool = False, load_weights: bool = False, source_dir: Path = Path(''), reproducible: bool = True, mode: str = classification, model: DLModel | MLModelClassifier | MLModelRegression | object = REQUIRED, weight: str = '', optimizer: type = Adam, precision: Optional[Literal[16, 32, 64, '16-mixed', 'bf16', 'bf16-mixed', '16-true']] = 32, batch_size: int = 1, epochs: int = 100, patience: int = 20, min_delta: float = 1e-05, test_on: str = test, dataset_names: Optional[dict] = None, use_wandb: bool = False, cpu: bool = False, verbose: bool = False, ram_cache: bool = False, pl_model: bool = True, train_only: bool = False, num_workers: int = min(cpu_core_count, device_count() * 8 * int(is_available()), 32), polars: bool = True, persistent_workers: bool = False, target_transform: Optional[TargetTransform] = None, explain_features: bool = False)

Common wrapper to train all benchmarked models.

Parameters:

Name Type Description Default
data dict[str, dict[str, DataFrame]]

Dict containing data to be trained on.

required
log_dir Path

Path to directory where model output should be saved.

required
eval_only bool

If set to true, skip training and only evaluate the model.

False
load_weights bool

If set to true, skip training and load weights from source_dir instead.

False
source_dir Path

If set to load weights, path to directory containing trained weights.

Path('')
reproducible bool

If set to true, set torch to run reproducibly.

True
mode str

Mode of the model. Can be one of the values of RunMode.

classification
model DLModel | MLModelClassifier | MLModelRegression | object

Model to be trained.

REQUIRED
weight str

Weight to be used for the loss function.

''
optimizer type

Optimizer to be used for training.

Adam
precision Optional[Literal[16, 32, 64, '16-mixed', 'bf16', 'bf16-mixed', '16-true']]

Pytorch precision to be used for training. Can be 16 or 32.

32
batch_size int

Batch size to be used for training.

1
epochs int

Number of epochs to train for.

100
patience int

Number of epochs to wait for improvement before early stopping.

20
min_delta float

Minimum change in loss to be considered an improvement.

1e-05
test_on str

If set to "test", evaluate the model on the test set. If set to "val", evaluate on the validation set.

test
use_wandb bool

If set to true, log to wandb.

False
cpu bool

If set to true, run on cpu.

False
verbose bool

Enable detailed logging.

False
ram_cache bool

Whether to cache the data in RAM.

False
pl_model bool

Loading a pytorch lightning model.

True
num_workers int

Number of workers to use for data loading.

min(cpu_core_count, device_count() * 8 * int(is_available()), 32)
target_transform Optional[TargetTransform]

Fitted preprocessing transform, required for regression.

None
explain_features bool

Save SHAP values of the test set (models that set an explainer_cls) or, for deep learning models, attributions and their quality metrics (icu_benchmarks.models.explain).

False

Returns:

Type Description

Native-unit MSE for regression, or test loss for other run modes.

Source code in icu_benchmarks/models/train.py
@gin.configurable("train_common")
def train_common(
    data: dict[str, dict[str, pl.DataFrame]],
    log_dir: Path,
    eval_only: bool = False,
    load_weights: bool = False,
    source_dir: Path = Path(""),
    reproducible: bool = True,
    mode: str = RunMode.classification,
    model: DLModel | MLModelClassifier | MLModelRegression | object = gin.REQUIRED,
    weight: str = "",
    optimizer: type = Adam,
    precision: Optional[Literal[16, 32, 64, "16-mixed", "bf16", "bf16-mixed", "16-true"]] = 32,
    batch_size: int = 1,
    epochs: int = 100,
    patience: int = 20,
    min_delta: float = 1e-5,
    test_on: str = DataSplit.test,
    dataset_names: Optional[dict] = None,
    use_wandb: bool = False,
    cpu: bool = False,
    verbose: bool = False,
    ram_cache: bool = False,
    pl_model: bool = True,
    train_only: bool = False,
    num_workers: int = min(
        cpu_core_count,
        torch.cuda.device_count() * 8 * int(torch.cuda.is_available()),
        32,
    ),
    polars: bool = True,
    persistent_workers: bool = False,
    target_transform: Optional[TargetTransform] = None,
    explain_features: bool = False,
):
    """Common wrapper to train all benchmarked models.

    Args:
        data: Dict containing data to be trained on.
        log_dir: Path to directory where model output should be saved.
        eval_only: If set to true, skip training and only evaluate the model.
        load_weights: If set to true, skip training and load weights from source_dir instead.
        source_dir: If set to load weights, path to directory containing trained weights.
        reproducible: If set to true, set torch to run reproducibly.
        mode: Mode of the model. Can be one of the values of RunMode.
        model: Model to be trained.
        weight: Weight to be used for the loss function.
        optimizer: Optimizer to be used for training.
        precision: Pytorch precision to be used for training. Can be 16 or 32.
        batch_size: Batch size to be used for training.
        epochs: Number of epochs to train for.
        patience: Number of epochs to wait for improvement before early stopping.
        min_delta: Minimum change in loss to be considered an improvement.
        test_on: If set to "test", evaluate the model on the test set. If set to "val", evaluate on the validation set.
        use_wandb: If set to true, log to wandb.
        cpu: If set to true, run on cpu.
        verbose: Enable detailed logging.
        ram_cache: Whether to cache the data in RAM.
        pl_model: Loading a pytorch lightning model.
        num_workers: Number of workers to use for data loading.
        target_transform: Fitted preprocessing transform, required for regression.
        explain_features: Save SHAP values of the test set (models that set an explainer_cls) or, for deep learning
            models, attributions and their quality metrics (icu_benchmarks.models.explain).

    Returns:
        Native-unit MSE for regression, or test loss for other run modes.
    """

    if mode == RunMode.regression and target_transform is None:
        raise ValueError("Regression training/evaluation requires its preprocessing target transform.")
    if explain_features and getattr(model, "explain_with_captum", False):
        require_polars(polars)
    if dataset_names is None:
        dataset_names = {"train": "default", "val": "default", "test": "default"}

    logging.info(f"Training model: {model.__name__}.")

    dataset_classes: dict = {
        RunMode.imputation: ImputationPandasDataset,
        RunMode.classification: PredictionPolarsDataset if polars else PredictionPandasDataset,
        RunMode.regression: PredictionPolarsDataset if polars else PredictionPandasDataset,
    }
    dataset_class = dataset_classes[mode]

    logging.info(f"Using dataset class: {dataset_class.__name__}.")
    logging.info(f"Logging to directory: {log_dir}.")
    save_config_file(log_dir)  # We save the operative config before and also after training
    train_dataset = dataset_class(data, split=DataSplit.train, ram_cache=ram_cache, name=dataset_names.get("train", "default"))
    val_dataset = dataset_class(data, split=DataSplit.val, ram_cache=ram_cache, name=dataset_names.get("val", "default"))
    train_dataset, val_dataset = (
        assure_minimum_length(train_dataset),
        assure_minimum_length(val_dataset),
    )
    batch_size = min(batch_size, len(train_dataset), len(val_dataset))

    if not eval_only:
        logging.info(
            f"Training on {train_dataset.name} with {len(train_dataset)} samples and validating on {val_dataset.name} with"
            f" {len(val_dataset)} samples."
        )
    logging.info(f"Using {num_workers} workers for data loading.")
    train_loader = DataLoader(
        train_dataset,
        batch_size=batch_size,
        shuffle=True,
        num_workers=num_workers,
        drop_last=True,
        persistent_workers=persistent_workers,
        pin_memory=not cpu,
    )
    val_loader = DataLoader(
        val_dataset,
        batch_size=batch_size,
        shuffle=False,
        num_workers=num_workers,
        drop_last=True,
        persistent_workers=persistent_workers,
        pin_memory=not cpu,
    )

    data_shape = next(iter(train_loader))[0].shape

    if load_weights:
        model: DLModel | MLModelClassifier | MLModelRegression = load_model(
            model, source_dir, pl_model=pl_model, mode=mode, cpu=cpu
        )
        if mode == RunMode.regression and model.target_transform != target_transform:
            raise ValueError("Model and preprocessing target transforms do not match.")
    else:
        model: DLModel | MLModelClassifier | MLModelRegression = model(
            optimizer=optimizer,
            input_size=data_shape,
            epochs=epochs,
            run_mode=mode,
            cpu=cpu,
        )

    model.set_explain_features(explain_features)
    model.target_transform = target_transform
    if target_transform is not None:
        target_transform.save(log_dir)
    model.set_weight(weight, train_dataset)
    model.set_trained_columns(train_dataset.get_feature_names())
    loggers = [TensorBoardLogger(log_dir), JSONMetricsLogger(log_dir)]
    devices = max(torch.cuda.device_count(), 1)

    if use_wandb:
        loggers.append(WandbLogger(save_dir=log_dir))
        logging.info("Use of wandb is detected. Only single gpu training is supported with wandb.")
        devices = 1

    callbacks = [
        EarlyStopping(
            monitor="val/loss",
            min_delta=min_delta,
            patience=patience,
            strict=False,
            verbose=verbose,
        ),
        # model.ckpt keeps the epoch with the best validation loss
        ModelCheckpoint(log_dir, filename="model", monitor="val/loss", mode="min", save_top_k=1, save_last=True),
        LearningRateMonitor(logging_interval="step"),
    ]
    if verbose:
        callbacks.append(TQDMProgressBar(refresh_rate=min(100, len(train_loader) // 2)))
    if precision in (16, "16-mixed", "bf16", "bf16-mixed"):
        torch.set_float32_matmul_precision("high")

    trainer = Trainer(
        max_epochs=epochs if model.requires_backprop else 1,
        min_epochs=1,  # We need at least one epoch to get results.
        callbacks=callbacks,
        precision=precision,
        accelerator="auto" if not cpu else "cpu",
        devices=devices,
        deterministic="warn" if reproducible else False,
        benchmark=not reproducible,
        enable_progress_bar=verbose,
        logger=loggers,
        num_sanity_val_steps=2,  # Helps catch errors in the validation loop before training begins.
        log_every_n_steps=5,
    )
    if not eval_only:
        if model.requires_backprop:
            logging.info("Training DL model.")
            trainer.fit(model, train_dataloaders=train_loader, val_dataloaders=val_loader)
            logging.info("Training complete.")
        else:
            logging.info("Training ML model.")
            model.fit(train_dataset, val_dataset)
            model.save_model(log_dir, "last")
            logging.info("Training complete.")
    if train_only:
        logging.info("Finished training full model.")
        save_config_file(log_dir)
        return 0
    test_dataset = dataset_class(data, split=test_on, name=dataset_names.get("test", "default"), ram_cache=ram_cache)
    test_dataset = assure_minimum_length(test_dataset)
    logging.info(f"Testing on {test_dataset.name}  with {len(test_dataset)} samples.")
    test_loader = (
        DataLoader(
            test_dataset,
            batch_size=min(batch_size * 4, len(test_dataset)),
            shuffle=False,
            num_workers=num_workers,
            pin_memory=not cpu,
            drop_last=True,
            persistent_workers=persistent_workers,
        )
        if model.requires_backprop
        else DataLoader([test_dataset.to_tensor()], batch_size=1)
    )

    model.set_weight("balanced", train_dataset)
    score_name = "test/MSE_native" if mode == RunMode.regression else "test/loss"
    # EarlyStopping does not restore weights, so test a trained DL model on its best validation checkpoint
    ckpt_path = "best" if model.requires_backprop and not eval_only else None
    # YAIB checkpoints store the model class and RunMode enum (and imputation models their ImputationInit), as in load_model.
    with torch.serialization.safe_globals([type(model), RunMode, ImputationInit]):
        test_results = trainer.test(model, dataloaders=test_loader, ckpt_path=ckpt_path, verbose=verbose)
    if not test_results or score_name not in test_results[0]:
        raise ValueError(f"Test evaluation did not produce {score_name}; check that the test split has labeled targets.")
    test_loss = test_results[0][score_name]
    persist_shap_data(trainer, log_dir)
    if explain_features and getattr(model, "explain_with_captum", False):
        # After testing, which leaves the model with the weights it was tested with (the best checkpoint)
        try:
            explain_predictions(model, test_dataset, log_dir)
        except Exception:
            # Explanations are auxiliary; do not fail a completed run over them, like the SHAP export
            logging.exception("Failed to explain the test predictions.")
    save_config_file(log_dir)
    return test_loss

persist_shap_data

persist_shap_data(trainer: Trainer, log_dir: Path)

Persist shap values to disk. Args: trainer: Pytorch lightning trainer object log_dir: Log directory

Source code in icu_benchmarks/models/train.py
def persist_shap_data(trainer: Trainer, log_dir: Path):
    """
    Persist shap values to disk.
    Args:
        trainer: Pytorch lightning trainer object
        log_dir: Log directory
    """
    model = trainer.lightning_module
    for split in ("train", "test"):
        explanation = getattr(model, f"{split}_shap_values", None)
        if explanation is None:
            continue
        try:
            values = explanation.values
            if model.target_transform is not None:
                values = values / model.target_transform.scale
                np.save(log_dir / f"{split}_shap_base_values.npy", model.inverse_target(explanation.base_values))
            # One row per sample; with orient given, Polars cannot transpose a square matrix based on its memory layout
            shaps = pl.DataFrame(values, schema=model.trained_columns, orient="row")
            shaps.write_parquet(log_dir / f"{split}_shap_values.parquet")
            logging.info(f"Saved {split} shap values to {log_dir / f'{split}_shap_values.parquet'}")
        except Exception as e:
            # SHAP export is auxiliary; do not fail a completed run over it.
            logging.error(f"Failed to save {split} shap values: {e}")

icu_benchmarks.models.wrappers

Classes:

Name Description
BaseModule
DLWrapper
DLPredictionWrapper

Interface for Deep Learning models.

ObservationMaskWrapper

Prediction wrapper for models that treat measured and imputed values differently, such as GRU-D and BAT.

MLWrapper

Interface for prediction with traditional Scikit-learn-like Machine Learning models.

ImputationWrapper

Interface for imputation models.

BaseModule

Bases: LightningModule

Methods:

Name Description
set_explain_features

Enables SHAP values for the test set; fails before training for models without an explainer.

set_weight

Set the weight for the loss function.

set_explain_features

set_explain_features(explain_features: bool)

Enables SHAP values for the test set; fails before training for models without an explainer.

Source code in icu_benchmarks/models/wrappers.py
def set_explain_features(self, explain_features: bool):
    """Enables SHAP values for the test set; fails before training for models without an explainer."""
    if explain_features and self.explainer_cls is None:
        raise NotImplementedError(f"{type(self).__name__} does not support SHAP explanations.")
    self.explain_features = explain_features

set_weight

set_weight(weight, dataset)

Set the weight for the loss function.

Source code in icu_benchmarks/models/wrappers.py
def set_weight(self, weight, dataset):
    """Set the weight for the loss function."""

    if self.run_mode != RunMode.classification or weight in (None, ""):
        # Class weights only apply to the classification loss
        weight = None
    elif isinstance(weight, list):
        weight = FloatTensor(weight).to(self.device)
    elif weight == "balanced":
        weight = FloatTensor(dataset.get_balance()).to(self.device)
    self.loss_weights = weight

DLWrapper

DLWrapper(loss=CrossEntropyLoss(), optimizer=Adam, run_mode: RunMode = classification, input_shape=None, lr: float = 0.002, momentum: float = 0.9, lr_scheduler: Optional[str] = None, lr_factor: float = 0.99, lr_steps: Optional[List[int]] = None, epochs: int = 100, input_size: Tensor = None, initialization_method: str = 'normal', **kwargs)

Bases: BaseModule, ABC

General interface for Deep Learning (DL) models.

Methods:

Name Description
configure_optimizers

Configure optimizers and learning rate schedulers.

Source code in icu_benchmarks/models/wrappers.py
def __init__(
    self,
    loss=CrossEntropyLoss(),
    optimizer=Adam,
    run_mode: RunMode = RunMode.classification,
    input_shape=None,
    lr: float = 0.002,
    momentum: float = 0.9,
    lr_scheduler: Optional[str] = None,
    lr_factor: float = 0.99,
    lr_steps: Optional[List[int]] = None,
    epochs: int = 100,
    input_size: Tensor = None,
    initialization_method: str = "normal",
    **kwargs,
):
    """General interface for Deep Learning (DL) models."""
    super().__init__()
    self.save_hyperparameters(ignore=["loss", "optimizer"])
    self.loss = loss
    self.optimizer = optimizer
    self.check_supported_runmode(run_mode)
    self.run_mode = run_mode
    self.input_shape = input_shape
    self.lr = lr
    self.momentum = momentum
    self.lr_scheduler = lr_scheduler
    self.lr_factor = lr_factor
    self.lr_steps = lr_steps
    self.epochs = epochs
    self.input_size = input_size
    self.initialization_method = initialization_method

configure_optimizers

configure_optimizers()

Configure optimizers and learning rate schedulers.

Source code in icu_benchmarks/models/wrappers.py
def configure_optimizers(self):
    """Configure optimizers and learning rate schedulers."""

    if isinstance(self.optimizer, str):
        optimizer = create_optimizer(self.optimizer, self.lr, self.hparams.momentum)
    elif isinstance(self.optimizer, Optimizer):
        # Already set
        optimizer = self.optimizer
    else:
        optimizer = self.optimizer(self.parameters())

    if self.hparams.lr_scheduler is None or self.hparams.lr_scheduler == "":
        return optimizer
    scheduler = create_scheduler(
        self.hparams.lr_scheduler,
        optimizer,
        self.hparams.lr_factor,
        self.hparams.lr_steps,
        self.hparams.epochs,
    )
    optimizers = {"optimizer": optimizer, "lr_scheduler": scheduler}
    logging.info(f"Using: {optimizers}")
    return optimizers

DLPredictionWrapper

DLPredictionWrapper(loss=CrossEntropyLoss(), optimizer=Adam, run_mode: RunMode = classification, input_shape=None, lr: float = 0.002, momentum: float = 0.9, lr_scheduler: Optional[str] = None, lr_factor: float = 0.99, lr_steps: Optional[List[int]] = None, epochs: int = 100, input_size: Tensor = None, initialization_method: str = 'normal', **kwargs)

Bases: DLWrapper

Interface for Deep Learning models.

Methods:

Name Description
set_explain_features

Enables attributions of the test predictions; fails before training if they cannot be computed.

set_metrics

Set the evaluation metrics for the prediction model.

inverse_output_transform

Maps regression predictions and targets back to label units.

step_fn

Perform a step in the DL prediction model training loop.

Source code in icu_benchmarks/models/wrappers.py
def __init__(
    self,
    loss=CrossEntropyLoss(),
    optimizer=torch.optim.Adam,
    run_mode: RunMode = RunMode.classification,
    input_shape=None,
    lr: float = 0.002,
    momentum: float = 0.9,
    lr_scheduler: Optional[str] = None,
    lr_factor: float = 0.99,
    lr_steps: Optional[List[int]] = None,
    epochs: int = 100,
    input_size: Tensor = None,
    initialization_method: str = "normal",
    **kwargs,
):
    super().__init__(
        loss=loss,
        optimizer=optimizer,
        run_mode=run_mode,
        input_shape=input_shape,
        lr=lr,
        momentum=momentum,
        lr_scheduler=lr_scheduler,
        lr_factor=lr_factor,
        lr_steps=lr_steps,
        epochs=epochs,
        input_size=input_size,
        initialization_method=initialization_method,
        kwargs=kwargs,
    )
    self.output_transform = None
    self.loss_weights = None

set_explain_features

set_explain_features(explain_features: bool)

Enables attributions of the test predictions; fails before training if they cannot be computed.

Source code in icu_benchmarks/models/wrappers.py
def set_explain_features(self, explain_features: bool):
    """Enables attributions of the test predictions; fails before training if they cannot be computed."""
    if explain_features:
        from icu_benchmarks.models.explain import require_captum

        require_captum()
        if self.run_mode == RunMode.classification and self.logit.out_features != 2:
            raise NotImplementedError("Explanations support binary classification and regression models only.")
    self.explain_features = explain_features

set_metrics

set_metrics(*args)

Set the evaluation metrics for the prediction model.

Source code in icu_benchmarks/models/wrappers.py
def set_metrics(self, *args):
    """Set the evaluation metrics for the prediction model."""
    # Output transform is not applied for contrib metrics, so we do our own.
    if self.run_mode == RunMode.classification:
        # Binary classification
        if self.logit.out_features == 2:
            self.output_transform = softmax_binary_output_transform
            metrics = DLMetrics.BINARY_CLASSIFICATION
        else:
            # Multiclass classification
            self.output_transform = softmax_multi_output_transform
            metrics = DLMetrics.MULTICLASS_CLASSIFICATION
    # Regression
    elif self.run_mode == RunMode.regression:
        self.output_transform = self.inverse_output_transform
        metrics = DLMetrics.REGRESSION
    else:
        raise ValueError(f"Run mode {self.run_mode} not supported.")
    for key, value in metrics.items():
        # Torchmetrics metrics are not moved to the device by default
        if isinstance(value, torchmetrics.Metric):
            value.to(self.device)
    return metrics

inverse_output_transform

inverse_output_transform(output)

Maps regression predictions and targets back to label units.

Source code in icu_benchmarks/models/wrappers.py
def inverse_output_transform(self, output):
    """Maps regression predictions and targets back to label units."""
    return self.inverse_target(output[0]), self.inverse_target(output[1])

step_fn

step_fn(element, step_prefix='')

Perform a step in the DL prediction model training loop.

Parameters:

Name Type Description Default
element object
required
step_prefix str

Step type, by default: test, train, val.

''
Source code in icu_benchmarks/models/wrappers.py
def step_fn(self, element, step_prefix=""):
    """Perform a step in the DL prediction model training loop.

    Args:
        element (object):
        step_prefix (str): Step type, by default: test, train, val.
    """

    if len(element) == 2:
        data, labels = element[0], element[1].to(self.device)
        if isinstance(data, list):
            for i in range(len(data)):
                data[i] = data[i].float().to(self.device)
        else:
            data = data.float().to(self.device)
        mask = torch.ones_like(labels).bool()

    elif len(element) == 3:
        data, labels, mask = (
            element[0],
            element[1].to(self.device),
            element[2].to(self.device),
        )
        if isinstance(data, list):
            for i in range(len(data)):
                data[i] = data[i].float().to(self.device)
        else:
            data = data.float().to(self.device)
    else:
        raise Exception("Loader should return either (data, label) or (data, label, mask)")
    out = self(data)

    # If aux_loss is present, it is returned as a tuple
    if len(out) == 2 and isinstance(out, tuple):
        out, aux_loss = out
    else:
        aux_loss = 0
    # Get prediction and target
    prediction = torch.masked_select(out, mask.unsqueeze(-1)).reshape(-1, out.shape[-1]).to(self.device)
    target = torch.masked_select(labels, mask).to(self.device)
    if not target.numel():
        return out.sum() * 0  # Entirely unlabeled/padded batch: no loss or metric contribution.

    if prediction.shape[-1] > 1 and self.run_mode == RunMode.classification:
        # Classification task
        weight = self.loss_weights.to(self.device) if self.loss_weights is not None else None
        loss = self.loss(prediction, target.long(), weight=weight) + aux_loss
        # Returns torch.long because negative log likelihood loss
    elif self.run_mode == RunMode.regression:
        # Regression task
        loss = self.loss(prediction[:, 0], target.float()) + aux_loss
    else:
        raise ValueError(f"Run mode {self.run_mode} not yet supported. Please implement it.")
    transformed_output = self.output_transform((prediction, target))

    for key, value in self.metrics[step_prefix].items():
        if isinstance(value, torchmetrics.Metric):
            if key == "Binary_Fairness":
                feature_names = key.feature_helper(self.trainer)
                value.update(
                    transformed_output[0],
                    transformed_output[1],
                    data,
                    feature_names,
                )
            else:
                value.update(transformed_output[0], transformed_output[1])
        else:
            value.update(transformed_output)
    self.log(f"{step_prefix}/loss", loss, on_step=False, on_epoch=True, sync_dist=True)
    return loss

ObservationMaskWrapper

ObservationMaskWrapper(*args, input_size, **kwargs)

Bases: DLPredictionWrapper

Prediction wrapper for models that treat measured and imputed values differently, such as GRU-D and BAT.

YAIB's preprocessing recipe standardises the features, adds a MissingIndicator_<name> column that is 1 where <name> was not measured, and then forward-fills the missing values (and fills the hours before the first measurement with 0, the training mean). The observation mask is therefore already part of every input, so these models need no extra dataset or input: once the column names are known, each column is paired with its indicator column and observed_mask returns 1 where a value was measured and 0 where it was imputed.

train_common passes the dataset's feature names to set_trained_columns before training and evaluation. The pairing is kept in buffers, so it is stored in checkpoints and pickled models and follows the model between devices. Columns without an indicator (the indicators themselves, variables in the preprocessor's vars_to_exclude, generated features) count as always observed, and so does every column until the names are set.

Methods:

Name Description
observed_mask

Return 1 where a value of x (batch, time, columns) was measured and 0 where it was imputed.

Source code in icu_benchmarks/models/wrappers.py
def __init__(self, *args, input_size, **kwargs):
    super().__init__(*args, input_size=input_size, **kwargs)
    num_columns = input_size[2]
    # Position of each column's missingness indicator column, or -1 if it has none
    self.register_buffer("indicator_index", torch.full((num_columns,), -1, dtype=torch.long))
    # Whether a column is the missingness indicator of another column
    self.register_buffer("is_indicator", torch.zeros(num_columns, dtype=torch.bool))

observed_mask

observed_mask(x: Tensor) -> Tensor

Return 1 where a value of x (batch, time, columns) was measured and 0 where it was imputed.

Source code in icu_benchmarks/models/wrappers.py
def observed_mask(self, x: Tensor) -> Tensor:
    """Return 1 where a value of x (batch, time, columns) was measured and 0 where it was imputed."""
    indicators = x[..., self.indicator_index.clamp(min=0)]
    return torch.where(self.indicator_index >= 0, 1 - indicators, torch.ones_like(x))

MLWrapper

MLWrapper(*args, run_mode=classification, loss=log_loss, patience=10, mps=False, **kwargs)

Bases: BaseModule, ABC

Interface for prediction with traditional Scikit-learn-like Machine Learning models.

Methods:

Name Description
fit

Fit the model to the training data.

fit_model

Fit the model to the training data (default SKlearn syntax)

log_metrics

Log metrics to the PL logs.

set_model_args

Set hyperparameters of the model if they are supported by the model.

Source code in icu_benchmarks/models/wrappers.py
def __init__(
    self,
    *args,
    run_mode=RunMode.classification,
    loss=log_loss,
    patience=10,
    mps=False,
    **kwargs,
):
    super().__init__()
    self.save_hyperparameters()
    self.check_supported_runmode(run_mode)
    self.run_mode = run_mode
    self.loss = loss
    self.patience = patience
    self.mps = mps
    self.loss_weight = None

fit

fit(train_dataset, val_dataset)

Fit the model to the training data.

Source code in icu_benchmarks/models/wrappers.py
def fit(self, train_dataset, val_dataset):
    """Fit the model to the training data."""
    train_rep, train_label, row_indicators = train_dataset.get_data_and_labels()
    val_rep, val_label, row_indicators = val_dataset.get_data_and_labels()

    self.set_metrics(train_label)

    if "class_weight" in self.model.get_params().keys():  # Set class weights
        self.model.set_params(class_weight=self.weight)

    val_loss = self.fit_model(train_rep, train_label, val_rep, val_label)

    train_pred = self.predict(train_rep)

    logging.debug(f"Model:{self.model}")

    self.log("train/loss", self.loss(train_label, train_pred), sync_dist=True)
    logging.debug(f"Train loss: {self.loss(train_label, train_pred)}")
    self.log("val/loss", val_loss, sync_dist=True)
    logging.debug(f"Val loss: {val_loss}")
    self.log_metrics(train_label, train_pred, "train")

fit_model

fit_model(train_data, train_labels, val_data, val_labels)

Fit the model to the training data (default SKlearn syntax)

Source code in icu_benchmarks/models/wrappers.py
def fit_model(self, train_data, train_labels, val_data, val_labels):
    """Fit the model to the training data (default SKlearn syntax)"""
    self.model.fit(train_data, train_labels)
    val_loss = 0.0
    return val_loss

log_metrics

log_metrics(label, pred, metric_type)

Log metrics to the PL logs.

Source code in icu_benchmarks/models/wrappers.py
def log_metrics(self, label, pred, metric_type):
    """Log metrics to the PL logs."""
    if "Confusion_Matrix" in self.metrics:
        confusion = confusion_matrix(self.label_transform(label), self.output_transform(pred))
        # Prefix with the split like the other metrics, so the JSON logger writes it to e.g. test_metrics.json
        self.log_dict({f"{metric_type}/{name}": count for name, count in confusion.items()}, sync_dist=True)
    self.log_dict(
        {
            f"{metric_type}/{name}": (metric(self.label_transform(label), self.output_transform(pred)))
            # For every metric
            for name, metric in self.metrics.items()
            # Filter out metrics that return a tuple (e.g. precision_recall_curve)
            if not isinstance(
                metric(self.label_transform(label), self.output_transform(pred)),
                tuple,
            )
            and name != "Confusion_Matrix"
        },
        sync_dist=True,
    )

set_model_args

set_model_args(model, *args, **kwargs)

Set hyperparameters of the model if they are supported by the model.

Source code in icu_benchmarks/models/wrappers.py
def set_model_args(self, model, *args, **kwargs):
    """Set hyperparameters of the model if they are supported by the model."""
    signature = inspect.signature(model.__init__).parameters
    possible_hps = list(signature.keys())
    # Get passed keyword arguments
    arguments = locals()["kwargs"]
    # Get valid hyperparameters
    logging.debug(f"Possible hps: {possible_hps}")
    hyperparams = {key: value for key, value in arguments.items() if key in possible_hps}
    logging.debug(f"Creating model with: {hyperparams}.")
    return model(**hyperparams)

ImputationWrapper

ImputationWrapper(loss: _Loss = MSELoss(), optimizer: Union[str, Optimizer] = 'adam', run_mode: RunMode = imputation, lr: float = 0.002, momentum: float = 0.9, lr_scheduler: Optional[str] = None, lr_factor: float = 0.99, lr_steps: Optional[List[int]] = None, input_size: Tensor = None, initialization_method: ImputationInit = NORMAL, epochs=100, **kwargs: str)

Bases: DLWrapper

Interface for imputation models.

Source code in icu_benchmarks/models/wrappers.py
def __init__(
    self,
    loss: nn.modules.loss._Loss = MSELoss(),
    optimizer: Union[str, Optimizer] = "adam",
    run_mode: RunMode = RunMode.imputation,
    lr: float = 0.002,
    momentum: float = 0.9,
    lr_scheduler: Optional[str] = None,
    lr_factor: float = 0.99,
    lr_steps: Optional[List[int]] = None,
    input_size: Tensor = None,
    initialization_method: ImputationInit = ImputationInit.NORMAL,
    epochs=100,
    **kwargs: str,
) -> None:
    super().__init__(
        loss=loss,
        optimizer=optimizer,
        run_mode=run_mode,
        lr=lr,
        momentum=momentum,
        lr_scheduler=lr_scheduler,
        lr_factor=lr_factor,
        lr_steps=lr_steps,
        epochs=epochs,
        input_size=input_size,
        initialization_method=initialization_method,
        kwargs=kwargs,
    )
    self.check_supported_runmode(run_mode)
    self.run_mode = run_mode
    self.save_hyperparameters(ignore=["loss", "optimizer"])
    self.loss = loss
    self.optimizer = optimizer

icu_benchmarks.models.constants

Classes:

Name Description
ImputationInit

Type of initialization to use for the imputation model.

ImputationInit

Bases: str, Enum

Type of initialization to use for the imputation model.

icu_benchmarks.models.custom_metrics

" This file contains custom metrics that can be added to YAIB.

Classes:

Name Description
BinaryFairnessWrapper

This class is a wrapper for the BinaryFairness metric from TorchMetrics.

Functions:

Name Description
accuracy

Computes the accuracy over the k top predictions for the specified values of k

BinaryFairnessWrapper

BinaryFairnessWrapper(group_name='sex', *args, **kwargs)

Bases: BinaryFairness

This class is a wrapper for the BinaryFairness metric from TorchMetrics.

Methods:

Name Description
update

" Standard metric update function

feature_helper

Helper function to get the feature names from the trainer

Source code in icu_benchmarks/models/custom_metrics.py
def __init__(self, group_name="sex", *args, **kwargs) -> None:
    self.group_name = group_name
    super().__init__(*args, **kwargs)

update

update(preds, target, data, feature_names) -> None

" Standard metric update function

Source code in icu_benchmarks/models/custom_metrics.py
def update(self, preds, target, data, feature_names) -> None:
    """ " Standard metric update function"""
    groups = data[:, :, feature_names.index(self.group_name)]
    group_per_id = groups[:, 0]
    return super().update(preds=preds.cpu(), target=target.cpu(), groups=group_per_id.long().cpu())

feature_helper

feature_helper(trainer, step_prefix)

Helper function to get the feature names from the trainer

Source code in icu_benchmarks/models/custom_metrics.py
def feature_helper(self, trainer, step_prefix):
    """Helper function to get the feature names from the trainer"""
    if step_prefix == "train":
        feature_names = trainer.train_dataloader.dataset.features
    elif step_prefix == "val":
        feature_names = trainer.train_dataloader.dataset.features
    else:
        feature_names = trainer.test_dataloaders.dataset.features
    return feature_names

accuracy

accuracy(output, target, topk=(1,))

Computes the accuracy over the k top predictions for the specified values of k

Source code in icu_benchmarks/models/custom_metrics.py
def accuracy(output, target, topk=(1,)):
    """Computes the accuracy over the k top predictions for the specified values of k"""
    with torch.no_grad():
        maxk = max(topk)
        batch_size = target.size(0)

        _, pred = output.topk(maxk, 1, True, True)
        pred = pred.t()
        correct = pred.eq(target.view(1, -1).expand_as(pred))

        res = []
        for k in topk:
            correct_k = correct[:k].reshape(-1).float().sum(0, keepdim=True)
            res.append(correct_k.mul_(100.0 / batch_size))
        return res

icu_benchmarks.models.utils

Classes:

Name Description
JsonResultLoggingEncoder

JSON converter for objects that are not serializable by default.

scorer_wrapper

Wrapper that flattens the binary classification input such that we can use a broader range of sklearn metrics.

Functions:

Name Description
create_optimizer

creates the specified optimizer with the given parameters

create_scheduler

creates a learning rate scheduler with the given parameters

log_table_row

Logs a table row.

JsonResultLoggingEncoder

Bases: JSONEncoder

JSON converter for objects that are not serializable by default.

scorer_wrapper

scorer_wrapper(scorer=average_precision_score)

Wrapper that flattens the binary classification input such that we can use a broader range of sklearn metrics.

Source code in icu_benchmarks/models/utils.py
def __init__(self, scorer=average_precision_score):
    self.scorer = scorer

create_optimizer

create_optimizer(name: str, model: Module, lr: float, momentum: float = 0) -> Optimizer

creates the specified optimizer with the given parameters

Parameters:

Name Type Description Default
name str

str name of optimizer

required
model Module

the model used for training

required
lr float

learning rate

required
momentum float

momentum (only for sgd optimizer)

0

Raises:

Type Description
ValueError

thrown if optimizer name not known

Returns:

Name Type Description
Optimizer Optimizer

the model optimizer

Source code in icu_benchmarks/models/utils.py
def create_optimizer(name: str, model: Module, lr: float, momentum: float = 0) -> Optimizer:
    """creates the specified optimizer with the given parameters

    Args:
        name (str): str name of optimizer
        model (Module): the model used for training
        lr (float): learning rate
        momentum (float): momentum (only for sgd optimizer)

    Raises:
        ValueError: thrown if optimizer name not known

    Returns:
        Optimizer: the model optimizer
    """
    name = name.lower()
    if name == "adam":
        return Adam(params=model.parameters(), lr=lr)
    elif name == "sgd":
        return SGD(params=model.parameters(), lr=lr, momentum=momentum)
    elif name == "radam":
        return RAdam(params=model.parameters(), lr=lr)
    else:
        raise ValueError(f"No optimizer with name {name} found!")

create_scheduler

create_scheduler(scheduler_name: Optional[str], optimizer: Optimizer, lr_factor: float, lr_steps: Optional[list], epochs: int) -> Union[_LRScheduler, None]

creates a learning rate scheduler with the given parameters

Parameters:

Name Type Description Default
scheduler_name Optional[str]

str name of scheduler or None, in which case None will be returned

required
optimizer Optimizer

the learning optimizer

required
lr_factor float

the learning rate factor

required
lr_steps Optional[list]

learning rate steps for the scheduler to take (only supported for step scheduler)

required
epochs int

number of scheduler epochs (only supported for cosine scheduler)

required

Raises:

Type Description
ValueError

thrown if step scheduler was chosen but no steps were passed

ValueError

thrown if scheduler name not known and not None

Returns:

Type Description
Union[_LRScheduler, None]

Union[_LRScheduler, None]: either the learning rate scheduler object or None if scheduler_name was None

Source code in icu_benchmarks/models/utils.py
def create_scheduler(
    scheduler_name: Optional[str],
    optimizer: Optimizer,
    lr_factor: float,
    lr_steps: Optional[list],
    epochs: int,
) -> Union[_LRScheduler, None]:
    """creates a learning rate scheduler with the given parameters

    Args:
        scheduler_name (Optional[str]): str name of scheduler or None, in which case None will be returned
        optimizer (Optimizer): the learning optimizer
        lr_factor (float): the learning rate factor
        lr_steps (Optional[list]): learning rate steps for the scheduler to take (only supported for step scheduler)
        epochs (int): number of scheduler epochs (only supported for cosine scheduler)

    Raises:
        ValueError: thrown if step scheduler was chosen but no steps were passed
        ValueError: thrown if scheduler name not known and not None

    Returns:
        Union[_LRScheduler, None]: either the learning rate scheduler object or None if scheduler_name was None
    """
    if scheduler_name == "step":
        if not lr_steps:
            raise ValueError("step scheduler chosen but no lr steps passed!")
        return MultiStepLR(optimizer, lr_steps, lr_factor)
    elif scheduler_name == "exponential":
        return ExponentialLR(optimizer, lr_factor)
    elif scheduler_name == "cosine":
        return CosineAnnealingLR(optimizer, epochs)
    elif not scheduler_name:
        return None
    else:
        raise ValueError(f"no scheduler with name {scheduler_name} found!")

log_table_row

log_table_row(cells: list, level: int = INFO, widths: list[int] = None, header: list[str] = None, align: Align = LEFT, highlight: bool = False)

Logs a table row.

Parameters:

Name Type Description Default
cells list

List of cells to log.

required
level int

Logging level.

INFO
widths list[int]

List of widths for each cell.

None
header list[str]

List of headers to calculate widths if widths not supplied.

None
highlight bool

If set to true, highlight the row.

False
Source code in icu_benchmarks/models/utils.py
def log_table_row(
    cells: list,
    level: int = logging.INFO,
    widths: list[int] = None,
    header: list[str] = None,
    align: Align = Align.LEFT,
    highlight: bool = False,
):
    """Logs a table row.

    Args:
        cells: List of cells to log.
        level: Logging level.
        widths: List of widths for each cell.
        header: List of headers to calculate widths if widths not supplied.
        highlight: If set to true, highlight the row.
    """
    table_cells = cells
    if not widths and header:
        widths = [len(head) for head in header]
    if widths:
        table_cells = []
        for cell, width in zip(cells, widths):
            cell = str(cell)[:width]  # truncate cell if it is too long
            table_cells.append("{: {align}{width}}".format(cell, align=align.value, width=width))
    table_row = " | ".join([f"{cell}" for cell in table_cells])
    if highlight:
        table_row = f"\x1b[31;32m{table_row}\x1b[0m"
    logging.log(level, table_row)

Explanations

Attributions and explanation-quality metrics for the deep learning models; see Feature explanations.

icu_benchmarks.models.explain

Feature attributions and explanation-quality metrics for the deep learning prediction models.

train_common calls :func:explain_predictions after testing a deep learning model when --explain-features is set. It explains every labeled hour of a sample of test stays and saves, per fold:

  • test_attributions.parquet: one row per method and explained hour, with one column per variable.
  • test_feature_importance.parquet: the mean absolute attribution of each variable, per method.
  • test_explanation_metrics.json: faithfulness, deletion and sparsity of each method, averaged over the explained hours. aggregate_results averages them over the folds like the other test metrics.

Integrated Gradients needs the optional captum package: uv sync --extra explain.

Modules:

Name Description
attribution

Attributions of deep learning predictions to the input variables, for every labeled hour.

metrics

Explanation-quality metrics for variable-level attributions.

Functions:

Name Description
require_captum

Fails early, with the install command, when the optional captum package is missing.

require_polars

Fails before training when the datasets are Pandas ones: the explanations read stay IDs and hours from Polars.

stay_times

The sequence value (e.g. the hour) of each input row, per stay, in the dataset's input order.

explain_predictions

Explains every labeled hour of a sample of test stays and saves the attributions and their quality metrics.

scale

The factor from the model's output space to native target units: regression models predict scaled targets.

save_explanations

Writes the attributions (in native units for regression), the feature importances and the metrics.

require_captum

require_captum() -> None

Fails early, with the install command, when the optional captum package is missing.

Source code in icu_benchmarks/models/explain/__init__.py
def require_captum() -> None:
    """Fails early, with the install command, when the optional captum package is missing."""
    try:
        import captum  # noqa: F401
    except ImportError as error:
        raise ImportError(
            "Explaining deep learning models needs the optional captum package. Install it with `uv sync --extra explain`."
        ) from error

require_polars

require_polars(polars: bool) -> None

Fails before training when the datasets are Pandas ones: the explanations read stay IDs and hours from Polars.

Source code in icu_benchmarks/models/explain/__init__.py
def require_polars(polars: bool) -> None:
    """Fails before training when the datasets are Pandas ones: the explanations read stay IDs and hours from Polars."""
    if not polars:
        raise NotImplementedError("Explaining deep learning models needs the Polars datasets (train_common.polars = True).")

stay_times

stay_times(dataset) -> dict

The sequence value (e.g. the hour) of each input row, per stay, in the dataset's input order.

Source code in icu_benchmarks/models/explain/__init__.py
def stay_times(dataset) -> dict:
    """The sequence value (e.g. the hour) of each input row, per stay, in the dataset's input order."""
    group, sequence = dataset.vars["GROUP"], dataset.vars["SEQUENCE"]
    rows = dataset.row_indicators
    if not isinstance(rows, pl.DataFrame) or sequence not in rows.columns:
        return {}
    by_stay = rows.sort([group, sequence]).group_by(group, maintain_order=True).agg(pl.col(sequence))
    return dict(by_stay.iter_rows())

explain_predictions

explain_predictions(model, dataset, log_dir: Path, methods: tuple[str, ...] = METHODS, metrics: tuple[str, ...] = METRICS, max_stays: int = 100, ig_steps: int = 32, batch_size: int = 64, faithfulness_subsets: int = 20, faithfulness_subset_size: float = 0.1, deletion_steps: int = 10, seed: int = 0) -> dict[str, float]

Explains every labeled hour of a sample of test stays and saves the attributions and their quality metrics.

Parameters:

Name Type Description Default
model

A trained deep learning prediction model (binary classification or regression).

required
dataset

The test dataset (PredictionPolarsDataset).

required
log_dir Path

The fold directory to save the results in.

required
methods tuple[str, ...]

Attribution methods: IntegratedGradients, FeatureAblation and/or Random (a reference).

METHODS
metrics tuple[str, ...]

Quality metrics: faithfulness, deletion and/or sparsity.

METRICS
max_stays int

Number of test stays to explain, drawn at random; every labeled hour of each is explained.

100
ig_steps int

Integration steps of Integrated Gradients.

32
batch_size int

Number of inputs per forward pass.

64
faithfulness_subsets int

Number of random variable subsets per stay for the faithfulness correlation.

20
faithfulness_subset_size float

Share of the variables in each subset.

0.1
deletion_steps int

Number of top variables removed one by one for the deletion curve.

10
seed int

Seed for drawing the stays, the subsets and the random reference.

0

Returns:

Type Description
dict[str, float]

The explanation metrics, keyed explain/<method>/<metric>.

Source code in icu_benchmarks/models/explain/__init__.py
@gin.configurable("explain_predictions")
def explain_predictions(
    model,
    dataset,
    log_dir: Path,
    methods: tuple[str, ...] = METHODS,
    metrics: tuple[str, ...] = METRICS,
    max_stays: int = 100,
    ig_steps: int = 32,
    batch_size: int = 64,
    faithfulness_subsets: int = 20,
    faithfulness_subset_size: float = 0.1,
    deletion_steps: int = 10,
    seed: int = 0,
) -> dict[str, float]:
    """Explains every labeled hour of a sample of test stays and saves the attributions and their quality metrics.

    Args:
        model: A trained deep learning prediction model (binary classification or regression).
        dataset: The test dataset (``PredictionPolarsDataset``).
        log_dir: The fold directory to save the results in.
        methods: Attribution methods: ``IntegratedGradients``, ``FeatureAblation`` and/or ``Random`` (a reference).
        metrics: Quality metrics: ``faithfulness``, ``deletion`` and/or ``sparsity``.
        max_stays: Number of test stays to explain, drawn at random; every labeled hour of each is explained.
        ig_steps: Integration steps of Integrated Gradients.
        batch_size: Number of inputs per forward pass.
        faithfulness_subsets: Number of random variable subsets per stay for the faithfulness correlation.
        faithfulness_subset_size: Share of the variables in each subset.
        deletion_steps: Number of top variables removed one by one for the deletion curve.
        seed: Seed for drawing the stays, the subsets and the random reference.

    Returns:
        The explanation metrics, keyed ``explain/<method>/<metric>``.
    """
    unknown = set(methods) - set(METHODS) or set(metrics) - set(METRICS)
    if unknown:
        raise ValueError(f"Unknown explanation methods or metrics: {sorted(unknown)}.")
    if "IntegratedGradients" in methods:
        require_captum()
    if not hasattr(dataset, "get_input_names"):
        raise NotImplementedError("Explanations need the Polars prediction dataset.")
    start = time.time()
    rng = np.random.default_rng(seed)

    columns = dataset.get_input_names()
    names, group_of = variable_groups(columns)
    n_variables = len(names)
    group_of = torch.as_tensor(group_of)
    baseline = missing_baseline(columns)

    selected = np.sort(rng.choice(len(dataset), size=min(max_stays, len(dataset)), replace=False))
    items = [dataset[int(index)] for index in selected]
    stay_inputs = torch.stack([item[0] for item in items]).float()
    labeled = torch.stack([item[2] for item in items]).bool()
    if stay_inputs.shape[-1] != len(columns):
        raise ValueError(f"The inputs have {stay_inputs.shape[-1]} columns, but the dataset names {len(columns)}.")
    stays, hours = (index.long() for index in torch.nonzero(labeled, as_tuple=True))
    if len(stays) == 0:
        logging.warning("No labeled hours in the sampled test stays; skipping explanations.")
        return {}
    explained = list(zip(stays.tolist(), hours.tolist()))
    logging.info(f"Explaining {len(explained)} labeled hours of {len(selected)} test stays with {', '.join(methods)}.")

    was_training = model.training
    model.eval()
    # cuDNN implements RNN backward passes only in training mode; the plain CUDA kernels work in eval mode too
    cudnn_off = torch.backends.cudnn.flags(enabled=False) if torch.cuda.is_available() else nullcontext()
    try:
        with torch.enable_grad(), cudnn_off:
            stay_outputs = output_all_hours(model, stay_inputs, batch_size)  # (stays, hours)
            output = stay_outputs[stays, hours].numpy()
            attributions, results = {}, {}
            for method in methods:
                if method == "IntegratedGradients":
                    attributions[method], deltas = integrated_gradients(
                        model, stay_inputs, stays, hours, baseline, group_of, n_variables, ig_steps, batch_size
                    )
                    results[f"explain/{method}/convergence_delta"] = float(np.mean(deltas)) / scale(model)
                elif method == "FeatureAblation":
                    attributions[method] = feature_ablation(
                        stay_inputs, stay_outputs, explained, model, baseline, group_of, n_variables, batch_size
                    )
                else:
                    attributions[method] = random_attribution(len(explained), n_variables, rng)

            if "faithfulness" in metrics:
                # The same subsets for every method, so that their scores are comparable
                size = max(1, round(faithfulness_subset_size * n_variables))
                stay_subsets = np.zeros((len(selected), faithfulness_subsets, n_variables), dtype=bool)
                for stay in range(len(selected)):
                    for subset in range(faithfulness_subsets):
                        stay_subsets[stay, subset, rng.choice(n_variables, size=size, replace=False)] = True
                subset_outputs = torch.stack(
                    [
                        output_all_hours(
                            model,
                            remove_variables(stay_inputs[stay].unsqueeze(0), torch.as_tensor(subsets), group_of, baseline),
                            batch_size,
                        )
                        for stay, subsets in enumerate(stay_subsets)
                    ]
                )  # (stays, subsets, hours)
                drops = output[:, None] - subset_outputs[stays, :, hours].numpy()
                for method, attribution in attributions.items():
                    scores = faithfulness_correlation(attribution, stay_subsets[stays.numpy()], drops)
                    results[f"explain/{method}/faithfulness"] = (
                        float(np.nanmean(scores)) if np.isfinite(scores).any() else None
                    )

            if "deletion" in metrics:
                steps = min(deletion_steps, n_variables)
                for method, attribution in attributions.items():
                    top = torch.as_tensor(np.argsort(-attribution, axis=1)[:, :steps])  # (explained, steps)
                    # Step k removes the top k + 1 variables
                    removed = torch.zeros(len(explained), steps, n_variables, dtype=torch.bool)
                    rows = torch.arange(len(explained))
                    for k in range(steps):
                        if k:
                            removed[:, k] = removed[:, k - 1]
                        removed[rows, k, top[:, k]] = True
                    deleted = []
                    for part in chunks(len(explained), max(1, batch_size // steps)):
                        x = remove_variables(stay_inputs[stays[part]].unsqueeze(1), removed[part], group_of, baseline)
                        out = output_all_hours(model, x.flatten(0, 1), batch_size).view(len(x), steps, -1)
                        deleted.append(out[torch.arange(len(x)), :, hours[part]])
                    scores = deletion_aopc(output, torch.cat(deleted).numpy())
                    results[f"explain/{method}/deletion"] = float(np.mean(scores)) / scale(model)

            if "sparsity" in metrics:
                for method, attribution in attributions.items():
                    scores = sparsity(attribution)
                    results[f"explain/{method}/sparsity"] = float(np.nanmean(scores)) if np.isfinite(scores).any() else None
    finally:
        model.train(was_training)

    save_explanations(log_dir, dataset, selected, explained, names, attributions, scale(model), results)
    logging.info(f"Explanations saved to {log_dir} in {time.time() - start:.1f} s.")
    return results

scale

scale(model) -> float

The factor from the model's output space to native target units: regression models predict scaled targets.

Source code in icu_benchmarks/models/explain/__init__.py
def scale(model) -> float:
    """The factor from the model's output space to native target units: regression models predict scaled targets."""
    transform = getattr(model, "target_transform", None)
    return transform.scale if transform is not None else 1.0

save_explanations

save_explanations(log_dir, dataset, selected, explained, names, attributions, output_scale, results) -> None

Writes the attributions (in native units for regression), the feature importances and the metrics.

Source code in icu_benchmarks/models/explain/__init__.py
def save_explanations(log_dir, dataset, selected, explained, names, attributions, output_scale, results) -> None:
    """Writes the attributions (in native units for regression), the feature importances and the metrics."""
    group, sequence = dataset.vars["GROUP"], dataset.vars["SEQUENCE"]
    stay_ids = dataset.get_stay_ids()
    times = stay_times(dataset)
    ids = [stay_ids[int(selected[stay])] for stay, _ in explained]
    hour_values = [times[stay_id][hour] if stay_id in times else hour for stay_id, (_, hour) in zip(ids, explained)]
    frames, importance = [], []
    for method, attribution in attributions.items():
        native = (attribution / output_scale).astype(np.float32)
        frame = pl.DataFrame(native, schema=names, orient="row")
        frames.append(
            frame.with_columns(pl.Series(group, ids), pl.Series(sequence, hour_values), pl.lit(method).alias("method"))
        )
        importance.append(
            pl.DataFrame(
                {
                    "method": method,
                    "variable": names,
                    "mean_abs_attribution": np.abs(native).mean(axis=0),
                    "mean_attribution": native.mean(axis=0),
                }
            )
        )
    attributions_frame = pl.concat(frames)
    attributions_frame.select(group, sequence, "method", *names).write_parquet(log_dir / "test_attributions.parquet")
    pl.concat(importance).write_parquet(log_dir / "test_feature_importance.parquet")
    with open(log_dir / "test_explanation_metrics.json", "w") as f:
        json.dump(results, f, indent=2)

icu_benchmarks.models.explain.attribution

Attributions of deep learning predictions to the input variables, for every labeled hour.

A variable is a value column together with its MissingIndicator_<name> column, so that removing a variable means "not measured": its value is set to 0 (the training mean, after YAIB's standardisation) and its indicator to 1. Columns without an indicator (vars_to_exclude and generated features such as counter) are set to 0 too, which means "replaced by the training mean" rather than "not measured". All methods return one attribution per explained hour and variable, summed over the hours before it and over the variable's columns.

The explained output is the log-odds of the positive class for binary classification (logit 1 minus logit 0) and the predicted value for regression, at the hour being explained.

Functions:

Name Description
variable_groups

Groups each value column with its missingness indicator.

missing_baseline

The input of a removed variable: 0 for values, 1 for missingness indicators.

explained_output

Reduces the model output of shape (..., classes) to the explained scalar: binary log-odds or the regression value.

output_at_hours

The explained output of each sample at its own hour, shape (samples,). Differentiable, for Captum.

output_all_hours

The explained output at every hour, shape (samples, hours), computed in batches without gradients.

remove_variables

Sets the whole history of the removed variables to the baseline.

chunks

Slices of at most size consecutive indices that cover range(n), for batched forward passes.

integrated_gradients

Integrated Gradients (Sundararajan et al., 2017) from the "not measured" baseline, with Captum.

feature_ablation

Occlusion of each variable's whole history: the output drop when the variable is set to "not measured".

random_attribution

Random attributions, the reference that every metric should beat.

variable_groups

variable_groups(columns: list[str]) -> tuple[list[str], ndarray]

Groups each value column with its missingness indicator.

Parameters:

Name Type Description Default
columns list[str]

The model's input columns, in input order.

required

Returns:

Type Description
list[str]

The variable names, and for each column the index of its variable. An indicator without a matching value column

ndarray

is its own variable.

Source code in icu_benchmarks/models/explain/attribution.py
def variable_groups(columns: list[str]) -> tuple[list[str], np.ndarray]:
    """Groups each value column with its missingness indicator.

    Args:
        columns: The model's input columns, in input order.

    Returns:
        The variable names, and for each column the index of its variable. An indicator without a matching value column
        is its own variable.
    """
    names: list[str] = []
    index: dict[str, int] = {}
    group_of = []
    present = set(columns)
    for column in columns:
        base = column[len(INDICATOR_PREFIX) :] if column.startswith(INDICATOR_PREFIX) else column
        variable = base if base in present else column
        if variable not in index:
            index[variable] = len(names)
            names.append(variable)
        group_of.append(index[variable])
    return names, np.asarray(group_of)

missing_baseline

missing_baseline(columns: list[str]) -> Tensor

The input of a removed variable: 0 for values, 1 for missingness indicators.

For a variable with an indicator this is "never measured". A column without one gets 0, the training mean after standardisation, so removing it replaces it by the mean.

Source code in icu_benchmarks/models/explain/attribution.py
def missing_baseline(columns: list[str]) -> Tensor:
    """The input of a removed variable: 0 for values, 1 for missingness indicators.

    For a variable with an indicator this is "never measured". A column without one gets 0, the training mean after
    standardisation, so removing it replaces it by the mean.
    """
    return torch.tensor([1.0 if column.startswith(INDICATOR_PREFIX) else 0.0 for column in columns])

explained_output

explained_output(output: Tensor | tuple) -> Tensor

Reduces the model output of shape (..., classes) to the explained scalar: binary log-odds or the regression value.

Source code in icu_benchmarks/models/explain/attribution.py
def explained_output(output: Tensor | tuple) -> Tensor:
    """Reduces the model output of shape (..., classes) to the explained scalar: binary log-odds or the regression value."""
    if isinstance(output, tuple):  # Models with an auxiliary loss return (prediction, aux_loss)
        output = output[0]
    if output.shape[-1] == 2:
        return output[..., 1] - output[..., 0]
    if output.shape[-1] == 1:
        return output[..., 0]
    raise NotImplementedError(f"Explanations support binary classification and regression, not {output.shape[-1]} classes.")

output_at_hours

output_at_hours(model: Module, x: Tensor, hours: Tensor) -> Tensor

The explained output of each sample at its own hour, shape (samples,). Differentiable, for Captum.

Source code in icu_benchmarks/models/explain/attribution.py
def output_at_hours(model: torch.nn.Module, x: Tensor, hours: Tensor) -> Tensor:
    """The explained output of each sample at its own hour, shape (samples,). Differentiable, for Captum."""
    output = explained_output(model(x))
    return output[torch.arange(len(hours), device=output.device), hours]

output_all_hours

output_all_hours(model: Module, x: Tensor, batch_size: int) -> Tensor

The explained output at every hour, shape (samples, hours), computed in batches without gradients.

Source code in icu_benchmarks/models/explain/attribution.py
@torch.no_grad()
def output_all_hours(model: torch.nn.Module, x: Tensor, batch_size: int) -> Tensor:
    """The explained output at every hour, shape (samples, hours), computed in batches without gradients."""
    device = next(model.parameters()).device
    outputs = [explained_output(model(chunk.to(device))).cpu() for chunk in x.split(batch_size)]
    return torch.cat(outputs)

remove_variables

remove_variables(x: Tensor, removed: Tensor, group_of: Tensor, baseline: Tensor) -> Tensor

Sets the whole history of the removed variables to the baseline.

Parameters:

Name Type Description Default
x Tensor

Inputs of shape (..., hours, columns).

required
removed Tensor

Boolean masks of shape (..., variables), broadcastable to the leading dimensions of x.

required
group_of Tensor

The variable index of each column, shape (columns,).

required
baseline Tensor

The baseline value of each column, shape (columns,).

required
Source code in icu_benchmarks/models/explain/attribution.py
def remove_variables(x: Tensor, removed: Tensor, group_of: Tensor, baseline: Tensor) -> Tensor:
    """Sets the whole history of the removed variables to the baseline.

    Args:
        x: Inputs of shape (..., hours, columns).
        removed: Boolean masks of shape (..., variables), broadcastable to the leading dimensions of x.
        group_of: The variable index of each column, shape (columns,).
        baseline: The baseline value of each column, shape (columns,).
    """
    columns = removed[..., group_of].unsqueeze(-2)  # (..., 1, columns)
    return torch.where(columns, baseline, x)

chunks

chunks(n: int, size: int) -> Iterator[slice]

Slices of at most size consecutive indices that cover range(n), for batched forward passes.

Source code in icu_benchmarks/models/explain/attribution.py
def chunks(n: int, size: int) -> Iterator[slice]:
    """Slices of at most ``size`` consecutive indices that cover ``range(n)``, for batched forward passes."""
    for start in range(0, n, size):
        yield slice(start, min(start + size, n))

integrated_gradients

integrated_gradients(model: Module, stay_inputs: Tensor, stays: Tensor, hours: Tensor, baseline: Tensor, group_of: Tensor, n_variables: int, steps: int, batch_size: int) -> tuple[ndarray, ndarray]

Integrated Gradients (Sundararajan et al., 2017) from the "not measured" baseline, with Captum.

Parameters:

Name Type Description Default
model Module

The model, in eval mode.

required
stay_inputs Tensor

The inputs of the explained stays, shape (stays, hours, columns).

required
stays Tensor

The stay index of each explained hour.

required
hours Tensor

The hour to explain, for each explained hour.

required
baseline Tensor

The baseline value of each column.

required
group_of Tensor

The variable index of each column.

required
n_variables int

The number of variables.

required
steps int

The number of integration steps.

required
batch_size int

The number of explained hours per Captum call.

required

Returns:

Type Description
ndarray

The attributions of shape (explained hours, variables), and the absolute convergence delta of each explained

ndarray

hour (how far the attributions are from summing to the output difference).

Source code in icu_benchmarks/models/explain/attribution.py
def integrated_gradients(
    model: torch.nn.Module,
    stay_inputs: Tensor,
    stays: Tensor,
    hours: Tensor,
    baseline: Tensor,
    group_of: Tensor,
    n_variables: int,
    steps: int,
    batch_size: int,
) -> tuple[np.ndarray, np.ndarray]:
    """Integrated Gradients (Sundararajan et al., 2017) from the "not measured" baseline, with Captum.

    Args:
        model: The model, in eval mode.
        stay_inputs: The inputs of the explained stays, shape (stays, hours, columns).
        stays: The stay index of each explained hour.
        hours: The hour to explain, for each explained hour.
        baseline: The baseline value of each column.
        group_of: The variable index of each column.
        n_variables: The number of variables.
        steps: The number of integration steps.
        batch_size: The number of explained hours per Captum call.

    Returns:
        The attributions of shape (explained hours, variables), and the absolute convergence delta of each explained
        hour (how far the attributions are from summing to the output difference).
    """
    from captum.attr import IntegratedGradients

    device = next(model.parameters()).device
    explainer = IntegratedGradients(lambda inputs, at: output_at_hours(model, inputs, at))
    group_one_hot = torch.nn.functional.one_hot(group_of, n_variables).float().to(device)  # (columns, variables)
    attributions, deltas = [], []
    for part in chunks(len(stays), batch_size):
        inputs = stay_inputs[stays[part]].to(device)
        attribution, delta = explainer.attribute(
            inputs,
            baselines=baseline.to(device).expand_as(inputs),
            additional_forward_args=(hours[part].to(device),),
            n_steps=steps,
            internal_batch_size=batch_size,
            return_convergence_delta=True,
        )
        attributions.append((attribution.sum(dim=1) @ group_one_hot).detach().cpu())
        deltas.append(delta.abs().detach().cpu())
    return torch.cat(attributions).numpy(), torch.cat(deltas).numpy()

feature_ablation

feature_ablation(stay_inputs: Tensor, stay_outputs: Tensor, explained: list[tuple[int, int]], model: Module, baseline: Tensor, group_of: Tensor, n_variables: int, batch_size: int) -> ndarray

Occlusion of each variable's whole history: the output drop when the variable is set to "not measured".

One forward pass per stay and variable gives the drop at every hour of the stay at once.

Parameters:

Name Type Description Default
stay_inputs Tensor

The inputs of the explained stays, shape (stays, hours, columns).

required
stay_outputs Tensor

Their explained outputs at every hour, shape (stays, hours).

required
explained list[tuple[int, int]]

The (stay index, hour) of each explained hour.

required
model Module

The model, in eval mode.

required
baseline Tensor

The baseline value of each column.

required
group_of Tensor

The variable index of each column.

required
n_variables int

The number of variables.

required
batch_size int

The number of inputs per forward pass.

required

Returns:

Type Description
ndarray

The attributions of shape (explained hours, variables).

Source code in icu_benchmarks/models/explain/attribution.py
def feature_ablation(
    stay_inputs: Tensor,
    stay_outputs: Tensor,
    explained: list[tuple[int, int]],
    model: torch.nn.Module,
    baseline: Tensor,
    group_of: Tensor,
    n_variables: int,
    batch_size: int,
) -> np.ndarray:
    """Occlusion of each variable's whole history: the output drop when the variable is set to "not measured".

    One forward pass per stay and variable gives the drop at every hour of the stay at once.

    Args:
        stay_inputs: The inputs of the explained stays, shape (stays, hours, columns).
        stay_outputs: Their explained outputs at every hour, shape (stays, hours).
        explained: The (stay index, hour) of each explained hour.
        model: The model, in eval mode.
        baseline: The baseline value of each column.
        group_of: The variable index of each column.
        n_variables: The number of variables.
        batch_size: The number of inputs per forward pass.

    Returns:
        The attributions of shape (explained hours, variables).
    """
    removed = torch.eye(n_variables, dtype=torch.bool)  # one variable per row
    drops = {}
    for stay in sorted({stay for stay, _ in explained}):
        ablated = remove_variables(stay_inputs[stay].unsqueeze(0), removed, group_of, baseline)  # (variables, hours, cols)
        drops[stay] = stay_outputs[stay].unsqueeze(0) - output_all_hours(model, ablated, batch_size)  # (variables, hours)
    return np.stack([drops[stay][:, hour].numpy() for stay, hour in explained])

random_attribution

random_attribution(n_explained: int, n_variables: int, rng: Generator) -> ndarray

Random attributions, the reference that every metric should beat.

Source code in icu_benchmarks/models/explain/attribution.py
def random_attribution(n_explained: int, n_variables: int, rng: np.random.Generator) -> np.ndarray:
    """Random attributions, the reference that every metric should beat."""
    return rng.standard_normal((n_explained, n_variables))

icu_benchmarks.models.explain.metrics

Explanation-quality metrics for variable-level attributions.

All metrics work on one attribution vector per explained hour (one value per variable) and remove a variable by setting its whole history, value and missingness indicator together, to the "not measured" baseline.

Functions:

Name Description
sparsity

Gini index of the absolute attributions of each explained hour (Chalasani et al., 2020).

faithfulness_correlation

Pearson correlation between the attribution of random variable subsets and the output drop when they are removed.

deletion_aopc

Area over the perturbation curve (Samek et al., 2017) for removing the k highest-attributed variables, k = 1..K.

sparsity

sparsity(attributions: ndarray) -> ndarray

Gini index of the absolute attributions of each explained hour (Chalasani et al., 2020).

Parameters:

Name Type Description Default
attributions ndarray

Attributions of shape (hours, variables).

required

Returns:

Type Description
ndarray

One value per explained hour: 0 when every variable gets the same share, close to 1 when one variable gets all of

ndarray

it. NaN for an all-zero attribution.

Source code in icu_benchmarks/models/explain/metrics.py
def sparsity(attributions: np.ndarray) -> np.ndarray:
    """Gini index of the absolute attributions of each explained hour (Chalasani et al., 2020).

    Args:
        attributions: Attributions of shape (hours, variables).

    Returns:
        One value per explained hour: 0 when every variable gets the same share, close to 1 when one variable gets all of
        it. NaN for an all-zero attribution.
    """
    values = np.sort(np.abs(attributions), axis=1)
    n = values.shape[1]
    total = values.sum(axis=1)
    weights = 2 * np.arange(1, n + 1) - n - 1
    with np.errstate(invalid="ignore", divide="ignore"):
        gini = (values * weights).sum(axis=1) / (n * total)
    return np.where(total > 0, gini, np.nan)

faithfulness_correlation

faithfulness_correlation(attributions: ndarray, subsets: ndarray, output_drops: ndarray) -> ndarray

Pearson correlation between the attribution of random variable subsets and the output drop when they are removed.

Bhatt et al. (2020): a faithful attribution assigns more to subsets whose removal changes the output more.

Parameters:

Name Type Description Default
attributions ndarray

Attributions of shape (hours, variables).

required
subsets ndarray

Boolean masks of the removed variables, shape (hours, subsets, variables).

required
output_drops ndarray

Model output minus the output without the subset, shape (hours, subsets).

required

Returns:

Type Description
ndarray

One correlation per explained hour; NaN where the attributions or the drops do not vary across the subsets.

Source code in icu_benchmarks/models/explain/metrics.py
def faithfulness_correlation(attributions: np.ndarray, subsets: np.ndarray, output_drops: np.ndarray) -> np.ndarray:
    """Pearson correlation between the attribution of random variable subsets and the output drop when they are removed.

    Bhatt et al. (2020): a faithful attribution assigns more to subsets whose removal changes the output more.

    Args:
        attributions: Attributions of shape (hours, variables).
        subsets: Boolean masks of the removed variables, shape (hours, subsets, variables).
        output_drops: Model output minus the output without the subset, shape (hours, subsets).

    Returns:
        One correlation per explained hour; NaN where the attributions or the drops do not vary across the subsets.
    """
    sums = np.einsum("hv,hsv->hs", attributions, subsets.astype(attributions.dtype))
    sums = sums - sums.mean(axis=1, keepdims=True)
    drops = output_drops - output_drops.mean(axis=1, keepdims=True)
    denominator = np.sqrt((sums**2).sum(axis=1) * (drops**2).sum(axis=1))
    with np.errstate(invalid="ignore", divide="ignore"):
        correlation = (sums * drops).sum(axis=1) / denominator
    return np.where(denominator > 1e-12, correlation, np.nan)

deletion_aopc

deletion_aopc(output: ndarray, deleted_outputs: ndarray) -> ndarray

Area over the perturbation curve (Samek et al., 2017) for removing the k highest-attributed variables, k = 1..K.

Parameters:

Name Type Description Default
output ndarray

Model output of each explained hour, shape (hours,).

required
deleted_outputs ndarray

Output after removing the top k variables, shape (hours, K).

required

Returns:

Type Description
ndarray

The mean output drop over k for each explained hour. Higher means the attribution found the variables that drive

ndarray

the output.

Source code in icu_benchmarks/models/explain/metrics.py
def deletion_aopc(output: np.ndarray, deleted_outputs: np.ndarray) -> np.ndarray:
    """Area over the perturbation curve (Samek et al., 2017) for removing the k highest-attributed variables, k = 1..K.

    Args:
        output: Model output of each explained hour, shape (hours,).
        deleted_outputs: Output after removing the top k variables, shape (hours, K).

    Returns:
        The mean output drop over k for each explained hour. Higher means the attribution found the variables that drive
        the output.
    """
    return (output[:, None] - deleted_outputs).mean(axis=1)