mllm_shap.shap.hierarchical package#

Submodules#

mllm_shap.shap.hierarchical.enums module#

Configuration for possible modes.

class mllm_shap.shap.hierarchical.enums.Mode(*values)[source]#

Bases: int, Enum

Defines supported grouping modes.

Warning

Depending on mode, first level groups might be large - only TEXT mode guarantees small first level groups, as only then it is divided by size corresponding to log(number of tokens, k) formula. Other modes do not divide first level groups at all, therefore first level call will have cost of up to 2^(number of groups), depending on shap explainer algorithm used.m

MULTI_MODAL = 1#: Splits first level groups according to size and modalities. Results in moderate first level group sizes, but might mix different users’ inputs together. Cheapest mode for multimodal inputs.

MULTI_MODAL_MULTI_USER = 2#: Splits first level groups according to size, modalities, and users. Results in larger first level groups, but better preserves logical structure.

TEXT = 0#: Splits first level groups just by size, requires single modality. As most models always include system prompts, this restricts usage to text-only mode.

as_integer_ratio()#

Return a pair of integers, whose ratio is equal to the original int.

The ratio is in lowest terms and has a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

bit_count()#

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

bit_length()#

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

conjugate()#: Returns self, the complex conjugate of any int.

denominator#: the denominator of a rational number in lowest terms

classmethod from_bytes(bytes, byteorder='big', *, signed=False)#

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.
signed: Indicates whether two’s complement is used to represent the integer.

imag#: the imaginary part of a complex number

is_integer()#: Returns True. Exists for duck type compatibility with float.is_integer.

numerator#: the numerator of a rational number in lowest terms

real#: the real part of a complex number

to_bytes(length=1, byteorder='big', *, signed=False)#

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. Default is length 1.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

mllm_shap.shap.hierarchical.explainer module#

Hierarchical SHAP explainer module.

class mllm_shap.shap.hierarchical.explainer.HierarchicalExplainer(shap_explainer: BaseShapExplainer | None = None, first_layer_explainer: BaseShapExplainer | None = None, mode: Mode = Mode.TEXT, k: int = 10, use_importance_sampling: bool = False, importance_sampling_min_fraction: float = 0.1, **kwargs: Any)[source]#

Bases: BaseExplainer

SHAP explainer implementing hierarchical approach for speed-up.

Groups are divided into subgroups recursively until the final group size. Groups cannot share different modalities (e.g., text and audio tokens). Uses an underlying SHAP explainer for group explanations.

Should be used with SHAP explainers that normalize using MinMaxNormalizer.

It has no history nor non-normalized shap values available. Refer to Mode for details on how groups are formed at the first level.

computation_graph: GraphNode | None#: Computation graph for the last explanation.

first_layer_explainer: BaseShapExplainer | None#: The SHAP explainer instance for the first layer. If provided, first layer explanation will be done using this explainer - it will be fitted with all explainable tokens. Calculated SV will be summed per group and used as first layer SHAP values.

importance_sampling_min_fraction: float#: Minimum fraction for importance sampling.

k: int#: Maximum final group size at each level.

mode: Mode#: The mode of the hierarchical explainer.

model: BaseMllmModel#: The model connector instance.

n_calls: int#: Number of internal SHAP explainer calls made for last explanation.

shap_explainer: BaseShapExplainer#: The SHAP explainer instance.

total_n_calls: int = 0#: Total number of MLLM calls made for last explanation.

use_importance_sampling: bool#: Whether to use importance for setting sampling budget (for each group).

Module contents#

Module for hierarchical SHAP explainer.

HierarchicalExplainer - Hierarchical SHAP explainer class. It
builds a hierarchy of feature groups and computes SHAP values for each group level by level. Supports text-only mode with high efficiency and multimodal mode with moderate efficiency (that is, fixed first level size dependent on input structure).

class mllm_shap.shap.hierarchical.HierarchicalExplainer(shap_explainer: BaseShapExplainer | None = None, first_layer_explainer: BaseShapExplainer | None = None, mode: Mode = Mode.TEXT, k: int = 10, use_importance_sampling: bool = False, importance_sampling_min_fraction: float = 0.1, **kwargs: Any)[source]#