safeai.rge.rge_curve

safeai.rge.rge_curve(model, data, removal_fractions=None, *, method: Literal['image', 'text', 'tabular'] = 'tabular', preprocess_fn=None, feature_names=None, model_class_order=None, class_order=None, model_type='sklearn', device=None, batch_size=64, class_weights=None, model_name='Model', rga_full=None, occlusion_method: Literal['random', 'gradcam_most'] = 'random', masking_method: Literal['random', 'most_important', 'greedy'] = 'greedy', baseline: Literal['zero', 'mean'] = 'zero', feature_ranking=None, patch_size=32, patch_rankings=None, patch_meta=None, n_steps=None, random_seed=None, mask_value=0.0, prob_full=None, plot=False, fig_size=(10, 6), save_path=None, show=False, verbose=True)[source]

Compute one Rank Graduation Explainability (RGE) curve and AURGE value.

Parameters:

  • model (object) – Trained sklearn estimator with predict_proba or PyTorch module that returns logits.

  • data (object) –

    Input data used for the selected workflow.

    For method=’image’, pass a PyTorch Dataset or compatible dataset returning image tensors.

    For method=’text’ or method=’tabular’, pass a feature matrix.

  • removal_fractions (array-like, optional) – Fractions of removed information. For image and text workflows this is required. For tabular workflow, if None, the curve is built using n_steps or all available features.

  • method ({'image', 'text', 'tabular'}, default='tabular') – RGE workflow used to construct the curve.

  • preprocess_fn (callable, optional) – Required for method=’image’. Maps image tensors to model-ready feature matrices.

  • feature_names (array-like, optional) – Required for method=’tabular’. Names of the feature columns.

  • model_class_order (array-like) – Class order produced by the model probability output.

  • class_order (array-like) – Target class order used to align probability columns.

  • model_type ({'sklearn', 'pytorch'}, default='sklearn') – Type of model being evaluated.

  • device (torch.device or str, optional) – Device used for PyTorch inference.

  • batch_size (int, default=64) – Batch size used when loading images or running PyTorch prediction.

  • class_weights (array-like, optional) – Weights used to aggregate per-class RGE values. If None, uniform class weights are used.

  • model_name (str, default='Model') – Name stored in the result dictionary and used in plot labels.

  • rga_full (float, optional) – If provided and finite, the RGE curve is rescaled by this RGA value.

  • occlusion_method ({'random', 'gradcam_most'}, default='random') – Image occlusion workflow used when method=’image’.

  • masking_method ({'random', 'most_important', 'greedy'}, default='greedy') – Feature masking workflow used when method=’text’ or method=’tabular’. Text supports ‘random’ and ‘most_important’. Tabular supports all three.

  • baseline ({'zero', 'mean'}, default='zero') – Baseline value used when masking text/tabular features.

  • feature_ranking (array-like, optional) – Feature ranking required when masking_method=’most_important’.

  • patch_size (int, default=32) – Patch size used for image occlusion.

  • patch_rankings (optional) – Required when occlusion_method=’gradcam_most’.

  • patch_meta (optional) – Required when occlusion_method=’gradcam_most’.

  • n_steps (int, optional) – Number of feature-removal steps for method=’tabular’. If None, all features are removed one by one.

  • random_seed (int, optional) – Random seed used for random masking or occlusion.

  • mask_value (float, default=0.0) – Constant value used for image patch masking.

  • prob_full (array-like, optional) – Cached full/original probability matrix. If None, it is computed.

  • plot (bool, default=False) – Whether to create a plot for the computed RGE curve.

  • fig_size (tuple, default=(10, 6)) – Figure size used when plotting.

  • save_path (str, optional) – Path where the plot should be saved.

  • show (bool, default=False) – Whether to display the plot with plt.show().

  • verbose (bool, default=True) – Whether to print progress and summary information.

Returns:

Dictionary containing the RGE curve, AURGE, removed fractions, optional rescaled curve, per-class RGE values, and method metadata.

Return type:

dict