Merge pull request #95 from s3alfisc/dev

fwildclusterboot version 0.13

.github/workflows/R-CMD-check.yaml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - master
-      - ropensci
   pull_request:
     branches:
       - master

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: fwildclusterboot
 Title: Fast Wild Cluster Bootstrap Inference for Linear Models
-Version: 0.12.4.2
+Version: 0.13.0
 Authors@R: 
     c(
     person(given = "Alexander",
@@ -45,7 +45,7 @@ Description: Implementation of fast algorithms for wild cluster bootstrap
              (from package 'fixest') and 'felm()' (from package 'lfe'). 
              Additionally implements a 'heteroskedasticity-robust' ('HC1') wild 
              bootstrap.
-             Further, the package provides an R binding to 'WildBootTests.jl',
+             Last, the package provides an R binding to 'WildBootTests.jl',
              which provides additional speed gains and functionality, 
              including the 'WRE' bootstrap for instrumental variable models 
              (based on models of type 'ivreg()' from package 'ivreg')
@@ -64,7 +64,8 @@ Imports:
     JuliaConnectoR, 
     MASS, 
     Rcpp, 
-    summclust
+    summclust, 
+    rlang
 Suggests: 
     fixest,
     lfe,
@@ -89,7 +90,7 @@ RoxygenNote: 7.2.1
 LinkingTo: Rcpp,RcppArmadillo, RcppEigen
 VignetteBuilder: knitr
 Language: en-US
-SystemRequirements: Version Requirements to run the wild bootstrap through Julia - Julia (>= 1.8), WildBootTests.jl (>=0.8.6).
+SystemRequirements: Version Requirements to run the wild bootstrap through Julia - Julia (>= 1.8), WildBootTests.jl (>=0.9).
                     Julia is downloadable via the official Julia website (https://julialang.org/downloads/), 
                     WildBootTests.jl via Julia's package manager (https://docs.julialang.org/en/v1/stdlib/Pkg/) or 
                     its github repository (https://github.com/droodman/WildBootTests.jl)

NAMESPACE

@@ -26,10 +26,6 @@ S3method(tidy,mboottest)
 export(boot_aggregate)
 export(boot_ssc)
 export(boottest)
-export(format_alert)
-export(format_error)
-export(format_message)
-export(format_warning)
 export(glance)
 export(mboottest)
 export(pval)
@@ -56,6 +52,9 @@ importFrom(generics,glance)
 importFrom(generics,tidy)
 importFrom(gtools,permutations)
 importFrom(parallel,detectCores)
+importFrom(rlang,abort)
+importFrom(rlang,inform)
+importFrom(rlang,warn)
 importFrom(stats,aggregate)
 importFrom(stats,as.formula)
 importFrom(stats,coef)

NEWS.md

@@ -1,3 +1,46 @@
+# fwildclusterboot 0.13
+
+## Potentially Breaking Changes: 
+
+* `boottest()`, `mboottest()` and `boot_aggregate()`no longer have a dedicated `seed` argument. From version 0.13, reproducibility of results can only be controlled by setting a **global seed** via `drqng::dqset.seed()` and `set.seed()`. For more context, see the discussion below. As a consequence, results produced via old versions of `fwildlcusterboot` are no longer exactly reproducible. 
+
+* When the bootstrap is run via `engine = "WildBootTests.jl"`, the bootstrapped t-statistics and the original t-statistic are now returned as vectors (to align with the results from other `enginges`). Previously, they were returned as matrices. 
+
+## Other Changes: 
+
+* `boottest()` receives a new argument, `sampling`, which controls if random numbers are drawn via functions from `base` or the `dqrng` package. 
+* Some code refactoring. All bootstrap algorithms and their associated files have been renamed (e.g. `boot_algo2.R` is not called `boot_algo_fastnwild.R`, etc.).
+* Much nicer error and message formatting, via `rlang::abort()`, `warn()` and `inform()`. `rlang` is added as a dependency.
+
+## Background on the Change to Seeding
+
+Prior to the changes introduced in `v0.13`, `boottest()` will always call `set.seed()` or `dqrng::dqset.seed()` internally, regardless of whether the `seed` argument is specified or not (in the ladder case, it will create an internal seed by randomly drawing from a large set of integers). I consider this harmless, as setting seeds inside `boottest()` in this way does not affect the reproducibility of scripts run end-to-end.
+
+However, I have learned that is generally considered bad practice to overwrite global variables without notification - for example, the authors of [numpy](https://numpy.org/doc/stable/reference/random/generated/numpy.random.seed.html) have deprecated their `np.random.seed()` function for this reason. 
+
+Here is a quick example on what happens if a function "reseeds": it affects the future chain of random draws. 
+
+```r
+fn_reseed <- function(x){set.seed(x)}
+
+set.seed(123)
+rnorm(1)
+# [1] -0.5604756
+fn_reseed(1)
+rnorm(1)
+# [1] -0.6264538
+
+set.seed(123)
+rnorm(1); rnorm(1)
+# [1] -0.5604756
+# [1] -0.2301775
+```
+The two 'second' calls to `rnorm(1)` are based on different global seed states. 
+
+As a result, I have decided to deprecate the `seed' function argument. Random number generation must now **be** set outside of `boottest()` using `set.seed()` and `dqrng::dqset.seed()`. 
+
+This means that bootstrap results generated via versions < 0.13 will no longer be exactly replicable under the new version, but with a sufficiently large number of bootstrap iterations, this change should not affect any of your conclusions. 
+
 # fwildclusterboot 0.12.1
 
 This is a hot-fix release which turns of tests on CRAN that fail in non-standard CRAN test environments.