Skip to content

Commit ffe24c0

Browse files
committed
readme
1 parent 81c9a0a commit ffe24c0

File tree

3 files changed

+129
-9
lines changed

3 files changed

+129
-9
lines changed

DESCRIPTION

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Config/testthat/edition: 3
5151
SystemRequirements: GNU make, C++17
5252
Biarch: true
5353
LazyData: true
54-
URL: https://github.com/CoryMcCartan/birdie, https://corymccartan.com/birdie/
54+
URL: https://corymccartan.com/birdie/, https://github.com/CoryMcCartan/birdie
5555
BugReports: https://github.com/CoryMcCartan/birdie/issues
5656
Roxygen: list(markdown = TRUE)
5757
RoxygenNote: 7.3.2

README.Rmd

Lines changed: 44 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ set.seed(5118)
1717

1818
<!-- badges: start -->
1919
[![R-CMD-check](https://github.com/CoryMcCartan/birdie/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/CoryMcCartan/birdie/actions/workflows/R-CMD-check.yaml)
20-
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/birdie)](https://cran.r-project.org/package=redist)
20+
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/birdie)](https://cran.r-project.org/package=birdie)
2121
![CRAN downloads](http://cranlogs.r-pkg.org/badges/grand-total/birdie)
2222
<!-- badges: end -->
2323

@@ -27,13 +27,51 @@ is not perfect, and measurement error in these predictions can cause problems
2727
in downstream analyses.
2828

2929
Bayesian Instrumental Regression for Disparity Estimation (BIRDiE) is a class of
30-
Bayesian models for accurately estimating conditional distributions by race,
31-
using BISG probabilities as inputs.
30+
Bayesian models for accurately estimating conditional distributions by race,
31+
using BISG probabilities as inputs.
3232
This package implements BIRDiE as described in [McCartan, Fisher, Goldin, Ho, and Imai (2025)](https://doi.org/10.1080/01621459.2025.2526695).
33-
It also implements standard BISG and an improved measurement-error BISG model as described
33+
It also implements standard BISG and an improved measurement-error BISG model as described
3434
in [Imai, Olivella, and Rosenman (2022)](https://www.science.org/doi/full/10.1126/sciadv.adc9824).
3535

36+
<details>
37+
<summary><b>Do I need BIRDiE?</b></summary>
38+
<p>
39+
BIRDiE is a statistical model to let you estimate the average value of a variable in different racial groups.
40+
To take an example from our research paper, if your data are tax records and you want to estimate the rate at which different racial groups take a certain tax credit, BIRDiE can help you do that.
41+
</p>
42+
<p>
43+
BIRDiE is applied on top of individual-level imputations/predictions of race from methods like BISG.
44+
If your only goal is to estimate individual race probabilities, then BIRDiE is not helpful&mdash;BISG alone suffices.
45+
The graphic below gives an overview of the problem BIRDiE solves and how it fits together with existing methods.
46+
</p>
47+
<p>
3648
<img src="man/figures/poster.svg" style="width: 100%" alt="BIRDiE Overview Poster" />
49+
</p>
50+
</details>
51+
52+
<details>
53+
<summary><b>What is the difference between BIRDiE and BISG?</b></summary>
54+
<p>
55+
BISG is a simple model that estimates the probability of each individual belonging to diferent racial groups, based on their last name and/or residence location.
56+
</p>
57+
<p>
58+
BIRDiE is a statistical model that takes race probabilities (like BISG) as <i>inputs</i> to estimate the average value of an outcome variable in different racial groups.
59+
If your research question involves both race and another (outcome) variable, then you likely need to apply BIRDiE on top of BISG to avoid biases caused by measurement error in BISG predictions.
60+
</p>
61+
</details>
62+
63+
<details>
64+
<summary><b>Is BIRDiE better than BISG, fBISG, etc?</b></summary>
65+
<p>
66+
There are many methods for imputing or predicting individual race, including BISG, fBISG, and others.
67+
Mainly, these methods use different data sources or slightly different models.
68+
</p>
69+
<p>
70+
BIRDiE is <i>not</i> a replacement for these methods, but rather a complementary tool that uses the outputs of these methods to properly estimate disparities in other variables.
71+
When BIRDiE is applied on top of these methods, it generally produces far more accurate estimates than directly thresholding or weighting by the outputs of the prediction methods alone.
72+
</p>
73+
</details>
74+
3775

3876
## Installation
3977

@@ -79,7 +117,7 @@ This is the "no-pooling" model from McCartan et al.
79117
We'll use Gibbs sampling for inference, which will also let us capture the uncertainty in our estimates.
80118

81119
```{r}
82-
fit = birdie(r_probs, turnout ~ proc_zip(zip), data=pseudo_vf,
120+
fit = birdie(r_probs, turnout ~ proc_zip(zip), data=pseudo_vf,
83121
family=cat_dir(), algorithm="gibbs")
84122
85123
print(fit)
@@ -101,5 +139,5 @@ tidy(fit)
101139
plot(fit)
102140
```
103141

104-
A more detailed introduction to the method and software package can be found
142+
A more detailed introduction to the method and software package can be found
105143
on the [Get Started](https://corymccartan.com/birdie/articles/birdie.html) page.

README.md

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<!-- badges: start -->
77

88
[![R-CMD-check](https://github.com/CoryMcCartan/birdie/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/CoryMcCartan/birdie/actions/workflows/R-CMD-check.yaml)
9-
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/birdie)](https://cran.r-project.org/package=redist)
9+
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/birdie)](https://cran.r-project.org/package=birdie)
1010
![CRAN downloads](http://cranlogs.r-pkg.org/badges/grand-total/birdie)
1111
<!-- badges: end -->
1212

@@ -24,7 +24,89 @@ implements standard BISG and an improved measurement-error BISG model as
2424
described in [Imai, Olivella, and Rosenman
2525
(2022)](https://www.science.org/doi/full/10.1126/sciadv.adc9824).
2626

27+
<details>
28+
29+
<summary>
30+
31+
<b>Do I need BIRDiE?</b>
32+
</summary>
33+
34+
<p>
35+
36+
BIRDiE is a statistical model to let you estimate the average value of a
37+
variable in different racial groups. To take an example from our
38+
research paper, if your data are tax records and you want to estimate
39+
the rate at which different racial groups take a certain tax credit,
40+
BIRDiE can help you do that.
41+
</p>
42+
43+
<p>
44+
45+
BIRDiE is applied on top of individual-level imputations/predictions of
46+
race from methods like BISG. If your only goal is to estimate individual
47+
race probabilities, then BIRDiE is not helpful—BISG alone suffices. The
48+
graphic below gives an overview of the problem BIRDiE solves and how it
49+
fits together with existing methods.
50+
</p>
51+
52+
<p>
53+
2754
<img src="man/figures/poster.svg" style="width: 100%" alt="BIRDiE Overview Poster" />
55+
</p>
56+
57+
</details>
58+
59+
<details>
60+
61+
<summary>
62+
63+
<b>What is the difference between BIRDiE and BISG?</b>
64+
</summary>
65+
66+
<p>
67+
68+
BISG is a simple model that estimates the probability of each individual
69+
belonging to diferent racial groups, based on their last name and/or
70+
residence location.
71+
</p>
72+
73+
<p>
74+
75+
BIRDiE is a statistical model that takes race probabilities (like BISG)
76+
as <i>inputs</i> to estimate the average value of an outcome variable in
77+
different racial groups. If your research question involves both race
78+
and another (outcome) variable, then you likely need to apply BIRDiE on
79+
top of BISG to avoid biases caused by measurement error in BISG
80+
predictions.
81+
</p>
82+
83+
</details>
84+
85+
<details>
86+
87+
<summary>
88+
89+
<b>Is BIRDiE better than BISG, fBISG, etc?</b>
90+
</summary>
91+
92+
<p>
93+
94+
There are many methods for imputing or predicting individual race,
95+
including BISG, fBISG, and others. Mainly, these methods use different
96+
data sources or slightly different models.
97+
</p>
98+
99+
<p>
100+
101+
BIRDiE is <i>not</i> a replacement for these methods, but rather a
102+
complementary tool that uses the outputs of these methods to properly
103+
estimate disparities in other variables. When BIRDiE is applied on top
104+
of these methods, it generally produces far more accurate estimates than
105+
directly thresholding or weighting by the outputs of the prediction
106+
methods alone.
107+
</p>
108+
109+
</details>
28110

29111
## Installation
30112

@@ -91,7 +173,7 @@ inference, which will also let us capture the uncertainty in our
91173
estimates.
92174

93175
``` r
94-
fit = birdie(r_probs, turnout ~ proc_zip(zip), data=pseudo_vf,
176+
fit = birdie(r_probs, turnout ~ proc_zip(zip), data=pseudo_vf,
95177
family=cat_dir(), algorithm="gibbs")
96178
#> Using weakly informative empirical Bayes prior for Pr(Y | R)
97179
#> This message is displayed once every 8 hours.

0 commit comments

Comments
 (0)