mllm_shap.shap.complementary package

Submodules

mllm_shap.shap.complementary.limited module

Limited Complementary SHAP explainer implementation.

class mllm_shap.shap.complementary.limited.LimitedComplementaryShapExplainer(*args: Any, num_samples: int | None = None, fraction: float = 0.6, **kwargs: Any)

Bases: BaseComplementaryShapExplainer

Limited Complementary SHAP implementation.

allow_mask_duplicates: bool

Whether to allow duplicate masks during generation.

embedding_model: BaseExternalEmbedding | None

The external embedding model to use. If provided, overrides mode.

embedding_reducer: BaseEmbeddingReducer

The embedding reduction strategy to use.

fraction: float | None

Fraction of total possible masks to generate if num_samples is None.

include_minimal_masks: bool = True

Whether to include minimal masks (single-feature and empty masks) in the sampling.

mode: Mode

The SHAP mode, either STATIC or CONTEXTUAL. Used if no embedding_model is provided.

normalizer: BaseNormalizer

The SHAP value normalizer to use.

num_samples: int | None

Number of random masks to generate. If None, uses fraction. -1 stands for minimal number of samples (only single-feature masks and empty mask).

similarity_measure: BaseEmbeddingSimilarity

The embedding similarity measure to use.

total_n_calls: int = 0

Total number of MLLM calls made for last explanation.

mllm_shap.shap.complementary.standard module

Standard Complementary SHAP explainer implementation.

class mllm_shap.shap.complementary.standard.StandardComplementaryShapExplainer(*args: Any, num_samples: int | None = None, fraction: float = 0.6, **kwargs: Any)

Bases: BaseComplementaryShapExplainer

Standard Complementary SHAP Explainer.

allow_mask_duplicates: bool

Whether to allow duplicate masks during generation.

embedding_model: BaseExternalEmbedding | None

The external embedding model to use. If provided, overrides mode.

embedding_reducer: BaseEmbeddingReducer

The embedding reduction strategy to use.

fraction: float | None

Fraction of total possible masks to generate if num_samples is None.

include_minimal_masks: bool = False

Whether to include minimal masks (single-feature and empty masks) in the sampling.

mode: Mode

The SHAP mode, either STATIC or CONTEXTUAL. Used if no embedding_model is provided.

normalizer: BaseNormalizer

The SHAP value normalizer to use.

num_samples: int | None

Number of random masks to generate. If None, uses fraction. -1 stands for minimal number of samples (only single-feature masks and empty mask).

similarity_measure: BaseEmbeddingSimilarity

The embedding similarity measure to use.

total_n_calls: int = 0

Total number of MLLM calls made for last explanation.

Module contents

Complementary SHAP explainers.

All Complementary SHAP explainers are based on approximating SHAP values using Monte Carlo sampling techniques. In oppose to algorithms from mllm_shap.shap.monte_carlo, however, they focus rely on complementary contributions (not marginal contributions).

They differ from standard Monte Carlo methods by including third-part-masks, where k-th pair (S, N S) follows (k = 0…n-1): - k-th token is present in S - |S| ~ ceil(n / 3)

• LimitedComplementaryShapExplainer implements a limited Monte Carlo sampling

  that always includes third-part-masks.

• StandardComplementaryShapExplainer does not include third-part-masks.

class mllm_shap.shap.complementary.LimitedComplementaryShapExplainer(*args: Any, num_samples: int | None = None, fraction: float = 0.6, **kwargs: Any)

Bases: BaseComplementaryShapExplainer

Limited Complementary SHAP implementation.

allow_mask_duplicates: bool

Whether to allow duplicate masks during generation.

embedding_model: BaseExternalEmbedding | None

The external embedding model to use. If provided, overrides mode.

embedding_reducer: BaseEmbeddingReducer

The embedding reduction strategy to use.

fraction: float | None

Fraction of total possible masks to generate if num_samples is None.

include_minimal_masks: bool = True

Whether to include minimal masks (single-feature and empty masks) in the sampling.

mode: Mode

The SHAP mode, either STATIC or CONTEXTUAL. Used if no embedding_model is provided.

normalizer: BaseNormalizer

The SHAP value normalizer to use.

num_samples: int | None

Number of random masks to generate. If None, uses fraction. -1 stands for minimal number of samples (only single-feature masks and empty mask).

similarity_measure: BaseEmbeddingSimilarity

The embedding similarity measure to use.

total_n_calls: int = 0

Total number of MLLM calls made for last explanation.

class mllm_shap.shap.complementary.StandardComplementaryShapExplainer(*args: Any, num_samples: int | None = None, fraction: float = 0.6, **kwargs: Any)

Bases: BaseComplementaryShapExplainer

Standard Complementary SHAP Explainer.

allow_mask_duplicates: bool

Whether to allow duplicate masks during generation.

embedding_model: BaseExternalEmbedding | None

The external embedding model to use. If provided, overrides mode.

embedding_reducer: BaseEmbeddingReducer

The embedding reduction strategy to use.

fraction: float | None

Fraction of total possible masks to generate if num_samples is None.

include_minimal_masks: bool = False

Whether to include minimal masks (single-feature and empty masks) in the sampling.

mode: Mode

The SHAP mode, either STATIC or CONTEXTUAL. Used if no embedding_model is provided.

normalizer: BaseNormalizer

The SHAP value normalizer to use.

num_samples: int | None

Number of random masks to generate. If None, uses fraction. -1 stands for minimal number of samples (only single-feature masks and empty mask).

similarity_measure: BaseEmbeddingSimilarity

The embedding similarity measure to use.

total_n_calls: int = 0

Total number of MLLM calls made for last explanation.