# Balancing Walk Design
[](code_of_conduct.md)
[](https://github.com/ddimmery/balancer-package/actions/workflows/ci.yml)
[](https://zenodo.org/badge/latestdoi/493411416)
This package provides a reference implementation of the [Balancing Walk Design](https://arxiv.org/abs/2203.02025). It relies on minimal dependencies and is intended to be an easy way to plug in advanced experimental designs into existing systems with little overhead.
More details on the design of the method on the [About page](https://ddimmery.github.io/balancer-package/about/) and in the [paper](https://arxiv.org/abs/2203.02025). An [example of usage is below](#usage).
## Installation
(packages not yet available)
With `pip`:
```
pip install bwd
```
## Usage
A simple example of how to use [BWD](https://ddimmery.github.io/balancer-package/reference/balancer/bwd/) to balance a stream of covariate data follows:
```python
from bwd import BWD
from numpy.random import default_rng
import numpy as np
rng = default_rng(2022)
n = 10000
d = 5
ate = 1
beta = rng.normal(size = d)
X = rng.normal(size = (n, d))
balancer = BWD(N = n, D = d)
A_bwd = []
A_rand = []
imbalance_bwd = np.array([[0] * d])
imbalance_rand = np.array([[0] * d])
increment_imbalance = lambda imba, a, x: np.concatenate([imba, imba[-1:, :] + (2 * a - 1) * x])
for x in X:
# Assign with BWD
a_bwd = balancer.assign_next(x)
imbalance_bwd = increment_imbalance(imbalance_bwd, a_bwd, x)
A_bwd.append(a_bwd)
# Assign with Bernoulli randomization
a_rand = rng.binomial(n = 1, p = 0.5, size = 1).item()
imbalance_rand = increment_imbalance(imbalance_rand, a_rand, x)
A_rand.append(a_rand)
# Outcomes are only realized at the conclusion of the experiment
eps = rng.normal(size=n)
Y_bwd = X @ beta + A_bwd * ate + eps
Y_rand = X @ beta + A_rand + ate + eps
```
We can see how imbalance progresses as a function of time:
```python
import seaborn as sns
import pandas as pd
norm_bwd = np.linalg.norm(imbalance_bwd, axis = 1).tolist()
norm_rand = np.linalg.norm(imbalance_rand, axis = 1).tolist()
sns.relplot(
x=list(range(n + 1)) * 2, y=norm_bwd + norm_rand,
hue = ["BWD"] * (n + 1) + ["Random"] * (n + 1),
kind="line", height=5, aspect=2,
).set_axis_labels("Iteration", "Imbalance");
```
It's clear from the above chart that using BWD keeps imbalance substantially more under control than standard methods of randomization.
## Citation
#### APA
> Arbour, D., Dimmery, D., Mai, T. & Rao, A.. (2022). Online Balanced Experimental Design. *Proceedings of the 39th International Conference on Machine Learning*, in *Proceedings of Machine Learning Research* 162:844-864 Available from https://proceedings.mlr.press/v162/arbour22a.html.
#### BibTeX
```
@InProceedings{arbour2022online,
title = {Online Balanced Experimental Design},
author = {Arbour, David and Dimmery, Drew and Mai, Tung and Rao, Anup},
booktitle = {Proceedings of the 39th International Conference on Machine Learning},
pages = {844--864},
year = {2022},
editor = {Chaudhuri, Kamalika and Jegelka, Stefanie and Song, Le and Szepesvari, Csaba and Niu, Gang and Sabato, Sivan},
volume = {162},
series = {Proceedings of Machine Learning Research},
month = {17--23 Jul},
publisher = {PMLR},
pdf = {https://proceedings.mlr.press/v162/arbour22a/arbour22a.pdf},
url = {https://proceedings.mlr.press/v162/arbour22a.html},
}
```
Raw data
{
"_id": null,
"home_page": "https://ddimmery.github.io/balancer-package/",
"name": "bwd",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "causal inference,experimentation,ab testing",
"author": "Drew Dimmery",
"author_email": "drew.dimmery@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7f/a5/cb2cc33e49242150336db13cb5049e7ce566d60aa936facd4369de126514/bwd-0.1.4.tar.gz",
"platform": null,
"description": "# Balancing Walk Design\n\n[](code_of_conduct.md)\n[](https://github.com/ddimmery/balancer-package/actions/workflows/ci.yml)\n[](https://zenodo.org/badge/latestdoi/493411416)\n\n\nThis package provides a reference implementation of the [Balancing Walk Design](https://arxiv.org/abs/2203.02025). It relies on minimal dependencies and is intended to be an easy way to plug in advanced experimental designs into existing systems with little overhead.\n\nMore details on the design of the method on the [About page](https://ddimmery.github.io/balancer-package/about/) and in the [paper](https://arxiv.org/abs/2203.02025). An [example of usage is below](#usage).\n\n## Installation\n\n(packages not yet available)\n\nWith `pip`:\n\n```\npip install bwd\n```\n\n\n## Usage\n\nA simple example of how to use [BWD](https://ddimmery.github.io/balancer-package/reference/balancer/bwd/) to balance a stream of covariate data follows:\n\n\n```python\nfrom bwd import BWD\nfrom numpy.random import default_rng\nimport numpy as np\nrng = default_rng(2022)\n\nn = 10000\nd = 5\nate = 1\nbeta = rng.normal(size = d)\n\nX = rng.normal(size = (n, d))\n\nbalancer = BWD(N = n, D = d)\nA_bwd = []\nA_rand = []\nimbalance_bwd = np.array([[0] * d])\nimbalance_rand = np.array([[0] * d])\n\nincrement_imbalance = lambda imba, a, x: np.concatenate([imba, imba[-1:, :] + (2 * a - 1) * x])\n\nfor x in X:\n # Assign with BWD\n a_bwd = balancer.assign_next(x)\n imbalance_bwd = increment_imbalance(imbalance_bwd, a_bwd, x)\n A_bwd.append(a_bwd)\n # Assign with Bernoulli randomization\n a_rand = rng.binomial(n = 1, p = 0.5, size = 1).item()\n imbalance_rand = increment_imbalance(imbalance_rand, a_rand, x)\n A_rand.append(a_rand)\n\n# Outcomes are only realized at the conclusion of the experiment\neps = rng.normal(size=n)\nY_bwd = X @ beta + A_bwd * ate + eps\nY_rand = X @ beta + A_rand + ate + eps\n```\n\nWe can see how imbalance progresses as a function of time:\n\n\n```python\nimport seaborn as sns\nimport pandas as pd\n\nnorm_bwd = np.linalg.norm(imbalance_bwd, axis = 1).tolist()\nnorm_rand = np.linalg.norm(imbalance_rand, axis = 1).tolist()\n\nsns.relplot(\n x=list(range(n + 1)) * 2, y=norm_bwd + norm_rand,\n hue = [\"BWD\"] * (n + 1) + [\"Random\"] * (n + 1),\n kind=\"line\", height=5, aspect=2,\n).set_axis_labels(\"Iteration\", \"Imbalance\");\n```\n\n\n \n\n \n\n\nIt's clear from the above chart that using BWD keeps imbalance substantially more under control than standard methods of randomization.\n\n## Citation\n#### APA\n> Arbour, D., Dimmery, D., Mai, T. & Rao, A.. (2022). Online Balanced Experimental Design. *Proceedings of the 39th International Conference on Machine Learning*, in *Proceedings of Machine Learning Research* 162:844-864 Available from https://proceedings.mlr.press/v162/arbour22a.html.\n\n#### BibTeX\n```\n\n@InProceedings{arbour2022online,\n title = \t {Online Balanced Experimental Design},\n author = {Arbour, David and Dimmery, Drew and Mai, Tung and Rao, Anup},\n booktitle = \t {Proceedings of the 39th International Conference on Machine Learning},\n pages = \t {844--864},\n year = \t {2022},\n editor = \t {Chaudhuri, Kamalika and Jegelka, Stefanie and Song, Le and Szepesvari, Csaba and Niu, Gang and Sabato, Sivan},\n volume = \t {162},\n series = \t {Proceedings of Machine Learning Research},\n month = \t {17--23 Jul},\n publisher = {PMLR},\n pdf = \t {https://proceedings.mlr.press/v162/arbour22a/arbour22a.pdf},\n url = \t {https://proceedings.mlr.press/v162/arbour22a.html},\n}\n\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A clean implementation of the Balancing Walk Design for online experimental design from Arbour, Dimmery, Mai and Rao (2022)",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://ddimmery.github.io/balancer-package/",
"Repository": "https://github.com/ddimmery/balancer-package"
},
"split_keywords": [
"causal inference",
"experimentation",
"ab testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aaf70bf24cfab72484b25b74994280f2ba354a1c6f0c41da9b1004cfcc3ee037",
"md5": "04966678ffea0d426402a31f2b84dbbe",
"sha256": "eeb8bbbb267d2c76c562b42354270e6c9c4926faa266248578c9979dfbb311de"
},
"downloads": -1,
"filename": "bwd-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "04966678ffea0d426402a31f2b84dbbe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 13891,
"upload_time": "2023-07-12T13:43:58",
"upload_time_iso_8601": "2023-07-12T13:43:58.467301Z",
"url": "https://files.pythonhosted.org/packages/aa/f7/0bf24cfab72484b25b74994280f2ba354a1c6f0c41da9b1004cfcc3ee037/bwd-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7fa5cb2cc33e49242150336db13cb5049e7ce566d60aa936facd4369de126514",
"md5": "29107c664e691f41cfa423c79ce75d9c",
"sha256": "ebe98f00eb2fafd0c73777b6e9ebcbbaf232580db9622e9a6e6e783e72069a1f"
},
"downloads": -1,
"filename": "bwd-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "29107c664e691f41cfa423c79ce75d9c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 11727,
"upload_time": "2023-07-12T13:44:00",
"upload_time_iso_8601": "2023-07-12T13:44:00.026659Z",
"url": "https://files.pythonhosted.org/packages/7f/a5/cb2cc33e49242150336db13cb5049e7ce566d60aa936facd4369de126514/bwd-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-12 13:44:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ddimmery",
"github_project": "balancer-package",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bwd"
}
JSON
