Minimum Spanning Tree Compacntess (MST-C) Implementation

[MMMesgari]

Description

This PR introduces the MST-C (Minimum Spanning Tree Compactness) metric to Quantus as a geometry-based complexity metric for attribution maps.

MST-C measures the structural compactness of an explanation by combining two complementary quantities: attribution spread and attribution cohesion. Salient attribution points are selected from the attribution map, their spatial spread is estimated using the convex hull area, and their structural cohesion is measured using the length of the minimum spanning tree over a symmetric k-nearest-neighbour graph.

This metric provides Quantus with an additional way to analyse explanation structure beyond pixel-wise magnitude or entropy-based measures. It is intended to help users quantify whether salient attribution regions form compact and coherent structures or appear scattered and fragmented.

Implemented changes

• Added the MSTC metric implementation for image attribution maps.
• Implemented percentile-based salient point selection from attribution maps.
• Implemented spread computation using the convex hull area of salient points.
• Implemented cohesion computation using a symmetric k-nearest-neighbour graph and minimum spanning tree length.
• Added optional automatic increase of k to improve graph connectivity.
• Added score scaling through scale_score, using the image diagonal and a factor of 100 for more interpretable score magnitudes.
• Added validation for MST-C-specific parameters: threshold, k, auto_increase_k, and scale_score.
• Added warning handling for invalid MST-C cases, including non-finite attribution maps, insufficient salient points, invalid MST length, and disconnected k-NN graphs.
• Added preprocessing logic to ensure MST-C operates on channel-aggregated attribution maps with shape (batch, height, width).

Minimum acceptance criteria

• The MST-C metric follows the Quantus metric API and can be called with precomputed attribution maps via a_batch.
• The implementation passes formatting and linting checks.
• The metric returns one score per attribution map.
• Invalid or undefined scores are handled consistently using np.nan and appropriate warnings.
• The k-NN graph construction, connectivity check, and MST-based computation behave as expected.
• Documentation and parameter descriptions are clear enough for users to understand the metric behavior.
• The PR is reviewed by a Quantus maintainer.