deprecate hide_progress

NEWS.md

@@ -1,3 +1,5 @@
+* The `hide_progress` keyword argument to `parametricbootstrap` is now deprecated. Users should isntead use `progress` (which is consistent with e.g. `fit`). [#717]
+
 MixedModels v4.21.0 Release Notes
 ==============================
 * Auto apply `Grouping()` to grouping variables that don't already have an explicit contrast. [#652]
@@ -476,3 +478,4 @@ Package dependencies
 [#703]: https://github.com/JuliaStats/MixedModels.jl/issues/703
 [#707]: https://github.com/JuliaStats/MixedModels.jl/issues/707
 [#709]: https://github.com/JuliaStats/MixedModels.jl/issues/709
+[#717]: https://github.com/JuliaStats/MixedModels.jl/issues/717

docs/src/bootstrap.md

@@ -143,13 +143,13 @@ The resultant loss in precision will generally be smaller than the variation tha
 More directly, lowering the fit quality for each replicate will reduce the quality of each replicate, but this may be more than compensated for by the ability to fit a much larger number of replicates in the same time.
 
 ```@example Main
-t = @timed parametricbootstrap(MersenneTwister(42), 1000, m2; hide_progress=true)
+t = @timed parametricbootstrap(MersenneTwister(42), 1000, m2; progress=false)
 t.time
 ```
 
 ```@example Main
 optsum_overrides = (; ftol_rel=1e-8)
-t = @timed parametricbootstrap(MersenneTwister(42), 1000, m2; optsum_overrides, hide_progress=true)
+t = @timed parametricbootstrap(MersenneTwister(42), 1000, m2; optsum_overrides, progress=false)
 t.time
 ```
 

src/bootstrap.jl

@@ -161,7 +161,7 @@ end
 
 """
     parametricbootstrap([rng::AbstractRNG], nsamp::Integer, m::MixedModel{T}, ftype=T;
-        β = coef(m), σ = m.σ, θ = m.θ, hide_progress=false, optsum_overrides=(;))
+        β = coef(m), σ = m.σ, θ = m.θ, progress=true, optsum_overrides=(;))
 
 Perform `nsamp` parametric bootstrap replication fits of `m`, returning a `MixedModelBootstrap`.
 
@@ -194,9 +194,16 @@ function parametricbootstrap(
     σ=morig.σ,
     θ::AbstractVector=morig.θ,
     use_threads::Bool=false,
-    hide_progress::Bool=false,
+    progress::Bool=true,
+    hide_progress::Union{Bool,Nothing}=nothing,
     optsum_overrides=(;),
 ) where {T}
+    if !isnothing(hide_progress)
+        Base.depwarn("`hide_progress` is deprecated, please use `progress` instead." *
+                     "NB: `progress` is a positive action, i.e. `progress=true` means show the progress bar.",
+                     :parametricbootstrap; force=true)
+        progress = !hide_progress
+    end
     if σ !== missing
         σ = T(σ)
     end
@@ -216,7 +223,7 @@ function parametricbootstrap(
         "use_threads is deprecated and will be removed in a future release",
         :parametricbootstrap,
     )
-    samp = replicate(n; hide_progress=hide_progress) do
+    samp = replicate(n; progress) do
         simulate!(rng, m; β, σ, θ)
         refit!(m; progress=false)
         # @info "" m.optsum.feval

src/utilities.jl

@@ -124,20 +124,26 @@ end
 _is_logging(io) = isa(io, Base.TTY) == false || (get(ENV, "CI", nothing) == "true")
 
 """
-    replicate(f::Function, n::Integer; hide_progress=false)
+    replicate(f::Function, n::Integer; progress=true)
 
 Return a vector of the values of `n` calls to `f()` - used in simulations where the value of `f` is stochastic.
 
-`hide_progress` can be used to disable the progress bar. Note that the progress
+`progress` controls whether the progress bar is shown. Note that the progress
 bar is automatically disabled for non-interactive (i.e. logging) contexts.
 """
-function replicate(f::Function, n::Integer; use_threads=false, hide_progress=false)
+function replicate(f::Function, n::Integer; use_threads=false, hide_progress=nothing, progress=true)
     use_threads && Base.depwarn(
         "use_threads is deprecated and will be removed in a future release",
         :replicate
     )
+    if !isnothing(hide_progress)
+        Base.depwarn("`hide_progress` is deprecated, please use `progress` instead." *
+                     "NB: `progress` is a positive action, i.e. `progress=true` means show the progress bar.",
+                     :parametricbootstrap; force=true)
+        progress = !hide_progress
+    end
     # and we want some advanced options
-    p = Progress(n; output=Base.stderr, enabled=!hide_progress && !_is_logging(stderr))
+    p = Progress(n; output=Base.stderr, enabled=progress && !_is_logging(stderr))
     # get the type
     rr = f()
     next!(p)

test/bootstrap.jl

@@ -14,7 +14,7 @@ include("modelcache.jl")
 
 function quickboot(m, n=2)
     return parametricbootstrap(MersenneTwister(42), n, m;
-                               hide_progress=true, use_threads=false,
+                               progress=false, use_threads=false,
                                optsum_overrides=(;ftol_rel=1e-8))
 end
 
@@ -75,10 +75,11 @@ end
     # two implicit tests
     # 1. type conversion of ints to floats
     # 2. test method for default RNG
-    parametricbootstrap(1, fm, β=[1], σ=1)
+    @test_logs((:warn, r"hide_progress"),
+                parametricbootstrap(1, fm, β=[1], σ=1, hide_progress=true))
 
     bsamp = parametricbootstrap(MersenneTwister(1234321), 100, fm;
-                                use_threads=false, hide_progress=true)
+                                use_threads=false, progress=false)
     @test isa(propertynames(bsamp), Vector{Symbol})
     @test length(bsamp.objective) == 100
     @test keys(first(bsamp.fits)) == (:objective, :σ, :β, :se, :θ)
@@ -89,13 +90,13 @@ end
 
     @testset "optsum_overrides" begin
         bsamp2 = parametricbootstrap(MersenneTwister(1234321), 100, fm;
-                                    use_threads=false, hide_progress=true,
+                                    use_threads=false, progress=false,
                                     optsum_overrides=(;ftol_rel=1e-8))
         # for such a simple, small model setting the function value
         # tolerance has little effect until we do something extreme
         @test bsamp.objective ≈ bsamp2.objective
         bsamp2 = parametricbootstrap(MersenneTwister(1234321), 100, fm;
-                                    use_threads=false, hide_progress=true,
+                                    use_threads=false, progress=false,
                                     optsum_overrides=(;ftol_rel=1.0))
         @test !(bsamp.objective ≈ bsamp2.objective)
     end
@@ -115,13 +116,13 @@ end
 
     @testset "threaded bootstrap" begin
         @test_logs (:warn, r"use_threads is deprecated") parametricbootstrap(MersenneTwister(1234321), 1, fm;
-                                                                             use_threads=true, hide_progress=true)
+                                                                             use_threads=true, progress=false)
     end
 
     @testset "zerocorr + Base.length + ftype" begin
         fmzc = models(:sleepstudy)[2]
         pbzc = parametricbootstrap(MersenneTwister(42), 5, fmzc, Float16;
-                                   hide_progress=true)
+                                   progress=false)
         @test length(pbzc) == 5
         @test Tables.istable(shortestcovint(pbzc))
         @test typeof(pbzc) == MixedModelBootstrap{Float16}
@@ -133,7 +134,7 @@ end
                                  zerocorr(1 + spkr + prec + load | item))
         fmzcnot = fit(MixedModel, form_zc_not, dataset(:kb07); progress=false)
         pbzcnot = parametricbootstrap(MersenneTwister(42), 2, fmzcnot, Float16;
-                                      hide_progress=true)
+                                      progress=false)
     end
 
     @testset "vcat" begin
@@ -195,7 +196,7 @@ end
         # need a model with fast=false to test that we only
         # copy the optimizer constraints for θ and not β
         gm0 = fit(MixedModel, first(gfms[:contra]), contra, Bernoulli(), fast=false, progress=false)
-        bs = parametricbootstrap(StableRNG(42), 100, gm0; hide_progress=true)
+        bs = parametricbootstrap(StableRNG(42), 100, gm0; progress=false)
         # make sure we're not copying
         @test length(bs.lowerbd) == length(gm0.θ)
         bsci = filter!(:type => ==("β"), DataFrame(shortestcovint(bs)))
@@ -216,15 +217,15 @@ end
 
         # can't specify dispersion for families without that parameter
         @test_throws ArgumentError parametricbootstrap(StableRNG(42), 100, gm0;
-                                                       σ=2, hide_progress=true)
+                                                       σ=2, progress=false)
         @test sum(issingular(bs)) == 0
     end
 end
 
 @testset "CI method comparison" begin
     fmzc = models(:sleepstudy)[2]
     level = 0.68
-    pb = parametricbootstrap(MersenneTwister(42), 500, fmzc; hide_progress=true)
+    pb = parametricbootstrap(MersenneTwister(42), 500, fmzc; progress=false)
     pr = profile(fmzc)
     ci_boot = confint(pb; level)
     ci_wald = confint(fmzc; level)

test/utilities.jl

@@ -39,8 +39,9 @@ end
 	@test isconstant(Union{Int,Missing}[missing, missing, missing])
 end
 
-@testset "threaded_replicate" begin
+@testset "replicate" begin
 	@test_logs (:warn, r"use_threads is deprecated") replicate(string, 1; use_threads=true)
+	@test_logs (:warn, r"hide_progress") replicate(string, 1; hide_progress=true)
 end
 
 @testset "datasets" begin