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
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 | |
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
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
set_weight
¶
Set the weight for the loss function.
Source code in icu_benchmarks/models/wrappers.py
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
configure_optimizers
¶
Configure optimizers and learning rate schedulers.
Source code in icu_benchmarks/models/wrappers.py
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
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
set_metrics
¶
Set the evaluation metrics for the prediction model.
Source code in icu_benchmarks/models/wrappers.py
inverse_output_transform
¶
Maps regression predictions and targets back to label units.
step_fn
¶
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
ObservationMaskWrapper
¶
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
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
MLWrapper
¶
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
fit
¶
Fit the model to the training data.
Source code in icu_benchmarks/models/wrappers.py
fit_model
¶
Fit the model to the training data (default SKlearn syntax)
log_metrics
¶
Log metrics to the PL logs.
Source code in icu_benchmarks/models/wrappers.py
set_model_args
¶
Set hyperparameters of the model if they are supported by the model.
Source code in icu_benchmarks/models/wrappers.py
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
icu_benchmarks.models.constants
¶
Classes:
| Name | Description |
|---|---|
ImputationInit |
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
¶
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
update
¶
" Standard metric update function
Source code in icu_benchmarks/models/custom_metrics.py
feature_helper
¶
Helper function to get the feature names from the trainer
Source code in icu_benchmarks/models/custom_metrics.py
accuracy
¶
Computes the accuracy over the k top predictions for the specified values of k
Source code in icu_benchmarks/models/custom_metrics.py
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
¶
scorer_wrapper
¶
create_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
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
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
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_resultsaverages 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
¶
Fails early, with the install command, when the optional captum package is missing.
Source code in icu_benchmarks/models/explain/__init__.py
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
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
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 ( |
required | |
log_dir
|
Path
|
The fold directory to save the results in. |
required |
methods
|
tuple[str, ...]
|
Attribution methods: |
METHODS
|
metrics
|
tuple[str, ...]
|
Quality metrics: |
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 |
Source code in icu_benchmarks/models/explain/__init__.py
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 | |
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
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
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 |
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
¶
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
missing_baseline
¶
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
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
output_at_hours
¶
The explained output of each sample at its own hour, shape (samples,). Differentiable, for Captum.
Source code in icu_benchmarks/models/explain/attribution.py
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
remove_variables
¶
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
chunks
¶
Slices of at most size consecutive indices that cover range(n), for batched forward passes.
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
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
random_attribution
¶
Random attributions, the reference that every metric should beat.
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
¶
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
faithfulness_correlation
¶
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
deletion_aopc
¶
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. |