Getting started¶

This page shows the minimal sequence of calls needed to obtain a personalization-effect estimate on the bundled kpe_toy dataset.

Install¶

Installed from GitHub — not yet on PyPI (planned):

pip install "git+https://github.com/StanfordAI4HI/kpe-py.git"

Learners and the packages they use¶

kpe() (and train_eval() / papd()) plug in three learner "slots" — a reward model, a contextual policy, and a best-arm rule — plus a propensity model when is_rct=False. Each slot takes a string naming a built-in backend. Unlike the R package, every backend is a required dependency, so installing the package pulls them all in automatically (declared in pyproject.toml): numpy, scipy, scikit-learn, joblib, econml, and pandas (the last is used by the dataset vignettes).

slot	string value	backing implementation
`reward_model`	`"random_forest"`	scikit-learn `RandomForestRegressor`
	`"linear"`	scikit-learn `LinearRegression`
	`"ridge"`, `"lasso"`	scikit-learn `Ridge` / `Lasso`
`contextual_policy`	`"policy_tree"` (alias `"dr_econml_2"`)	econml `DRPolicyTree` (its nuisance models are scikit-learn)
	`"policy_forest"` (alias `"dr_econml"`)	econml `DRPolicyForest`
	`"linear"`	per-arm scikit-learn `LinearRegression`
`best_arm`	`"ips"`/`"best_arm_erm"`, `"simple"`/`"simple_best_arm"`	built into `kpe` (numpy)
`propensity_model` (only if `is_rct=False`)	`"logistic"`	scikit-learn `LogisticRegression`
	`"random_forest"`	scikit-learn `RandomForestClassifier`

Which "random_forest"? In this Python package, reward_model = "random_forest" is scikit-learn's RandomForestRegressor. That is a different random-forest library from the sibling R package kpe-r, whose "random_forest" is the ranger package. Likewise Python's "policy_tree" (econml DRPolicyTree) differs from R's "policy_tree" (the policytree package). The two ports agree on linear/lasso-style learners but are not bitwise identical on the forest/tree learners.

Example¶

from kpe import kpe
from kpe.data import load_kpe_toy

d = load_kpe_toy()                         # 500-row simulated dataset
res = kpe(
    d["X"], d["A"], d["Y"], d["propensity"],
    n_shuffles=100,
    n_folds=6,
    random_state=0,
)
print(res.summary())

Output fields¶

The returned KPEResult contains the following fields:

field	type	meaning
`psi`	`float`	Point estimate of the personalization effect on the outcome scale.
`std_error`	`float`	Standard error of `psi`.
`confidence_interval`	`tuple`	95% Wald confidence interval `(lo, hi)`.
`p_value`	`float`	One-sided upper-tail t-test p-value.
`psi_per_shuffle`	`np.ndarray`	Per-shuffle `psi_hat` values.
`sigma_per_shuffle`	`np.ndarray`	Per-shuffle `sigma_hat` values.
`policy_stability`	`float`	Fraction of samples for which every shuffle predicted the same action under the contextual policy.
`overall_stability`	`float`	Same fraction under the best-arm policy.
`predicted_policy_actions`	`np.ndarray`	Length-`n` contextual-policy actions from the final shuffle.
`predicted_overall_actions`	`np.ndarray`	Length-`n` best-arm actions from the final shuffle.
`method`, `n_samples`, `n_shuffles`, `n_folds`	—	Run metadata.

Input specification¶

argument	shape / type	description
`X`	`(n, d)` array	Baseline covariates.
`A`	length-`n` integer array	Observed action in `{0, ..., K-1}`.
`Y`	length-`n` numeric array	Observed outcome.
`propensity`	scalar, length-`n`, or `(n, K)`	`p(A \\| X)` for the observed action; scalar and vector are broadcast.
`policy_features`	iterable of int, optional	Column subset of `X` passed to the contextual-policy learner.