Title:	Methods for the Office of Evaluation Sciences
Version:	0.1.0
Date:	2023-02-09
Description:	Methods for statistical analysis and reporting preferred by the US Office of Evaluation Sciences (OES). This package prepares data from standard model output objects (such as from \code{lm()} and \code{estimatr::lm_robust()}) and creates visualizations of treatment effects from the prepared quantities, according to the standards of the US Office of Evaluation Sciences.
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.3
Imports:	broom, dplyr, estimatr, extrafont, ggplot2, rlang, sandwich, stats, tibble
Depends:	R (≥ 2.10)
NeedsCompilation:	no
Packaged:	2023-02-09 19:26:10 UTC; rtm
Author:	Ryan T. Moore [aut, cre], Miles Williams [aut]
Maintainer:	Ryan T. Moore <ryan.moore@gsa.gov>
Repository:	CRAN
Date/Publication:	2023-02-11 15:10:02 UTC

Sample Data for OES

Description

A simulated dataset containing outcomes, intervention variables, and covariates.

Usage

df_oes

Format

A data frame with 10000 rows and 7 variables:

x1

A binary 0/1 treatment assignment.

x2

A four-level factor treatment assignment with levels "0", ..., "3".

y1

A binary 0/1 outcome.

y2

A binary 0/1 outcome.

z1

A continuous normally-distributed covariate.

z2

A binary 0/1 covariate.

z3

A six-level factor covariate with levels "0", ..., "5".

Create OES Plot

Description

Plot experimental results using OES style

Usage

oes_plot(
  prep,
  font = "sans",
  device = "pdf",
  treatment_fill = "#F2C446",
  control_fill = "#2E9AC4",
  digits = 3,
  report_stars = TRUE,
  xlab,
  ylab,
  title = "Outcomes under Treatment",
  save = FALSE,
  name_save = "figure1.png",
  base_size = 12,
  width = 3.1,
  height = 4,
  dpi_forplot = 300
)

Arguments

Details

oes_plot plots the observed response mean of a control group and the predicted response means of one or more treatment groups based on OES guidance on data reporting and visualization best-practice. Read more about this OES guidance at https://oes.gsa.gov/assets/files/reporting-statistical-results.pdf.

Value

A plot; if save = TRUE, a file containing a plot.

Author(s)

Miles Williams

Examples

data(df_oes)

# Single binary treatment:
fit <- lm(y1 ~ x1, df_oes)

# Multiple treatment conditions:
fit2 <- lm(y2 ~ x2, df_oes)

# Using HC2 SE's from lm_robust():
fit_robust <- estimatr::lm_robust(y1 ~ x1, df_oes)
fit_robust2 <- estimatr::lm_robust(y2 ~ x2, df_oes)

# Using covariates and lm():
fit_covars <- lm(y2 ~ x2 + z1 + z2 + z3, df_oes)

# Using covariates and lm_robust():
fit_covars_robust <- estimatr::lm_robust(y2 ~ x2 + z1 + z2 + z3, df_oes)

# Specify treatment_arms:
oes_prep(fit, treatment_arms = 1) |> oes_plot()

# Specify treatment_vars:
fit |>
  oes_prep(treatment_vars = "x1") |>
  oes_plot()

# Specify treatment_arms:
oes_prep(fit2, treatment_arms = 3) |>
  oes_plot()

# Specify treatment_vars:
fit2 |>
  oes_prep(treatment_vars = c("x21", "x22", "x23")) |>
  oes_plot()

# Specify custom treatment_labels:
prep_w_labels <- oes_prep(fit2, treatment_arms = 3,
  treatment_labels = c(
    "Email",
    "Email +\nReward",
    "Email +\nRisk"),
  control_label = "Status Quo")

oes_plot(prep_w_labels)

# Using objects from estimatr::lm_robust():
oes_prep(fit_robust, treatment_arms = 1) |> oes_plot()

oes_prep(fit_robust2, treatment_arms = 3) |> oes_plot()

# Specify covariates with lm:
oes_prep(fit_covars, treatment_arms = 3) |> oes_plot()

# Specify covariates with lm_robust():
oes_prep(fit_covars_robust, treatment_arms = 3) |> oes_plot()

# For the Lin estimator, a manual version of lm_lin():
m.mat <- cbind(y2 = df_oes$y2, model.matrix(y2 ~ x2 + z1 + z2 + z3, df_oes)[, -1])
m.mat <- dplyr::mutate_at(
  data.frame(m.mat),
  .vars = c('z1', 'z2', 'z31', 'z32', 'z33', 'z34', 'z35'),
  function(x) x - mean(x)
  )

fit_lin <- estimatr::lm_robust(y2 ~ (x21 + x22 + x23) *
  (z1 + z2 + z31 + z32 + z33 + z34 + z35), m.mat)

oes_prep(fit_lin, treatment_arms = 3) |> oes_plot()

Prepare Model Output for OES Plots

Description

Prepare output of linear modeling object into a tidy data table to feed into OES plotting function

Usage

oes_prep(
  model,
  treatment_vars = NULL,
  treatment_arms = NULL,
  scale = c("response", "percentage"),
  treatment_labels,
  control_label,
  alpha_level = 0.05
)

Arguments

Details

oes_prep() takes a linear modeling output object (from lm() or lm_robust()) and returns a tidy tibble of estimates, confidence bounds, and related quantities ready for oes_plot to plot. Functionality for lm_lin() objects is in development.

Value

A tibble of T+1 rows and 8 columns, where T is the number of treatment conditions specified via treatment_vars or treatment_arms.

Author(s)

Miles Williams

Examples

data(df_oes)

# Single binary treatment:
fit <- lm(y1 ~ x1, df_oes)

# Multiple treatment conditions:
fit2 <- lm(y2 ~ x2, df_oes)

# Using HC2 SE's from lm_robust():
fit_robust <- estimatr::lm_robust(y1 ~ x1, df_oes)
fit_robust2 <- estimatr::lm_robust(y2 ~ x2, df_oes)

# Using covariates and lm():
fit_covars <- lm(y2 ~ x2 + z1 + z2 + z3, df_oes)

# Using covariates and lm_robust():
fit_covars_robust <- estimatr::lm_robust(y2 ~ x2 + z1 + z2 + z3, df_oes)

# Example specifying number of treatment arms:
oes_prep(fit, treatment_arms = 1)

# Example specifying name of treatment variable:
oes_prep(fit, treatment_vars = "x1")

# Example reporting outcomes as percentages:
oes_prep(fit, treatment_vars = "x1", scale = "percentage")

# Example specifying several treatment arms, labels, etc.:
oes_prep(fit2, treatment_arms = 3,
  treatment_labels = c(
    "Email",
    "Email +\nReward",
    "Email +\nRisk"),
  control_label = "Status Quo",
  scale = "percentage")

# Examples with lm_robust():
oes_prep(fit_robust, treatment_arms = 1)
oes_prep(fit_robust2, treatment_arms = 3)

# Examples with covariates:
oes_prep(fit_covars, treatment_arms = 3)
oes_prep(fit_covars_robust, treatment_arms = 3)

Render OES Theme

Description

Defines the OES plotting theme

Usage

theme_oes(base_size = 12, base_family = "Lato", device = "pdf")

Arguments

Details

A list of length 93 of classes theme and gg that defines elements of the display other than the data. theme_oes() wraps ggplot2::theme_bw() and replaces several default values.

Value

A list specifying a ggplot theme. See Details for more.

Author(s)

Miles Williams