Skip to content

featurebyte.Propensity

class Propensity(
*,
granularity: PropensityGranularity,
knowledge: PropensityKnowledge,
p_global: Union[float, Dict[Any, float], NoneType]=None
)

Description

The Propensity class specifies how treatment assignment probabilities :math:p(T \mid \cdot) are defined and obtained for a given experiment or policy. It is used to configure estimators that rely on inverse probability weighting or doubly robust corrections.

Parameters

  • granularity: PropensityGranularity
    Level at which the propensity score is assumed to be constant.

    Valid values:

    - "global":
    A single probability shared by all units
    (for example, a 50/50 A/B test).
    - "block":
    Probability is constant within blocks / strata, and may differ across them.
    - "cluster":
    Probability is constant within clusters (stores, schools, regions).
    - "unit":
    Probability varies at the individual level :math:p(T \mid X_i).
    - "deterministic":
    Assignment is essentially determined by covariates
    (threshold rules, hard tiers).

  • knowledge: PropensityKnowledge
    How the propensity is obtained (known from design or estimated from data).

    Valid values:

    - "design-known":
    Exact probabilities are available from the experimental design
    or policy specification.
    - "estimated":
    Probabilities are estimated from data using a model :math:p(T \mid X).

  • p_global: Union[float, Dict[Any, float], NoneType]
    Global assignment probabilities. This field is only meaningful when
    granularity == "global".

    Valid values:

    - float between 0 and 1 for a binary treatment (probability of the active arm).
    - Dict[Any, float] mapping each treatment value to its probability for
    multi-arm treatments. The probabilities are expected to sum to 1.

Examples

Example 1: Known Global Propensity

propensity = fb.Propensity(
    granularity="global",
    knowledge="design-known",
    p_global=0.5,  # 50/50 experiment
)

Example 2: Estimated Unit-Level Propensity

propensity = fb.Propensity(
    granularity="unit",
    knowledge="estimated",  # Requires model-based p(T|X)
)

See Also