safeai.rge.compare_rge

safeai.rge.compare_rge(models, class_order, *, method: Literal['image', 'text', 'tabular'] = 'tabular', removal_fractions=None, images_dataset=None, occlusion_method='random', patch_size=32, batch_size=64, class_weights=None, rga_dict=None, device=None, fig_size=(12, 6), verbose=True, random_seed=None, patch_rankings=None, patch_meta=None, save_path=None, show=False, mask_value=0.0, use_shared_feature_cache=True, masking_method='greedy', baseline='zero', n_steps=None, feature_rankings=None)[source]

Compare several models using Rank Graduation Explainability (RGE) curves.

This is the main user-facing comparison function for RGE. It provides one unified interface for all supported RGE workflows:

Image occlusion, using method=’image’
Text or generic feature removal, using method=’text’
Tabular feature removal, using method=’tabular’

The function returns one result dictionary per model and can optionally plot a comparison of the resulting RGE curves.

Parameters:

models (dict) –
Dictionary containing model configurations.

For method=’image’, each entry must have the form:
```
model_name -> (
    model,
    preprocess_fn,
    model_class_order,
    model_type
)
```
where:
- model is a trained sklearn estimator or PyTorch module.
- preprocess_fn maps image tensors to model-ready feature matrices.
- model_class_order is the class order of the model probability output.
- model_type is either ‘sklearn’ or ‘pytorch’.
For method=’text’, each entry must have the form:
```
model_name -> (
    model,
    x,
    prob_full,
    model_class_order,
    model_type,
    device
)
```
where:
- x is the feature matrix to mask.
- prob_full is the original probability matrix, or None.
- device is the torch device for PyTorch models, or None for sklearn.
For method=’tabular’, each entry must have the form:
```
model_name -> (
    model,
    x,
    feature_names,
    prob_full,
    model_class_order,
    model_type,
    device
)
```
where feature_names contains the names of the columns in x.
class_order (array-like) – Shared target class order used to align probability columns across all models.
method ({'image', 'text', 'tabular'}, default='tabular') – RGE workflow used for all models in the comparison.
removal_fractions (array-like, optional) –
Fractions of removed information.

Required for method=’image’ and method=’text’.

For method=’tabular’, this argument is not used. The tabular curve is controlled by n_steps.
images_dataset (torch.utils.data.Dataset, optional) – Image dataset required when method=’image’. The dataset should return image tensors, or tuples/lists where the first element is the image tensor.
occlusion_method ({'random', 'gradcam_most'} or dict, default='random') –
Image occlusion method used when method=’image’.

If a string is provided, the same occlusion method is used for all models.

If a dictionary is provided, it should map model names to occlusion methods.
patch_size (int, default=32) – Patch size used for image occlusion.
batch_size (int, default=64) – Batch size used when loading images and when running PyTorch prediction.
class_weights (array-like, optional) – Weights used to aggregate per-class RGE values. If None, uniform class weights are used.
rga_dict (dict, optional) – Mapping from model name to full RGA score. If provided, each RGE curve is rescaled by the corresponding RGA value.
device (torch.device or str, optional) – Device used for PyTorch inference.
fig_size (tuple, default=(12, 6)) – Figure size used for the comparison plot.
verbose (bool, default=True) – Whether to print progress and summary information.
random_seed (int, optional) – Random seed used for random image occlusion or random feature masking.
patch_rankings (list or array-like, optional) – Patch rankings used when occlusion_method=’gradcam_most’.
patch_meta (dict, optional) – Patch metadata used when occlusion_method=’gradcam_most’.
save_path (str, optional) – Path where the comparison plot should be saved. If None and show=False, no plot is saved.
show (bool, default=False) – Whether to display the comparison plot with plt.show().
mask_value (float, default=0.0) – Constant value used for image patch masking.
use_shared_feature_cache (bool, default=True) – Whether to cache image features shared across models when method=’image’. This can speed up comparison when all models use the same preprocessing function and occlusion method.
masking_method ({'random', 'most_important', 'greedy'}, default='greedy') –
Feature masking method used for method=’text’ and method=’tabular’.

For method=’text’, only ‘random’ and ‘most_important’ are supported.

For method=’tabular’, ‘random’, ‘most_important’, and ‘greedy’ are supported.
baseline ({'zero', 'mean'}, default='zero') – Baseline value used when masking text or tabular features.
n_steps (int, optional) – Number of feature-removal steps for method=’tabular’. If None, all features are removed one by one.
feature_rankings (array-like or dict, optional) –
Feature rankings used when masking_method=’most_important’.

If an array is provided, the same ranking is used for all models.

If a dictionary is provided, it should map model names to feature-ranking arrays.

Returns:

Mapping from model name to RGE result dictionary.

Each result contains:

’rge_scores’np.ndarray
Raw RGE scores at each removal level.
’rge_rescaled’np.ndarray
RGE scores after optional rescaling by rga_dict.
’aurge’float
Area under the RGE curve.
’per_class_rge’np.ndarray or None
Per-class RGE values at each removal level.
’class_order’np.ndarray
Class order used for probability alignment.
’method’str
RGE workflow used in the comparison.

Depending on method, each result may also include:

’removal_fractions’
’x_axis’
’occlusion_method’
’masking_method’
’baseline’
’removed_features’

Return type:

dict