`raitap.transparency`¶

class raitap.transparency.explainers.base_explainer.BaseExplainer¶

Bases: AdapterMixin, ABC

Root base class for all explainer adapters.

Owns the shared interface: output_payload_kind and algorithm_registry class variables (algorithm_registry is validated at decoration time by TRANSPARENCY.has_algorithm_registry=True). The capability gate (check_backend_compat) is inherited from AdapterMixin.

Extend via AttributionOnlyExplainer when the framework should manage the full explain pipeline and you only need to implement compute_attributions, or via FullExplainer when you own the entire explain pipeline yourself.

class raitap.transparency.explainers.base_explainer.AttributionOnlyExplainer¶

Bases: BaseExplainer, ABC

Explainer where you implement one step and the framework handles the rest.

Subclasses implement compute_attributions() only; batching, normalisation, result construction, and artifact persistence are provided by this class via explain().

abstractmethod compute_attributions(model, inputs, **kwargs)¶

Compute attributions for the given inputs.

Parameters:

model -- The model shape this explainer needs (nn.Module for gradient methods, a predict callable for model-agnostic methods).
inputs -- Input tensor (shape depends on modality).
**kwargs -- Framework-specific keyword arguments. The framework always passes backend and input_spec (the inferred InputSpec); a subclass may declare either to use it (e.g. to build a per-modality masker) or let **kwargs absorb it. Also carries target / baselines / background_data.

Returns:

Attribution tensor matching the input shape.

explain(model, inputs, *, backend=None, run_dir=None, output_root=None, experiment_name=None, explainer_target=None, explainer_name=None, visualisers=None, raitap_kwargs=None, call_provenance=None, baseline_render_cache=None, **kwargs)¶: Compute attributions (via compute_attributions()), build an ExplanationResult, write artifacts, and return it.

class raitap.transparency.explainers.full_explainer.FullExplainer¶

Bases: BaseExplainer, ABC

Explainer where you own the full explain pipeline end-to-end.

Subclasses implement explain() entirely — data conversion, model invocation, result construction, and artifact persistence. Use this when the target library's API does not map to a simple compute_attributions(model, inputs) → Tensor step.

abstractmethod explain(model, inputs, *, backend=None, run_dir=None, output_root=None, experiment_name=None, explainer_target=None, explainer_name=None, visualisers=None, **kwargs)¶: Implement the full explanation pipeline.

RAITAP Transparency Module

Provides model explanation / attribution capabilities using SHAP and Captum.

Transparency Public Surface¶

Explainer classes expose explainer.explain(model, inputs, **kwargs), which returns an ExplanationResult. Each explanation can then render one or more visualisations via explanation.visualise(**kwargs).

Explainer classes (used as `_target_` values)¶

CaptumExplainer, ShapExplainer

Visualiser classes (used as `_target_` values in visualisers list)¶

CaptumImageVisualiser, CaptumTimeSeriesVisualiser, CaptumTextVisualiser ShapBarVisualiser, ShapBeeswarmVisualiser, ShapWaterfallVisualiser, ShapForceVisualiser, ShapImageVisualiser TabularBarChartVisualiser

Module layout (for contributors):

phase.py — pipeline entry point: TransparencyPhase (what the registry assembles) + the assess_transparency work fn. Start here to follow a run.
explain_detection.py — detection-task per-box K-loop (one result per box).
factory.py — builds explainer + visualiser instances from config.
results.py — ExplanationResult (owns its .visualisations) + VisualisationResult.
report.py — TransparencyPhaseResult + report-section builders.
explainers/ — the XAI adapters (Captum, SHAP).
visualisers/ — the figure renderers.

class raitap.transparency.AttributionOnlyExplainer¶

Bases: BaseExplainer, ABC

Explainer where you implement one step and the framework handles the rest.

Subclasses implement compute_attributions() only; batching, normalisation, result construction, and artifact persistence are provided by this class via explain().

abstractmethod compute_attributions(model, inputs, **kwargs)¶

Compute attributions for the given inputs.

Parameters:

model -- The model shape this explainer needs (nn.Module for gradient methods, a predict callable for model-agnostic methods).
inputs -- Input tensor (shape depends on modality).
**kwargs -- Framework-specific keyword arguments. The framework always passes backend and input_spec (the inferred InputSpec); a subclass may declare either to use it (e.g. to build a per-modality masker) or let **kwargs absorb it. Also carries target / baselines / background_data.

Returns:

Attribution tensor matching the input shape.

explain(model, inputs, *, backend=None, run_dir=None, output_root=None, experiment_name=None, explainer_target=None, explainer_name=None, visualisers=None, raitap_kwargs=None, call_provenance=None, baseline_render_cache=None, **kwargs)¶: Compute attributions (via compute_attributions()), build an ExplanationResult, write artifacts, and return it.

class raitap.transparency.BaseExplainer¶

Bases: AdapterMixin, ABC

Root base class for all explainer adapters.

class raitap.transparency.CaptumExplainer(algorithm, **init_kwargs)¶

Bases: AttributionOnlyExplainer

Single wrapper for ALL Captum attribution methods.

Uses dynamic method loading - no need for class-per-method.

compute_attributions(model, inputs, backend=None, input_spec=None, target=None, baselines=None, **attr_kwargs)¶

Compute Captum attributions via the per-entry invoker (#266).

Default methods use _default_captum_invoker (the uniform method_class(model).attribute(...) path). Methods with a non-uniform lifecycle (NoiseTunnel) carry a custom invoker on their registry entry.

class raitap.transparency.CaptumImageVisualiser(method='blended_heat_map', sign='all', show_colorbar=True, title=None, include_original_image=True)¶

Bases: BaseVisualiser

Visualise image attributions using captum.attr.visualization.visualize_image_attr.

Wraps the Captum native function so the output is a Matplotlib Figure that can be saved or returned by explain().

Compatible with ALL Captum attribution algorithms.

renders_attribution_only_when_original_hidden()¶

Whether include_original_input=False still leaves a meaningful attribution view.

This is instance-level because some visualisers depend on constructor settings such as Captum's method.

validate_explanation(explanation, attributions, inputs)¶: Validate that this visualiser can render an explanation's typed semantics.

visualise(attributions, inputs=None, *, context=None, max_samples=8, **kwargs)¶

Parameters:

attributions -- (B, C, H, W) or (B, H, W) tensor / array.
inputs -- Original images (B, C, H, W) for overlay.
context -- Standard RAITAP metadata (optional).
max_samples -- Maximum number of samples to display (default: 8).
**kwargs -- Forwarded to visualize_image_attr.

Returns:

Matplotlib Figure with one column per sample.

class raitap.transparency.CaptumTextVisualiser¶

Bases: BaseVisualiser

Visualise per-token text attributions as a horizontal bar chart.

This is a lightweight matplotlib-based implementation since Captum's native text visualisation renders HTML (not a Matplotlib Figure).

Compatible with ALL Captum attribution algorithms on text/sequence inputs.

Note: attributions should be a 1-D array of per-token scores for a single input. Pass token_labels via kwargs for readable output.

validate_explanation(explanation, attributions, inputs)¶: Validate that this visualiser can render an explanation's typed semantics.

visualise(attributions, inputs=None, token_labels=None, **kwargs)¶

Parameters:

attributions -- 1-D attribution scores (one per token).
inputs -- Ignored.
token_labels -- List of token strings (optional).
**kwargs -- Ignored (for API consistency).

Returns:

Matplotlib Figure with a horizontal bar chart of token importance.

class raitap.transparency.CaptumTimeSeriesVisualiser(method='overlay_individual', sign='absolute_value')¶

Bases: BaseVisualiser

Visualise time-series attributions via captum.attr.visualization.visualize_timeseries_attr.

Compatible with ALL Captum attribution algorithms.

validate_explanation(explanation, attributions, inputs)¶: Validate that this visualiser can render an explanation's typed semantics.

visualise(attributions, inputs=None, *, context=None, **kwargs)¶

Parameters:

attributions -- (N, C) numpy array / tensor (channels-last). If a batch of shape (B, N, C) is given, the first sample is used.
inputs -- Matching (N, C) time-series data (optional).
context -- Standard RAITAP metadata (not used by this visualiser).
**kwargs -- Forwarded to visualize_timeseries_attr.

Returns:

Matplotlib Figure.

class raitap.transparency.ConfiguredVisualiser(visualiser, call_kwargs=<factory>)¶

Bases: object

Visualiser instance plus per-call kwargs for BaseVisualiser.visualise.

class raitap.transparency.DetectionImageVisualiser(*, method=None, sign=None, show_colorbar=None, title=None)¶

Bases: BaseVisualiser

Render one fig per box: original image + bbox rectangle + heatmap.

Reads the per-box metadata from context.detection_box (populated by the detection explain phase). The visualiser does not know which box k it is rendering until the context is passed in.

visualise(attributions, inputs=None, *, context=None, **kwargs)¶

Create visualization from attributions.

Parameters:

attributions -- Attribution values (numpy array or tensor)
inputs -- Original inputs for overlay (optional)
context -- Standard RAITAP pipeline metadata (optional)
**kwargs -- visualiser-specific arguments

Returns:

Matplotlib figure

class raitap.transparency.ExplainerAdapter(*args, **kwargs)¶

Bases: Protocol

Hydra explainer: explain matches BaseExplainer.

Read output_payload_kind via raitap.transparency.contracts.explainer_output_kind() (not via direct attribute access — the attribute is optional and defaults to ATTRIBUTIONS when absent).

class raitap.transparency.ExplainerAlgorithmSpec(families, baseline_default=None, baseline_cardinality=None, requires=<factory>, stochastic=False, invoker=None, extra_outputs=())¶

Bases: object

Per-algorithm metadata carried by a transparency adapter's algorithm_registry.

The transparency analogue of robustness's AssessorAlgorithmSpec: one entry per algorithm an adapter wraps, holding everything the framework tracks and reports for that algorithm. baseline_default is the implicit BaselineMode used when the user omits the baseline kwarg (None for algorithms with no meaningful default, e.g. Saliency / TreeExplainer). baseline_cardinality declares whether the baseline is a single reference or a sample set, so a mismatched raitap.baseline is flagged (not reshaped); None skips the check.

class raitap.transparency.ExplainerCapability(scope, scope_definition_step, payload_kind, method_families, candidate_output_spaces)¶

Bases: object

Broad pre-compute semantic capability for an explainer configuration.

class raitap.transparency.ExplanationOutputSpace(*values)¶

Bases: StrEnum

Coordinate space represented by attribution values.

class raitap.transparency.ExplanationPayloadKind(*values)¶

Bases: StrEnum

Primary payload category on ExplanationResult.

class raitap.transparency.ExplanationResult(attributions: 'torch.Tensor', inputs: 'torch.Tensor', run_dir: 'Path', experiment_name: 'str | None', adapter_target: 'str', algorithm: 'str', name: 'str | None' = None, kwargs: 'dict[str, Any]'=<factory>, call_kwargs: 'dict[str, Any]'=<factory>, visualiser_targets: 'list[str]' = <factory>, visualisers: 'list[ConfiguredVisualiser]' = <factory>, visualisations: 'list[VisualisationResult]' = <factory>, payload_kind: 'ExplanationPayloadKind' = <ExplanationPayloadKind.ATTRIBUTIONS: 'attributions'>, detection_box: 'DetectionBox | None' = None, original_sample_index: 'int | None' = None, source_library: 'str | None' = None, baseline: 'BaselineRecord | None' = None, structured_payloads: 'list[StructuredPayload]' = <factory>, *, semantics: 'ExplanationSemantics')¶

Bases: Trackable

log(tracker, artifact_path='transparency', use_subdirectory=True, **kwargs)¶: Log the object's artifacts or metadata to the provided tracker.

render_visualisation_for_scope(visualiser_index, *, scope, sample_index=None, **render_kwargs)¶

Render one scoped visualisation without persisting it to disk.

Returns None when the selected visualiser does not produce the requested scope.

render_visualisations_for_scope(*, scope, sample_index=None, **render_kwargs)¶

Render scoped visualisations without persisting them to disk.

The returned VisualisationResult objects are intended for downstream consumers such as reporting, which own file staging and figure cleanup. Their output_path values are placeholders only and must not be treated as real on-disk artifacts or passed to VisualisationResult.log().

class raitap.transparency.ExplanationScope(*values)¶

Bases: StrEnum

Semantic breadth represented by an explanation artifact.

class raitap.transparency.ExplanationSemantics(scope, scope_definition_step, payload_kind, method_families, target, sample_selection, input_spec, output_space, stochastic=False)¶

Bases: object

Typed contract describing the meaning of an explanation artifact.

class raitap.transparency.ExplanationTarget(target=None, label=None)¶

Bases: object

Model output target described by an explanation.

class raitap.transparency.FullExplainer¶

Bases: BaseExplainer, ABC

Explainer where you own the full explain pipeline end-to-end.

abstractmethod explain(model, inputs, *, backend=None, run_dir=None, output_root=None, experiment_name=None, explainer_target=None, explainer_name=None, visualisers=None, **kwargs)¶: Implement the full explanation pipeline.

class raitap.transparency.InputKind(*values)¶

Bases: StrEnum

Known input modalities used by semantic validation.

class raitap.transparency.InputSpec(kind, shape, layout, feature_names=None, metadata=None)¶

Bases: object

Input metadata used for deterministic semantic inference.

class raitap.transparency.MethodFamily(*values)¶

Bases: StrEnum

Explicit algorithm families supported by the typed transparency contract.

class raitap.transparency.OutputSpaceSpec(space, shape, layout, layer_path=None, feature_names=None, requires_interpolation=False)¶

Bases: object

Attribution output-space metadata.

exception raitap.transparency.PayloadVisualiserIncompatibilityError(*, explainer_target, visualiser, output_payload_kind, supported_payload_kinds)¶

Bases: Exception

Raised when a visualiser does not accept the explainer's output payload kind.

class raitap.transparency.SampleSelection(sample_ids: 'list[str] | None', sample_display_names: 'list[str] | None')¶: Bases: object

class raitap.transparency.ScopeDefinitionStep(*values)¶

Bases: StrEnum

Pipeline step that defined an artifact's semantic scope.

class raitap.transparency.ShapBarVisualiser(feature_names=None, max_display=20)¶

Bases: _TabularSummaryContractMixin

Mean absolute SHAP value bar chart via shap.summary_plot(plot_type='bar').

Compatible with all SHAP explainer algorithms.

visualise(attributions, inputs=None, *, context=None, **kwargs)¶

Parameters:

attributions -- (B, F) SHAP values tensor / array.
inputs -- Original feature values (B, F) (used for colouring).
context -- Standard RAITAP metadata (not used by this visualiser).
**kwargs -- Forwarded to shap.summary_plot.

class raitap.transparency.ShapBeeswarmVisualiser(feature_names=None, max_display=20)¶

Bases: _TabularSummaryContractMixin

SHAP beeswarm summary plot via shap.summary_plot().

Compatible with all SHAP explainer algorithms.

visualise(attributions, inputs=None, *, context=None, **kwargs)¶

Create visualization from attributions.

Parameters:

attributions -- Attribution values (numpy array or tensor)
inputs -- Original inputs for overlay (optional)
context -- Standard RAITAP pipeline metadata (optional)
**kwargs -- visualiser-specific arguments

Returns:

Matplotlib figure

class raitap.transparency.ShapExplainer(algorithm, **init_kwargs)¶

Bases: AttributionOnlyExplainer

Single wrapper for ALL SHAP explainer types.

Uses dynamic explainer loading - no need for class-per-explainer.

compute_attributions(model, inputs, backend=None, input_spec=None, background_data=None, target=None, **shap_kwargs)¶

Compute SHAP values via the per-entry invoker (legacy or modern).

The modern path additionally returns the SHAP base value, so the raw runtime result may be a (attributions, base_value) tuple. It is typed torch.Tensor to match the base contract (as Captum's tuple-returning methods do); the framework's split seam consumes the raw output as object and never relies on this annotation. (#101)

Parameters:

model -- PyTorch model
inputs -- Input tensor
input_spec -- Inferred input specification; passed to the invoker.
background_data -- Background dataset (REQUIRED for most explainers) - GradientExplainer: Required - DeepExplainer: Required - KernelExplainer: Required - TreeExplainer: Optional
target -- Target class(es) for attributions (optional) If not specified, returns attributions for all classes
**shap_kwargs -- Additional arguments for .shap_values() method

Returns:

SHAP values as torch.Tensor

class raitap.transparency.ShapForceVisualiser(feature_names=None, expected_value=0.0, sample_index=0)¶

Bases: BaseVisualiser

Per-sample SHAP force plot via shap.plots.force (matplotlib backend).

Compatible with all SHAP explainer algorithms.

visualise(attributions, inputs=None, *, context=None, **kwargs)¶

Create visualization from attributions.

Parameters:

attributions -- Attribution values (numpy array or tensor)
inputs -- Original inputs for overlay (optional)
context -- Standard RAITAP pipeline metadata (optional)
**kwargs -- visualiser-specific arguments

Returns:

Matplotlib figure

class raitap.transparency.ShapImageVisualiser(max_samples=4, title=None, include_original_image=True, show_colorbar=True, cmap=None, overlay_alpha=0.15, outlier_perc=99.9)¶

Bases: BaseVisualiser

Render image-level SHAP attributions with Matplotlib.

This visualiser does not call shap.image_plot directly; instead it renders a RAITAP-managed figure that follows the same rendering recipe as shap.plots.image — a grayscale background at overlay_alpha=0.15, a red_transparent_blue diverging colormap, and a symmetric ±np.nanpercentile(|attribution|, outlier_perc) colormap scale (outlier_perc=99.9 by default). RAITAP layers sample-aware titles, the paired-original panel, and the colorbar on top of that recipe.

Warning

Only compatible with ``GradientExplainer`` and ``DeepExplainer``. These are the only SHAP explainers that compute pixel-level SHAP values suitable for image visualisation. Passing attributions from other explainers will produce meaningless plots.

Positive contributions are shown in red and negative contributions in blue with a transparent mid-range, matching SHAP's native presentation.

validate_explanation(explanation, attributions, inputs)¶: Validate that this visualiser can render an explanation's typed semantics.

visualise(attributions, inputs=None, *, context=None, max_samples=None, title=None, **kwargs)¶

Parameters:

attributions -- (B, C, H, W) SHAP values tensor / array.
inputs -- Original images (B, C, H, W) for background.
context -- Standard RAITAP metadata (optional).
max_samples -- Maximum number of images to display.
title -- Optional attribution panel title. Overrides the algorithm-based default title, even when set to an empty string.
**kwargs -- Optional visual styling overrides.

Returns:

Matplotlib Figure.

class raitap.transparency.ShapWaterfallVisualiser(feature_names=None, expected_value=0.0, sample_index=0, max_display=10)¶

Bases: BaseVisualiser

Per-sample SHAP waterfall chart via shap.plots.waterfall.

Compatible with all SHAP explainer algorithms.

visualise(attributions, inputs=None, *, context=None, **kwargs)¶

Create visualization from attributions.

Parameters:

attributions -- Attribution values (numpy array or tensor)
inputs -- Original inputs for overlay (optional)
context -- Standard RAITAP pipeline metadata (optional)
**kwargs -- visualiser-specific arguments

Returns:

Matplotlib figure

class raitap.transparency.TabularBarChartVisualiser(feature_names=None)¶

Bases: BaseVisualiser

Visualise attributions for tabular data as bar charts.

Works with any attribution method (Captum, SHAP, etc.)

validate_explanation(explanation, attributions, inputs)¶: Validate that this visualiser can render an explanation's typed semantics.

visualise(attributions, inputs=None, *, context=None, title=None, **kwargs)¶

Create feature importance bar chart.

Parameters:

attributions -- (B, num_features) array
inputs -- Not used for tabular visualization
context -- Standard RAITAP metadata (not used by this aggregate visualiser)
title -- Optional chart title override

Returns:

Matplotlib figure

class raitap.transparency.TensorLayout(*values)¶

Bases: StrEnum

Named tensor layouts accepted by built-in visualisers.

class raitap.transparency.VisualSummarySpec(summary_type, aggregation=None, description=None)¶

Bases: object

Metadata for visualisers that summarize a set of local explanations.

class raitap.transparency.VisualisationResult(explanation, figure, visualiser_name, visualiser_target, output_path, scope=ExplanationScope.LOCAL, scope_definition_step=ScopeDefinitionStep.EXPLAINER_OUTPUT, visual_summary=None)¶

Bases: Trackable

PNG is written to output_path; figure is closed after save to limit memory use.

log(tracker, artifact_path='transparency', use_subdirectory=True, **kwargs)¶: Log the object's artifacts or metadata to the provided tracker.

exception raitap.transparency.VisualiserIncompatibilityError(framework, visualiser, algorithm, compatible_algorithms)¶

Bases: Exception

Raised when a visualiser is not compatible with the chosen explainer algorithm.

raitap.transparency.explainer_capability(explainer, *, task_kind=None)¶: Return broad pre-compute semantic capabilities for an explainer.

raitap.transparency.infer_input_spec(inputs=None, *, input_metadata=None, kind=None, layout=None, feature_names=None)¶: Build an InputSpec from explicit metadata and tensor shape.

raitap.transparency.infer_output_space(*, input_spec, attributions=None, explainer=None, algorithm=None, method_families=None, layer_path=None, feature_names=None, task_kind=None)¶: Infer deterministic output-space metadata from input and method semantics.

raitap.transparency.method_families_for_explainer(explainer)¶

Return the explicit method-family mapping for a configured explainer.

Resolution order:

type(explainer).algorithm_registry — required class-body ClassVar on every transparency adapter (validated at decoration time by @adapters.transparency's required kwarg).
Framework label on the explainer (framework="shap" / "captum") → matching adapter class's registry.
Cross-framework algorithm-name lookup (used by minimal test stubs and config-only entry points where only the algorithm string is known).

raitap.transparency.contracts.explainer_output_kind(explainer)¶

raitap.transparency¶

Transparency Public Surface¶

Explainer classes (used as _target_ values)¶

Visualiser classes (used as _target_ values in visualisers list)¶

`raitap.transparency`¶

Explainer classes (used as `_target_` values)¶

Visualiser classes (used as `_target_` values in visualisers list)¶