EXAM API Reference

Compute probabilities and assign treatment

exam.compute_probs.assign(probs: Sequence, treatment_labels: Sequence = None, subject_ids: Sequence = None, save_path: str = None, seed: int = None)[source]

Assign treatments given set of probabilities

Parameters

  • probs (array-like) – Array of treatment assignment probabilites for each suvhect

  • treatment_labels (array-like, default: None) – Treatment labels for recording assignment. Default is 0,1,…

  • subject_ids (array-like, default: None) – Ids to set as the index of the output dataframe. Default is the default pandas index.

  • save_path (str, default: None) – String path to save assignments file to CSV.

  • seed (int, default: None) – Numpy seed

Returns

Dataframe of assigned treatments

Return type

pd.DataFrame

exam.compute_probs.compute_probs(wtp: Sequence, predicted_effects: Sequence, capacity: Sequence = None, probability_bound: float = 0, error_threshold: float = 0.01, iterations_threshold: int = 20, budget: int = 100, subject_budgets: Sequence = None, round: int = None, save_path: str = None, treatment_labels: Sequence = None, subject_ids: Sequence = None, max_search: int = 100)[source]

Given the market parameters, compute the equilibrium and return treatment assignment probabilities.

Parameters

  • wtp (array-like) – 2-D array of participant willingness-to-pay for each treatment

  • predicted_effects (array-like) – 2-D array of participant estimated treatment effects

  • capacity (array-like, default: None) – Capacity constraints for treatments.

  • probability_bound (float, default: 0) – The minimum bound for any treatment assignment probability. All computed probabilities will be constrained within [\(\epsilon\), \(1 - \epsilon\)] where \(\epsilon\) is the probability bound.

  • error_threshold (float, default: 0.01) – The minimum market clearing error to satisfy the market clearing algorithm.

  • max_iterations (int, default: 10) – The maximum number of iterations to run the market clearing algorithm before resetting the search.

  • budget (int, default: 100) – The budget to assign to each participant.

  • subject_budgets (list-like, default: None) – An array of budgets if distributing budgets unequally among subjects.

  • round (int, default: None) – Decimal places to round output probabilities, to ensure coarseness. Must be > 0.

  • save_path (str, default: None) – String path to save output probabilities to CSV.

  • treatment_labels (array-like, default: None) – Treatment labels for recording assignment. Default is 0,1,…

  • subject_ids (array-like, default: None) – Ids to set as the index of the output dataframe. Default is the default pandas index.

Returns

Returns dict containing calculated treament probabilities for each participant (‘p_star’), the optimized treatment-effect coefficient \(\alpha*\) (‘alpha_star’), the vector of optimized treatment coefficients (\(\beta_t*\)) (‘beta_star’), and the minimized market clearing error \(\text{error}_{min}\) (‘error’).

Return type

dict[str, any]

Notes

The market equilibrium is computed iteratively by finding optimal alpha and beta_t such that prices \(\pi_{ti} = \alpha e_{ti} + \beta_t\) clear the market within a certain threshold. The iteration works by updating \(\beta_t = \beta_t(1 + \lambda_t\min(1, \text{E}_t/\text{C}_t))\) where \(\text{E}_t\) is excess demand for treatment t and \(\text{C}_t\) is the experimental capacity for treatment t. \(\lambda_t\) is a scaling factor computed as the absolute value of the mean of the ratio between the \(\alpha\) and \(\beta\) contributions to the price equation. In mathematical terms, \(\lambda_t = |\frac{1}{N}\sum_{i = 1}^{N} \alpha e_{ti}/\beta_t |\).

Estimate treatment effects

exam.estimate_effects.estimate_effects(Y: Sequence, D: Sequence, probs: Sequence, X: Sequence = None, control: str = None, method: str = 'matched', save_path: str = None, return_model: bool = True, verbose=True)[source]

Estimate treatment effects using either single regression with propensity controls or propensity-matched subpopulation regressions.

Parameters

  • Y (array-like) – Array of outcome data

  • D (array-like) – Array of treatment assignment data

  • probs (array-like) – 2D array of treatment probabilities, where the first column is the control probability.

  • X (array-like, default: None) – Control variables to include in regression

  • control (str, default: None) – Name of control treatment as given in D. Defaults to first column from pandas get_dummies.

  • method (str, default: “matched”) – Estimation method. Supports “matched” for subpopulation regressions or “single” for single regression with propensity controls.

  • save_path (str, default: None) – Path to save output

  • return_model (bool, default: True) – Whether to return fitted models as part of output

  • verbose (bool, default: True) – Whether to print estimation summary

Returns

Dictionary containing estimated coefficients, p-values, and other relevant estimation parameters. If return_model is set to True, then the estimated model is returned as well.

Return type

dict[str, any]