diff --git a/README.Rmd b/README.Rmd index b70fbcb..39de11d 100644 --- a/README.Rmd +++ b/README.Rmd @@ -51,7 +51,8 @@ devtools::install_github("tylermorganwall/skpr") * `eval_design_mc()` evaluates power with a Monte Carlo simulation, for linear and generalized linear models. This function also supports calculating power for split-plot designs using REML. * `eval_design_survival_mc()` evaluates power with a Monte Carlo simulation, allowing the user to specify a point at which the data is censored. * `eval_design_custom_mc()` allows the user to import their own libraries and use the Monte Carlo framework provided by skpr to calculate power. -* `skprGUI()` and `skprGUIbrowser()` opens up the GUI in either R Studio or an external browser. +* `calculate_power_curves()` provides an interface to automate the generation and evaluation of designs to create power versus sample size and effect size curves. +* `skprGUI()` opens up the GUI in either RStudio or an external browser. If addition, the package offers two functions to generate common plots related to designs: @@ -60,7 +61,7 @@ If addition, the package offers two functions to generate common plots related t ##skprGUI -skprGUI provides an graphical user interface to access all of the main features of skpr. An interactive tutorial is provided to familiarize the user with the available functionality. Type `skprGUI()` or `skprGUIbrowser()` to begin. Screenshots: +`skprGUI()` provides an graphical user interface to access all of the main features of skpr. An interactive tutorial is provided to familiarize the user with the available functionality. Type `skprGUI()` to begin. Screenshots: @@ -98,11 +99,11 @@ eval_design_mc(design, effectsize=1.5) #Here, we also increase the number of simululations to improve the precision of the results. eval_design_mc(design, nsim=5000, glmfamily = "poisson", effectsize=c(2,6)) -#skpr was designed to operate with the pipe (%>%) in mind. +#skpr was designed to operate with the pipe (|>) in mind. #Here is an example of an entire design of experiments analysis in three lines: -expand.grid(temp = c(80,90,100), type = c("Kona","Java"), beansize = c("Large","Medium","Small")) %>% - gen_design(model = ~temp + type + beansize + beansize:type + I(temp^2), trials=24, optimality="I") %>% - eval_design_mc() +expand.grid(temp = c(80,90,100), type = c("Kona","Java"), beansize = c("Large","Medium","Small")) |> + gen_design(model = ~temp + type + beansize + beansize:type + I(temp^2), trials=24, optimality="I") |> + eval_design_mc(detailedoutput = TRUE) ``` diff --git a/README.md b/README.md index eb3b8c5..8dcbb25 100644 --- a/README.md +++ b/README.md @@ -17,17 +17,17 @@ Status](https://travis-ci.org/tylermorganwall/skpr.svg?branch=master)](https://t and evaluating optimal designs in R. Here is a sampling of what skpr offers: -- Generates and evaluates D, I, A, Alias, E, T, and G optimal designs, - as well as user-defined custom optimality criteria. -- Supports generation and evaluation of split/split-split/…/N-split - plot designs. -- Includes parametric and Monte Carlo power evaluation functions, and - supports calculating power for censored responses. -- Provides an extensible framework for the user to evaluate Monte - Carlo power using their own libraries. -- Includes a Shiny graphical user interface, skprGUI, that - auto-generates the R code used to create and evaluate the design to - improve ease-of-use and enhance reproducibility. +- Generates and evaluates D, I, A, Alias, E, T, and G optimal designs, + as well as user-defined custom optimality criteria. +- Supports generation and evaluation of split/split-split/…/N-split plot + designs. +- Includes parametric and Monte Carlo power evaluation functions, and + supports calculating power for censored responses. +- Provides an extensible framework for the user to evaluate Monte Carlo + power using their own libraries. +- Includes a Shiny graphical user interface, skprGUI, that + auto-generates the R code used to create and evaluate the design to + improve ease-of-use and enhance reproducibility. ## Installation @@ -42,36 +42,38 @@ devtools::install_github("tylermorganwall/skpr") ## Functions -- `gen_design()` generates optimal designs from a candidate set, given - a model and the desired number of runs. -- `eval_design()` evaluates power parametrically for linear models, - for normal and split-plot designs. -- `eval_design_mc()` evaluates power with a Monte Carlo simulation, - for linear and generalized linear models. This function also - supports calculating power for split-plot designs using REML. -- `eval_design_survival_mc()` evaluates power with a Monte Carlo - simulation, allowing the user to specify a point at which the data - is censored. -- `eval_design_custom_mc()` allows the user to import their own - libraries and use the Monte Carlo framework provided by skpr to - calculate power. -- `skprGUI()` and `skprGUIbrowser()` opens up the GUI in either R - Studio or an external browser. +- `gen_design()` generates optimal designs from a candidate set, given a + model and the desired number of runs. +- `eval_design()` evaluates power parametrically for linear models, for + normal and split-plot designs. +- `eval_design_mc()` evaluates power with a Monte Carlo simulation, for + linear and generalized linear models. This function also supports + calculating power for split-plot designs using REML. +- `eval_design_survival_mc()` evaluates power with a Monte Carlo + simulation, allowing the user to specify a point at which the data is + censored. +- `eval_design_custom_mc()` allows the user to import their own + libraries and use the Monte Carlo framework provided by skpr to + calculate power. +- `calculate_power_curves()` provides an interface to automate the + generation and evaluation of designs to create power versus sample + size and effect size curves. +- `skprGUI()` opens up the GUI in either RStudio or an external browser. If addition, the package offers two functions to generate common plots related to designs: -- `plot_correlations()` generates a color map of correlations between - variables. -- `plot_fds()` generates the fraction of design space plot for a given - design. +- `plot_correlations()` generates a color map of correlations between + variables. +- `plot_fds()` generates the fraction of design space plot for a given + design. \##skprGUI -skprGUI provides an graphical user interface to access all of the main -features of skpr. An interactive tutorial is provided to familiarize the -user with the available functionality. Type `skprGUI()` or -`skprGUIbrowser()` to begin. Screenshots: +`skprGUI()` provides an graphical user interface to access all of the +main features of skpr. An interactive tutorial is provided to +familiarize the user with the available functionality. Type `skprGUI()` +to begin. Screenshots: @@ -138,9 +140,12 @@ eval_design(design) #> 8 beansize1 parameter.power 0.5593966 #> 9 beansize2 parameter.power 0.5593966 #> ============Evaluation Info============ -#> • Alpha = 0.05 • Trials = 12 • Blocked = FALSE -#> • Evaluating Model = ~temp + type + beansize -#> • Anticipated Coefficients = c(1, 1, 1, 1, -1) +#> * Alpha = 0.05 * Trials = 12 * Blocked = FALSE +#> * Evaluating Model = ~temp + type + beansize +#> * Anticipated Coefficients = c(1, 1, 1, 1, -1) +#> * Contrasts = `contr.sum` +#> * Parameter Analysis Method = `lm(...)` +#> * Effect Analysis Method = `car::Anova(fit, type = "III")` #Evaluate power for the design using a Monte Carlo simulation. #Here, we set the effect size (here, the signal-to-noise ratio) to 1.5. @@ -156,9 +161,12 @@ eval_design_mc(design, effectsize=1.5) #> 8 beansize1 parameter.power.mc 0.359 #> 9 beansize2 parameter.power.mc 0.354 #> ===========Evaluation Info============ -#> • Alpha = 0.05 • Trials = 12 • Blocked = FALSE -#> • Evaluating Model = ~temp + type + beansize -#> • Anticipated Coefficients = c(0.750, 0.750, 0.750, 0.750, -0.750) +#> * Alpha = 0.05 * Trials = 12 * Blocked = FALSE +#> * Evaluating Model = ~temp + type + beansize +#> * Anticipated Coefficients = c(0.750, 0.750, 0.750, 0.750, -0.750) +#> * Contrasts = `contr.sum` +#> * Parameter Analysis Method = `lm(...)` +#> * Effect Analysis Method = `car::Anova(fit, type = "III")` #Evaluate power for the design using a Monte Carlo simulation, for a non-normal response. #Here, we also increase the number of simululations to improve the precision of the results. @@ -174,33 +182,55 @@ eval_design_mc(design, nsim=5000, glmfamily = "poisson", effectsize=c(2,6)) #> 8 beansize1 parameter.power.mc 0.8842 #> 9 beansize2 parameter.power.mc 0.7052 #> ============Evaluation Info============ -#> • Alpha = 0.05 • Trials = 12 • Blocked = FALSE -#> • Evaluating Model = ~temp + type + beansize -#> • Anticipated Coefficients = c(1.242, 0.549, 0.549, 0.549, -0.549) - -#skpr was designed to operate with the pipe (%>%) in mind. +#> * Alpha = 0.05 * Trials = 12 * Blocked = FALSE +#> * Evaluating Model = ~temp + type + beansize +#> * Anticipated Coefficients = c(1.242, 0.549, 0.549, 0.549, -0.549) +#> * Contrasts = `contr.sum` +#> * Parameter Analysis Method = `glm(..., family = "poisson")` +#> * Effect Analysis Method = `car::Anova(fit, type = "III")` + +#skpr was designed to operate with the pipe (|>) in mind. #Here is an example of an entire design of experiments analysis in three lines: -expand.grid(temp = c(80,90,100), type = c("Kona","Java"), beansize = c("Large","Medium","Small")) %>% - gen_design(model = ~temp + type + beansize + beansize:type + I(temp^2), trials=24, optimality="I") %>% - eval_design_mc() -#> parameter type power -#> 1 (Intercept) effect.power.mc 0.912 -#> 2 temp effect.power.mc 0.927 -#> 3 type effect.power.mc 0.997 -#> 4 beansize effect.power.mc 0.935 -#> 5 I(temp^2) effect.power.mc 0.637 -#> 6 type:beansize effect.power.mc 0.913 -#> 7 (Intercept) parameter.power.mc 0.912 -#> 8 temp parameter.power.mc 0.927 -#> 9 type1 parameter.power.mc 0.997 -#> 10 beansize1 parameter.power.mc 0.917 -#> 11 beansize2 parameter.power.mc 0.913 -#> 12 I(temp^2) parameter.power.mc 0.637 -#> 13 type1:beansize1 parameter.power.mc 0.899 -#> 14 type1:beansize2 parameter.power.mc 0.902 -#> ==============Evaluation Info============== -#> • Alpha = 0.05 • Trials = 24 • Blocked = FALSE -#> • Evaluating Model = ~temp + type + beansize + type:beansize + I(temp^2) -#> • Anticipated Coefficients = c(1, 1, 1, 1, -1, 1, 1, -1) +expand.grid(temp = c(80,90,100), type = c("Kona","Java"), beansize = c("Large","Medium","Small")) |> + gen_design(model = ~temp + type + beansize + beansize:type + I(temp^2), trials=24, optimality="I") |> + eval_design_mc(detailedoutput = TRUE) +#> parameter type power anticoef alpha glmfamily trials +#> 1 (Intercept) effect.power.mc 0.912 NA 0.05 gaussian 24 +#> 2 temp effect.power.mc 0.927 NA 0.05 gaussian 24 +#> 3 type effect.power.mc 0.997 NA 0.05 gaussian 24 +#> 4 beansize effect.power.mc 0.935 NA 0.05 gaussian 24 +#> 5 I(temp^2) effect.power.mc 0.637 NA 0.05 gaussian 24 +#> 6 type:beansize effect.power.mc 0.913 NA 0.05 gaussian 24 +#> 7 (Intercept) parameter.power.mc 0.912 1 0.05 gaussian 24 +#> 8 temp parameter.power.mc 0.927 1 0.05 gaussian 24 +#> 9 type1 parameter.power.mc 0.997 1 0.05 gaussian 24 +#> 10 beansize1 parameter.power.mc 0.917 1 0.05 gaussian 24 +#> 11 beansize2 parameter.power.mc 0.913 -1 0.05 gaussian 24 +#> 12 I(temp^2) parameter.power.mc 0.637 1 0.05 gaussian 24 +#> 13 type1:beansize1 parameter.power.mc 0.899 1 0.05 gaussian 24 +#> 14 type1:beansize2 parameter.power.mc 0.902 -1 0.05 gaussian 24 +#> nsim blocking error_adjusted_alpha power_lcb power_ucb +#> 1 1000 FALSE 0.05 0.8927052 0.9288249 +#> 2 1000 FALSE 0.05 0.9090858 0.9423464 +#> 3 1000 FALSE 0.05 0.9912580 0.9993809 +#> 4 1000 FALSE 0.05 0.9178989 0.9494797 +#> 5 1000 FALSE 0.05 0.6063275 0.6668632 +#> 6 1000 FALSE 0.05 0.8937921 0.9297315 +#> 7 1000 FALSE 0.05 0.8927052 0.9288249 +#> 8 1000 FALSE 0.05 0.9090858 0.9423464 +#> 9 1000 FALSE 0.05 0.9912580 0.9993809 +#> 10 1000 FALSE 0.05 0.8981467 0.9333511 +#> 11 1000 FALSE 0.05 0.8937921 0.9297315 +#> 12 1000 FALSE 0.05 0.6063275 0.6668632 +#> 13 1000 FALSE 0.05 0.8786332 0.9169799 +#> 14 1000 FALSE 0.05 0.8818715 0.9197225 +#> =========================================================Evaluation Info========================================================== +#> * Alpha = 0.05 * Trials = 24 * Blocked = FALSE +#> * Evaluating Model = ~temp + type + beansize + type:beansize + I(temp^2) +#> * Anticipated Coefficients = c(1, 1, 1, 1, -1, 1, 1, -1) +#> * Contrasts = `contr.sum` +#> * Parameter Analysis Method = `lm(...)` +#> * Effect Analysis Method = `car::Anova(fit, type = "III")` +#> * MC Power CI Confidence = 95% ```