diff --git a/020-Data-generating-models.Rmd b/020-Data-generating-models.Rmd index e0332da..26ee31e 100644 --- a/020-Data-generating-models.Rmd +++ b/020-Data-generating-models.Rmd @@ -242,6 +242,7 @@ Here is a plot of 30 observations from the bivariate Poisson distribution with m #| fig.width: 6 #| fig.height: 4 +set.seed( 40440 ) bvp_dat <- r_bivariate_Poisson( 30, rho = 0.65, @@ -252,9 +253,12 @@ ggplot(bvp_dat) + aes(C1, C2) + geom_vline(xintercept = 0) + geom_hline(yintercept = 0) + - scale_x_continuous(expand = expansion(0,c(0,1))) + - scale_y_continuous(expand = expansion(0,c(0,1))) + - geom_point(position = position_jitter(width = 0.2, height = 0.2)) + + scale_x_continuous(expand = expansion(0,c(0,1)), + breaks = seq(0,16,2)) + + scale_y_continuous(expand = expansion(0,c(0,1)), + breaks = seq(2,12,2)) + + coord_fixed() + + geom_point(position = position_jitter(width = 0.075, height = 0.075)) + theme_minimal() ``` Plots like these are useful for building intuitions about a model. For instance, we can inspect \@ref(fig:bivariate-Poisson-scatter) to get a sense of the order of magnitude and range of the observations, as well as the likelihood of obtaining multiple observations with identical counts. @@ -444,9 +448,9 @@ The mathematical model gives us the details we need to execute with each of thes Here is the skeleton of a DGP function with arguments for each of the parameters we might want to control, including defaults for each (see \@ref(default-arguments) for more on function defaults): ```{r, echo = FALSE} -source( "case_study_code/gen_cluster_RCT.R" ) +source( "case_study_code/gen_cluster_RCT_bug.R" ) -cluster_RCT_fun <- readLines("case_study_code/gen_cluster_RCT.R") +cluster_RCT_fun <- readLines("case_study_code/gen_cluster_RCT_bug.R") skeleton <- c(cluster_RCT_fun[1:10], " # Code (see below) goes here", "}") ``` @@ -477,7 +481,7 @@ Next, we use the site characteristics to generate the individual-level variables A key piece here is the `rep()` function that takes a list and repeats each element of the list a specified number of times. In particular, `rep()` repeats each number ($1, 2, \ldots, J$), the corresponding number of times as listed in `nj`. -Putting the code above into the function skeleton will produce a complete DGP function (view the [complete function here](/case_study_code/gen_cluster_RCT.R)). +Putting the code above into the function skeleton will produce a complete DGP function (view the [complete function here](/case_study_code/gen_cluster_RCT_bug.R)). We can then call the function as so: ```{r} dat <- gen_cluster_RCT( @@ -486,7 +490,7 @@ dat <- gen_cluster_RCT( sigma2_u = 0.4, sigma2_e = 1 ) -dat +head( dat ) ``` With this function, we can control the average size of the clusters (`n`), the number of clusters (`J`), the proportion treated (`p`), the average outcome in the control group (`gamma_0`), the average treatment effect (`gamma_1`), the site size by treatment interaction (`gamma_2`), the amount of cross site variation (`sigma2_u`), the residual variation (`sigma2_e`), and the amount of site size variation (`alpha`). @@ -534,10 +538,13 @@ A further consequence of setting the overall scale of the outcome to 1 is that t The standardized mean difference for a treatment impact is defined as the average impact over the standard deviation of the outcome among control observations.^[An alternative definition is based on the pooled standard deviation, but this is usually a bad choice if one suspects treatment variation. More treatment variation should not reduce the effect size for the same absolute average impact.] Letting $\delta$ denote the standardized mean difference parameter, $$ \delta = \frac{E(Y | Z_j = 1) - E(Y | Z_j = 0)}{SD( Y | Z_j = 0 )} = \frac{\gamma_1}{\sqrt{ \sigma^2_u + \sigma^2_\epsilon } } $$ -Because we have constrained the total variance, $\gamma_1$ is equivalent to $\delta$. This equivalence holds for any value of $\gamma_0$, so we do not have to worry about manipulating $\gamma_0$ in the simulations---we can simply leave it at its default value. +Because we have constrained the total variance to 1, $\gamma_1$ is equivalent to $\delta$. +This equivalence holds for any value of $\gamma_0$, so we do not have to worry about manipulating $\gamma_0$ in the simulations---we can simply leave it at its default value. +The $\gamma_2$ parameter only influences outcomes for those in the treatment condition, with larger values inducing more variation. +Standardizing based on the total variance also makes $\gamma_2$ somewhat easier to interpret because this parameter the same units as $\gamma_1$. +Specifically, $\gamma_2$ is the expected difference in the standardized treatment impact for schools that differ in size by $\bar{n}$ (the overall average school size). +More broadly, standardizing by a stable parameter (the variation among those in the control condition) rather than something that changes in reaction to other parameters (which would be the case if we standardized by overall variation or pooled variation) will lead to more interpretable quantities. - - ## Sometimes a DGP is all you need {#three-parameter-IRT} @@ -719,8 +726,7 @@ The exercises below will give you further practice in developing, testing, and e Of course, we have not covered every consideration and challenge that arises when writing DGPs for simulations---there is _much_ more to explore! We will cover some further challenges in subsequent chapters. - - +See, for example, Chapters \@ref(sec:power) and \@ref(potential-outcomes). Yet more challenges will surely arise as you apply simulations in your own work. Even though such challenges might not align with the examples or contexts that we have covered here, the concepts and principles that we have introduced should allow you to reason about potential solutions. In doing so, we encourage you adopt the attitude of a chef in a test kitchen by trying out your ideas with code. diff --git a/030-Estimation-procedures.Rmd b/030-Estimation-procedures.Rmd index a629904..e4fb78c 100644 --- a/030-Estimation-procedures.Rmd +++ b/030-Estimation-procedures.Rmd @@ -11,7 +11,7 @@ set.seed(20250606) source("case_study_code/generate_ANOVA_data.R") source("case_study_code/ANOVA_Welch_F.R") source("case_study_code/r_bivariate_Poisson.R") -source("case_study_code/gen_cluster_RCT_rev.R") +source("case_study_code/gen_cluster_RCT.R") source("case_study_code/analyze_cluster_RCT.R") ``` @@ -114,11 +114,15 @@ Several different procedures might be used to estimate an overall average effect All three of these methods are widely used and have some theoretical guarantees supporting their use. Education researchers tend to be more comfortable using multi-level regression models, whereas economists tend to use OLS with clustered standard errors. - + + + We next develop estimation functions for each of these procedures, focusing on a simple model that does not include any covariates besides the treatment indicator. Each function needs to produce a point estimate, standard error, and $p$-value for the average treatment effect. -To have data to practice on, we generate a sample dataset using [a revised version of `gen_cluster_RCT()`](/case_study_code/gen_cluster_RCT_rev.R), which corrects the bug discussed in Exercise \@ref(cluster-RCT-checks): +To write estimation functions, it is useful to work with an example dataset that has the same structure as the data that will be simulated. To that end, we generate a sample dataset using [a revised version of `gen_cluster_RCT()`](/case_study_code/gen_cluster_RCT.R), which corrects the bug discussed in Exercise \@ref(cluster-RCT-checks): + + ```{r} dat <- gen_cluster_RCT( J=16, n_bar = 30, alpha = 0.8, p = 0.5, @@ -391,12 +395,11 @@ Furthermore, warnings can clutter up the console and slow down code execution, s On a conceptual level, we need to decide how to use the information contained in errors and warnings, whether that be by further elaborating the estimators to address different contingencies or by evaluating the performance of the estimators in a way that appropriately accounts for these events. We consider both these problems here, and then revisit the conceptual considerations in Chapter \@ref(performance-measures), where we discuss assessing estimator performance. - -### Capturing errors and warnings +### Capturing errors and warnings {#error-handling} Some estimation functions will require complicated or stochastic calculations that can sometimes produce errors. Intermittent errors can really be annoying and time-consuming if not addressed. -To protect yourself, it is good practice to anticipate potential errors, preventing them from stopping code execution and allowing your simulations to keep running. +To protect yourself, it is good practice to anticipate potential errors, so that you can prevent them from stopping code execution and allow your simulations to keep running. We next demonstrate some techniques for error-handling using tools from the `purrr` package. For illustrative purposes, consider the following error-prone function that sometimes returns what we want, sometimes returns `NaN` due to taking the square root of a negative number, and sometimes crashes completely because `broken_code()` does not exist: @@ -453,6 +456,7 @@ However, `quietly()` does not trap errors: rs <- replicate(20, my_quiet_function( 7 )) ``` To handle both errors and warnings, we double-wrap the function, first with `possibly()` and then with `quietly()`: + ```{r} my_safe_quiet_function <- quietly( possibly( my_complex_function, otherwise = NA ) ) my_safe_quiet_function(7) @@ -465,39 +469,54 @@ set.seed(101012) # (hand-picked to show a warning.) dat <- gen_cluster_RCT( J = 50, n_bar = 100, sigma2_u = 0 ) mod <- analysis_MLM(dat) ``` + Wrapping `lmer()` with `quietly()` makes it possible to catch such output and store it along with other results, as in the following: ```{r} -quiet_safe_lmer <- quietly( possibly( lmerTest::lmer, otherwise=NULL ) ) +quiet_safe_lmer <- quietly( possibly( lmerTest::lmer, otherwise = NULL ) ) M1 <- quiet_safe_lmer( Yobs ~ 1 + Z + (1|sid), data=dat ) M1 ``` -We then pick apart the pieces and construct a dataset of results: + +In our estimation function, we replace the original `lmer()` call with our quiet-and-safe version, `quiet_safe_lmer()`. We then pick apart the pieces of its output to return a tidy dataset of results. (Separately, we also add in a generally preferred optimizer, bobyqa, to try and avoid the warnings and errors in the first place.) The resulting function is: + ```{r} -if ( is.null( M1$result ) ) { - # we had an error! - tibble( ATE_hat = NA, SE_hat = NA, p_value = NA, - message = M1$message, - warning = M1$warning, - error = TRUE ) -} else { - sum <- summary( M1$result ) - tibble( - ATE_hat = sum$coefficients["Z","Estimate"], - SE_hat = sum$coefficients["Z","Std. Error"], - p_value = sum$coefficients["Z", "Pr(>|t|)"], - message = list( M1$message ), - warning = list( M1$warning ), - error = FALSE ) +analysis_MLM_safe <- function( dat ) { + + M1 <- quiet_safe_lmer( Yobs ~ 1 + Z + (1 | sid), + data=dat, + control = lme4::lmerControl( + optimizer = "bobyqa" + ) ) + + if ( is.null( M1$result ) ) { + # we had an error! + tibble( ATE_hat = NA, SE_hat = NA, p_value = NA, + message = M1$message, + warning = M1$warning, + error = TRUE ) + } else { + # no error! + sum <- summary( M1$result ) + + tibble( + ATE_hat = sum$coefficients["Z","Estimate"], + SE_hat = sum$coefficients["Z","Std. Error"], + p_value = sum$coefficients["Z", "Pr(>|t|)"], + message = length( M1$messages ) > 0, + warning = length( M1$warning ) > 0, + error = FALSE + ) + } } ``` -Now we can plug in the above code to make a nicely quieted and safe function. -This version runs without extraneous messages: + +Our improved function runs without extraneous messages and returns the estimation results along with any diagnostic information from messages or warnings: + ```{r} mod <- analysis_MLM_safe(dat) mod ``` -Now we have the estimation results along with any diagnostic information from messages or warnings. Storing this information will let us evaluate what proportion of the time there was a warning or message, run additional analyses on the subset of replications where there was no such warning, or even modify the estimator to take the diagnostics into account. We have solved the technical problem---our code will run and give results---but not the conceptual one: what does it mean when our estimator gives an NA or a convergence warning with a nominal answer? How do we decide how good our estimator is when it does this? @@ -575,7 +594,7 @@ We end up with a 20-entry list, with each element consisting of a pair of the re length( resu ) resu[[3]] ``` -We can massage our data to a more easy to parse format: +We can massage our data into a format that is easier to parse: ```{r} resu <- transpose( resu ) unlist(resu$result) diff --git a/035-running-simulation.Rmd b/035-running-simulation.Rmd index 8ee5dfd..1be5a51 100644 --- a/035-running-simulation.Rmd +++ b/035-running-simulation.Rmd @@ -20,15 +20,15 @@ source("case_study_code/analyze_cluster_RCT.R") # Running the Simulation Process {#running-the-simulation-process} In the prior two chapters we saw how to write functions that generate data according to a particular model and functions that implement data-analysis procedures on simulated data. -The next step in a simulation involves putting these two pieces together, running the DGP function and the data-analysis function repeatedly to obtain results (in the form of point estimates, standard errors, confidence intervals, p-values, or other quantities) from many replications of the whole process. +The next step in building a simulation involves putting these two pieces together, running the DGP function and the data-analysis function repeatedly to obtain results (in the form of point estimates, standard errors, confidence intervals, $p$-values, or other quantities) from many replications of the whole process. As with most things R-related, there are many different techniques that can be used to repeat a set of calculations over and over. -In this chapter, we demonstrate several techniques for doing so. +In this chapter, we demonstrate two key techniques for doing so. We then explain how to ensure reproducibility of simulation results by setting the seed used by R's random number generator. ## Repeating oneself {#repeating-oneself} -Suppose that we want to simulate Pearson's correlation coefficient calculated based on a sample from the bivariate Poisson function. +Suppose that we want to repeatedly generate bivariate Poisson data and then use the data to estimate the correlation between the variates. We saw a DGP function for the bivariate Poisson in Section \@ref(DGP-functions), and an estimation function in Section \@ref(estimation-functions). To produce a simulated correlation coefficient, we need to run these two functions in turn: ```{r} @@ -55,12 +55,12 @@ The first argument specifies the number of times to repeat the calculation. The second argument is an R expression that will be evaluated. The expression is wrapped in curly braces (`{}`) because it involves more than a single line of code. Including the option `id = "rep"` returns a dataset that includes a variable called `rep` to identify each replication of the process. -Setting the option `stack = TRUE` will stack up the output of each expression into a single tibble, which will facilitate later calculations on the results. -Setting this option is not necessary because it is `TRUE` by default; setting `stack = FALSE` will return the results in a list rather than a tibble (try this for yourself to see!). +Setting the option `stack = TRUE` will stack up the output of each expression into a single tibble, which will facilitate further calculations on the results. +Explicitly setting this option is not necessary because it is `TRUE` by default; setting `stack = FALSE` will return the results in a list rather than a tibble (try this for yourself to see!). There are many other functions that work very much like `repeat_and_stack()`, including the base-R function `replicate()` and the now-deprecated function `rerun()` from `{purrr}`. The functions in the `map()` family from `{purrr}` can also be used to do the same thing as `repeat_and_stack()`. -See Appendix \@ref(more-repeating-oneself) for more discussion of these alternatives. +See Appendix \@ref(more-repeating-oneself) for more discussion of these options. ## One run at a time @@ -124,31 +124,14 @@ Note how the `bind_rows()` method can take naming on the fly, and give us a colu Once we have a function to execute a single run, we can produce multiple results using `repeat_and_stack()`: -```{r secret_run_cluster_rand_sim, include=FALSE} -R <- 1000 -ATE <- 0.30 - -if ( !file.exists("results/cluster_RCT_simulation.rds") ) { - tictoc::tic() # Start the clock! - set.seed( 40404 ) - runs <- repeat_and_stack(R, one_run( n_bar = 30, J=20, gamma_1 = ATE ), id = "runID") - tictoc::toc() - - saveRDS( runs, file = "results/cluster_RCT_simulation.rds" ) -} else { - runs <- readRDS( file = "results/cluster_RCT_simulation.rds" ) -} -``` - - ```{r cluster_rand_sim, eval=FALSE} R <- 1000 ATE <- 0.30 -runs <- repeat_and_stack(R, - one_run( n_bar = 30, J=20, gamma_1 = ATE ), - id = "runID") -saveRDS( runs, file = "results/cluster_RCT_simulation.rds" ) +runs <- repeat_and_stack( R, + one_run( n_bar = 30, J = 20, gamma_1 = ATE ), + id = "runID") ``` + Setting `id = "runID"` lets us keep track of which iteration number produced which result. Once our simulation is complete, we save our results to a file so that we can avoid having to re-run the full simulation if we want to explore the results in some future work session. @@ -157,11 +140,12 @@ The next step is to evaluate how well the estimators did. For example, we will want to examine questions about bias, precision, and accuracy of the three point estimators. In Chapter \@ref(performance-measures), we will look systematically at ways to quantify the performance of estimation methods. -### Reparameterizing {#one-run-reparameterization} +## Reparameterizing {#one-run-reparameterization} In Section \@ref(DGP-standardization), we discussed how to index the DGP of the cluster-randomized experiment using an intra-class correlation (ICC) instead of using two separate variance components. This type of re-parameterization can be handled as part of writing a wrapper function for executing the DGP and estimation procedures. -Here is a revised version of `one_run()`, which also renames some of the more obscure model parameters using terms that are easier to interpret: +Here is a revised version of `one_run()`[^stopifnot], which also renames some of the more obscure model parameters using terms that are easier to interpret: + ```{r revised_CRT, eval=FALSE} one_run <- function( n_bar = 30, J = 20, ATE = 0.3, size_coef = 0.5, @@ -181,14 +165,72 @@ one_run <- function( bind_rows( MLM = MLM, LR = LR, Agg = Agg, .id = "method" ) } ``` -Note the `stopifnot`: it is wise to ensure our parameter transforms are all reasonable, so we do not get unexplained errors or strange results later on. + +[^stopifnot]: Note the use of `stopifnot` in the body of `one_run()`. +It is wise to ensure our parameter transforms are all reasonable, so we do not get unexplained errors or strange results later on. It is best if your code fails as soon as possible! Otherwise debugging can be quite hard. + + -Controlling how we use the foundational elements such as our data generating code is a key technique for making the higher level simulations sensible and more easily interpretable. +Controlling how we use the foundational elements such as our data generating code is a key technique for making the higher level simulations sensible and more readily interpretable. In the revised `one_run()` function, we transform the `ICC` input parameter into the parameters used by `gen_cluster_RCT()` so as to maintain the effect size interpretation of our simulation. We have not modified `gen_cluster_RCT()` at all: instead, we specify the parameters of the DGP function in terms of the parameters we want to directly control in the simulation. -Here we have put our entire simulation into effect size units, and are now providing "knobs" to the simulation that are directly interpretable. + +We can then wrap the reparameterization and replication into a function that runs an entire simulation: + + +```{r secret_run_cluster_rand_sim, include=FALSE} +R <- 1000 +ATE <- 0.30 +source( here::here( "case_study_code/clustered_data_simulation.R" ) ) +if ( !file.exists("results/cluster_RCT_simulation.rds") ) { + tictoc::tic() # Start the clock! + set.seed( 40404 ) + run_CRT_sim( reps = 1000, + n_bar = 30, J = 20, + ATE = 0.3, ICC = 0.2, + size_coef = 0.5, alpha = 0.5 ) + + tictoc::toc() + + saveRDS( runs, file = "results/cluster_RCT_simulation.rds" ) +} else { + runs <- readRDS( file = "results/cluster_RCT_simulation.rds" ) +} +``` + +```{r} +run_CRT_sim <- function( reps, + n_bar = 10, J = 30, p = 0.5, + ATE = 0, ICC = 0.4, + size_coef = 0, alpha = 0 ) { + + res <- + simhelpers::repeat_and_stack( reps, { + dat <- gen_cluster_RCT( n_bar = n_bar, J = J, p = p, + gamma_0 = 0, gamma_1 = ATE, gamma_2 = size_coef, + sigma2_u = ICC, sigma2_e = 1 - ICC, + alpha = alpha ) + quiet_analyze_data(dat) + }) %>% + bind_rows( .id="runID" ) + + res +} +``` + +Using it is then quite simple: +```{r, eval = FALSE} +run_CRT_sim( reps = 1000, + n_bar = 30, J = 20, + ATE = 0.3, ICC = 0.2, + size_coef = 0.5, alpha = 0.5 ) +saveRDS( runs, file = "results/cluster_RCT_simulation.rds" ) +``` +Notice how our simulation takes easy-to-interpret parameters (`ATE`, `ICC`) rather than the raw variance components. +We have put our simulation into effect size units, and are now providing "knobs" to the simulation that are directly interpretable. + ## Bundling simulations with `simhelpers` {#bundle-sim-demo} @@ -196,18 +238,20 @@ The techniques that we have demonstrated for repeating a set of calculations eac The `simhelpers` package provides a function `bundle_sim()` that abstracts this common pattern and allows you to automatically stitch together (or "bundle") a DGP function and an estimation function, so that they can be run once or multiple times. Thus, `bundle_sim()` provides a convenient alternative to writing your own `one_run()` function for each simulation, thereby saving a bit of typing (and avoiding an opportunity for bugs to creep into your code). -`bundle_sim()` takes a DGP function and an estimation function as inputs and gives us back a new function that will run a simulation using whatever parameters we give it. -Here is a basic example, which creates a function for simulating Pearson correlation coefficients with a bivariate Poisson distribution: +The `bundle_sim()` function takes a DGP function and an estimation function as inputs and gives us back a new function that will run a simulation using whatever parameters we give it. +The `bundle_sim()` function is a "factory" in that it creates a new function for you on the fly. + +Here is a basic example, where we create a function for running our simulation to evaluate how well our Pearson correlation coefficient confidence interval works on a bivariate Poisson distribution: ```{r} -sim_r_Poisson <- bundle_sim(f_generate = r_bivariate_Poisson, - f_analyze = r_and_z, - id = "rep") +sim_r_Poisson <- bundle_sim( f_generate = r_bivariate_Poisson, + f_analyze = r_and_z, + id = "rep" ) ``` -If we specify the optional argument `id = "rep"`, the function will include a variable called `rep` with a unique identifier for each replication of the simulation process. +If we specify the optional argument `id = "rep"`, the built function will generate a variable called `rep` with a unique identifier for each replication of the simulation. We can use the newly created function like so: ```{r, messages=FALSE} -sim_r_Poisson( 4, N = 30, rho = 0.4, mu1 = 8, mu2 = 14) +sim_r_Poisson( 4, N = 30, rho = 0.4, mu1 = 8, mu2 = 14 ) ``` To create this simulation function, `bundle_sim()` examined `r_bivariate_Poisson()`, figured out what its input arguments are, and made sure that the simulation function includes the same input arguments. @@ -220,10 +264,11 @@ Its first argument is `reps`, which controls the number of times that the simula Its last argument is `seed`, which we will discuss in Section \@ref(seeds-and-pseudo-RNGs). The `bundle_sim()` function requires specifying a DGP function and a _single_ estimation function, with the data as the first argument. -For our cluster-randomized experiment example, we would then need to use our `estimate_Tx_Fx()` function that organizes all of the estimators (see Chapter \@ref(multiple-estimation-procedures)). +To apply it in our cluster-randomized experiment example, we will need to use our `estimate_Tx_Fx()` function that organizes all of the estimators (see Chapter \@ref(multiple-estimation-procedures)). We then use `bundle_sim()` to create a function for running an entire simulation: ```{r, messages=FALSE} -sim_cluster_RCT <- bundle_sim( gen_cluster_RCT, estimate_Tx_Fx, id = "runID" ) +sim_cluster_RCT <- bundle_sim( gen_cluster_RCT, estimate_Tx_Fx, + id = "runID" ) ``` We can call the newly created function like so: ```{r, messages=FALSE} @@ -236,20 +281,22 @@ Again, `bundle_sim()` produces a function with input names that exactly match th It is not possible to re-parameterize or change argument names, as we did with `one_run()` in Section \@ref(one-run-reparameterization). See Exercise \@ref(reparameterization-redux) for further discussion of this limitation. -To use the simulation function in practice, we call it by specifying the number of replications desired (which we have stored in `R`) and any relevant input parameters. +To use the simulation function in practice, we would call it by specifying the number of replications desired (which we have stored in `R`) and any relevant input parameters. ```{r, eval=FALSE} runs <- sim_cluster_RCT( reps = R, J = 20, n_bar = 30, alpha = 0.5, gamma_1 = ATE, gamma_2 = 0.5, sigma2_u = 0.2, sigma2_e = 0.8 ) -saveRDS( runs, file = "results/cluster_RCT_simulation.rds" ) ``` -The `bundle_sim()` function is just a convenient way to create a function that pieces together the steps in the simulation process, which is especially useful when the component functions include many input parameters. +The `bundle_sim()` function is just a convenient way to create a function that pieces together the steps in the simulation process. +This is especially useful when the component functions include many input parameters. +Think of it as a not overly smart coding assistant who will take some basic directions and give you some code back. The function has several further features, which we will demonstrate in subsequent chapters. + ## Seeds and pseudo-random number generators {#seeds-and-pseudo-RNGs} -In prior chapters, we have used built-in functions to generate random numbers and also written our own data-generating functions that produce artificial data following a specific random process. +In prior chapters, we used built-in functions to generate random numbers and wrote our own data-generating functions that produce artificial data following a specific random process. With either type of function, re-running it with the exact same input parameters will produce different results. For instance, running the `rchisq` function with the same set of inputs will produce two different sequences of $\chi^2$ random variables: ```{r} @@ -269,10 +316,12 @@ sim_B <- sim_r_Poisson( 10, N = 30, rho = 0.4, mu1 = 8, mu2 = 14) identical(sim_A, sim_B) ``` Of course, this is the intended behavior of these functions, but it has an important consequence that needs some care and attention. -Using functions like `rchisq()`, `r_bivariate_Poisson()`, or `r_bivariate_Poisson()` in a simulation study means that the results will not be fully reproducible. +Using functions like `rchisq()`, `r_bivariate_Poisson()`, or `r_bivariate_Poisson()` in a simulation study means that the results will not be fully reproducible. +If we run the simulation code and write up our results, and then someone else tries to run the same simulation using the very same code, they will not get the very same results. +This undermines transparency and makes it hard to verify if a set of presented results really came from a given codebase. When using DGP functions for simulations, it is useful to be able to exactly control the process of generating random numbers. -This is much more feasible than it sounds: Monte Carlo simulations are random, at least in theory, but computers are deterministic. +This is much more feasible than it sounds: although Monte Carlo simulations are random in theory, computers are deterministic. When we use R to generate what we have been referring to as "random numbers," the functions produce what are actually _pseudo-random_ numbers. Pseudo-random numbers are generated from chains of mathematical equations designed to produce sequences of numbers that appear random, but actually follow a deterministic sequence. Each subsequent random number is a calculated by starting from the previously generated value (i.e., the current state of the random number generator), applying a complicated function, and storing the result (i.e., updating the state). @@ -282,7 +331,7 @@ The state of the pseudo-random number generator is shared across different funct Each time we ask for a random number from the generator, its state is updated. Functions like `rnorm()` and `rchisq()` all call the low-level generator and then transform the result to be of the correct distribution. -Because the generator is actually deterministic, we can control its output by specify a starting value or initial state, +Because the generator is actually deterministic, we can control its output by specify a starting value or initial state. In R, the state of the random number generator can be controlled by setting what its known as the seed. The `set.seed()` function allows us to specify a seed value, so that we can exactly reproduce a calculation. For example, @@ -293,6 +342,8 @@ set.seed(6) c2 <- rchisq(4, df = 3) rbind(c1, c2) ``` +The sequences are the same! + Similarly, we can set the seed and run a series of calculations involving multiple functions that make use of the random number generator: ```{r} # First time @@ -308,9 +359,23 @@ dat_B <- r_bivariate_Poisson(20, rho = 0.5, mu1 = 4, mu2 = 7) bind_rows(A = r_and_z(dat_A), B = r_and_z(dat_B), .id = "Rep") ``` -The `bundle_sim()` function demonstrated in Section \@ref(bundle-sim-demo) creates a function for repeating the process of generating and analyzing data. -By default, the function it produces includes an argument `seed`, which allows the user to set a seed value before repeatedly evaluating the DGP function and estimation function. -By default, the `seed` argument is `NULL` and so the current seed is not modified. +When writing code, you can pass the seed as a parameter, such as the following: + +```{r, eval=FALSE} +run_CRT_sim <- function(reps, + n_bar = 10, J = 30, p = 0.5, + ATE = 0, ICC = 0.4, + size_coef = 0, alpha = 0, + seed = NULL ) { + + if (!is.null(seed)) set.seed(seed) + ... +} +``` +A `seed` argument allows the user to set a seed value before running the full simulation. +By default, the `seed` argument is `NULL` and so the current seed is not modified, but if you set the seed, you will get the same run each time. + +The `bundle_sim()` function, demonstrated in Section \@ref(bundle-sim-demo), produces a function with a `seed` seed argument that works just as in the example above. Specifying an integer-valued seed will make the results exactly reproducible: ```{r} sim_A <- sim_r_Poisson( 10, N = 30, rho = 0.4, mu1 = 8, mu2 = 14, @@ -330,7 +395,17 @@ If we set a seed and find that the code crashes, we can debug and then rerun the If it now runs without error, we know we fixed the problem. If we had not set the seed, we would not know if we were just getting (un)lucky, and avoiding the error by chance. - + +## Conclusions + +The act of running a simulation is not itself the goal of a simulation study. Rather, it is only the procedural mechanism by which we generate many realizations of a data analysis procedure under a specified data-generating process. +As we have seen in this chapter, doing so requires carefully stitching together the one-two step of data generation and analysis, repeating that combined process many times, and then organizing the resulting output in a form that can be easily and systematically evaluated. +Different coding strategies can be used to accomplish this, but they all serve the same purpose: to make repeated evaluation of a procedure reliable, transparent, and easy to extend. +Finally, because simulation studies rely on stochastic data generation, it is critical that we pay careful attention to reproducibility. +By controlling the pseudo-random number generator through explicit use of seeds, we can ensure that simulation results can be exactly reproduced, checked, and debugged. +This reproducibility is essential for both scientific transparency and practical development of simulation code. + +With the tools of this chapter in place, we are now positioned to move from running simulations to evaluating what they tell us about estimator behavior---the focus of Chapter \@ref(performance-measures). ## Exercises diff --git a/040-Performance-criteria.Rmd b/040-Performance-criteria.Rmd index 2bc51a0..7231415 100644 --- a/040-Performance-criteria.Rmd +++ b/040-Performance-criteria.Rmd @@ -6,13 +6,17 @@ output: ```{r include = FALSE} library(tidyverse) +library(simhelpers) options(list(dplyr.summarise.inform = FALSE)) -source("case_study_code/gen_cluster_RCT_rev.R") +source("case_study_code/gen_cluster_RCT.R") cluster_RCT_res <- readRDS("results/cluster_RCT_simulation.rds") %>% mutate( - method = case_match(method, "Agg" ~ "Aggregation", "LR" ~ "Linear regression", "MLM" ~ "Multilevel model") + method = case_match(method, + "Agg" ~ "Aggregation", + "LR" ~ "Linear regression", + "MLM" ~ "Multilevel model") ) ``` @@ -20,17 +24,25 @@ cluster_RCT_res <- # Performance Measures {#performance-measures} Once we run a simulation, we end up with a pile of results to sort through. -For example, Figure \@ref(fig:CRT-ATE-hist) depicts the distribution of average treatment effect estimates from the cluster-randomized experiment simulation, which we generated in Chapter \@ref(running-the-simulation-process). +For example, Figure \@ref(fig:CRT-ATE-hist) depicts the distribution of average treatment effect estimates from the cluster-randomized experiment simulation we generated in Section \@ref(one-run-reparameterization). There are three different estimators, each with 1000 replications. Each histogram is an approximation of the _sampling distribution_ of the estimator, meaning its distribution across repetitions of the data-generating process. -With results such as these, the question before us is now how to evaluate how well each procedure works. If we are comparing several different estimators, we also need to determine which ones work better or worse than others. In this chapter, we look at a variety of __performance measures__ that can answer these questions. +Visually, we see the three estimators look about the same---they sometimes estimate too low, and sometimes estimate too high. +We also see linear regression is shifted up a bit, and maybe aggregation and MLM have a few more outlines. +These observations are assessing how well each estimator _performs_, and we next dig into quantifying that performance more precisely with what we call _performance measures_. + + ```{r CRT-ATE-hist} #| fig.width: 8 #| fig.height: 3 +#| out.width: "100%" #| echo: false #| message: false -#| fig.cap: "Sampling distribution of average treatment effect estimates from a cluster-randomized trial with a true average treatment effect of 0.3." +#| fig.cap: "Sampling distribution of average treatment effect estimates from a cluster-randomized trial with a true average treatment effect of 0.3 (dashed line)." cluster_RCT_mean <- cluster_RCT_res %>% @@ -39,72 +51,91 @@ cluster_RCT_mean <- ggplot(cluster_RCT_res) + aes(ATE_hat, fill = method) + geom_vline(xintercept = 0.3, linetype = "dashed") + - geom_vline(data = cluster_RCT_mean, aes(xintercept = ATE_hat, color = method)) + - geom_point(data = cluster_RCT_mean, aes(x = ATE_hat, y = -1, color = method)) + + geom_vline(data = cluster_RCT_mean, aes(xintercept = ATE_hat), color="black") + + geom_point(data = cluster_RCT_mean, aes(x = ATE_hat, y = -1), color = "black") + geom_histogram(alpha = 0.5) + facet_wrap(~ method, nrow = 1) + theme_minimal() + labs(x = "Average treatment effect estimate", y = "") + scale_y_continuous(labels = NULL) + + scale_x_continuous( breaks=c( -.3, 0, 0.3, 0.6, 0.9 ) ) + theme(legend.position = "none") ``` -Performance measures are summaries of a sampling distribution that describe how an estimator or data analysis procedure behaves on average if we could repeat the data-generating process an infinite number of times. +A _performance measure_ summarizes an estimator's sampling distribution to describe how an estimator would behave on average if we were to repeat the data-generating process an infinite number of times. For example, the bias of an estimator is the difference between the average value of the estimator and the corresponding target parameter. -Bias measures the central tendency of the sampling distribution, capturing how far off, on average, the estimator would be from the true parameter value if we repeated the data-generating process an infinite number of times. -In Figure \@ref(fig:CRT-ATE-hist), black dashed lines mark the true average treatment effect of 0.3 and the colored vertical lines with circles at the end mark the means of the estimators. -The distance between the colored lines and the black dashed lines corresponds to the bias of the estimator. +Bias measures the central tendency of the sampling distribution, capturing whether we are systematically off, on average, from the true parameter value. + +In Figure \@ref(fig:CRT-ATE-hist), the black dashed lines mark the true average treatment effect of 0.3 and the solid lines with the dot mark the means of the estimators. +The horizontal distance between the solid and dashed lines corresponds to the bias of the estimator. This distance is nearly zero for the aggregation estimator and the multilevel model estimator, but larger for the linear regression estimator. +Our performance measure of bias would be about zero for Agg and MLM, and around 0.05 to 0.1 for linear regression. + +Many performance measures exist. +For point estimates, conventional performance measures include bias, variance, and root mean squared error. +Our definition of "success" could depend on which measure we find more important: is lower bias good? Is it better than lower variance? -Different types of data-analysis results produce different types of information, and so the relevant set of performance measures depends on the type of data analysis result we are studying. -For procedures that produce point estimates or point predictions, conventional performance measures include bias, variance, and root mean squared error. If the point estimates come with corresponding standard errors, then we may also want to evaluate how accurately the standard errors represent the true uncertainty of the point estimators; conventional performance measures for capturing this include the relative bias and relative root mean squared error of the variance estimator. For procedures that produce confidence intervals or other types of interval estimates, conventional performance measures include the coverage rate and average interval width. Finally, for inferential procedures that involve hypothesis tests (or more generally, classification tasks), conventional performance measures include Type I error rates and power. We describe each of these measures in Sections \@ref(assessing-point-estimators) through \@ref(assessing-inferential-procedures). -Performance measures are defined with respect to sampling distributions, or the results of applying a data analysis procedure to data generated according to a particular process across an infinite number of replications. -In defining specific measures, we will follow statistical conventions to denote the mean, variance, and other moments of the sampling distribution. -For a random variable $T$, we will use the expectation operator $\E(T)$ to denote the mean of the sampling distribution of $T$, $\M(T)$ to denote the median of its sampling distribution, $\Var(T)$ to denote the variance of its sampling distribution, and $\Prob()$ to denote probabilities of specific outcomes with respect to its sampling distribution. -We will use $\Q_p(T)$ to denote the $p^{th}$ quantile of a distribution, which is the value $x$ such that $\Prob(T \leq x) = p$. With this notation, the median of a continuous distribution is equivalent to the 0.5 quantile: $\M(T) = \Q_{0.5}(T)$. - -For some simple combinations of data-generating processes and data analysis procedures, it may be possible to derive exact mathematical formulas for calculating some performance measures (such as exact mathematical expressions for the bias and variance of the linear regression estimator). -But for many problems, the math is difficult or intractable---that's why we do simulations in the first place. -Simulations do not produce the _exact_ sampling distribution or give us _exact_ values of performance measures. -Instead, simulations generate _samples_ (usually large samples) from the the sampling distribution, and we can use these to compute _estimates_ of the performance measures of interest. -In Figure \@ref(fig:CRT-ATE-hist), we calculated the bias of each estimator by taking the mean of 1000 observations from its sampling distribution. If we were to repeat the whole set of calculations (with a different seed), then our bias results would shift slightly because they are imperfect estimates of the actual bias. - -In working with simulation results, it is important to keep track of the degree of uncertainty in performance measure estimates. +One might have other performance measures than these, depending on what kind of estimator or data analysis procedure we are evaluating. +Perhaps it is some measure of classification accuracy such as the F1 rate. +Or perhaps it is something very specific, such as the chance of an error larger than some threshold. + +Regardless of measure chosen, the true performance of an estimator depends on the data generating process being used. +We might see good performance against some DGPs, and bad performance against other DGPs. +Performance measures are defined with respect to the sampling distribution of our estimator, which is the distribution of values we would see across different datasets that all came from the same DGP. + +In the following, we define many of the most common measures in terms of standard statistical quantities such as the mean, variance, and other moments of the sampling distribution. +Notation-wise, for a random variable $T$ (e.g., for some estimator $T$), we will use the expectation operator $\E(T)$ to denote the mean, $\M(T)$ to denote the median, $\Var(T)$ to denote the variance, and $\Prob()$ to denote probabilities of specific outcomes, all with respect to the sampling distribution of $T$. +We also use $\Q_p(T)$ to denote the $p^{th}$ quantile of a distribution, which is the value $x$ such that $\Prob(T \leq x) = p$. +With this notation, the median of a continuous distribution is equivalent to the 0.5 quantile: $\M(T) = \Q_{0.5}(T)$. +Using this notation we can write, for example, that the bias of $T$ is $\E(T) - \theta$, where $\theta$ is the target parameter. +We develop all of this further, below. + +For some simple combinations of data-generating processes and data analysis procedures, it may be possible to derive exact mathematical formulas for some performance measures (such as exact mathematical expressions for the bias and variance of the linear regression estimator). +But for many problems, the math is difficult or intractable---which is partly why we do simulations in the first place. +Simulations, however, do not produce the _exact_ sampling distribution or give us _exact_ values of performance measures. +Instead, simulations generate _samples_ (usually large samples) from the the sampling distribution, and we can use these to _estimate_ the performance measures of interest. +In Figure \@ref(fig:CRT-ATE-hist), for example, we estimated the bias of each estimator by taking the mean of 1000 observations from its sampling distribution. +If we were to repeat the whole simulation (with a different seed), then our bias results would shift slightly because they are imperfect estimates of the actual bias. + +In working with simulation results, it is important to track how much uncertainty we have in our performance measure estimates. We call such uncertainty _Monte Carlo error_ because it is the error arising from using a finite number of replications of the Monte Carlo simulation process. -One way to quantify it is with the _Monte Carlo standard error (MCSE)_, or the standard error of a performance estimate based on a finite number of replications. +One way to quantify the simulation uncertainty is with the _Monte Carlo Standard Error (MCSE)_, which is the standard error of a performance estimate given a specific number of replications. Just as when we analyze real data, we can apply statistical techniques to estimate the MCSE and even to generate confidence intervals for performance measures. -The magnitude of MCSE is driven by how many replications we use: if we only use a few, we will have noisy estimates of performance with large MCSEs; if we use millions of replications, the MCSE will usually be tiny. -It is important to keep in mind that the MCSE is not measuring anything about how a data analysis procedure performs in general. -It only describes how precisely we have approximated a performance criterion, an artifact of how we conducted the simulation. -Moreover, MCSEs are under our control. -Given a desired MCSE, we can determine how many replications we would need to ensure our performance estimates have the specified level of precision. +The magnitude of the MCSE is driven by how many replications we use: if we only use a few, we will have noisy estimates of performance with large MCSEs; if we use millions of replications, the MCSE will usually be tiny. +It is important to keep in mind that the MCSE is not measuring anything about how our estimator performs. +It only describes how precisely we have _estimated_ its performance; MCSE is an artifact of how we conducted the simulation. +The MCSE are also under our control: Given a desired MCSE, we can determine how many replications we would need to ensure our performance estimates have a MCSE of that size. Section \@ref(MCSE) provides details about how to compute MCSEs for conventional performance measures, along with some discussion of general techniques for computing MCSE for less conventional measures. ## Measures for Point Estimators {#assessing-point-estimators} -The most common performance measures used to assess a point estimator are bias, variance, and root mean squared error. -Bias compares the mean of the sampling distribution to the target parameter. +The most common performance measures used to assess a point estimator are **bias**, **variance**, and **root mean squared error**. + +**Bias** compares the mean of the sampling distribution to the target parameter. +It answers, "Are we systematically too high or too low, on average?" Positive bias implies that the estimator tends to systematically over-state the quantity of interest, while negative bias implies that it systematically under-shoots the quantity of interest. If bias is zero (or nearly zero), we say that the estimator is unbiased (or approximately unbiased). -Variance (or its square root, the true standard error) describes the spread of the sampling distribution, or the extent to which it varies around its central tendency. -All else equal, we would like estimators to have low variance (or to be more precise). -Root mean squared error (RMSE) is a conventional measure of the overall accuracy of an estimator, or its average degree of error with respect to the target parameter. + +**Variance** (or its square root, the **true standard error**) describes the spread of the sampling distribution, or the extent to which it varies around its central tendency. +All else equal, we would like estimators to have low variance (which means being more precise). + +**Root mean squared error (RMSE)** is a conventional measure of the overall accuracy of an estimator, or its average degree of error with respect to the target parameter. For absolute assessments of performance, an estimator with low bias, low variance, and thus low RMSE is desired. In making comparisons of several different estimators, one with lower RMSE is usually preferable to one with higher RMSE. If two estimators have comparable RMSE, then the estimator with lower bias would usually be preferable. -To define these quantities more precisely, let us consider a generic estimator $T$ that is targeting a parameter $\theta$. +To define these quantities more precisely, consider a generic estimator $T$ that is targeting a parameter $\theta$. We call the target parameter the _estimand_. -In most cases, in running our simulation we set the estimand $\theta$ and then generate a (typically large) series of $R$ datasets, for each of which $\theta$ is the true target parameter. -We then analyze each dataset, obtaining a sample of estimates $T_1,...,T_R$. -Formally, the bias, variance, and RMSE of $T$ are defined as +In most cases, in running our simulation we set the estimand $\theta$ and then generate a (typically large) series of $R$ datasets, with $\theta$ being the true target parameter for each. +We also analyze each dataset, obtaining a sample of estimates $T_1,...,T_R$. +Formally, the bias, variance, and RMSE of $T$ are then defined as $$ \begin{aligned} \Bias(T) &= \E(T) - \theta, \\ @@ -113,6 +144,10 @@ $$ \end{aligned} (\#eq:bias-variance-RMSE) $$ +In words, bias is the average estimate minus the truth---is it systematically too high or too low, on average? +The variance is the average squared deviation of the estimator from its own mean---how much does it vary around its average estimate? Is it precise? +RMSE is the square root of the average squared deviation of the estimator from the truth---how far off are we, on average, from the truth? Does it predict well? + These three measures are inter-connected. In particular, RMSE is the combination of (squared) bias and variance, as in $$ @@ -134,8 +169,11 @@ $$ S_T^2 = \frac{1}{R - 1}\sum_{r=1}^R \left(T_r - \bar{T}\right)^2. (\#eq:var-estimator) $$ -$S_T$ (the square root of $S^2_T$) is an estimate of the empirical standard error of $T$, or the standard deviation of the estimator across an infinite set of replications of the data-generating process.[^SE-meaning] -We usually prefer to work with the empirical SE $S_T$ rather than the sampling variance $S_T^2$ because the former quantity has the same units as the target parameter. +$S_T$ (the square root of $S^2_T$) is an estimate of the _true_ standard error, $SE$, of $T$, which is the standard deviation of the estimator across an infinite set of replications of the data-generating process. +Generally, when people say "Standard Error" they actually mean _estimated_ Standard Error, ($\widehat{SE}$), as we generally calculate in a real data analysis (where we have only a single realization of the data-generating process). +It is easy to forget that this standard error is itself an estimate of a parameter---the true SE---and thus has its own uncertainty. +We usually prefer to work with the true SE $S_T$ rather than the sampling variance $S_T^2$ because the former quantity has the same units as the target parameter. + Finally, the RMSE estimate can be calculated as $$ \widehat{\RMSE}(T) = \sqrt{\frac{1}{R} \sum_{r = 1}^R \left( T_r - \theta\right)^2 }. @@ -144,29 +182,31 @@ $$ Often, people talk about the MSE (Mean Squared Error), which is just the square of RMSE. Just as the true SE is usually easier to interpret than the sampling variance, units of RMSE are easier to interpret than the units of MSE. -[^SE-meaning]: Generally, when people say "Standard Error" they actually mean _estimated_ Standard Error, ($\widehat{SE}$), as we would calculate in a real data analysis (where we have only a single realization of the data-generating process). It is easy to forget that this standard error is itself an estimate of a parameter--the true or empirical SE---and thus has its own uncertainty. - -It is important to recognize that the above performance measures depend on the scale of the parameter. +The above performance measures depend on the scale of the parameter. For example, if our estimators are measuring a treatment impact in dollars, then the bias, SE, and RMSE of the estimators are all in dollars. (The variance and MSE would be in dollars squared, which is why we take their square roots to put them back on the more intepretable scale of dollars.) In many simulations, the scale of the outcome is an arbitrary feature of the data-generating process, making the absolute magnitude of performance measures less meaningful. -To ease interpretation of performance measures, it is useful to consider their magnitude relative to the baseline level of variation in the outcome. -One way to achieve this is to generate data so the outcome has unit variance (i.e., we generate outcomes in _standardized units_). -Doing so puts the bias, empirical standard error, and root mean squared error on the scale of standard deviation units, which can facilitate interpretation about what constitutes a meaningfully large bias or a meaningful difference in RMSE. +To ease interpretation of performance measures, it is useful to consider their magnitude relative to some reference amount. +We generally recommend using the baseline level of variation in the outcome. +For example, we might report a bias of $0.2\sigma$, where $\sigma$ is the standard deviation of the outcome in the population. -In addition to understanding the scale of these performance measures, it is also important to recognize that their magnitude depends on the metric of the parameter. -A non-linear transformation of a parameter will generally lead to changes in the magnitude of the performance measures. +One way to automatically get all your performance metrics on such a standardized scale is to generate data so the outcome has unit variance (i.e., we generate outcomes in _standardized units_). +This automatically puts the bias, empirical standard error, and root mean squared error on the scale of standard deviation units, which can facilitate interpretation about what constitutes a meaningfully large bias or a meaningful difference in RMSE. + +Finally, a non-linear transformation of a parameter will also generally change a performance measure. For instance, suppose that $\theta$ measures the proportion of time that something occurs. -One natural way to transform this parameter would be to put it on the log-odds (logit) scale. +This parameter could also be given on the log-odds (logit) scale. However, because the log-odds transformation is non-linear, $$ \text{Bias}\left[\text{logit}(T)\right] \neq \text{logit}\left(\text{Bias}[T]\right), \qquad \text{RMSE}\left[\text{logit}(T)\right] \neq \text{logit}\left(\text{RMSE}[T]\right), $$ and so on. + + ### Comparing the Performance of the Cluster RCT Estimation Procedures {#clusterRCTperformance} @@ -175,9 +215,7 @@ runs <- readRDS( file = "results/cluster_RCT_simulation.rds" ) ``` We now demonstrate the calculation of performance measures for the point estimators of average treatment effects in the cluster-RCT example. -In Chapter \@ref(running-the-simulation-process), we generated a large set of replications of several different treatment effect estimators. -Using these results, we can assess the bias, standard error, and RMSE of three different estimators of the ATE. -These performance measures address the following questions: +Our three performance measures address the following questions: - Is the estimator systematically off? (bias) - Is it precise? (standard error) @@ -189,7 +227,7 @@ Let us see how the three estimators compare on these measures. Bias is defined with respect to a target estimand. Here we assess whether our estimates are systematically different from the $\gamma_1$ parameter, which we defined in standardized units by setting the standard deviation of the student-level distribution of the outcome equal to one. -For these data, we generated data based on a school-level ATE parameter of 0.30 SDs. +In our simulation, we generated data with a school-level ATE parameter of 0.30 SDs. ```{r cluster-bias} ATE <- 0.30 @@ -203,9 +241,9 @@ runs %>% ``` There is no indication of major bias for aggregation or multi-level modeling. -Linear regression, with a bias of about 0.09 SDs, appears about ten times as biased as the other estimators. +Linear regression, with a bias of about 0.08 SDs, appears much more biased than the other estimators. This is because the linear regression is targeting the person-level average average treatment effect. -The data-generating process of this simulation makes larger sites have larger effects, so the person-level average effect is going to be higher because those larger sites will count more. +Our data-generating process makes larger sites have larger effects, so the person-level average effect is going to be higher because those larger sites will count more. In contrast, our estimand is the school-level average treatment effect, or the simple average of each school's true impact, which we have set to 0.30. The aggregation and multi-level modeling methods target this school-level average effect. If we had instead decided that the target estimand should be the person-level average effect, then we would find that linear regression is unbiased whereas aggregation and multi-level modeling are biased. @@ -213,9 +251,9 @@ This example illustrates how crucial it is to think carefully about the appropri #### Which method has the smallest standard error? {-} -The empirical standard error measures the degree of variability in a point estimator. -It reflects how stable our estimates are across replications of the data-generating process. -We calculate the standard error by taking the standard deviation of the replications of each estimator. +The standard error measures the degree of variability in a point estimator. +It reflects how stable an estimator is across replications of the data-generating process. +We estimate the standard error by taking the standard deviation of the set of estimates of each estimator. For purposes of interpretation, it is useful to compare the empirical standard errors to the variation in a benchmark estimator. Here, we treat the linear regression estimator as the benchmark and compute the magnitude of the empirical SEs of each method _relative_ to the SE of the linear regression estimator: @@ -230,7 +268,7 @@ true_SE ``` In a real data analysis, these standard errors are what we would be trying to approximate with a standard error estimator. -Aggregation and multi-level modeling have SEs about 8% smaller than linear regression. +Aggregation and multi-level modeling have SEs about 4 to 5% smaller than linear regression, meaning these estimates tend to be a bit less variable across different datasets. For these data-generating conditions, aggregation and multi-level modeling are preferable to linear regression because they are more precise. #### Which method has the smallest Root Mean Squared Error? {-} @@ -257,31 +295,38 @@ RMSE takes into account both bias and variance. For aggregation and multi-level modeling, the RMSE is the same as the standard error, which makes sense because these estimators are not biased. For linear regression, the combination of bias plus increased variability yields a higher RMSE, with the standard error dominating the bias term (note how RMSE and SE are more similar than RMSE and bias). The difference between the estimators are pronounced because RMSE is the square root of the _squared_ bias and _squared_ standard error. -Overall, aggregation and multi-level modeling have RMSEs around 17% smaller than linear regression---a consequential difference in accuracy. +Overall, aggregation and multi-level modeling have RMSEs around 10% smaller than linear regression, meaning they tend to give estimates that are closer to the truth than linear regression. -### Less Conventional Performance Measures {#less-conventional-measures} +### Robust Performance Measures {#less-conventional-measures} -Depending on the model and estimation procedures being examined, a range of different measures might be used to assess estimator performance. -For point estimation, we have introduced bias, variance and RMSE as three core measures of performance. + +For point estimation, we introduced bias, variance and RMSE as three core measures of performance. However, all of these measures are sensitive to outliers in the sampling distribution. -Consider an estimator that generally does well, except for an occasional large mistake. Because conventional measures are based on arithmetic averages, they will indicate that the estimator performs very poorly overall. -Other measures such as the median bias and the median absolute deviation of $T$ are less sensitive to outliers in the sampling distribution compared to the conventional measures. -Estimating these measures will involve calculating sample quantiles of $T_1,...,T_R$, which are functions of the sample ordered from smallest to largest. -We will denote the $r^{th}$ order statistic as $T_{(r)}$ for $r = 1,...,R$. +Consider an estimator that generally does well, except for an occasional large mistake. +Because conventional measures are based on arithmetic averages, they could indicate that the estimator performs very poorly overall, when in fact it performs very well most of the time and terribly only rarely. + +If we are more curious about typical performance, then we could use other measures, such as the __median bias__ and the __median absolute deviation__ of $T$, that are less sensitive to outliers in the sampling distribution. +These are called "robust" measures because they are not massively changed by only a few extreme values. +The overall approach for most robust measures is to simply chop off some percent of the most extreme values, and then look at the center or spread of the remaining values. -Median bias is an alternative measure of the central tendency of a sampling distribution. +For example, median bias is an alternative measure of the central tendency of a sampling distribution. +Here we "chop off" essentially all the values, focusing on the middle one only. Positive median bias implies that more than 50% of the sampling distribution exceeds the quantity of interest, while negative median bias implies that more than 50% of the sampling distribution fall below the quantity of interest. Formally, $$ \text{Median-Bias}(T) = \M(T) - \theta (\#eq:median-bias). $$ -An estimator of median bias is computed using the sample median, as +where $\M(T)$ is the median of $T$. + +We estimate median bias with the sample median, as $$ \widehat{\text{Median-Bias}}(T) = M_T - \theta (\#eq:sample-median-bias) $$ -where $M_T = T_{((R+1)/2)}$ if $R$ is odd or $M_T = \frac{1}{2}\left(T_{(R/2)} + T_{(R/2+1)}\right)$ if $R$ is even. +where, if we define $T_{(r)}$ as the $r^{th}$ order statistic for $r = 1,...,R$, we have $M_T = T_{((R+1)/2)}$ if $R$ is odd or $M_T = \frac{1}{2}\left(T_{(R/2)} + T_{(R/2+1)}\right)$ if $R$ is even. + + Another robust measure of central tendency uses the $p \times 100\%$-trimmed mean, which ignores the estimates in the lowest and highest $p$-quantiles of the sampling distribution. Formally, the trimmed-mean bias is @@ -294,17 +339,17 @@ To estimate the trimmed bias, we take the mean of the middle $1 - 2p$ fraction o $$ \widehat{\text{Trimmed-Bias}}(T; p) = \tilde{T}_{\{p\}} - \theta. (\#eq:sample-trimmed-bias) $$ -where +where (assuming $pR$ is a whole number) $$ \tilde{T}_{\{p\}} = \frac{1}{(1 - 2p)R} \sum_{r=pR + 1}^{(1-p)R} T_{(r)} $$ For a symmetric sampling distribution, trimmed-mean bias will be the same as the conventional (mean) bias, but its estimator $\tilde{T}_{\{p\}}$ will be less affected by outlying values (i.e., values of $T$ very far from the center of the distribution) compared to $\bar{T}$. -However, if a sampling distribution is not symmetric, trimmed-mean bias become distinct performance measures, which put less emphasis on large errors compared to the conventional bias measure. +However, if a sampling distribution is not symmetric, trimmed-mean bias will be a distinct performance measure, different from mean bias, that puts less emphasis on large errors compared to the conventional bias measure. A further robust measure of central tendency is based on winsorizing the sampling distribution, or truncating all errors larger than a certain maximum size. -Using a winsorized distribution amounts to arguing that you don't care about errors beyond a certain size, so anything beyond a certain threshold will be treated the same as if it were exactly on the threshold. -The threshold for truncation is usually defined relative to the first and third quartiles of the sampling distribution, along with a given span of the inter-quartile range. -The thresholds for truncation are taken as +A winsorized distribution amounts to arguing that you don't care about errors beyond a certain size, so anything beyond a certain threshold will be treated the same as if it were exactly on the threshold. +The threshold for truncation is often defined relative to the first and third quartiles of the sampling distribution, along with a given span of the inter-quartile range. +In this case, the thresholds for truncation would be $$ \begin{aligned} L_w &= \Q_{0.25}(T) - w \times (\Q_{0.75}(T) - \Q_{0.25}(T)) \\ @@ -312,7 +357,7 @@ U_w &= \Q_{0.75}(T) + w \times (\Q_{0.75}(T) - \Q_{0.25}(T)), \end{aligned} $$ where $\Q_{0.25}(T)$ and $\Q_{0.75}(T)$ are the first and third quartiles of the distribution of $T$, respectively, and $w$ is the number of inter-quartile ranges below which an observation will be treated as an outlier.[^fences] -Let $X = \min\{\max\{T, L_w\}, U_w\}$. +Once we have our thresholds, we let our truncated estimate be $X = \min\{\max\{T, L_w\}, U_w\}$. The winsorized bias, variance, and RMSE are then defined using winsorized values in place of the raw values of $T$, as $$ \begin{aligned} @@ -340,78 +385,142 @@ The `robustbase` package [@robustbase] provides functions for calculating many o ## Measures for Variance Estimators -Statistics is concerned not only with how to estimate things, but also with understanding the extent of uncertainty in estimates of target parameters. -These concerns apply in Monte Carlo simulation studies as well. -In a simulation, we can simply compute an estimator's actual properties. -When we use an estimator with real data, we need to _estimate_ its associated standard error and generate confidence intervals and other assessments of uncertainty. -To understand if these uncertainty assessments work in practice, we need to evaluate not only the behavior of the estimator itself, but also the behavior of these associated quantities. - -Commonly used measures for quantifying the performance of estimated standard errors include relative bias, relative standard error, and relative root mean squared error. -These measures are defined in relative terms (rather than absolute ones) by comparing their magnitude to the _true_ degree of uncertainty. -Typically, performance measures are computed for _variance_ estimators rather than standard error estimators. -There are a few reasons for working with variance rather than standard error. -First, in practice, so-called unbiased standard errors usually are not actually unbiased.[^Jokes-on-us] +Statistics is concerned not only with how to estimate things (e.g., point estimates), but also with understanding how well we have estimated them (e.g., standard errors). +Monte Carlo simulation studies can help us evaluate both these concerns. +The prior section focused on assessing how well our estimators work. +In this section we focus on assessing how well our uncertainty assessments work. +We focus on the standard error. + +The first order question is whether our estimated standard errors are __calibrated__, meaning they are the right size, on average. +The second order question is whether our estimated standard errors are __stable__, meaning they do not vary too much from one dataset to another. +For this question we can think of the standard errors in terms of effective degrees of freedom, or look at the standard error (or RMSE) of the standard error. + + + + +### Calibration + +Calibration is a relative measure, where we look at the ratio of the expected (average) value of our uncertainty estimator to the true uncertainty. +The relative measure removes scale, which is important because the absolute magnitude of uncertainty will depend on many features of the data-generating process, such as sample size. +In particular, across simulation scenarios, even those with the same target parameter $\theta$, the true standard error of our estimator $T$ might change considerably. +With a relative measure, we will, even under such conditions, end up with statements such as "Our standard errors are 10% too large, on average," which are easy to interpret. + +Typically, we assess performance for _variance_ estimators ($\widehat{SE^2}$) rather than standard error estimators. +There are a few reasons it is more common to work with variance rather than standard error. +First, in practice, so-called unbiased standard errors usually are not actually unbiased, while variance estimators might be.[^Jokes-on-us] For linear regression, for example, the classic standard error estimator is an unbiased _variance_ estimator, but the standard error estimator is not exactly unbiased because $$ \E[ \sqrt{ V } ] \neq \sqrt{ \E[ V ] }. $$ -Variance is also the measure that gives us the bias-variance decomposition of Equation \@ref(eq:RMSE-decomposition). Thus, if we are trying to determine whether MSE is due to instability or systematic bias, operating in this squared space may be preferable. +Variance is also the measure that gives us the bias-variance decomposition of Equation \@ref(eq:RMSE-decomposition). +Thus, if we are trying to determine whether an overall MSE is due to instability or systematic bias, operating in this squared space may be preferable. [^Jokes-on-us]: See the delightfully titled section 11.5, "The Joke Is on Us: The Standard Deviation Estimator is Biased after All," in @westfall2013understanding for further discussion. -To make this concrete, let us consider a generic standard error estimator $\widehat{SE}$ to go along with our generic estimator $T$ of target parameter $\theta$, and let $V = \widehat{SE}^2$. -We can simulate to obtain a large sample of standard errors, $\widehat{SE}_1,...,\widehat{SE}_R$ and variance estimators $V_r = \widehat{SE}_r^2$ for $r = 1,...,R$. -Formally, the relative bias, standard error, and RMSE of $V$ are defined as +To make assessing calibration concrete, consider a generic standard error estimator $\widehat{SE}$ to go along with our generic estimator $T$ of target parameter $\theta$, and let $V = \widehat{SE^2}$ be the corresponding variance estimator. + +In our simulation we obtain a large sample of standard errors, $\widehat{SE}_1,...,\widehat{SE}_R$ and corresponding variance estimators $V_r = \widehat{SE}_r^2$ for $r = 1,...,R$. +Formally, the __relative bias__ or __calibration__ of $V$ is then defined as $$ \begin{aligned} \text{Relative Bias}(V) &= \frac{\E(V)}{\Var(T)} \\ -\text{Relative SE}(V) &= \frac{\Var(V)}{\Var(T)} \\ -\text{Relative RMSE}(V) &= \frac{\sqrt{\E\left[\left(V - \Var(T)\right)^2 \right]}}{\Var(T)}. \end{aligned} (\#eq:relative-bias-SE-RMSE) $$ -In contrast to performance measures for $T$, we define these measures in relative terms because the raw magnitude of $V$ is not a stable or interpretable parameter. +Relative bias describes whether the central tendency of $V$ aligns with the actual degree of uncertainty in the point estimator $T$. +We say our variance estimator $V$ is _calibrated_ if the relative bias is close to one. +When calibrated, $V$ accurately reflects how much uncertainty there actually is, on average. +If relative bias is less than one, $V$ is _anti-conservative_, meaning it tends to under-estimate the true variance of $T$. +This is usually considered quite bad. +If it is more than one, it is _conservative_, meaning it tends to over-estimate the true variance of $T$. +This is usually considered non-ideal, but livable. + +Calibration also has implications for the performance of other uncertainty assessments such as hypothesis tests and confidence intervals. +A relative bias of less than 1 implies that $V$ tends to under-state the amount of uncertainty, which will lead to confidence intervals that are overly narrow and do not cover the true parameter value at the desired rate. +It also will lead to rejecting the null more often than desired, which elevates Type I error. +Relative bias greater than 1 implies that $V$ tends to over-state the amount of uncertainty in the point estimator, making confidence intervals too large and null hypotheses hard to reject. + + + -To estimate these relative performance measures, we proceed by substituting sample quantities in place of the expectations and variances. -In contrast to the performance measures for $T$, we will not generally be able to compute the true degree of uncertainty exactly. -Instead, we must estimate the target quantity $\Var(T)$ using $S_T^2$, the sample variance of $T$ across replications. -Denoting the arithmetic mean of the variance estimates as +To estimate relative bias, simply substitute sample quantities in place of the $\E(V)$ and $\Var(T)$. +Unlike with performance measures for $T$, where we know the target quantity $\theta$, here we do not know $\Var(T)$ exactly, +Instead, we must estimate it using $S_T^2$, the sample variance of $T$ across replications. +Denoting the arithmetic mean of the variance estimates across simulation trials as $$ \bar{V} = \frac{1}{R} \sum_{r=1}^R V_r $$ -and the sample variance as -$$ -S_V^2 = \frac{1}{R - 1}\sum_{r=1}^R \left(V_r - \bar{V}\right)^2, -$$ -we estimate the relative bias, standard error, and RMSE of $V$ using +we estimate the relative bias (calibration) of $V$ using $$ \begin{aligned} -\widehat{\text{Relative Bias}}(V) &= \frac{\bar{V}}{S_T^2} \\ -\widehat{\text{Relative SE}}(V) &= \frac{S_V}{S_T^2} \\ -\widehat{\text{Relative RMSE}}(V) &= \frac{\sqrt{\frac{1}{R}\sum_{r=1}^R\left(V_r - S_T^2\right)^2}}{S_T^2}. +\widehat{\text{Relative Bias}}(V) &= \frac{\bar{V}}{S_T^2} . \\ \end{aligned} (\#eq:relative-bias-SE-RMSE-estimators) $$ -These performance measures are informative about the properties of the uncertainty estimator $V$ (or standard error $\widehat{SE}$), which have implications for the performance of other uncertainty assessments such as hypothesis tests and confidence intervals. +If we then take the square root of our estimate, we can obtain the estimated relative bias of the standard error. + + + + + +### Stability {#performance-stability} + +Beyond calibration, we also care about the stability of our variance estimator. +Are the estimates of uncertainty $V$ close to the true uncertainty $Var(T)$, from dataset to dataset? + +We offer two ways of assessing this. +The first is to look at the relative SE or RMSE of the variance estimator $V$. +The second is to assess the effective "degrees of freedom" of $V$, which takes into account how one would account for uncertainty estimator uncertainty when generating confidence intervals or conducting hypothesis tests (this is what a degrees of freedom correction does---for example, when $V$ is unstable, as represented by a low degree of freedom, we hedge against it being randomly too small by making our confidence intervals systematically larger). + +The relative Variance and MSE of $V$ as an estimate of $Var(T)$ are the following: +$$ +\begin{aligned} +\text{Relative Var}(V) &= \frac{\Var(V)}{\Var(T)} \\ +\text{Relative MSE}(V) &= \frac{\E\left[\left(V - \Var(T)\right)^2 \right]}{\Var(T)}. +\end{aligned} +$$ +As usual, we would generally work with the the square root of these values (to get relative SE and relative RMSE). Relative standard errors describe the variability of $V$ in comparison to the true degree of uncertainty in $T$---the lower the better. -A relative standard error of 0.5 would mean that the variance estimator has average error of 50% of the true uncertainty, implying that $V$ will often be off by a factor of 2 compared to the true sampling variance of $T$. -Ideally, a variance estimator will have small relative bias, small relative standard errors, and thus small relative RMSE. +A relative standard error of 0.5 would mean that the variance estimator has average error of 50% of the true uncertainty, implying that $V$ could often be off by a factor of 2---this would be very bad. +Ideally, a variance estimator will have small relative bias (i.e., it is calibrated), small relative standard error (i.e., it is stable), and thus a small relative RMSE. + +We can estimate the relative variance and MSE simply by plugging in estimates of the various quantities: +$$ +\begin{aligned} +\widehat{\text{Relative Var}}(V) &= \frac{S^2_V}{S_T^2} \\ +\widehat{\text{Relative MSE}}(V) &= \frac{\frac{1}{R}\sum_{r=1}^R\left(V_r - S_T^2\right)^2}{S_T^2}. +\end{aligned} +(\#eq:relative-bias-SE-RMSE-estimators) +$$ +where the sample variance of $V$ is +$$ +S_V^2 = \frac{1}{R - 1}\sum_{r=1}^R \left(V_r - \bar{V}\right)^2, +$$ -### Satterthwaite degrees of freedom Another more abstract measure of the stability of a variance estimator is its Satterthwaite degrees of freedom. -For some simple statistical models such as classical analysis of variance and linear regression with homoskedastic errors, the variance estimator is computed by taking a sum of squares of normally distributed errors. -In such cases, the sampling distribution of the variance estimator is a multiple of a $\chi^2$ distribution, with degrees of freedom corresponding to the number of independent observations used to compute the sum of squares. -In the context of analysis of variance problems, @Satterthwaite1946approximate described a method of approximating the variability of more complex statistics, involving linear combinations of sums of squares, by using a chi-squared distribution with a certain degrees of freedom. -When applied to an arbitrary variance estimator $V$, these degrees of freedom can be interpreted as the number of independent, normally distributed errors going into a sum of squares that would lead to a variance estimator that is equally precise as $V$. +For some simple statistical models such as classical analysis of variance and linear regression with homoskedastic errors, the variance estimator is a sum of squares of normally distributed errors. +In such cases, the sampling distribution of the variance estimator is a multiple of a $\chi^2$ distribution, with degrees of freedom corresponding to the number of independent observations used to compute the sum of squares. +This is what leads to $t$ statistics and so forth. + +In the context of analysis of variance problems, @Satterthwaite1946approximate described a method of extending this idea by approximating the variability of more complex statistics, involving linear combinations of sums of squares, by using a chi-squared distribution with a certain degrees of freedom. + +When applied to an arbitrary variance estimator $V$, these degrees of freedom can be interpreted as the number of independent, normally distributed errors going into a sum of squares that would lead to a variance estimator that is as equally precise as $V$. More succinctly, these degrees of freedom correspond to the amount of independent observations used to estimate $V$. Following @Satterthwaite1946approximate, we define the degrees of freedom of $V$ as @@ -427,9 +536,9 @@ $$ For simple statistical methods in which $V$ is based on a sum-of-squares of normally distributed errors, then the Satterthwaite degrees of freedom will be constant and correspond exactly to the number of independent observations in the sum of squares. Even with more complex methods, the degrees of freedom are interpretable: higher degrees of freedom imply that $V$ is based on more observations, and thus will be a more precise estimate of the actual degree of uncertainty in $T$. -### Assessing SEs for the Cluster RCT Simulation +### Assessing SEs for the Cluster RCT Simulation {#assess-cluster-RCT-SEs} -Returning to the cluster RCT example, we will assess whether our estimated SEs are about right by comparing the average _estimated_ (squared) standard error versus the empirical sampling variance. +Returning to the cluster RCT example, we will assess whether our estimated SEs are about right by comparing the average _estimated_ (squared) standard error to the empirical sampling variance. Our standard errors are _inflated_ if they are systematically larger than they should be, across the simulation runs. We will also look at how stable our variance estimates are by comparing their standard deviation to the empirical sampling variance and by computing the Satterthwaite degrees of freedom. @@ -441,20 +550,21 @@ SE_performance <- summarise( SE_sq = var( ATE_hat ), V_bar = mean( V ), - rel_bias = V_bar / SE_sq, + calib = V_bar / SE_sq, S_V = sd( V ), rel_SE_V = S_V / SE_sq, df = 2 * mean( V )^2 / var( V ) ) -SE_performance +SE_performance %>% + knitr::kable( digits = c(0,3,3,2,3,2,1) ) ``` -The variance estimators for the aggregation estimator and multilevel model estimator appear to be a bit conservative on average, with relative bias of around `r round(SE_performance$rel_bias[1], 2)`, or about `r round(100 * SE_performance$rel_bias[1]) - 100`% higher than the true sampling variance. +The variance estimators all appear to be a bit conservative on average, with relative bias of around `r round(mean(SE_performance$calib), 2)`, or about `r round(100 * mean(SE_performance$calib)) - 100`% higher than the true sampling variance. The column labelled `rel_SE_V` reports how variable the variance estimators are relative to the true sampling variances of the estimators. The column labelled `df` reports the Satterthwaite degrees of freedom of each variance estimator. Both of these measures indicate that the linear regression variance estimator is less stable than the other methods, with around `r round(diff(SE_performance$df[2:1]))` fewer degrees of freedom. -The linear regression method uses a cluster-robust variance estimator, which is known to be a bit unstable [@cameronPractitionerGuideClusterRobust2015]. +The linear regression method uses a cluster-robust variance estimator, which is known to be unstable with few clusters [@cameronPractitionerGuideClusterRobust2015]. Overall, it is a bad day for linear regression. ## Measures for Confidence Intervals @@ -466,19 +576,21 @@ However, with the exception of some simple methods and models, methods for const We typically measure confidence interval performance along two dimensions: __coverage rate__ and __expected width__. Suppose that the confidence interval is for the target parameter $\theta$ and has intended coverage level $\beta$ for $0 < \beta < 1$. Denote the lower and upper end-points of the $\beta$-level confidence interval as $A$ and $B$. -$A$ and $B$ are random quantities---they will differ each time we compute the interval on a different replication of the data-generating process. +$A$ and $B$ are random quantities---they will differ each time we compute the interval on a different dataset. The coverage rate of a $\beta$-level interval estimator is the probability that it covers the true parameter, formally defined as $$ \text{Coverage}(A,B) = \Prob(A \leq \theta \leq B). (\#eq:coverage) $$ For a well-performing interval estimator, $\text{Coverage}$ will at least $\beta$ and, ideally will not exceed $\beta$ by too much. + The expected width of a $\beta$-level interval estimator is the average difference between the upper and lower endpoints, formally defined as $$ \text{Width}(A,B) = \E(B - A). (\#eq:expected-width) $$ -Smaller expected width means that the interval tends to be narrower, on average, and thus more informative about the value of the target parameter. +Smaller expected width means that the interval tends to be narrower, on average, and thus more informative about the value of the target parameter. +Expected width is related to the average estimated standard error, but also includes how much wider we need to make our interval if we have a degree-of-freedom correction. In practice, we approximate the coverage and width of a confidence interval by summarizing across replications of the data-generating process. Let $A_r$ and $B_r$ denote the lower and upper end-points of the confidence interval from simulation replication $r$, and let $W_r = B_r - A_r$, all for $r = 1,...,R$. @@ -499,7 +611,7 @@ For example, a conventional Wald-type confidence interval is centered on a point $$ A = T - c \times \widehat{SE}, \quad B = T + c \times \widehat{SE} $$ -for some critical value $c$ (e.g.,for a normal critical value with a $\beta = 0.95$ confidence level, $c = `r round(qnorm(0.975), 3)`$). +for some critical value $c$ (e.g., for a normal critical value with a $\beta = 0.95$ confidence level, $c = `r round(qnorm(0.975), 3)`$). Because of these connections, confidence interval coverage will often be closely related to the performance of the point estimator and variance estimator. Biased point estimators will tend to have confidence intervals with coverage below the desired level because they are not centered in the right place. Likewise, variance estimators that have relative bias below 1 will tend to produce confidence intervals that are too short, leading to coverage below the desired level. @@ -528,19 +640,20 @@ runs_CIs %>% ) ``` -The coverage rate is close to the desired level of 0.95 for the multilevel model and aggregation estimators, but it is around 5 percentage points too low for linear regression. +The coverage rate is close to the desired level of 0.95 for the multilevel model and aggregation estimators, but it is a bit too low for linear regression. The lower-than-nominal coverage level occurs because of the bias of the linear regression point estimator. The linear regression confidence intervals are also a bit wider than the other methods due to the larger sampling variance of its point estimator and higher variability (lower degrees of freedom) of its standard error estimator. The normal Wald-type confidence intervals we have examined here are based on fairly rough approximations. In practice, we might want to examine more carefully constructed intervals such as ones that use critical values based on $t$ distributions or ones constructed by profile likelihood. Especially in scenarios with a small or moderate number of clusters, such methods might provide better intervals, with coverage closer to the desired confidence level. +In our earlier assessment of the variance estimator (see \@ref(assess-cluster-RCT-SEs)), we also found Linear Regression had lower degrees of freedom, meaning it might have notably wider intervals if they were calculated more carefully. See Exercise \@ref(cluster-RCT-t-confidence-intervals). ## Measures for Inferential Procedures (Hypothesis Tests) {#assessing-inferential-procedures} Hypothesis testing entails first specifying a null hypothesis, such as that there is no difference in average outcomes between two experimental groups. One then collects data and evaluates whether the observed data is compatible with the null hypothesis. -Hypothesis test results are often describes in terms of a $p$-value, which measures how extreme or surprising a feature of the observed data (a test statistic) is relative to what one would expect if the null hypothesis is true. +Hypothesis test results are often described in terms of a $p$-value, which measures how extreme or surprising a feature of the observed data (a test statistic) is relative to what one would expect if the null hypothesis is true. A small $p$-value (such as $p < .05$ or $p < .01$) indicates that the observed data would be unlikely to occur if the null is true, leading the researcher to reject the null hypothesis. Alternately, testing procedures might be formulated by comparing a test statistic to a specified critical value; a test statistic exceeding the critical value would lead the researcher to reject the null. @@ -548,6 +661,7 @@ Hypothesis testing procedures aim to control the level of false positives, corre The level of a testing procedure is often denoted as $\alpha$, and it has become conventional in many fields to conduct tests with a level of $\alpha = .05$.[^significance] Just as in the case of confidence intervals, hypothesis testing procedures can sometimes be developed that will have false positive rates exactly equal to the intended level $\alpha$. However, in many other problems, hypothesis testing procedures involve approximations or assumption violations, so that the actual rate of false positives might deviate from the intended $\alpha$-level. +Knowing the risk of this is important. When we evaluate a hypothesis testing procedure, we are concerned with two primary measures of performance: *validity* and *power*. [^significance]: The convention of using $\alpha = .05$ does not have a strong theoretical rationale. Many scholars have criticized the rote application of this convention and argued for using other $\alpha$ levels. See @Benjamin2017redefine and @Lakens2018justify for spirited arguments about choosing $\alpha$ levels for hypothesis testing. @@ -556,7 +670,7 @@ When we evaluate a hypothesis testing procedure, we are concerned with two prima Validity pertains to whether we erroneously reject a true null more than we should. An $\alpha$-level testing procedure is valid if it has no more than an $\alpha$ chance of rejecting the null, when the null is true. -If we were using the conventional $\alpha = .05$ level, then a valid testing procedure will reject the null in only 50 of 1000 replications of a data-generating process where the null hypothesis actually holds true. +If we were using the conventional $\alpha = .05$ level, then a valid testing procedure will reject the null in only about 50 of 1000 replications of a data-generating process where the null hypothesis actually holds true. To assess validity, we will need to specify a data generating process where the null hypothesis holds (e.g., where there is no difference in average outcomes between experimental groups). We then generate a large series of data sets with a true null, conduct the testing procedure on each dataset and record the $p$-value or critical value, then score whether we reject the null hypothesis. @@ -577,26 +691,38 @@ In other words, we will need to ensure that the null hypothesis is violated (and The process of evaluating the power of a testing procedure is otherwise identical to that for evaluating its validity: generate many datasets, carry out the testing procedure, and track the rate at which the null hypothesis is rejected. The only difference is the _conditions_ under which the data are generated. -We find it useful to think of power as a _function_ rather than as a single quantity because its absolute magnitude will generally depend on the sample size of a dataset and the magnitude of the effect of interest. +We often find it useful to think of power as a _function_ rather than as a single quantity because its absolute magnitude will generally depend on the sample size of a dataset and the magnitude of the effect of interest. Because of this, power evaluations will typically involve examining a _sequence_ of data-generating scenarios with varying sample size or varying effect size. -Further, if our goal is to evaluate several different testing procedures, the absolute power of a procedure will be of less concern than the _relative_ performance of one procedure compared to another. +If we are actually planning a future analysis, we would then look to determine what sample size or effect size would give us 80% power (the traditional target power used for planning in many cases). +See Chapter \@ref(sec:power) for more on power analysis for study planning. + +Separately, if our goal is to compare testing procedures, then absolute power at substantively large effects is often less informative than relative performance near the null. +In this setting, attention naturally shifts to infinitesimal power---that is, how quickly power increases as we move from a null effect to very small alternatives. +Examining infinitesimal power helps identify which tests are most sensitive to small departures from the null in a more standardized way. + + - + + + ### Rejection Rates -When evaluating either validity or power, the main performance measure is the __rejection rate__ of the hypothesis test. Letting $P$ be the p-value from a procedure for testing the null hypothesis that a parameter $\theta = 0$, generated under a data-generating process with parameter $\theta$ (which could in truth be zero or non-zero). The rejection rate is then +When evaluating either validity or power, the main performance measure is the __rejection rate__ of the hypothesis test. +Let $P$ be the $p$-value from a procedure for testing the null hypothesis that a parameter $\theta = 0$. +The rejection rate is then $$ \rho_\alpha(\theta) = \Prob(P < \alpha) (\#eq:rejection-rate) $$ -When data are simulated from a process in which the null hypothesis is true, then the rejection rate is equivalent to the Type-I error rate of the test, which should ideally be near the desired $\alpha$ level. -When the data are simulated from a process in which the null hypothesis is violated, then the rejection rate is equivalent to the power of the test (for the given alternate hypothesis specified in the data-generating process). -Ideally, a testing procedure should have actual Type-I error equal to the nominal level $\alpha$ (this is the definition of validity), but such exact tests are rare. + +When data are simulated from a process in which the null hypothesis is true (i.e., $\theta$ really does equal 0), then the rejection rate is equivalent to the Type-I error rate of the test. +Ideally, a testing procedure should have actual Type-I error exactly equal to the nominal level $\alpha$. +When the data are simulated from a process in which the null hypothesis is violated ($\theta \neq 0$), then the rejection rate is equivalent to the power of the test (for the given scenario defined by the DGP and the alternate hypothesis specified by the value of $\theta$). To estimate the rejection rate of a test, we calculate the proportion of replications where the test rejects the null hypothesis. -Letting $P_1,...,P_R$ be the p-values simulated from $R$ replications of a data-generating process with true parameter $\theta$, we estimate the rejection rate by calculating +Letting $P_1,...,P_R$ be the $p$-values simulated from $R$ replications of a data-generating process with true parameter $\theta$, we estimate the rejection rate by calculating $$ r_\alpha(\theta) = \frac{1}{R} \sum_{r=1}^R I(P_r < \alpha). (\#eq:rejection-rate-estimate) @@ -609,13 +735,18 @@ When simulating from a data-generating process where the null hypothesis holds, Methodologists hold a variety of perspectives on how close the actual Type-I error rate should be in order to qualify as suitable for use in practice. Following a strict statistical definition, a hypothesis testing procedure is said to be __level-$\alpha$__ if its actual Type-I error rate is _always_ less than or equal to $\alpha$, for any specific conditions of a data-generating process. Among a collection of level-$\alpha$ testing procedures, we would prefer the one with highest power. If looking only at null rejection rates, then the test with Type-I error closest to $\alpha$ would usually be preferred. -However, some scholars prefer to use a less stringent criterion, where the Type-I error rate of a testing procedure would be considered acceptable if it is within 50\% of the desired $\alpha$ level. + + + + + ### Inference in the Cluster RCT Simulation -Returning to the cluster RCT simulation, we will evaluate the validity and power of hypothesis tests for the average treatment effect based on each of the three estimation methods. +Returning to the cluster RCT simulation, we evaluate the validity and power of hypothesis tests for the average treatment effect based on each of the three estimation methods. The data used in previous sections of the chapter was simulated under a process with a non-null treatment effect parameter (equal to 0.3 SDs), so the null hypothesis of zero average treatment effect does not hold. Thus, the rejection rates for this scenario correspond to estimates of power. We compute the rejection rate for tests with an $\alpha$ level of $.05$: @@ -628,28 +759,21 @@ runs %>% For this particular scenario, none of the tests have especially high power, and the linear regression estimator apparently has higher power than the aggregation method and the multi-level model. -To make sense of this power pattern, we need to also consider the validity of the testing procedures. -We can do so by re-running the simulation using code we constructed in Chapter \@ref(running-the-simulation-process) using the `simhelpers` package. -To evaluate the Type-I error rate of the tests, we will set the average treatment effect parameter to zero by specifying `ATE = 0`: +To make sense of this power pattern, we should consider the validity of the testing procedures. +We can do so by running a new simulation using the function we wrote in Section \@ref(one-run-reparameterization), but with an average treatment effect of zero (i.e., we make the null hypothesis true), an elevated `size_coef` and `alpha` parameter to induce additional treatment effect heterogeneity, and a larger number of clusters to get more stable estimation: -```{r secret-run-cluster-rct, include=FALSE} -library(simhelpers) -source("case_study_code/gen_cluster_RCT.R") -source("case_study_code/analyze_cluster_RCT.R") -sim_cluster_RCT <- bundle_sim( gen_cluster_RCT, estimate_Tx_Fx, id = "runID" ) +```{r secret-run-null-cluster-rct, include=FALSE} +source("case_study_code/clustered_data_simulation.R") if ( !file.exists("results/cluster_RCT_simulation_validity.rds" )) { tictoc::tic() # Start the clock! - set.seed( 404044 ) - runs_val <- sim_cluster_RCT( - reps = 1000, - J = 20, n_bar = 30, alpha = 0.75, - gamma_1 = 0, gamma_2 = 0.5, - sigma2_u = 0.2, sigma2_e = 0.8 - ) - + set.seed( 4404044 ) + runs_val <- run_CRT_sim( reps = 1000, + n_bar = 30, J = 30, + ATE = 0, ICC = 0.2, + size_coef = 0.75, alpha = 0.75 ) tictoc::toc() saveRDS( runs_val, file = "results/cluster_RCT_simulation_validity.rds" ) @@ -661,39 +785,58 @@ if ( !file.exists("results/cluster_RCT_simulation_validity.rds" )) { ``` ```{r run-cluster-rct, eval=FALSE} -set.seed( 404044 ) -runs_val <- sim_cluster_RCT( - reps = 1000, - J = 20, n_bar = 30, alpha = 0.75, - gamma_1 = 0, gamma_2 = 0.5, - sigma2_u = 0.2, sigma2_e = 0.8 -) +set.seed( 4404044 ) +runs_val <- run_CRT_sim( reps = 1000, + n_bar = 30, J = 30, + ATE = 0, ICC = 0.2, + size_coef = 0.75, alpha = 0.75 ) ``` -Assessing validity involves repeating the exact same rejection rate calculations as we did for power: +Assessing validity involves repeating the exact same rejection rate calculations as we did for power. +We also estimate the bias of the point estimator, since bias can affect the validity of a testing procedure: ```{r demo-calc-validity} runs_val %>% - group_by( estimator ) %>% - summarise( power = mean( p_value <= 0.05 ) ) + group_by( method ) %>% + summarise( bias = mean(ATE_hat), + power = mean( p_value <= 0.05 ) ) %>% + knitr::kable( digits=3 ) ``` -The Type-I error rates of the tests for the aggregation and multi-level modeling approaches are around 5%, as desired. -The test for the linear regression estimator has Type-I error above the specified $\alpha$-level due to the upward bias of the point estimator used in constructing the test. -The elevated rejection rate might be part of the reason that the linear regression test has higher power than the other procedures. -It is not entirely fair to compare the power of these testing procedures, because one of them has Type-I error in excess of the desired level. - + +The aggregation and multi-level modeling approaches both seem to reject a bit below 0.05, at 0.04, while LR is here at 0.10. +The test for the linear regression estimator has an elevated Type-I error, probably driven by the upward bias of the point estimator used in constructing the test (see the bias column). +The elevated rejection rate due to bias might then be part of the reason that the linear regression had higher power than the other procedures in our power example, above. +If so, it is not entirely fair to compare the power of the three testing procedures, because one of them has Type-I error in excess of the desired level. As discussed above, linear regression targets the person-level average treatment effect. -In the scenario we simulated for evaluating validity, the person-level average effect is not zero because we have specified a non-zero impact heterogeneity parameter ($\gamma_2=0.2$), meaning that the school-specific treatment effects vary around 0. -To see if this is why the linear regression test has an inflated Type-I error rate, we could re-run the simulation using settings where both the school-level and person-level average effects are truly zero. +In the scenario we just simulated for evaluating validity, the person-level average effect is not zero even though our cluster-average effect is zero, because we have specified a non-zero impact heterogeneity parameter (`size_coef=0.75`) along with school size variation (`alpha = 0.75`), meaning that the school-specific treatment effects vary around 0. +To see if this is why the linear regression test has an inflated Type-I error rate, we could re-run the simulation using settings where both the school-level and person-level average effects are truly zero by setting `size_coef = 0`. + + ## Relative or Absolute Measures? {#sec-relative-performance} +A __relative measure__ is when you compare a performance measure to the target quantity by taking a ratio. +For example, __relative bias__ is the expected value of an estimator divided by the true parameter value. +As we saw when evaluating variance, above, relative measures can be very powerful, giving statements such as "this estimator's standard errors are 10% too big, on average." +In their best case, they are easy to interpret, since they are unitless. +That said, they also suffer from some notable drawbacks. + +In particular, ratios can be deceiving when the denominator is near zero. +This can be a problem when, for example, examining bias relative to a benchmark estimator. +They can also be problematic when the denominator, i.e. reference value, can take on either negative or positive values. +Finally, if the reference value changes unexpectedly with changes in the simulation context, then relative measures can be misleading. + +We next discuss these issues in more detail, and provide guidance on when to use relative versus absolute performance measures. + +### Performance relative to the target parameter + In considering performance measures for point estimators, we have defined the measures in terms of differences (bias, median bias) and average deviations (variance and RMSE), all of which are on the scale of the target parameter. -In contrast, for evaluating estimated standard errors we have defined measures in relative terms, calculated as _ratios_ of the target quantity rather than as differences. -In the latter case, relative measures are justified because the target quantity (the true degree of uncertainty) is always positive and is usually strongly affected by design parameters of the data-generating process. +In contrast, for evaluating estimated standard errors we have defined measures in relative terms, calculated as _ratios_ of the average estimate to the target quantity, rather than as differences. +In the latter case, relative measures are justified because the target quantity (the true degree of uncertainty) is always positive and is usually strongly affected by design parameters of the data-generating process. Is it ever reasonable to use relative measures for point estimators? If so, how should we decide whether to use relative or absolute measures? -Many published simulation studies have used relative performance measures for evaluating point estimators. For instance, studies might use relative bias or relative RMSE, defined as +Many published simulation studies do use relative performance measures for evaluating point estimators. +For instance, studies might use relative bias or relative RMSE, defined as $$ \begin{aligned} \text{Relative }\Bias(T) &= \frac{\E(T)}{\theta}, \\ @@ -713,15 +856,27 @@ As justification for evaluating bias in relative terms, authors often appeal to However, @hoogland1998RobustnessStudiesCovariance were writing about a very specific context---robustness studies of structural equation modeling techniques---that have parameters of a particular form. In our view, their proposed rule-of-thumb is often generalized far beyond the circumstances where it might be defensible, including to problems where it is clearly arbitrary and inappropriate. -A more principled approach to choosing between absolute and relative measures is to consider how the magnitude of the measure changes across different values of the target parameter $\theta$. -If the estimand of interest is a location parameter, then shifting $\theta$ by 0.1 or by 10.1 would not usually lead to changes in the magnitude of bias, variance, or RMSE. -The relationship between bias and the target parameter might be similar to Scenario A in Figure \@ref(fig:absolute-relative), where bias is roughly constant across a range of different values of $\theta$. +The problem with relative bias, in particular, is when the target estimand is near zero or zero. +Say you have a bias of 0.1 when estimating a parameter with true value of 0.2. +Then the relative bias would be 0.5. +But if the true value were 0.01, then the relative bias is 10. +As the true value gets smaller and smaller, the relative bias will explode. + +Another problem with relative bias is that when estimating a location parameter the location is often fairly arbitrary. +In our Cluster RCT case, for example, the relative bias of our estimate of the ATE would change if we moved the ATE from 0.2 to 0.5, or from 0.2 to 0 (where relative bias would now be entirely undefined). +The absolute bias, however, would stay the same regardless of the ATE. + +A more principled approach to choosing between whether to use absolute and relative measures is to first consider whether the magnitude of the measure changes across different values of the target parameter $\theta$. +If the estimand of interest is a location parameter, then the bias, variance or RMSE of an estimator will likely not change as $\theta$ changes (see Figure \@ref(fig:absolute-relative), left). +Do not use relative measures in this case! + + -Another possibility is that shifting $\theta$ by 0.1 or 10.1 will lead to proportionate changes in the magnitude of bias, variance, or RMSE. -The relationship between bias and the target parameter might be similar to Scenario B in \@ref(fig:absolute-relative), where bias is is roughly a constant multiple of the target parameter $\theta$. -Focusing on relative measures in this scenario is useful because it leads to a simple story: relative bias is always around 1.12 across all values of $\theta$, even though the raw bias varies considerably. -We would usually expect this type of pattern to occur for scale parameters. +If, however, change $\theta$ would lead to proportionate changes in the magnitude of bias, variance, or RMSE, then relative bias may be useful because it could lead to a simple story such as "the estimator is usually estimating around 12% too high," or similar. +This is what is shown at right of Figure \@ref(fig:absolute-relative). +We usually expect this type of pattern to occur for scale parameters, such as standard deviations or, as we saw earlier, standard errors. ```{r absolute-relative} #| fig.width: 8 @@ -731,7 +886,7 @@ We would usually expect this type of pattern to occur for scale parameters. #| fig.cap: "Hypothetical relationships between bias and a target parameter $\\theta$. In Scenario A, bias is unrelated to $\\theta$ and absolute bias is a more appropriate measure. In Scenario B, bias is proportional to $\\theta$ and relative bias is a more appropriate measure." -theta <- seq(-0.8, 0.8, 0.2) +theta <- seq(0, 0.8, 0.2) bias1 <- rnorm(length(theta), mean = 0.06, sd = 0.004) bias2 <- rnorm(length(theta), mean = theta * 0.12, sd = 0.004) type <- rep(c("Scenario A","Scenario B"), each = length(theta)) @@ -750,33 +905,37 @@ ggplot(dat, aes(theta, bias, color = type)) + ``` How do we know which of these scenarios is a better match for a particular problem? -For some estimators and data-generating processes, it may be possible to analyze a problem with statistical theory and examine the how bias or variance would be expected to change as a function of $\theta$. +For some estimators and data-generating processes, it may be possible to use statistical theory to examine the how bias or variance would be expected to change as a function of $\theta$. However, many problems are too complex to be tractable. -Another, much more feasible route is to evaluate performance for _multiple_ values of the target parameter. -As done in many simulation studies, we can simulate sampling distributions and calculate performance measures (in raw terms) for several different values of a parameter, selected so that we can distinguish between constant and multiplicative relationships. -Then, in analyzing the simulation results, we can generate graphs such as those in Figure \@ref(fig:absolute-relative) to understand how performance changes as a function of the target parameter. -If the absolute bias is roughly the same for all values of $\theta$ (as in Scenario A), then it makes sense to report absolute bias as the summary performance criterion. +A generally more feasible route is to evaluate performance for _multiple_ values of the target parameter and then generate a graph such as shown in Figure \@ref(fig:absolute-relative) to understand how performance changes as a function of the target parameter. +If the absolute bias is roughly the same for all values of $\theta$ (as in Scenario A), then use absolute bias. On the other hand, if the bias grows roughly in proportion to $\theta$ (as in Scenario B), then relative bias might be a better summary criterion. +Generally, unless you believe bias must be zero if the parameter $\theta$ is zero, absolute bias is usually the better choice. + ### Performance relative to a benchmark estimator -Another way to define performance measures in relative terms to by taking the ratio of the performance measure for one estimator over the performance measure for a benchmark estimator. -We have already demonstrated this approach in calculating performance measures for the cluster RCT example (Section \@ref(clusterRCTperformance)), where we used the linear regression estimator as the benchmark against which to compare the other estimators. +Another way to define performance measures in relative terms is to take the ratio of the performance measure for one estimator over the performance measure for a benchmark estimator (or some other benchmark quantity). +We have already demonstrated this approach in comparing standard errors and RMSEs for the cluster RCT example (Section \@ref(clusterRCTperformance)), where we used the linear regression estimator as the benchmark. This approach is natural in simulations that involve comparing the performance of multiple estimators and where one of the estimators could be considered the current standard or conventional method. Comparing the performance of one estimator relative to another can be especially useful when examining measures whose magnitude varies drastically across design parameters. -For most statistical methods, we would usually expect precision and accuracy to improve (variance and RMSE to decrease) as sample size increases. -Comparing estimators in terms of _relative_ precision or _relative_ accuracy may make it easier to identify consistent patterns in the simulation results. -For instance, this approach might allow us to summarize findings by saying that "the aggregation estimator has standard errors that are consistently 6-10% smaller than the standard errors of the linear regression estimator." -This is much easier to interpret than saying that "aggregation has standard errors that are around 0.01 smaller than linear regression, on average." -In the latter case, it is very difficult to determine whether a difference of 0.01 is large or small, and focusing on an average difference conceals relevant variation across scenarios involving different sample sizes. +For example, we typically expect precision and accuracy to improve (variance and RMSE to decrease) as sample size increases. +Comparing estimators in terms of _relative_ precision or _relative_ accuracy may then make it easier to identify consistent patterns in the simulation results. +A relative measure might allow us to summarize findings by saying that "the aggregation estimator has standard errors that are consistently 6-10% smaller than the standard errors of the linear regression estimator." +This is much easier to interpret than saying that "aggregation has standard errors that are around 0.01 smaller than linear regression, on average." +In the latter case, it is very difficult to determine whether a difference of 0.01 is large or small. +Furthermore, focusing on an average difference conceals relevant variation across scenarios involving different sample sizes. Comparing performance relative to a benchmark method can be an effective tool, but it also has potential drawbacks. Because these relative performance measures are inherently comparative, higher or lower ratios could either be due to the behavior of the method of interest (the numerator) or due to the behavior of the benchmark method (the denominator). -Ratio comparisons are also less effective for performance measures that are on a constrained scale, such as power. -If we have a power of 0.05, and we improve it to 0.10, we have doubled our power, but if it is 0.10 and we increase to 0.15, we have only increased by 50%. -Ratios can also be very deceiving when the denominator quantity is near zero or when it can take on either negative or positive values; this can be a problem when examining bias relative to a benchmark estimator. -Because of these drawbacks, it is prudent to compute and examine performance measures in absolute terms in addition to examining relative comparisons between methods. +Consider if the benchmark completely falls apart under some circumstance, but the comparison only worsens a slight bit. +The relative measure, focused on the comparison, would appear to be a marked improvement, which could be deceptive. + +Ratio comparisons are also less effective for performance measures, such as power, that are on a constrained scale. +If we have a power of 0.05, and we improve it to 0.10, we have doubled our power, but if it is 0.50 and we increase to 0.55, we have only increased by 10%. +Whether this is misleading or not will depend on context. + ## Estimands Not Represented By a Parameter {#implicit-estimands} @@ -784,18 +943,17 @@ In our Cluster RCT example, we focused on the estimand of the school-level ATE, What if we were instead interested in the person-level average effect? This estimand does not correspond to any input parameter in our data generating process. Instead, it is defined _implicitly_ by a combination of other parameters. -In order to compute performance characteristics such as bias and RMSE, we would need to calculate the parameter based on the inputs of the data-generating processes. -There are at least three possible ways to accomplish this. +In order to compute performance characteristics such as bias and RMSE, we would need to first calculate what the target estimand is based on the inputs of the data-generating processes. +There are at least three possible ways to accomplish this: mathematical theory, generating a massive dataset, or tracking the estimand during simulation. -One way is to use mathematical distribution theory to compute an implied parameter. +**Mathematical theory.** The first way is to use mathematical distribution theory to compute the implied parameter. Our target parameter will be some function of the parameters and random variables in the data-generating process, and it may be possible to evaluate that function algebraically or numerically (i.e., using numerical integration functions such as `integrate()`). This can be a very worthwhile exercise if it provides insights into the relationship between the target parameter and the inputs of the data-generating process. However, this approach requires knowledge of distribution theory, and it can get quite complicated and technical.[^cluster-RCT-estimand] -Other approaches are often feasible and more closely aligned with the tools and techniques of Monte Carlo simulation. -[^cluster-RCT-estimand]: In the cluster-RCT example, the distribution theory is tractable. See Exercise \@ref(cluster-RCT-SPATE) +[^cluster-RCT-estimand]: In the cluster-RCT example, the distribution theory is tractable. See Exercise \@ref(cluster-RCT-SPATE). -An alternative approach is to simply generate a massive dataset---so large that it can stand in for the entire data-generating model---and then simply calculate the target parameter of interest in this massive dataset. In the cluster-RCT example, we can apply this strategy by generating data from a very large number of clusters and then simply calculating the true person-average effect across all generated clusters. +**Massive dataset.** Instead, one can simply generate a massive dataset---one so large that it can stand in for the entire data-generating model---and then simply calculate the target parameter of interest in this massive dataset. In the cluster-RCT example, we can apply this strategy by generating data from a very large number of clusters and then simply calculating the true person-average effect across all generated clusters. If the dataset is big enough, then the uncertainty in this estimate will be negligible compared to the uncertainty in our simulation. We implement this approach as follows, generating a dataset with 100,000 clusters: @@ -804,14 +962,15 @@ dat <- gen_cluster_RCT( n_bar = 30, J = 100000, gamma_1 = 0.3, gamma_2 = 0.5, sigma2_u = 0.20, sigma2_e = 0.80, - alpha = 0.75 + alpha = 0.5 ) + ATE_person <- mean( dat$Yobs[dat$Z==1] ) - mean( dat$Yobs[dat$Z==0] ) -ATE_person ``` -The extremely precise estimate of the person-average effect is `r round( ATE_person, 2)`, which is consistent with what we would expect given the bias we saw earlier for the linear model. +Our extremely precise estimate of the person-average effect is `r round( ATE_person, 3)`, which is consistent with what we would expect given the bias we saw earlier for the linear model. -If we recalculate performance measures for all of our estimators with respect to the `ATE_person` estimand, the bias and RMSE of our estimators will shift but the standard errors will stay the same as in previous performance calculations using the school-level average effect: +If we recalculate performance measures for all of our estimators with respect to the `ATE_person` estimand, the bias and RMSE of our estimators will shift. +The standard errors will stay the same, however. ```{r} performance_person_ATE <- @@ -838,9 +997,10 @@ RMSE_ratio <- For the person-weighted estimand, the aggregation estimator and multilevel model are biased but the linear regression estimator is unbiased. However, the aggregation estimator and multilevel model estimator still have smaller standard errors than the linear regression estimator. RMSE now captures the trade-off between bias and reduced variance. -Overall, aggregation and multilevel modeling have RMSE that is around `r round(100 * (RMSE_ratio - 1))`% larger than linear regression. +Overall, aggregation and multilevel modeling have an RMSE that is around `r round(100 * (RMSE_ratio - 1))`% larger than linear regression. +The greater precision is worth the bias price. -A further approach for calculating `ATE_person` would be to record the true person average effect of the dataset with each simulation iteration, and then average the sample-specific parameters at the end. +**Track during the simulation.** A further approach for calculating `ATE_person` would be to record the true person average effect of the dataset with each simulation iteration, and then average the sample-specific parameters at the end. The overall average of the dataset-specific `ATE_person` parameters corresponds to the population person-level ATE. This approach is equivalent to generating a single massive dataset---we just generate it piece by piece. @@ -872,23 +1032,28 @@ analyze_data = function( dat ) { Now when we run our simulation, we will have a column corresponding to the true person-level average treatment effect for each dataset. We could then take the average of these value across replications to estimate the true person average treatment effect in the population, and then use this as the target parameter for performance calculations. -An estimand not represented by any single input parameter is more difficult to work with than one that corresponds directly to an input parameter. -Still, it is feasible to examine such estimands with a bit of forethought and careful programming. +An estimand not represented by any single input parameter is more difficult to work with than one that corresponds directly to an input parameter. +That said, it might be a more important estimand than ones represented directly by your DGP. +As the above shows, it is quite feasible to examine such estimands with a bit of forethought and careful programming. The key is to be clear about what you are trying to estimate because the performance of an estimator depends critically on the estimand against which it is compared. + + ## Uncertainty in Performance Estimates (the Monte Carlo Standard Error) {#MCSE} -The performance measures we have described are all defined with respect to the sampling distribution of an estimator, or its distribution across an infinite number of replications of the data-generating process. -Of course, simulations will only involve a finite set of replications, based on which we calculate _estimates_ of the performance measures. +The performance measures we have described are all defined in terms of an infinite number of replications of the data-generating process. +Of course, simulations will only involve a finite set of replications, based on which we _estimate_ the measures. These estimates involve some Monte Carlo error because they are based on a limited number of replications. -It is important to understand the extent of Monte Carlo error when interpreting simulation results, so we need methods for asssessing this source of uncertainty. +If we re-ran the simulation (with a different seed), our estimates would change. +We next discuss how to quantify how much they might change. -To account for Monte Carlo error, we can think of our simulation results as a sample from a population. -Each replication is an independent and identically distributed draw from the population of the sampling distribution. -Once we frame the problem in these terms, standard statistical techniques for independent and identically distributed random variables can be applied to calculate standard errors. +To account for Monte Carlo error, we can think of our simulation results as a sample from a population. +Each replication is independent drawn from the population of the sampling distribution. +Once we frame the problem in these terms, we can easily apply standard statistical techniques to calculate standard errors. We call these standard errors Monte Carlo Simulation Errors, or MCSEs. -For most of the performance measures, closed-form expressions are available for calculating MCSEs. -For a few of the measures, we can apply techniques such as the jackknife to calculate reasonable approximations for MCSEs. +For most performance measures, we have closed-form expressions for their MCSEs. +We can estimate MCSEs for the rest via techniques such as the jackknife or bootstrap. + ### Conventional measures for point estimators @@ -904,21 +1069,22 @@ $$ (\#eq:skewness-kurtosis) $$ -[^estimated-MCSEs]: To be precise, the formulas that we give are _estimators_ for the Monte Carlo standard errors of the performance measure estimators. Our presentation does not emphasize this point because the performance measures will usually be estimated using a large number of replications from an independent and identically distributed process, so the distinction between empirical and estimated standard errors will not be consequential. +[^estimated-MCSEs]: To be precise, the formulas that we give are _estimators_ for the Monte Carlo standard errors of the performance measure estimators. Our presentation does not emphasize this point because the performance measures will usually be estimated using a large number of replications from an independent and identically distributed process, so the distinction between empirical and estimated Monte Carlo standard errors will not be consequential. One could write $SE$ and $\widehat{SE}$ to distinguish between the two, but we avoid this notation for clarity and simplicity. See, e.g., -The bias of $T$ is estimated as $\bar{T} - \theta$, so the MCSE for bias is equal the MCSE of $\bar{T}$. It can be estimated as +The bias of $T$ is estimated as $\bar{T} - \theta$, so the MCSE for bias, equal to the MCSE of $\bar{T}$ as $\theta$ is fixed, can be estimated as $$ MCSE\left(\widehat{\Bias}(T)\right) = \sqrt{\frac{S_T^2}{R}}. (\#eq:MCSE-bias) $$ -The sampling variance of $T$ is estimated as $S_T^2$, with MCSE of +The sampling variance of $T$ is estimated as $S_T^2$, with a MCSE of $$ MCSE\left(\widehat{\Var}(T)\right) = S_T^2 \sqrt{\frac{k_T - 1}{R}}. (\#eq:MCSE-var) $$ -The empirical standard error (the square root of the sampling variance) is estimated as $S_T$. Using a delta method approximation[^delta-method], the MCSE of $S_T$ is +The empirical standard error (the square root of the sampling variance) is estimated as $S_T$. +Using a delta method approximation,[^delta-method] the MCSE of $S_T$ is approximately $$ -MCSE\left(S_T\right) = \frac{S_T}{2}\sqrt{\frac{k_T - 1}{R}}. +MCSE\left(S_T\right) \approx \frac{S_T}{2}\sqrt{\frac{k_T - 1}{R}}. (\#eq:MCSE-SE) $$ @@ -928,7 +1094,7 @@ where $g'(\phi)$ is the derivative of $g(\cdot)$ evaluated at $\phi$. Following this approximation, $$ SE( g(X) ) \approx \left| g'(\theta) \right| \times SE(X) .$$ For estimation, we plug in $\hat{\theta}$ and our estimate of $SE(X)$ into the above. -To find the MCSE for $S_T$, we can apply the delta method approximation to $X = S_T^2$ with $g(x) = \sqrt(x)$ and $g'(x) =\frac{1}{2\sqrt{x}}$. +To find the MCSE for $S_T$, we can apply the delta method approximation to $X = S_T^2$ with $g(x) = \sqrt(x)$ and $g'(x) =\frac{1}{2\sqrt{x}}$. See [ths blog post](https://jepusto.com/posts/Multivariate-delta-method/index.html) for a friendly introduction. We estimate RMSE using Equation \@ref(eq:rmse-estimator), which can also be written as $$ @@ -946,7 +1112,7 @@ MCSE( \widehat{RMSE} ) = \frac{\sqrt{\frac{1}{R}\left[S_T^4 (k_T - 1) + 4 S_T^3 $$ Section \@ref(sec-relative-performance) discussed circumstances where we might prefer to calculate performance measures in relative rather than absolute terms. -For measures that are calculated by dividing a raw measure by the target parameter, the MCSE for the relative measure is simply the MCSE for the raw measure divided by the target parameter. +For measures that are calculated by dividing a raw measure by the known target parameter, the MCSE for the relative measure is simply the MCSE for the raw measure divided by the target parameter. For instance, the MCSE of relative bias $\bar{T} / \theta$ is $$ MCSE\left( \frac{\bar{T}}{\theta} \right) = \frac{1}{\theta} MCSE(\bar{T}) = \frac{S_T}{\theta \sqrt{R}}. @@ -954,7 +1120,7 @@ MCSE\left( \frac{\bar{T}}{\theta} \right) = \frac{1}{\theta} MCSE(\bar{T}) = \fr $$ MCSEs for relative variance and relative RMSE follow similarly. -### Less conventional measures for point estimators +### MCSEs for robust measures for point estimators In Section \@ref(less-conventional-measures) we described several alternative performance measures for evaluating point estimators, which are less commonly used but are more robust to outliers compared to measures such as bias and variance. MCSEs for these less conventional measures can be obtained using results from the theory of robust statistics [@Hettmansperger2010robust; @Maronna2006robust]. @@ -974,19 +1140,56 @@ $$ MCSE\left(\tilde{T}_{\{p\}}\right) = \sqrt{\frac{U_p}{R}}, (\#eq:MCSE-trimmed-mean) $$ -where +where, taking from [@Maronna2006robust, Eq. 2.85], $$ -U_p = \frac{1}{(1 - 2p)R}\left( pR\left(T_{(pR)} - \tilde{T}_{\{p\}}\right)^2 + pR\left(T_{((1-p)R + 1)} - \tilde{T}_{\{p\}}\right)^2 + \sum_{r=pR + 1}^{(1 - p)R} \left(T_{(r)} - \tilde{T}_{\{p\}}\right)^2 \right) +U_p = \frac{1}{(1 - 2p)R}\left( pR\left(T_{(pR)} - \tilde{T}_{\{p\}}\right)^2 + pR\left(T_{((1-p)R + 1)} - \tilde{T}_{\{p\}}\right)^2 + \sum_{r=pR + 1}^{(1 - p)R} \left(T_{(r)} - \tilde{T}_{\{p\}}\right)^2 \right) . $$ -[@Maronna2006robust, Eq. 2.85]. +The additional uncertainty due to the thresholds is ignorable Performance measures based on winsorization include winsorized bias, winsorized standard error, and winsorized RMSE. MCSEs for these measures can be computed using the same formuals as for the conventional measures of bias, empirical standard error, and RMSE, but using sample moments of $\hat{X}_r$ in place of the sample moments of $T_r$. -### MCSE for Relative Variance Estimators {#MCSE-for-relative-variance} + + + +### MCSE for Confidence Intervals and Hypothesis Tests + +Performance measures for confidence intervals and hypothesis tests are simple compared to those we have described for point and variance estimators. +For evaluating hypothesis tests, the main measure is the rejection rate of the test, which is a proportion estimated as $r_\alpha$ (Equation \@ref(eq:rejection-rate-estimate)). +An estimated MCSE for the estimated rejection rate is +$$ +MCSE(r_\alpha) = \sqrt{\frac{r_\alpha ( 1 - r_\alpha)}{R}}. +(\#eq:MCSE-rejection-rate) +$$ +This MCSE uses the estimated rejection rate to approximate its Monte Carlo error. +When evaluating the validity of a test, we may expect the rejection rate to be fairly close to the nominal $\alpha$ level, in which case we could compute a MCSE using $\alpha$ in place of $r_\alpha$, taking $\sqrt{\alpha(1 - \alpha) / R}$. +When evaluating power, we will not usually know the neighborhood of the rejection rate in advance of the simulation. +However, a conservative upper bound on the MCSE can be derived by observing that MCSE is maximized when $\rho_\alpha = \frac{1}{2}$, and so +$$ +MCSE(r_\alpha) \leq \sqrt{\frac{1}{4 R}}. +$$ + +When evaluating confidence interval performance, we focus on coverage rates and expected widths. +MCSEs for the estimated coverage rate work similarly to those for rejection rates. +If the coverage rate is expected to be in the neighborhood of the intended coverage level $\beta$, then we can approximate the MCSE as +$$ +MCSE(\widehat{\text{Coverage}}(A,B)) = \sqrt{\frac{\beta(1 - \beta)}{R}}. +(\#eq:MCSE-coverage) +$$ +Alternately, Equation \@ref(eq:MCSE-coverage) could be computed using the estimated coverage rate $\widehat{\text{Coverage}}(A,B)$ in place of $\beta$. + +Finally, the expected confidence interval width can be estimated as $\bar{W}$, with MCSE +$$ +MCSE(\bar{W}) = \sqrt{\frac{S_W^2}{R}}, +(\#eq:MCSE-width) +$$ +where $S_W^2$ is the sample variance of $W_1,...,W_R$, the widths of the confidence interval from each replication. + + +### Using the Jackknife to obtain MCSEs (for relative variance estimators) {#MCSE-for-relative-variance} Estimating the MCSE of relative performance measures for variance estimators is complicated by the appearance of an estimated quantity in the denominator of the ratio. -For instance, the relative bias of $V$ is estimates as the ratio $\bar{V} / S_T^2$, and both the numerator and denominator are estimated quantities that will include some Monte Carlo error. +For instance, the relative bias of $V$ is estimated as the ratio $\bar{V} / S_T^2$, and both the numerator and denominator are estimated quantities that will include some Monte Carlo error. To properly account for the Monte Carlo uncertainty of the ratio, one possibility is to use formulas for the standard errors of ratio estimators. Alternately, we can use general uncertainty approximation techniques such as the jackknife or bootstrap [@boos2015Assessing]. The jackknife involves calculating a statistic of interest repeatedly, each time excluding one observation from the calculation. @@ -994,7 +1197,7 @@ The variance of this set of one-left-out statistics then serves as a reasonable To apply the jackknife to assess MCSEs of relative bias or relative RMSE of a variance estimator, we will need to compute several statistics repeatedly. Let $\bar{V}_{(j)}$ and $S_{T(j)}^2$ be the average variance estimate and the empirical variance estimate calculated from the set of replicates __*that excludes replicate $j$*__, for $j = 1,...,R$. -The relative bias estimate, excluding replicate $j$ would then be $\bar{V}_{(j)} / S_{T(j)}^2$. +The relative bias estimate, excluding replicate $j$, would then be $\bar{V}_{(j)} / S_{T(j)}^2$. Calculating all $R$ versions of this relative bias estimate and taking the variance of these $R$ versions yields a jackknife MCSE: $$ MCSE\left( \frac{ \bar{V}}{S_T^2} \right) = \sqrt{\frac{1}{R} \sum_{j=1}^R \left(\frac{\bar{V}_{(j)}}{S_{T(j)}^2} - \frac{\bar{V}}{S_T^2}\right)^2}. @@ -1034,42 +1237,84 @@ Instead, all we need to do is calculate the overall mean and overall variance, a Jackknife methods are useful for approximating MCSEs of other performance measures beyond just those for variance estimators. For instance, the jackknife is a convenient alternative for computing the MCSE of the empirical standard error or (raw) RMSE of a point estimator, which avoids the need to compute skewness or kurtosis. -However, @boos2015Assessing notes that the jackknife does not work for performance measures involving medians, although bootstrapping remains valid. +However, @boos2015Assessing notes that the jackknife does not work for performance measures involving percentiles, including medians, although bootstrapping (discussed next) usually remains valid. -### MCSE for Confidence Intervals and Hypothesis Tests +### Using bootstrap for MCSEs for relative performance measures -Performance measures for confidence intervals and hypothesis tests are simple compared to those we have described for point and variance estimators. -For evaluating hypothesis tests, the main measure is the rejection rate of the test, which is a proportion estimated as $r_\alpha$ (Equation \@ref(eq:rejection-rate-estimate)). -A MCSE for the estimated rejection rate is -$$ -MCSE(r_\alpha) = \sqrt{\frac{r_\alpha ( 1 - r_\alpha)}{R}}. -(\#eq:MCSE-rejection-rate) -$$ -This MCSE uses the estimated rejection rate to approximate its Monte Carlo error. -When evaluating the validity of a test, we may expect the rejection rate to be fairly close to the nominal $\alpha$ level, in which case we could compute a MCSE using $\alpha$ in place of $r_\alpha$, taking $\sqrt{\alpha(1 - \alpha) / R}$. -When evaluating power, we will not usually know the neighborhood of the rejection rate in advance of the simulation. -However, a conservative upper bound on the MCSE can be derived by observing that MCSE is maximized when $\rho_\alpha = \frac{1}{2}$, and so -$$ -MCSE(r_\alpha) \leq \sqrt{\frac{1}{4 R}}. -$$ +An alternative to the jackknife for estimating MCSEs is the bootstrap [@efron1994introduction]. +The bootstrap involves repeatedly resampling the set of simulation replications with replacement, calculating the performance measure of interest for each resample, and then calculating the standard deviation of the performance measures across the resamples. -When evaluating confidence interval performance, we focus on coverage rates and expected widths. -MCSEs for the estimated coverage rate work similarly to those for rejection rates. -If the coverage rate is expected to be in the neighborhood of the intended coverage level $\beta$, then we can approximate the MCSE as -$$ -MCSE(\widehat{\text{Coverage}}(A,B)) = \sqrt{\frac{\beta(1 - \beta)}{R}}. -(\#eq:MCSE-coverage) -$$ -Alternately, Equation \@ref(eq:MCSE-coverage) could be computed using the estimated coverage rate $\widehat{\text{Coverage}}(A,B)$ in place of $\beta$. +To illustrate, we next calculate a bootstrap MCSE for two quantities: the relative improvement in variance for Aggregation vs. Linear Regression, and the relative bias of Aggregation's variance estimator (how well calibrated it is). -Finally, the expected confidence interval width can be estimated as $\bar{W}$, with MCSE -$$ -MCSE(\bar{W}) = \sqrt{\frac{S_W^2}{R}}, -(\#eq:MCSE-width) -$$ -where $S_W^2$ is the sample variance of $W_1,...,W_R$, the widths of the confidence interval from each replication. +We first calculate these performance measures for quick reference and for making confidence intervals after we bootstrap: -### Calculating MCSEs With the `simhelpers` Package +```{r} +ests <- runs %>% + group_by( method ) %>% + summarise( + SE2 = var( ATE_hat ), + Vbar = mean( SE_hat^2 ) + ) %>% + mutate( calib = Vbar / SE2, + imp_var = SE2 / SE2[method=="LR"] ) +ests +``` +As before, we see Aggregation has a variance around 9% smaller than LR, and that its variance estimator is inflated by around 13%. +Let's make bootstrap confidence intervals on these two quantities to account for Monte Carlo error in our simulation. + +We first make our data wide format to ease bootstrapping: +```{r} +runW <- runs %>% + dplyr::select( runID, method, SE_hat, ATE_hat ) %>% + rename( S=SE_hat, A=ATE_hat ) %>% + tidyr::pivot_wider( names_from = method, + values_from = c( S, A ) ) +print( runW, n = 4 ) +``` + +We make the data wide because we want to bootstrap simulation trials, which in the long form are groups of 3 rows each. +We want to resample the _simulation iteration_ (the sets of three estimates that go together) to take within-dataset correlation of the model estimates into account. +By going wide, we can just bootstrap the rows, as so: + +```{r, cache=TRUE} +rps <- repeat_and_stack( 1000, { + run_star = sample_n( runW, size = nrow(runW), replace = TRUE ) + tibble( + cal_agg = mean( run_star$S_Agg^2 ) / var( run_star$A_Agg ), + rel_imp_var = var( run_star$A_Agg ) / var( run_star$A_LR ) + ) +}) +``` + +For simplicity, we are only looking at the aggregated estimator---we could extend our code to bootstrap for everything. +Regardless, once we have our 1000 bootstrap iterations, we see how much our performance measures change across iteration: + +```{r} +rps %>% + pivot_longer( everything(), names_to = "measure", values_to = "value" ) %>% + group_by( measure ) %>% + summarise( + avg = mean( value ), + MCSE = sd( value ) ) %>% + mutate( theta = c( ests$calib[[1]], ests$imp_var[[1]] ), + CI_l = theta - 2*MCSE, + CI_u = theta + 2*MCSE + ) %>% + relocate( measure, theta ) %>% + knitr::kable( digits = 3 ) +``` +We see two results: +First, Aggregation has a lower variance than linear regression, with the upper end of the confidence interval being 97%. +Second, we have evidence that the Aggregation variance estimator is systematically too high, with the lower end of the confidence interval being above 1 (but only just). +If we had run fewer bootstrap iterations, we may well not have been able to make these claims with certainty. + + +The bootstrap is a very general tool. +You can calculate MCSE similarly for nearly any performance measures you can come up with. + + + +## Performance Calculations with the `simhelpers` Package The `simhelpers` package provides several functions for calculating most of the performance measures that we have reviewed, along with MCSEs for each performance measures. The functions are easy to use. @@ -1134,12 +1379,10 @@ all_rejection_rates %>% - - -### MCSE Calculation in our Cluster RCT Example +### Quick Performance Calculations for our Cluster RCT Example In Section \@ref(clusterRCTperformance), we computed performance measures for three point estimators of the school-level average treatment effect in a cluster RCT. -We can carry out the same calculations using the `calc_absolute()` function from `simhelpers`, which also provides MCSEs for each measure. +We can carry out the same calculations using the `calc_absolute()` function from `simhelpers`, which also provides MCSEs. Examining the MCSEs is useful to ensure that 1000 replications of the simulation is suffiicent to provide reasonably precise estimates of the performance measures. In particular, we have: @@ -1156,14 +1399,60 @@ runs %>% ) ``` -We see the MCSEs are quite small relative to the linear regression bias term and all the SEs (`stddev`) and RMSEs. Results based on 1000 replications seems adequate to support our conclusions about the gross trends identified. +We see the MCSEs are quite small relative to the linear regression bias term and all the SEs (`stddev`) and RMSEs. +Results based on 1000 replications seems adequate to support our conclusions about the gross trends identified. We have _not_ simulated enough to rule out the possibility that the aggregation estimator and multilevel modeling estimator could be slightly biased. Given our MCSEs, they could have true bias of as much as 0.01 (two MCSEs). -## Summary of Peformance Measures +For our variance estimators, we can use the `calc_variance()` function to compute performance measures and MCSEs using the jackknife: + +```{r cluster-variance-MCSE-calculation} +perf <- runs %>% + group_by(method) %>% + summarise( + calc_relative_var( + estimates = ATE_hat, + var_estimates = SE_hat^2, + criteria = c("relative bias", "relative rmse") + ) + ) +perf %>% + dplyr::select( -K_relvar ) %>% + knitr::kable( digits = 2 ) +``` +Comparing our calibration results to those we got from the bootstrap, above, we can use our performance table to make confidence intervals as so: +```{r} +perf %>% + dplyr:: select( method, rel_bias_var, rel_bias_var_mcse ) %>% + mutate( CI_l = rel_bias_var - 2 * rel_bias_var_mcse, + CI_u = rel_bias_var + 2 * rel_bias_var_mcse ) %>% + knitr::kable( digits = 2 ) +``` +We get essentially the same results! - -We list most of the performance criteria we saw in this chapter in the table below, for reference: +## Concluding thoughts + +The performance of an estimator is not usually any single number. +As we saw above, there are many different qualities a given estimator can have, bias and precision being just two of them. +We list the main ones we discussed on the table below. +Furthermore, many data analysis procedures produce multiple pieces of information---not just point estimates, but also standard errors and confidence intervals and $p$-values from null hypothesis tests---and those pieces are inter-related. +For instance, a confidence interval is usually computed from a point estimate and its standard error. +Consequently, the performance of that confidence interval will be strongly affected by whether the point estimator is biased and whether the standard error tends to understates or over-states the true uncertainty. +Likewise, the performance of a hypothesis testing procedure will often strongly depend on the properties of the point estimator and standard error used to compute the test. +Thus, to understand "performance," most simulations will involve evaluating a data analysis procedure on several measures to arrive at a holistic understanding of its performance. + +Moreover, the main aim of many simulations is to compare the performance of several different estimators or to determine which of several data analysis procedures is preferable. +For such aims, we will need to use a suite of performance measures to understand how different procedures work differently, when and how one is superior to the other, and what factors influence differences in performance. + +Finally, we will actually need to assess how performance _changes_ in response to different conditions as given by the DGP. +In the next chapters we talk about how to expand a simulation from a single scenario to multiple scenarios. +Once we do this, we will then begin to graph how performance changes as a function of the DGP conditions, which will help us truly understand when and why different data analysis procedures work well or poorly. + + +### Summary of Peformance Measures + + + | Criterion | Definition | Estimator | Monte Carlo Standard Error | |-------------------------|---------------------------------------------------------|----------------------|----------------------------| @@ -1187,17 +1476,6 @@ We list most of the performance criteria we saw in this chapter in the table bel * The median absolute deviation (MAD) is another measure of overall accuracy that is less sensitive to outlier estimates. The RMSE can be driven up by a single bad egg. The MAD is less sensitive to this. -## Concluding thoughts - -In practice, many data analysis procedures produce multiple pieces of information---not just point estimates, but also standard errors and confidence intervals and p-values from null hypothesis tests---and those pieces are inter-related. -For instance, a confidence interval is usually computed from a point estimate and its standard error. -Consequently, the performance of that confidence interval will be strongly affected by whether the point estimator is biased and whether the standard error tends to understates or over-states the true uncertainty. -Likewise, the performance of a hypothesis testing procedure will often strongly depend on the properties of the point estimator and standard error used to compute the test. -Thus, most simulations will involve evaluating a data analysis procedure on several measures to arrive at a holistic understanding of its performance. - -Moreover, the main aim of many simulations is to compare the performance of several different estimators or to determine which of several data analysis procedures is preferable. -For such aims, we will need to use the performance measures to understand whether a set of procedures work differently, when and how one is superior to the other, and what factors influence differences in performance. -To fully understand the advantages and trade-offs among a set of estimators, we will generally need to compare them using several performance measures. ## Exercises @@ -1308,16 +1586,14 @@ How do the normal Wald-type intervals compare to the cluster-robust intervals? ### Jackknife calculation of MCSEs for RMSE {#jackknife-MCSE} -The following code generates 100 replications of a simulation of three average treatment effect estimators in a cluster RCT, using a simulation driver function we developed in Section \@ref(bundle-sim-demo) using components described in Sections \@ref(case-cluster) and \@ref(multiple-estimation-procedures). +The following code generates 100 replications of a simulation of three average treatment effect estimators in a cluster RCT, using a simulation driver function we developed in Section \@ref(one-run-reparameterization) using components described in Sections \@ref(case-cluster) and \@ref(multiple-estimation-procedures). ```{r, eval = FALSE} set.seed( 20251029 ) -runs_val <- sim_cluster_RCT( +runs_val <- run_RCT_sim( reps = 100, J = 16, n_bar = 20, alpha = 0.5, - gamma_1 = 0.3, gamma_2 = 0.8, - sigma2_u = 0.25, sigma2_e = 0.75 -) + ATE = 0.3, ICC = 0.2 ) ``` Compute the RMSE of each estimator, and use the jackknife technique described in Section \@ref(MCSE-for-relative-variance) to compute a MCSE for the RMSE. diff --git a/070-experimental-design.Rmd b/070-experimental-design.Rmd index 3320ca3..1c4eea9 100644 --- a/070-experimental-design.Rmd +++ b/070-experimental-design.Rmd @@ -201,7 +201,6 @@ saveRDS( res, file = "results/simulation_CRT.rds" ) ```{r secret_run_full_CRT, include=FALSE} if ( !file.exists( "results/simulation_CRT.rds" ) ) { - source( here::here( "case_study_code/clustered_data_simulation_runner.R" ) ) } else { res = readRDS("results/simulation_CRT.rds") @@ -266,9 +265,38 @@ sres <- glimpse( sres ) ``` - +Either way, we now have a lot of results to wade through. +After we calculate our performance measures, we have 810 rows of results across 270 different scenarios. +We can simply aggregate across everything to get overall comparisons: + +```{r} +sres %>% + group_by( method ) %>% + summarise( mean_bias = mean( bias ), + mean_SE = mean( SE ), + mean_rmse = mean( rmse ) ) +``` + +Even with this very crude summary of the results, we see tantalizing hints of differences between the methods. +Linear Regression does seem biased, on average, across the scenarios considered. +But so does multilevel modeling---we did not see bias before, but apparently for some scenarios it is biased as well. +Overall SE and RMSE seems roughly the same across scenarios, and it is clear that uncertainty trumps bias, at least on average. +However, this pattern could be driven by the scenarios with few clusters that are small in size. +In order to understand the full story of what is going on, we need to dig further into the results. + +## Conclusions + +In this chapter, we have moved from isolated simulation scenarios to fully specified multifactor simulation designs. +By systematically varying multiple features of a data-generating process while holding others fixed, we can explore how the performance of an estimator depends on the context in which it is used. +By thinking of simulations as designed experiments, we gain a principled framework for choosing parameters and curating a set of scenarios to explore. +The result is a rich collection of simulation output that can capture bias, variability, uncertainty estimation, or testing behavior across a wide range of plausible conditions. + +However, the volume and complexity of systematic simulation results also create new challenges for interpretation. +With many factors, levels, and performance measures, it is no longer possible to understand results simply by inspecting a table of results. +In the next few chapters, we therefore turn to the problem of analyzing and presenting simulation results, with an emphasis on graphical approaches that clarify how performance varies across conditions. +Through further analysis, we will seek to identify systematic trends in estimator performance, understand the generality of identified patterns, and identify trade-offs between different methods. + - diff --git a/074-building-good-vizualizations.Rmd b/074-building-good-vizualizations.Rmd index bc98404..4ea9abb 100644 --- a/074-building-good-vizualizations.Rmd +++ b/074-building-good-vizualizations.Rmd @@ -117,7 +117,7 @@ We connect the points with lines to help us see trends within each of the small The lines help us visually track which group of points goes with which. We immediately see that when there is a lot of site variation (`alpha = 0.80`), and it relates to outcome (`size_coef=0.2`), linear regression is very different from the other two methods. -We also see that when `alpha` is 0 and `size_coef` is 0, we may also have a negative bias when $J = 5`. +We also see that when `alpha` is 0 and `size_coef` is 0, we may also have a negative bias when $J = 5$. Before we get too excited about this surprising result, we add MCSEs to our plot to see if this is a real effect or just noise: ```{r} @@ -137,9 +137,9 @@ ggplot( sres_sub, aes( as.factor(J), bias, Our confidence intervals exclude zero! Our excitement mounts. We next subset our overall results again to check all the scenarios with `alpha = 0`, and `size_coef = 0` to see if this is a real effect. -We can still plot all our data, as for that subset of scenarios we still only have three factors, `ICC`, `J_bar`, and `n_bar`, left to plot. +We can still plot all our data, as for that subset of scenarios we still only have three factors, `ICC`, `J_bar`, and `n_bar`, left to plot (we omit the code as it is similar to above). -```{r} +```{r, echo=FALSE} null_sub <- sres %>% dplyr::filter( alpha == 0, size_coef == 0 ) ggplot( null_sub, aes( ICC, bias, @@ -186,14 +186,14 @@ If the boxes are wide, then we know that the factors that vary within the box ma With bundling, we generally need a good number of simulation runs per scenario, so that the MCSE in the performance measures does not make our boxplots look substantially more variable (wider) than the truth. Consider a case where all the scenarios within a box have zero _true_ bias; if the MCSE were large, the _estimated_ biases would still vary and we would see a wide boxplot when we should not. -To illustrate bundling, we replicate our small subset figure from above, but instead of each point (with a given `J', `alpha`, and `size_coef`) just being the single scenario with `n_bar=80` and `ICC = 0.20`, we plot all the scenarios in a boxplot at that location. +To illustrate bundling, we replicate our small subset figure from above, but instead of each point (with a given `J`, `alpha`, and `size_coef`) just being the single scenario with `n_bar=80` and `ICC = 0.20`, we plot all the scenarios (across the `n_bar` and `ICC` values) in a boxplot at that location. We put the boxes for the three methods side-by-side to directly compare them: ```{r clusterRCT_plot_bias_v1} ggplot( sres, aes( as.factor(J), bias, col=method, group=paste0(method, J) ) ) + facet_grid( size_coef ~ alpha, labeller = label_both ) + - geom_boxplot( coef = Inf, width=0.7, fill="grey" ) + + geom_boxplot( width=0.7, fill="grey", outlier.size = 0.5 ) + geom_hline( yintercept = 0 ) + theme_minimal() @@ -216,8 +216,8 @@ ggplot( sres, aes( as.factor(ICC), bias, col=as.factor(alpha), group=paste0(ICC, --> All of our simulation trials are represented in this plot. -Each box is a collection of simulation trials. E.g., for `J = 5`, `size_coef = 0`, and `alpha = 0.8` each of the three boxes contains 15 scenarios representing the varying ICC and cluster size. -Here are the 15 results in the top right box for the Aggregation method: +Each box is a collection of trials. E.g., for `J = 5`, `size_coef = 0`, and `alpha = 0.8` each of the three boxes contains 15 scenarios representing the varying ICC and cluster size. +Here are the 15 results in the `J = 5` box in the top right facet for the Aggregation method: ```{r} filter( sres, J == 5, @@ -238,24 +238,25 @@ The apparent outliers (long tails) for some of the boxplots suggest that the two They could also be due to MCSE, and given that we primariy see these tails when $J$ is small, this is a real concern. MCSE aside, a long tail means that some scenario in the box had a high level of estimated bias. We could try bundling along different aspects to see if either of the remaining factors (e.g., ICC) explains these differences. -Here we try bundling cluster size and number of clusters. +Here we try bundling cluster size and number of clusters (we again omit the code). -```{r clusterRCT_plot_bias_v2} +```{r clusterRCT_plot_bias_v2, echo=FALSE} ggplot( sres, aes( as.factor(alpha), bias, col=method, group=paste0(method, alpha) ) ) + facet_grid( size_coef ~ ICC, labeller = label_both ) + - geom_boxplot( coef = Inf, width=0.7, fill="grey" ) + + geom_boxplot( width=0.7, fill="grey", outlier.size=0.5 ) + geom_hline( yintercept = 0 ) + theme_minimal() ``` -We have some progress now: the long tails are primarily when the ICC is high, but we also see that MLM has bias with ICC is 0, if alpha is nonzero. +We have some progress now: the long tails are primarily when the ICC is high, but we also see that MLM has bias when the ICC is 0, if alpha is nonzero. -We know things are more unstable in smaller samples sizes, so the tails could still be MCSE, with some of our bias estimates being large due to random chance. +Estimates of bias will be more unstable in smaller samples sizes, because the estimators themselves are more unstable (recall the MCSE of bias is $SE/\sqrt{R}$, with $R$ the number of trials and $SE$ is the true standard error of the estimator). +Because of this instability, the tails could still be MCSE, with some of our bias estimates being large due to random chance. Or perhaps there is still some specific combination of factors that allow for large bias (e.g., perhaps small sample sizes makes our estimators more vulnerable to bias). In an actual analysis, we would make a note to investigate these anomalies later on. -In general, trying to group your simulation scenarios so that their boxes are generally narrow is a good idea; narrow boxes means that you have found a representation of the data where you know what is driving the variation in your performance measure, and that the factors bundled inside the boxes are less important. +In general, trying to group your simulation scenarios so that their boxes are generally small is a good idea; small boxes means that you have found a representation of the data where you know what is driving the variation in your performance measure, and that the factors bundled inside the boxes are less important. This might not always be possible, if all your factors matter; in this case the width of your boxes tells you to what extent the bundled factors matter relative to the factors explicitly present in your plot. One might wonder, with only few trials per box, whether we should instead look at the individual scenarios. @@ -278,10 +279,9 @@ Using boxplots, even over such a few number of points, notably clarifies a visua Boxplots can make seeing trends more difficult, as the eye is drawn to the boxes and tails, and the range of your plot axes can be large due to needing to accommodate the full tails and outliers of your results; this can compress the mean differences between groups, making them look small. They can also be artificially inflated, especially if the MCSEs are large. -Instead of bundling, we can therefore aggregate, where we average all the scenarios within a box to get a single number of average performance. -This will show us overall trends rather than individual simulation variation. +Instead of bundling, we can therefore aggregate, where we average all the scenarios within a box to get a single number of average performance, to see overall trends. -When we aggregate, and average over some of the factors, we collapse our simulation results down to fewer moving parts. +When we aggregate, i.e. average over some of the factors, we collapse our simulation results down to fewer moving parts. Aggregation across factors is better than not having varied those factors in the first place! A performance measure averaged over a factor is a more general answer of how things work in practice than having not varied the factor at all. @@ -316,46 +316,33 @@ ggplot( ssres, aes( as.factor(J), bias, col=method, group=method ) ) + theme_minimal() ``` -We now see quite clearly that as `alpha` grows, linear regression gets more biased if cluster size relates to average impact in the cluster (`size_coef`). +We now see quite clearly that as `alpha` grows, linear regression gets more biased if cluster size relates to average impact in the cluster (`size_coef = 0.2`). Our finding makes sense given our theoretical understanding of the problem---if size is not related to treatment effect, it is hard to imagine how varying cluster sizes would cause much bias. We are looking at an interaction between our simulation factors: we only see bias for linear regression when cluster size relates to impact and there is variation in cluster size. -We also see that all the estimators have near zero bias when there is no variation in cluster size or the cluster size does not relate to outcome, as shown by the top row and left column facets. +We also see that all the estimators have near zero bias when there is no variation in cluster size or the cluster size does not relate to outcome, as shown by the top row and left column of facets. Finally, we see the methods all likely give the same answers when there is no cluster size variation, given the overplotted lines on the left column of the figure. -We might take this figure as still too complex. So far we have learned that MLM does seem to react to ICC, and that LR reacts to `alpha` and `size_coef` in combination. +We can continue to explore by changing our $x$-axis, e.g., to ICC. More broadly, with many levels of a factor, as we have with ICC, we can let ggplot aggregate directly by taking advantage of `geom_smooth()`. This leads to the following: ```{r, echo=FALSE, message=FALSE} -ggplot( sres, aes( ICC, bias, col=as.factor(alpha), +ggplot( sres, aes( ICC, bias, col=method, group=interaction(method,alpha) ) ) + - facet_grid( size_coef ~ method, labeller = label_both ) + + facet_grid( size_coef ~ alpha, labeller = label_both ) + geom_smooth( alpha=0.75, se=FALSE, method="loess", span=1.5 ) + geom_hline( yintercept = 0 ) + theme_minimal() ``` -Our story is fairly clear now: LR is biased when alpha is large and the cluster size relates to impact. -MLM can be biased when ICC is low, if cluster size relates to impact (this is because it is driving towards person-weighting when there is little cluster variation). - - - Aggregation is powerful, but it can be misleading if you have scaling issues or extreme outliers. With bias, our scale is fairly well set, so we are good. @@ -379,22 +366,22 @@ agg_perf <- sres %>% summarise( SE = sqrt( mean( SE^2 ) ) ) ``` -Because bias is linear, you do not need to worry about the MCSE. -But if you are looking at the magnitude of bias ($|bias|$), then you can run into issues when the biases are close to zero, if they are measured noisily. -For example, imagine you have two scenarios with true bias of 0.0, but your MCSE is 0.02. +MCSE can sometimes distort an aggregation of a performance measure. +For example, if you are looking at the magnitude of bias ($|bias|$), then you can run into issues when the biases are close to zero, if they are measured noisily. +In particular, imagine you have two scenarios with true bias of 0.0, but your MCSE is 0.02. In one scenario, you estimate a bias of 0.017, and in the other -0.023. If you average the estimated biases, you get -0.003, which suggests a small bias as we would wish. Averaging the absolute biases, on the other hand, gives you 0.02, which could be deceptive. With high MCSE and small magnitudes of bias, looking at average bias, not average $|bias|$, is safer. Alternatively, you can use the formula $RMSE^2 = Bias^2 + SE^2$ to back out the average absolute bias from the RMSE and SE. +In this approach, first aggregate to get overall RMSE and SE, and then calculate $Bias^2$ as $RMSE^2 - SE^2$. ## Comparing true SEs with standardization We just did a deep dive into bias. Uncertainty (standard errors) is another primary performance criterion of interest. - As an initial exploration, we plot the standard error estimates from our Cluster RCT simulation, using smoothed lines to visualize trends. We use `ggplot`'s `geom_smooth` to aggregate over `size_coef` and `alpha`, which we leave out of the plot. We include individual data points to visualize variation around the smoothed estimates: @@ -413,12 +400,12 @@ Second, standard error decreases as the number of clusters (J) increases, which In contrast, increasing the cluster size (n_bar) has relatively little effect on the standard error (the rows of our facets look about the same). Lastly, all methods show fairly similar levels of standard error overall. -While we can extract all of these from the figure, the figure is still not ideal for _comparing_ our methods. +While we can extract all of these observations from the figure, the figure is not ideal for _comparing_ our methods. The dominant influence of design features like ICC and sample size obscures our ability to detect meaningful differences between methods. In other words, even though SE changes across scenarios, it’s difficult to tell which method is actually performing better within each scenario. We can also view the same information by bundling over the left-out dimensions. -We put `n_bar` in our bundles because maybe it does not matter that much: +We add `n_bar` to our bundles, instead of faceting by it, because maybe it does not matter that much: ```{r} ggplot( sres, aes( ICC, SE, col=method, group=paste0( ICC, method ) ) ) + facet_grid( . ~ J, labeller = label_both ) + @@ -429,18 +416,19 @@ ggplot( sres, aes( ICC, SE, col=method, group=paste0( ICC, method ) ) ) + Our plots are still dominated by the strong effects of ICC and the number of clusters (J). When performance metrics like standard error vary systematically with design features, it becomes difficult to compare methods meaningfully across scenarios. -To address this, we shift our focus through standardization. Instead of noting that: +To address this, we shift our focus through standardization. +We want to shift from observations such as: > “All my SEs are getting smaller,” -we want to conclude that: +to conclusions such as: > “Estimator 1 has systematically higher SEs than Estimator 2 across scenarios.” -Simulation results are often driven by broad design effects, which can obscure the specific methodological questions we care about. Standardizing helps bring those comparisons to the forefront. -Let's try that next. - -One straightforward strategy for standardization is to compare each method’s performance to a designated baseline. In this example, we use Linear Regression (LR) as our baseline. +Simulation results are often driven by broad design effects, which can obscure the specific methodological questions we care about. +We can therefore standardize, by calculating a relative performance measure, to bring our desired comparisons to the forefront. +One straightforward strategy for standardization is to compare each method’s performance to a designated baseline. +In this example, we use Linear Regression (LR) as our baseline. We standardize by, for each simulation scenario, dividing each method’s SE by the SE of LR, to produce `SE.scale`. This relative measure, `SE.scale`, allows us to examine how much better or worse, across our scenarios, each method performs relative to a chosen reference method. @@ -456,7 +444,7 @@ ssres <- We can then treat `SE.scale` as a measure like any other. Here we bundle, showing how relative SE changes by J, `n_bar` and ICC: -```{r} +```{r, out.width="100%"} ggplot( ssres, aes( ICC, SE.scale, col=method, group = interaction(ICC, method) ) ) + facet_grid( n_bar ~ J, labeller = label_both ) + @@ -465,14 +453,15 @@ ggplot( ssres, aes( ICC, SE.scale, col=method, ``` The figure above shows how each method compares to LR across simulation scenarios. -Aggregation clearly performs worse than LR when the Intraclass Correlation Coefficient (ICC) is zero. However, when ICC is greater than zero, Aggregation yields improved precision. +Aggregation clearly performs worse than LR when the Intraclass Correlation Coefficient (ICC) is zero. +However, when the ICC is greater than zero, Aggregation yields improved precision. The Multilevel Model (MLM), in contrast, appears more adaptive. -It captures the benefits of aggregation when ICC is high, but avoids the precision cost when ICC is zero. -This adaptivity makes MLM appealing in practice when ICC is unknown or variable across contexts. +It captures the benefits of aggregation when the ICC is high, but avoids the precision cost when ICC is zero. +This adaptability makes MLM appealing in practice when the ICC is unknown or variable across contexts. -In looking at the plot we are seeing essentially identical rows and and fairly similar across columns. -This suggests we should bundle the `n_bar` to get a cleaner view of the main patterns, and that we can also bundle over `J` as well. -We finally drop the `LR` results entirely, as it is the reference method and always has a relative SE of 1. +In looking at the plot we are seeing essentially identical rows and fairly similar columns. +This suggests we should bundle the `n_bar` to get a cleaner view of the main patterns, and that we could also bundle over `J` as well. +We finally can drop the `LR` results entirely, as it is the reference method and always has a relative SE of 1. ```{r} ssres %>% @@ -486,7 +475,8 @@ ssres %>% scale_y_continuous( breaks=seq(90, 125, by=5 ) ) ``` -The pattern is clear: when ICC = 0, Aggregation performs worse than LR, and MLM performs about the same. But as ICC increases, Aggregation and MLM both improve, and perform about the same to each other. +The pattern is clear: when ICC = 0, Aggregation performs worse than LR, and MLM performs about the same. +But as ICC increases, Aggregation and MLM both improve, and perform about the same to each other. This highlights the robustness of MLM across diverse conditions. @@ -579,9 +569,9 @@ This is the kind of diagnostic plot we often wish were included in more applied So far we have examined the performance of our _point estimators_. We next look at ways to assess our _estimated_ standard errors. -A good first question is whether they are about the right size, on average, across all the scenarios. +A good first question is whether they are _calibrated_ (about the right size on average) across all the scenarios. -When assessing estimated standard errors it is very important to see if they are _reliably_ the right size, making the bundling method an especially important tool here. +When assessing estimated standard errors it is very important to see if they are _reliably_ the right size across the scenarios, making bundling an especially important tool here. We first see if the average estimated SE, relative to the true SE, is usually around 1 across all scenarios: ```{r, out.width="100%"} @@ -663,6 +653,27 @@ It is a tricky measure: if the true SE is high for a method, then the relative i Thinking through what might be driving what can be difficult, and is often not central to the main purpose of an evaluation. People often look at confidence interval coverage and confidence interval width, instead, to assess the quality of estimated SEs. +We can instead try using the degree of freedom calculations we saw in Section \@ref(performance-stability). +We plug in $\widehat{df} = \frac{2 \bar{V}^2}{S_V^2}$ for each scenario and plot: + +```{r} +sres <- mutate( sres, + df_hat = 2 * ( ESE_hat^4 ) / ( SD_SE_hat^4 ) ) +ggplot( sres, + aes( ICC, df_hat, col=method, + group = interaction(ICC,method) ) ) + + facet_grid( . ~ J, labeller = label_both) + + geom_boxplot( position="dodge" ) + + labs( color="n" ) + + scale_y_log10( breaks = c( 2.5, 5, 10, 20, 40, 80, 160 ), + labels = c( 2.5, 5, 10, 20, 40, 80, 160 ) + ) + + geom_hline( yintercept = c(5,20,80), lty=2, col="grey" ) + + scale_x_continuous( breaks = unique( sres$ICC ) ) +``` + +The multilevel model generally has higher estimated degrees of freedom, especially when ICC is low, and Linear Regression has generally lower degrees of freedom overall (except when ICC is zero). + ## Assessing confidence intervals @@ -698,11 +709,12 @@ c_sub <- covres %>% ggplot( c_sub, aes( ICC, coverage, col=method, group=method ) ) + facet_grid( . ~ J, labeller = label_both ) + geom_line( position = position_dodge( width=0.05)) + - geom_point( position = position_dodge( width=0.05) ) + + geom_point( position = position_dodge( width=0.05), size = 2 ) + geom_errorbar( aes( ymax = coverage + 2*coverage_mcse, ymin = coverage - 2*coverage_mcse ), width=0, position = position_dodge( width=0.05) ) + - geom_hline( yintercept = 0.95 ) + geom_hline( yintercept = 0.95 ) + + scale_y_continuous( labels = scales::percent_format() ) ``` Generally coverage is good unless $J$ is low or ICC is 0. @@ -740,8 +752,19 @@ There are mild differences due to differences in how the degrees of freedom are +## Conclusions + +Visualization is rarely a single plot; it is the process of iterating from messy, exploratory graphs to a small set of figures that communicate the main findings. +In this chapter we walked through four core tools for that process---subsetting, many small multiples, bundling, and aggregation---and showed how they can be used together to manage the complexity of multifactor simulations. +Subsetting helps with orientation and sanity checks, small multiples reveal interactions, bundling summarizes variability across scenarios, and aggregation highlights broad trends when the raw results are too noisy or too high dimensional to interpret directly. +We illustrated these tools using the Cluster RCT case study, beginning with bias and then extending the same workflow to standard errors, RMSE, estimated standard errors, and confidence interval performance. +A recurring theme was that raw performance measures are often dominated by design effects such as ICC and sample size, which can obscure the method comparisons we care about. +Standardization---especially expressing performance relative to a baseline method---can make comparisons far clearer, though it also propagates uncertainty from the baseline and should be interpreted with care. +Ultimately, the goal of visualization is to discover and communicate structure: where is performance stable and when does it change? +The plots in this chapter provide a template for an overall workflow, and we encourage you to use the code and approach in your own work. +There are further tools, and further concerns, that build on this core set of techniques; that is what we discuss in the following chapter. ## Exercises @@ -779,6 +802,13 @@ sres <- res %>% names( sres ) ``` +### Checking bias + +Under the discussion of aggregation, we closed with a plot suggesting negative bias as ICC increases when `size_coef=0`. +Investigate that finding, either by digging into the results more or by running additional simulations. +_Do not_ re-run the entire simulation; sometimes a targeted investigation can be just as effective for answering a specific question. + + ### Assessing uncertainty diff --git a/075-special-topics-on-reporting.Rmd b/075-special-topics-on-reporting.Rmd index adfc1a6..3a604cc 100644 --- a/075-special-topics-on-reporting.Rmd +++ b/075-special-topics-on-reporting.Rmd @@ -635,82 +635,66 @@ knitr::kable(rr, digits = 2) ## What to do with warnings in simulations Sometimes our analytic strategy might give some sort of warning (or fail altogether). -For example, from the cluster randomized experiment case study we have: +In Section \@ref(error-handling) we saw how to trap such warnings or errors. +In particular, in Section \@ref(error-handling) we illustrated error trapping on the multilevel model for the cluster RCT experiment by revising our `analysis_MLM()` method to a `analysis_MLM_safe()` method, which gave output from the MLM method that looked like this: ```{r, include=FALSE} source( "case_study_code/clustered_data_simulation.R" ) ``` ```{r} -set.seed(101012) # (I picked this to show a warning.) +set.seed(101012) # (I picked this to show an issue.) dat <- gen_cluster_RCT( J = 50, n_bar = 100, sigma2_u = 0 ) -mod <- lmer( Yobs ~ 1 + Z + (1|sid), data=dat ) +analysis_MLM_safe( dat ) ``` +For this dataset, for example, we see that there was a convergence issue that gave rise to the indicated message. +Once the full simulation is run, we can examine the patterns of these warnings and errors to see if they are a serious or minor problem. +We first do this by calculating the rate of errors or warning messages as a performance measure across the simulation scenarios. +Especially if we plan on possibly droping some trials, it is important to see how often things are acting peculiarly. -We have to make a deliberate decision as to what to do about this: - - - Keep these "weird" trials? - - Drop them? - -Generally, when a method fails or gives a warning is something to investigate in its own right. -Ideally, failure would not be too common, meaning we could drop those trials, or keep them, without really impacting our overall results. -But one should at least know what one is ignoring. - -If you decide to drop them, you should drop the entire simulation iteration including the other estimators, even if they worked fine! -If there is something particularly unusual about the dataset, then dropping for one estimator, and keeping for the others that maybe didn't give a warning, but did struggle to estimate the estimand, would be unfair: in the final performance measures the estimators that did not give a warning could be being held to a higher standard, making the comparisons between estimators biased. - -If your estimators generate warnings, you should calculate the rate of errors or warning messages as a performance measure. -Especially if you drop some trials, it is important to see how often things are acting pecularly. - -As discussed earlier, the main tool for doing this is the `quietly()` function: -```{r} -quiet_lmer = quietly( lmer ) -qmod <- quiet_lmer( Yobs ~ 1 + Z + (1|sid), data=dat ) -qmod -``` - -You then might have, in your analyzing code: -```{r, eval=FALSE} -analyze_data <- function( dat ) { - - M1 <- quiet_lmer( Yobs ~ 1 + Z + (1|sid), data=dat ) - message1 = ifelse( length( M1$message ) > 0, 1, 0 ) - warning1 = ifelse( length( M1$warning ) > 0, 1, 0 ) - - # Compile our results - tibble( ATE_hat = coef(M1)["Z"], - SE_hat = se.coef(M1)["Z"], - message = message1, - warning = warning1 ) -} -``` - -Now you have your primary estimates, and also flags for whether there was a convergence issue. -In the analysis section you can then evaluate what proportion of the time there was a warning or message, and then do subset analyses to those simulation trials where there was no such warning. - - -For example, in our cluster RCT running example, we know that ICC is an important driver of when these convergence issues might occur, so we can explore how often we get a convergence message by ICC level: - - +For example, in our cluster RCT running example, we know that ICC is an important driver of when convergence issues might occur, so we can explore how often we get a convergence message by ICC level by calculating the number of messages, warnings, or errors per 1000 iterations: ```{r examine_convergence_rates} res %>% + dplyr::filter( method == "MLM" ) %>% group_by( method, ICC ) %>% - summarise( message = mean( message ) ) %>% - pivot_wider( names_from = "method", values_from="message" ) + summarise( message = 1000*mean( message ), + warning = 1000*mean( warning ), + error = 1000*mean( error ) ) %>% + pivot_wider( names_from = method, + values_from=c( "message", "warning", "error" ) ) ``` We see that when the ICC is 0 we get a lot of convergence issues, but as soon as we pull away from 0 it drops off considerably. -At this point we might decide to drop those runs with a message or keep them. -In this case, we decide to keep. -It should not matter much, except possibly when ICC = 0, and we know the convergence issues are driven by trying to estimate a 0 variance, and thus is in some sense expected. +Thankfully, we never saw actual errors and our warnings were very rare. + +At this point we have to decide whether to drop the problematic runs or keep them. +Ideally, failure would not be too common, meaning we could drop or keep the problematic iterations without really impacting our overall results. + +In our case, for example, it should not matter much, except possibly when ICC = 0, and we know the convergence issues are driven by trying to estimate a 0 variance, and thus is in some sense expected. Furthermore, we know people using these methods would likely ignore these messages, and thus we are faithfully capturing how these methods would be used in practice. We might eventually, however, want to do a separate analysis of the ICC = 0 context to see if the MLM approach is actually falling apart, or if it is just throwing warnings. +Importantly, if the decision is to drop, then the entire simulation iteration, including the other estimators, should be dropped even if the other estimators worked fine! +If there is something particularly unusual about the dataset that caused the concern, then dropping for one estimator and keeping for the others would be unfair: in the final performance measures the estimators that did not give a warning could be being held to a higher standard, making the comparisons between estimators biased. +Consider, for example, if the dropped datasets were fundamentally harder to evaluate. + + +## Conclusions + +Designed experiments in simulation are only as useful as the summaries you make of their output. +In this chapter, we showed a few advanced ways of moving from raw simulation outputs to interpretable summaries using regression, ANOVA, LASSO, trees, and multilevel meta-models. +These tools let you parse the main effects of your simulation factors along with their interactions, and can help turn many scenario-level estimates into clear statements about where methods work and where they break. +They can also help protect against how Monte Carlo simulation error can potentially distort findings. +We also focused on two specific areas where analyzing a set of results can be tricky: when each iteration is expensive (so you do not have too many of them), and when sometimes your estimators fail or perform poorly in a way that raises warnings or flags. +In the former case, aggregation and multilevel models can be especially useful when replicates are expensive. +In the latter, evaluate when failures occur, and then either drop them consistently or explicitly model them. +Overall, these tools give a way to go deeper into a set of simulation results. +Often the findings here would not be presented in the main text, but they can be important supporting detail, especially when placed in a supplement. diff --git a/200-coding-tidbits.Rmd b/200-coding-tidbits.Rmd index 27ccda7..2e6fcd2 100644 --- a/200-coding-tidbits.Rmd +++ b/200-coding-tidbits.Rmd @@ -221,7 +221,7 @@ For example, we can time how long it takes to analyze some data from our cluster library( bench ) dat <- gen_cluster_RCT(n_bar=100, J = 100) timings <- mark( - MLM = quiet_analysis_MLM(dat), + MLM = analysis_MLM_safe(dat), OLS = analysis_OLS(dat), agg = analysis_agg(dat), check = FALSE @@ -246,7 +246,7 @@ timings <- bench::press( { dat <- gen_cluster_RCT(n_bar=n_bar, J = J) bench::mark( - MLM = quiet_analysis_MLM(dat), + MLM = analysis_MLM_safe(dat), OLS = analysis_OLS(dat), agg = analysis_agg(dat), check = FALSE @@ -278,7 +278,7 @@ For example, you might have the following: profvis( { replicate( 10, { data <- gen_cluster_RCT( n_bar = 100, J = 100 ) - res1 <- quiet_analysis_MLM(data) + res1 <- analysis_MLM_safe(data) res2 <- analysis_OLS(data) res3 <- analysis_agg(data) } ) diff --git a/book.bib b/book.bib index 18cbdd8..ce50ab3 100644 --- a/book.bib +++ b/book.bib @@ -1,13 +1,21 @@ %% This BibTeX bibliography file was created using BibDesk. %% https://bibdesk.sourceforge.io/ -%% Created for Luke Miratrix at 2025-12-18 10:05:30 -0500 +%% Created for Luke Miratrix at 2026-01-16 15:00:23 -0500 %% Saved with string encoding Unicode (UTF-8) +@book{efron1994introduction, + author = {Efron, Bradley and Tibshirani, Robert J}, + date-added = {2026-01-16 15:00:18 -0500}, + date-modified = {2026-01-16 15:00:18 -0500}, + publisher = {Chapman and Hall/CRC}, + title = {An introduction to the bootstrap}, + year = {1994}} + @article{Benjamin2017redefine, author = {Benjamin, Daniel J. and Berger, James O. and Johannesson, Magnus and Nosek, Brian A. and Wagenmakers, E.-J. and Berk, Richard and Bollen, Kenneth A. and Brembs, Bj{\"o}rn and Brown, Lawrence and Camerer, Colin and Cesarini, David and Chambers, Christopher D. and Clyde, Merlise and Cook, Thomas D. and De Boeck, Paul and Dienes, Zoltan and Dreber, Anna and Easwaran, Kenny and Efferson, Charles and Fehr, Ernst and Fidler, Fiona and Field, Andy P. and Forster, Malcolm and George, Edward I. and Gonzalez, Richard and Goodman, Steven and Green, Edwin and Green, Donald P. and Greenwald, Anthony G. and Hadfield, Jarrod D. and Hedges, Larry V. and Held, Leonhard and Hua Ho, Teck and Hoijtink, Herbert and Hruschka, Daniel J. and Imai, Kosuke and Imbens, Guido and Ioannidis, John P. A. and Jeon, Minjeong and Jones, James Holland and Kirchler, Michael and Laibson, David and List, John and Little, Roderick and Lupia, Arthur and Machery, Edouard and Maxwell, Scott E. and McCarthy, Michael and Moore, Don A. and Morgan, Stephen L. and Munaf{\'o}, Marcus and Nakagawa, Shinichi and Nyhan, Brendan and Parker, Timothy H. and Pericchi, Luis and Perugini, Marco and Rouder, Jeff and Rousseau, Judith and Savalei, Victoria and Sch{\"o}nbrodt, Felix D. and Sellke, Thomas and Sinclair, Betsy and Tingley, Dustin and Van Zandt, Trisha and Vazire, Simine and Watts, Duncan J. and Winship, Christopher and Wolpert, Robert L. and Xie, Yu and Young, Cristobal and Zinman, Jonathan and Johnson, Valen E.}, doi = {10.1038/s41562-017-0189-z}, @@ -455,7 +463,7 @@ @article{Bloom2016using title = {{Using Multisite Experiments to Study Cross-Site Variation in Treatment Effects: A Hybrid Approach With Fixed Intercepts and a Random Treatment Coefficient}}, volume = {10}, year = {2016}, - bdsk-file-1 = {YnBsaXN0MDDSAQIDBFxyZWxhdGl2ZVBhdGhYYm9va21hcmtfEGguLi8uLi8uLi8uLi9Eb2N1bWVudHMvUGFwZXJzIExpYnJhcnkvQmxvb20vSm91cm5hbCBvZiBSZXNlYXJjaCBvbiBFZHVjYXRpb25hbCBFZmZlY3RpdmVuZXNzX1BvcnRlcl8xLnBkZk8RBGRib29rZAQAAAAABBAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABgAwAABQAAAAEBAABVc2VycwAAAAkAAAABAQAAbG1pcmF0cml4AAAACQAAAAEBAABEb2N1bWVudHMAAAAOAAAAAQEAAFBhcGVycyBMaWJyYXJ5AAAFAAAAAQEAAEJsb29tAAAAPQAAAAEBAABKb3VybmFsIG9mIFJlc2VhcmNoIG9uIEVkdWNhdGlvbmFsIEVmZmVjdGl2ZW5lc3NfUG9ydGVyXzEucGRmAAAAGAAAAAEGAAAEAAAAFAAAACgAAAA8AAAAVAAAAGQAAAAIAAAABAMAAMs4AAAAAAAACAAAAAQDAAC97g4AAAAAAAgAAAAEAwAAMEEPAAAAAAAIAAAABAMAANRHDwAAAAAACAAAAAQDAAA5SQ8AAAAAAAgAAAAEAwAATUkPAAAAAAAYAAAAAQYAAMwAAADcAAAA7AAAAPwAAAAMAQAAHAEAAAgAAAAABAAAQb5MnI4AAAAYAAAAAQIAAAEAAAAAAAAADwAAAAAAAAAAAAAAAAAAAAgAAAAEAwAABAAAAAAAAAAEAAAAAwMAAPcBAAAIAAAAAQkAAGZpbGU6Ly8vCAAAAAEBAABMb2JhZG9yYQgAAAAEAwAAAJCClucAAAAIAAAAAAQAAEHHFbB+AAAAJAAAAAEBAAA4OTYxOUJFQy1DRENDLTQyQ0EtODAwNy0yOTc0QUE5RUI4MzQYAAAAAQIAAIEAAAABAAAA7xMAAAEAAAAAAAAAAAAAAAEAAAABAQAALwAAAAAAAAABBQAAHwEAAAECAAAwNDM1NjM1YTNiZjkxMTc2MTFlYzk1NWM1YzlmYjNhZGFmY2ZiMTY5OWNmN2QyMzA3ZjBjMmZiNjZjOGRiYzI1OzAwOzAwMDAwMDAwOzAwMDAwMDAwOzAwMDAwMDAwOzAwMDAwMDAwMDAwMDAwMjA7Y29tLmFwcGxlLmFwcC1zYW5kYm94LnJlYWQtd3JpdGU7MDE7MDEwMDAwMTE7MDAwMDAwMDAwMDBmNDk0ZDs2NDsvdXNlcnMvbG1pcmF0cml4L2RvY3VtZW50cy9wYXBlcnMgbGlicmFyeS9ibG9vbS9qb3VybmFsIG9mIHJlc2VhcmNoIG9uIGVkdWNhdGlvbmFsIGVmZmVjdGl2ZW5lc3NfcG9ydGVyXzEucGRmAADMAAAA/v///wEAAAAAAAAAEAAAAAQQAACsAAAAAAAAAAUQAAAsAQAAAAAAABAQAABcAQAAAAAAAEAQAABMAQAAAAAAAAIgAAAkAgAAAAAAAAUgAACYAQAAAAAAABAgAACoAQAAAAAAABEgAADYAQAAAAAAABIgAAC4AQAAAAAAABMgAADIAQAAAAAAACAgAAAEAgAAAAAAADAgAAAwAgAAAAAAAAHAAAB8AQAAAAAAABHAAAAUAAAAAAAAABLAAACMAQAAAAAAAIDwAAA4AgAAAAAAAAAIAA0AGgAjAI4AAAAAAAACAQAAAAAAAAAFAAAAAAAAAAAAAAAAAAAE9g==}, + bdsk-file-1 = {YnBsaXN0MDDSAQIDBFxyZWxhdGl2ZVBhdGhYYm9va21hcmtfEGguLi8uLi8uLi8uLi9Eb2N1bWVudHMvUGFwZXJzIExpYnJhcnkvQmxvb20vSm91cm5hbCBvZiBSZXNlYXJjaCBvbiBFZHVjYXRpb25hbCBFZmZlY3RpdmVuZXNzX1BvcnRlcl8xLnBkZk8RBGRib29rZAQAAAAABBAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABgAwAABQAAAAEBAABVc2VycwAAAAkAAAABAQAAbG1pcmF0cml4AAAACQAAAAEBAABEb2N1bWVudHMAAAAOAAAAAQEAAFBhcGVycyBMaWJyYXJ5AAAFAAAAAQEAAEJsb29tAAAAPQAAAAEBAABKb3VybmFsIG9mIFJlc2VhcmNoIG9uIEVkdWNhdGlvbmFsIEVmZmVjdGl2ZW5lc3NfUG9ydGVyXzEucGRmAAAAGAAAAAEGAAAEAAAAFAAAACgAAAA8AAAAVAAAAGQAAAAIAAAABAMAAMs4AAAAAAAACAAAAAQDAAC97g4AAAAAAAgAAAAEAwAAMEEPAAAAAAAIAAAABAMAANRHDwAAAAAACAAAAAQDAAA5SQ8AAAAAAAgAAAAEAwAATUkPAAAAAAAYAAAAAQYAAMwAAADcAAAA7AAAAPwAAAAMAQAAHAEAAAgAAAAABAAAQb5MnI4AAAAYAAAAAQIAAAEAAAAAAAAADwAAAAAAAAAAAAAAAAAAAAgAAAAEAwAABAAAAAAAAAAEAAAAAwMAAPcBAAAIAAAAAQkAAGZpbGU6Ly8vCAAAAAEBAABMb2JhZG9yYQgAAAAEAwAAAJCClucAAAAIAAAAAAQAAEHHFbB+AAAAJAAAAAEBAAA4OTYxOUJFQy1DRENDLTQyQ0EtODAwNy0yOTc0QUE5RUI4MzQYAAAAAQIAAIEAAAABAAAA7xMAAAEAAAAAAAAAAAAAAAEAAAABAQAALwAAAAAAAAABBQAAHwEAAAECAAAzMWZjNjQ4OTM0YjY2MjhhNWE4YzE2ODg0ZDYxM2M1OWQwOWExZDRkNThkYzVhMTNhMDY1MDg5ZTkyMGY1MzBhOzAwOzAwMDAwMDAwOzAwMDAwMDAwOzAwMDAwMDAwOzAwMDAwMDAwMDAwMDAwMjA7Y29tLmFwcGxlLmFwcC1zYW5kYm94LnJlYWQtd3JpdGU7MDE7MDEwMDAwMGU7MDAwMDAwMDAwMDBmNDk0ZDs1NDsvdXNlcnMvbG1pcmF0cml4L2RvY3VtZW50cy9wYXBlcnMgbGlicmFyeS9ibG9vbS9qb3VybmFsIG9mIHJlc2VhcmNoIG9uIGVkdWNhdGlvbmFsIGVmZmVjdGl2ZW5lc3NfcG9ydGVyXzEucGRmAADMAAAA/v///wEAAAAAAAAAEAAAAAQQAACsAAAAAAAAAAUQAAAsAQAAAAAAABAQAABcAQAAAAAAAEAQAABMAQAAAAAAAAIgAAAkAgAAAAAAAAUgAACYAQAAAAAAABAgAACoAQAAAAAAABEgAADYAQAAAAAAABIgAAC4AQAAAAAAABMgAADIAQAAAAAAACAgAAAEAgAAAAAAADAgAAAwAgAAAAAAAAHAAAB8AQAAAAAAABHAAAAUAAAAAAAAABLAAACMAQAAAAAAAIDwAAA4AgAAAAAAAAAIAA0AGgAjAI4AAAAAAAACAQAAAAAAAAAFAAAAAAAAAAAAAAAAAAAE9g==}, bdsk-url-1 = {https://doi.org/10.1080/19345747.2016.1264518}} @article{brown1974SmallSampleBehavior, diff --git a/case_study_code/analyze_cluster_RCT.R b/case_study_code/analyze_cluster_RCT.R index 632365f..f699c1a 100644 --- a/case_study_code/analyze_cluster_RCT.R +++ b/case_study_code/analyze_cluster_RCT.R @@ -76,24 +76,28 @@ analysis_MLM_safe <- function( dat, all_results = FALSE ) { if ( is.null( M1$result ) ) { # we had an error! tibble( ATE_hat = NA, SE_hat = NA, p_value = NA, - message = M1$message, - warning = M1$warning, + message = length( M1$message ) > 0, + warning = length( M1$warning > 0 ), error = TRUE ) } else { sum <- summary( M1$result ) + tibble( ATE_hat = sum$coefficients["Z","Estimate"], SE_hat = sum$coefficients["Z","Std. Error"], p_value = sum$coefficients["Z", "Pr(>|t|)"], - message = list( M1$message ), - warning = list( M1$warning ), + message = length( list( M1$messages ) ) > 0, + warning = length( list( M1$warning ) ) > 0, error = FALSE ) } } - +#' This is to illustrate how we can implement a data analytic workflow +#' mimicing human decision-making. +#' +#' This is _not_ what we use for the simulation results. analysis_MLM_contingent <- function( dat ) { M1 <- quiet_safe_lmer( Yobs ~ 1 + Z + (1 | sid), data=dat ) diff --git a/case_study_code/clustered_data_simulation.R b/case_study_code/clustered_data_simulation.R index e8ffdd9..4643f00 100644 --- a/case_study_code/clustered_data_simulation.R +++ b/case_study_code/clustered_data_simulation.R @@ -11,6 +11,9 @@ library( estimatr ) options(list(dplyr.summarise.inform = FALSE)) +source( here::here( "case_study_code/gen_cluster_RCT.R" ) ) + +source( here::here( "case_study_code/analyze_cluster_RCT.R" ) ) # Utility function for printout @@ -19,156 +22,43 @@ scat = function( str, ... ) { } -gen_cluster_RCT <- function( n_bar = 10, - J = 30, - p = 0.5, - gamma_0 = 0, gamma_1 = 0, gamma_2 = 0, - sigma2_u = 0, sigma2_e = 1, - alpha = 0 ) { - - stopifnot( alpha >= 0 ) - - # generate site sizes - n_min = round( n_bar * (1 - alpha) ) - n_max = round( n_bar * (1 + alpha) ) - if ( n_max == n_min ) { - if ( alpha > 0 ) { - warning( "alpha > 0 has no effect when there is no variation in site size" ) - } - nj = rep( n_min, J ) - } else { - nj <- sample( n_min:n_max, J, replace=TRUE ) - } - - # Generate average control outcome and average ATE for all sites - # (The random effects) - u0j = rnorm( J, mean=0, sd=sqrt( sigma2_u ) ) - - # randomize units within each site (proportion p to treatment) - Zj = ifelse( sample( 1:J ) <= J * p, 1, 0) - - # Calculate site intercept for each site - beta_0j = gamma_0 + gamma_1 * Zj + gamma_2 * Zj * (nj-n_bar)/n_bar + u0j - - # Make individual site membership - sid = as.factor( rep( 1:J, nj ) ) - dd = data.frame( sid = sid ) - - # Make individual level tx variables - dd$Z = Zj[ dd$sid ] - - # Generate the residuals - N = sum( nj ) - e = rnorm( N, mean=0, sd=sqrt( sigma2_e ) ) - - # Bundle and send out - dd <- mutate( dd, - sid=as.factor(sid), - Yobs = beta_0j[sid] + e, - Z = Zj[ sid ] ) - - dd -} - - - -#### Analysis functions ##### - -quiet_lmer = purrr::quietly( lmer ) - -quiet_analysis_MLM <- function( dat ) { - M1 = quiet_lmer( Yobs ~ 1 + Z + (1|sid), - data=dat ) - message1 = ifelse( length( M1$message ) > 0, 1, 0 ) - warning1 = ifelse( length( M1$warning ) > 0, 1, 0 ) - M1 = M1$result - - est = fixef( M1 )[["Z"]] - se = se.fixef( M1 )[["Z"]] - sc = summary(M1)$coefficients - pv = sc["Z",5] - df = sc["Z", "df"] - tibble( ATE_hat = est, SE_hat = se, df = df, p_value = pv, - message = message1, warning = warning1 ) -} - - -analysis_MLM <- function( dat ) { - M1 = lmer( Yobs ~ 1 + Z + (1|sid), - data=dat ) +quiet_analyze_data <- function(dat, + CR_se_type = "CR2", + agg_se_type = "HC2") { - est = fixef( M1 )[["Z"]] - se = se.fixef( M1 )[["Z"]] - sc = summary(M1)$coefficients - pv = sc["Z",5] - df = sc["Z", "df"] - tibble( ATE_hat = est, SE_hat = se, df = df, p_value = pv ) -} - - -analysis_OLS <- function( dat ) { - M2 <- lm_robust( Yobs ~ 1 + Z, - data=dat, clusters=sid ) - est <- M2$coefficients[["Z"]] - se <- M2$std.error[["Z"]] - pv <- M2$p.value[["Z"]] - df <- M2$df[["Z"]] - tibble( ATE_hat = est, SE_hat = se, df = df, p_value = pv ) -} - - -analysis_agg <- function( dat ) { - datagg <- - dat %>% - group_by( sid, Z ) %>% - summarise( - Ybar = mean( Yobs ), - n = n(), - .groups = "drop" - ) + # MLM + a = Sys.time() + MLM <- analysis_MLM_safe(dat) + MLM$seconds <- as.numeric(Sys.time() - a, units = "secs") - stopifnot( nrow( datagg ) == length(unique(dat$sid) ) ) + # OLS + a = Sys.time() + LR <- analysis_OLS(dat, se_type = CR_se_type) + LR$seconds <- as.numeric(Sys.time() - a, units = "secs") + LR$message <- 0 + LR$warning <- 0 + LR$error <- 0 - M3 <- lm_robust( Ybar ~ 1 + Z, - data=datagg, se_type = "HC2" ) - est <- M3$coefficients[["Z"]] - se <- M3$std.error[["Z"]] - df <- M3$df[["Z"]] - pv <- M3$p.value[["Z"]] - tibble( ATE_hat = est, SE_hat = se, df = df, p_value = pv ) -} - - - -analyze_data = function( dat ) { - MLM = analysis_MLM( dat ) - LR = analysis_OLS( dat ) - Agg = analysis_agg( dat ) + # Aggregated + a = Sys.time() + Agg <- analysis_agg(dat, se_type = agg_se_type) + Agg$seconds <- as.numeric(Sys.time() - a, units = "secs") + Agg$message <- 0 + Agg$warning <- 0 + Agg$error <- 0 - bind_rows( MLM = MLM, LR = LR, Agg = Agg, - .id = "method" ) + bind_rows(MLM = MLM, LR = LR, Agg = Agg, .id = "method") } -quiet_analyze_data = function( dat ) { - MLM = quiet_analysis_MLM( dat ) - LR = analysis_OLS( dat ) - Agg = analysis_agg( dat ) - LR$message = 0 - LR$warning = 0 - Agg$message = 0 - Agg$warning = 0 - bind_rows( MLM = MLM, LR = LR, Agg = Agg, - .id = "method" ) -} -run_CRT_sim <- function(reps, - n_bar = 10, J = 30, p = 0.5, - ATE = 0, ICC = 0.4, - size_coef = 0, alpha = 0, - seed = NULL, aggregate = TRUE) { +run_CRT_sim <- function( reps, + n_bar = 10, J = 30, p = 0.5, + ATE = 0, ICC = 0.4, + size_coef = 0, alpha = 0, + seed = NULL ) { stopifnot( ICC >= 0 && ICC < 1 ) @@ -197,7 +87,6 @@ if ( FALSE ) { dat <- gen_cluster_RCT( 5, 3 ) dat - undebug( quiet_analysis_MLM ) quiet_analyze_data( dat ) res <- run_CRT_sim( reps = 5, alpha=0.5 ) diff --git a/case_study_code/clustered_data_simulation_runner.R b/case_study_code/clustered_data_simulation_runner.R index ee11647..a5bb91d 100644 --- a/case_study_code/clustered_data_simulation_runner.R +++ b/case_study_code/clustered_data_simulation_runner.R @@ -5,6 +5,8 @@ # It is sourced in the Secret Run code block in the designing # multifactor simulation area. +# You can also run it directly here. + library( tidyverse ) library( future ) library( furrr ) @@ -25,6 +27,10 @@ params <- expand_grid(!!!crt_design_factors) params$seed = 1:nrow(params) * 17 + 100000 params +set.seed( 40440 ) +params = slice_sample( params, n=nrow(params) ) +params + plan(multisession, workers = parallel::detectCores() - 2) params$res = future_pmap(params, .f = run_CRT_sim, reps = 1000, @@ -36,6 +42,9 @@ res <- params %>% unnest( cols=c(res) ) saveRDS( res, file = "results/simulation_CRT.rds" ) + +# Quick check of the simulation ---- + if ( FALSE ) { # check sim format run_CRT_sim( reps = 5, diff --git a/case_study_code/clustered_data_simulation_timer.R b/case_study_code/clustered_data_simulation_timer.R new file mode 100644 index 0000000..3ffa463 --- /dev/null +++ b/case_study_code/clustered_data_simulation_timer.R @@ -0,0 +1,293 @@ + +# This script runs the multifactor simulation in parallel to generate +# the result files used in the book. + +# It is sourced in the Secret Run code block in the designing +# multifactor simulation area. + +# You can also run it directly here. + +library( tidyverse ) +library( future ) +library( furrr ) + +source( "case_study_code/clustered_data_simulation.R") + + +# Updated MLM analysis with max iterations + flags for convergence / maxfun hit +analysis_MLM_safe <- function( dat, all_results = FALSE, maxfun = 1000 ) { + + M1 <- quiet_safe_lmer( Yobs ~ 1 + Z + (1 | sid), + data=dat, + control = lme4::lmerControl( + optimizer = "bobyqa", + optCtrl = list(maxfun = maxfun) + ) ) + + if (all_results) { + return(M1) + } + + if ( is.null( M1$result ) ) { + # we had an error! + tibble( ATE_hat = NA, SE_hat = NA, p_value = NA, + message = length( M1$message ) > 0, + warning = length( M1$warning ) > 0, + error = TRUE ) + } else { + fit = M1$result + sum <- summary( fit ) + + optinfo <- fit@optinfo + + feval = optinfo$feval + + #if ( length( optinfo$conv$lme4 ) > 0 || + # length( optinfo$messages ) > 0 ) { + # browser() + #} + + tibble( + ATE_hat = sum$coefficients["Z","Estimate"], + SE_hat = sum$coefficients["Z","Std. Error"], + p_value = sum$coefficients["Z", "Pr(>|t|)"], + message = length( M1$messages ) > 0, + warning = length( M1$warning ) > 0 , + error = FALSE, + hit_maxfun = feval >= maxfun + ) + + } +} + + + + +run_CRT_sim <- function( reps, + n_bar = 10, J = 30, p = 0.5, + ATE = 0, ICC = 0.4, + size_coef = 0, alpha = 0, + seed = NULL ) { + + a = Sys.time() + stopifnot( ICC >= 0 && ICC < 1 ) + + scat( "Running n=%d, J=%d, ICC=%.2f, ATE=%.2f (%d replicates)\n", + n_bar, J, ICC, ATE, reps) + + if (!is.null(seed)) set.seed(seed) + + res <- + simhelpers::repeat_and_stack( reps, { + dat <- gen_cluster_RCT( n_bar = n_bar, J = J, p = p, + gamma_0 = 0, gamma_1 = ATE, gamma_2 = size_coef, + sigma2_u = ICC, sigma2_e = 1 - ICC, + alpha = alpha ) + quiet_analyze_data(dat) + }, + id = "runID" ) + + res$total_time <- as.numeric( Sys.time() - a, units="secs" ) + + res +} + + + + +if ( FALSE ) { + # Test the updated analysis function + set.seed( 40440 ) + test_dat <- gen_cluster_RCT( n_bar = 320, + J = 80, + gamma_1 = 0.2, + gamma_2 = 0.2, + sigma2_u = 0, + alpha = 0.5 ) + + debug( analysis_MLM_safe ) + analysis_MLM_safe( test_dat ) + + quiet_analyze_data( test_dat ) + + rr <- run_CRT_sim( reps = 5, + n_bar = 320, + J = 30, + ATE = 0.2, + size_coef = 0.2, + ICC = 0, + alpha = 0.5, + seed = 1234567) + rr + rr$total_time[[1]] - sum( rr$seconds) +} + + + +# Run the simulation ---- + + +crt_design_factors <- list( + n_bar = c( 20, 80, 320 ), + J = c( 5, 20, 80 ), + ATE = c( 0.2 ), + size_coef = c( 0, 0.2 ), + ICC = c( 0, 0.2, 0.4, 0.6, 0.8 ), + alpha = c( 0, 0.5, 0.8 ) +) + +params <- expand_grid(!!!crt_design_factors) + +params$seed = 1:nrow(params) * 17 + 100000 +params + +set.seed( 404450 ) +params = slice_sample( params, n=nrow(params) ) +params + + +start_time = Sys.time() + +plan(multisession, workers = parallel::detectCores() - 2) + +cat( "Starting simulation\n" ) + +R = 1000 +params$res = future_pmap(params, .f = run_CRT_sim, + reps = R, + .options = furrr_options(seed = NULL), + .progress = TRUE ) +plan(sequential) +gc() +res <- params %>% unnest( cols=c(res) ) +saveRDS( res, file = "results/simulation_CRT_timing.rds" ) + +end_time = Sys.time() + +cat( "Total computation time:\n" ) +print( end_time - start_time ) + + +# Analyze timing results ---- + + +res +nrow( params ) +nrow( res ) +nrow( res ) / nrow( params ) + +mt = mean( res$seconds ) +mt + +# Estimated total time in hours for full 1000 reps +comp_time <- mt * nrow(params) * 3 * 1000 / (60*60) +comp_time + +# Across 6 threads (est.) +comp_time / 5 + +# Timing for longest runs + +rs <- res %>% + group_by( n_bar, J, ATE, size_coef, ICC, alpha, method ) %>% + summarise( Etime = mean( seconds ) * 1000 / 60, + ttime = total_time[1], + sdttime = sd( total_time ), + conv = mean( hit_maxfun ) ) + +ggplot( rs, aes( method, Etime ) ) + + geom_boxplot() + + coord_flip() + + +sum( rs$Etime >= 30 ) + +# Any failure to converge? +rs$conv[ rs$method == "MLM" ] + + +ggplot( rs, aes( as.factor(n_bar), Etime, color=as.factor(J), group=interaction( J, n_bar ) ) ) + + geom_boxplot( width = 0.5 ) + + #geom_smooth() + + facet_wrap( ~ method ) + + #geom_line( aes( group=method ) ) + + #facet_grid( ICC ~ J, scales="free_y" ) + + scale_y_log10( breaks =c( 0.1, 1, 10, 30, 60 ) ) + + theme_minimal() + +# As above, but swap n_bar and J +ggplot( rs, aes( as.factor(J), Etime, color=as.factor(n_bar), group=interaction( J, n_bar ) ) ) + + geom_boxplot( width = 0.5 ) + + #geom_smooth() + + facet_wrap( ~ method ) + + #geom_line( aes( group=method ) ) + + #facet_grid( ICC ~ J, scales="free_y" ) + + scale_y_log10( breaks =c( 0.1, 1, 10, 30, 60 ) ) + + theme_minimal() + +# ICC matters? +ggplot( rs, aes( ICC, Etime, color=as.factor(n_bar), lty=as.factor(J), + group=interaction( J, n_bar ) ) ) + + geom_smooth( se = FALSE, method="lm" ) + + facet_wrap( ~ method ) + + #geom_line( aes( group=method ) ) + + #facet_grid( ICC ~ J, scales="free_y" ) + + scale_y_log10( breaks =c( 0.1, 1, 10, 30, 60 ) ) + + theme_minimal() + + +# Calculate _total_ time to run simulation ---- + +rst <- res %>% + group_by( n_bar, J, ATE, size_coef, ICC, alpha ) %>% + summarise( ttime = total_time[1], + sdttime = sd( total_time ), + dtime = ttime - sum( seconds ) ) + +nrow( rst ) +sum( rst$ttime ) / (60*60) + +rst$sdttime +summary( rst$dtime ) + +nrow( rst ) + +# Time for single iteration for all (minutes) +single_iter <- sum( rst$ttime / (R*60) ) +single_iter + +# Total sim, in hours +1000*single_iter / 60 + + +3 * 4 * 60 / single_iter + + + +# Save to core results file ---- + +res$hit_maxfun = NULL +res$total_time = NULL +res +saveRDS( res, file = "results/simulation_CRT.rds" ) + + +if ( FALSE ) { + # check sim format + run_CRT_sim( reps = 5, + n_bar = 20, + J = 5, + ATE = 0.2, + size_coef = 0.2, + ICC = 0, + alpha = 0.5, + seed = 1234567) + + + # Check the results + res = readRDS( "results/simulation_CRT.rds" ) + res +} + + + diff --git a/case_study_code/gen_cluster_RCT.R b/case_study_code/gen_cluster_RCT.R index 907d71b..0be58c1 100644 --- a/case_study_code/gen_cluster_RCT.R +++ b/case_study_code/gen_cluster_RCT.R @@ -6,12 +6,21 @@ gen_cluster_RCT <- function( gamma_0 = 0, gamma_1 = 0, gamma_2 = 0, sigma2_u = 0, sigma2_e = 1 ) { + stopifnot( alpha >= 0 ) # generate schools sizes n_min <- round( n_bar * (1 - alpha) ) n_max <- round( n_bar * (1 + alpha) ) - nj <- sample( n_min:n_max, J, replace = TRUE ) + if (n_min < n_max) { + nj <- sample( n_min:n_max, J, replace = TRUE ) + } else { + if ( alpha > 0 ) { + warning( "alpha > 0 has no effect when there is no variation in site size" ) + } + nj <- rep(n_bar, J) + } + # Generate average control outcome for all schools # (the random effects) u0j <- rnorm( J, mean = 0, sd = sqrt(sigma2_u) ) diff --git a/case_study_code/gen_cluster_RCT_rev.R b/case_study_code/gen_cluster_RCT_bug.R similarity index 82% rename from case_study_code/gen_cluster_RCT_rev.R rename to case_study_code/gen_cluster_RCT_bug.R index 647d636..907d71b 100644 --- a/case_study_code/gen_cluster_RCT_rev.R +++ b/case_study_code/gen_cluster_RCT_bug.R @@ -10,14 +10,10 @@ gen_cluster_RCT <- function( # generate schools sizes n_min <- round( n_bar * (1 - alpha) ) n_max <- round( n_bar * (1 + alpha) ) + nj <- sample( n_min:n_max, J, replace = TRUE ) - if (n_min < n_max) { - nj <- sample( n_min:n_max, J, replace = TRUE ) - } else { - nj <- rep(n_bar, J) - } - - # Generate average control outcome for all schools (the random effects) + # Generate average control outcome for all schools + # (the random effects) u0j <- rnorm( J, mean = 0, sd = sqrt(sigma2_u) ) # randomize schools (proportion p to treatment) diff --git a/results/cluster_RCT_simulation.rds b/results/cluster_RCT_simulation.rds index 74a5ba0..7f67515 100644 Binary files a/results/cluster_RCT_simulation.rds and b/results/cluster_RCT_simulation.rds differ diff --git a/results/cluster_RCT_simulation_validity.rds b/results/cluster_RCT_simulation_validity.rds index 8c9b58f..af16721 100644 Binary files a/results/cluster_RCT_simulation_validity.rds and b/results/cluster_RCT_simulation_validity.rds differ diff --git a/results/simulation_CRT.rds b/results/simulation_CRT.rds index 7421776..91b762a 100644 Binary files a/results/simulation_CRT.rds and b/results/simulation_CRT.rds differ