Estimand aggregators and estimation

Exact coalition enumeration estimator.

class nlp_shap.estimation.exact.ExactEstimator

Bases: object

Enumerate all coalitions and delegate attribution to an estimand plugin.

property name: str

Return the registered estimator identifier.

static num_coalitions(num_players: int) → int

Return the number of coalitions evaluated by exact enumeration.

static iter_mask_ints(num_players: int) → Iterator[int]

Lazily yield coalition bitmasks except the all-present coalition.

static mask_int_to_present(mask_int: int, num_players: int) → tuple[bool, ...]

Decode a coalition bitmask into presence flags.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

sample_masks(player_set: PlayerSet, budget_fraction: float, include_minimal_masks: bool, seed: int) → Iterator[CoalitionMask]

Yield every coalition mask except the grand coalition.

static iter_masks(player_set: PlayerSet) → Iterator[CoalitionMask]

Lazily yield coalition masks except the all-present coalition.

estimate_attributions(masks: Sequence[CoalitionMask], payoffs: Sequence[float], aggregator: EstimandAggregator) → list[float]

Aggregate coalition payoffs with the selected estimand plugin.

Monte Carlo coalition sampling estimator.

class nlp_shap.estimation.monte_carlo.MonteCarloEstimator

Bases: object

Sample random coalitions and delegate attribution to an estimand plugin.

property name: str

Return the registered estimator identifier.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

sample_masks(player_set: PlayerSet, budget_fraction: float, include_minimal_masks: bool, seed: int) → Iterator[CoalitionMask]

Yield random coalition masks up to the configured budget.

estimate_attributions(masks: Sequence[CoalitionMask], payoffs: Sequence[float], aggregator: EstimandAggregator) → list[float]

Aggregate sampled coalition payoffs with the selected estimand plugin.

Complementary pair sampling estimator.

class nlp_shap.estimation.complementary.ComplementaryEstimator

Bases: object

Sample complementary coalition pairs and aggregate CC attributions.

property name: str

Return the registered estimator identifier.

property m_counts: ndarray | None

Return the latest complementary M-matrix counts from sampling.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

reset_sampling_state(num_players: int) → None

Reset complementary M-matrix counts before a new sampling run.

sample_masks(player_set: PlayerSet, budget_fraction: float, include_minimal_masks: bool, seed: int) → Iterator[CoalitionMask]

Yield complementary coalition pairs up to the configured budget.

estimate_attributions(masks: Sequence[CoalitionMask], payoffs: Sequence[float]) → list[float]

Aggregate complementary pair payoffs into CC Shapley attributions.

Neyman complementary allocation estimator.

class nlp_shap.estimation.neyman.NeymanEstimator(initial_fraction: float | None = None, initial_num_samples: int | None = None, use_standard_method: bool = False)

Bases: ComplementaryEstimator

Two-phase complementary estimator with Neyman coalition-size allocation.

property name: str

Return the registered estimator identifier.

bind_snapshot(snapshot: ConversationSnapshot) → None

Attach the conversation snapshot under explanation.

sample_masks(player_set: PlayerSet, budget_fraction: float, include_minimal_masks: bool, seed: int) → Iterator[CoalitionMask]

Yield phase-one Neyman masks until the initial M-matrix grid is filled.

begin_allocation(masks: Sequence[CoalitionMask], payoffs: Sequence[float]) → None

Estimate Neyman allocation after phase-one payoffs are available.

sample_allocation_masks() → Iterator[CoalitionMask]

Yield phase-two masks according to the estimated Neyman allocation.

estimate_attributions(masks: Sequence[CoalitionMask], payoffs: Sequence[float]) → list[float]

Aggregate Neyman CC payoffs into Shapley-style attributions.

Shapley estimand aggregation.

class nlp_shap.estimation.estimands.shapley.ShapleyAggregator

Bases: object

Aggregate coalition samples with Shapley coalition weights.

property estimand: Estimand

Return the Shapley estimand label.

coalition_weight(coalition_size: int, num_players: int) → float

Return Shapley coalition weight k!(n-k-1)!/n!.

aggregate(masks: Sequence[Sequence[bool]], payoffs: Sequence[float]) → list[float]

Aggregate coalition samples into Shapley values.

Banzhaf estimand aggregation.

class nlp_shap.estimation.estimands.banzhaf.BanzhafAggregator

Bases: object

Aggregate coalition samples with uniform Banzhaf coalition weights.

property estimand: Estimand

Return the Banzhaf estimand label.

coalition_weight(coalition_size: int, num_players: int) → float

Return uniform Banzhaf coalition weight 1/2^(n-1).

aggregate(masks: Sequence[Sequence[bool]], payoffs: Sequence[float]) → list[float]

Aggregate coalition samples into Banzhaf indices.

Post-aggregation attribution normalizers.

class nlp_shap.estimation.normalizers.IdentityNormalizer

Bases: object

Return attributions unchanged.

property name: str

Return the registered normalizer identifier.

normalize(values: Sequence[float]) → list[float]

Return a copy of values.

class nlp_shap.estimation.normalizers.AbsSumNormalizer

Bases: object

Scale attributions by the sum of absolute values.

property name: str

Return the registered normalizer identifier.

normalize(values: Sequence[float]) → list[float]

Return values divided by the sum of absolute entries.

class nlp_shap.estimation.normalizers.PowerShiftNormalizer(power: float = 1.0)

Bases: object

Shift to non-negative values, apply a power, then scale to sum one.

property name: str

Return the registered normalizer identifier.

normalize(values: Sequence[float]) → list[float]

Return power-shift normalized attributions.

class nlp_shap.estimation.normalizers.MinMaxNormalizer

Bases: object

Min-max scale to [0, 1] then normalize to sum one.

property name: str

Return the registered normalizer identifier.

normalize(values: Sequence[float]) → list[float]

Return min-max scaled attributions that sum to one.