├── .Rbuildignore ├── .Rprofile ├── .github ├── .gitignore └── workflows │ ├── checks.yml │ ├── pkgdown.yaml │ └── tests.yml ├── .gitignore ├── .travis.yml ├── DESCRIPTION ├── Makefile ├── NAMESPACE ├── NEWS.md ├── R ├── AnalyseIf.R ├── Attach.R ├── Bradley1978.R ├── Design.R ├── GenerateIf.R ├── PBA.R ├── RobbinsMonro.R ├── SFA.R ├── Serlin2000.R ├── SimAnova.R ├── SimBoot.R ├── SimCheck.R ├── SimClean.R ├── SimCollect.R ├── SimDesign.R ├── SimExtract.R ├── SimFunctions.R ├── SimResults.R ├── SimShiny.R ├── SimSolve.R ├── addMissing.R ├── analysis.R ├── bootPredict.R ├── functions.R ├── getArrayID.R ├── manageMessages.R ├── manageWarnings.R ├── notifications.R ├── rbind.SimDesign.R ├── reSummarise.R ├── rejectionSampling.R ├── rgenerate.R ├── rtruncate.R ├── runArraySimulation.R ├── runSimulation.R ├── summary_functions.R ├── util.R └── zzz.R ├── README.md ├── SimDesign-logo.png ├── SimDesign.Rproj ├── _pkgdown.yml ├── data ├── BF_sim.RData └── BF_sim_alternative.RData ├── inst └── CITATION ├── man ├── Analyse.Rd ├── AnalyseIf.Rd ├── Attach.Rd ├── BF_sim.Rd ├── BF_sim_alternative.Rd ├── Bradley1978.Rd ├── CC.Rd ├── ECR.Rd ├── EDR.Rd ├── Generate.Rd ├── GenerateIf.Rd ├── IRMSE.Rd ├── MAE.Rd ├── MSRSE.Rd ├── PBA.Rd ├── RAB.Rd ├── RD.Rd ├── RE.Rd ├── RMSE.Rd ├── RSE.Rd ├── RobbinsMonro.Rd ├── SFA.Rd ├── Serlin2000.Rd ├── SimAnova.Rd ├── SimCheck.Rd ├── SimClean.Rd ├── SimCollect.Rd ├── SimDesign.Rd ├── SimExtract.Rd ├── SimFunctions.Rd ├── SimResults.Rd ├── SimShiny.Rd ├── SimSolve.Rd ├── Summarise.Rd ├── addMissing.Rd ├── bias.Rd ├── bootPredict.Rd ├── clusterSetRNGSubStream.Rd ├── colVars.Rd ├── createDesign.Rd ├── expandDesign.Rd ├── expandReplications.Rd ├── genSeeds.Rd ├── getArrayID.Rd ├── listAvailableNotifiers.Rd ├── manageMessages.Rd ├── manageWarnings.Rd ├── nc.Rd ├── new_PushbulletNotifier.Rd ├── new_TelegramNotifier.Rd ├── notify.PushbulletNotifier.Rd ├── notify.Rd ├── notify.TelegramNotifier.Rd ├── quiet.Rd ├── rHeadrick.Rd ├── rValeMaurelli.Rd ├── rbind.SimDesign.Rd ├── reSummarise.Rd ├── rejectionSampling.Rd ├── rint.Rd ├── rinvWishart.Rd ├── rmgh.Rd ├── rmvnorm.Rd ├── rmvt.Rd ├── rtruncate.Rd ├── runArraySimulation.Rd ├── runSimulation.Rd └── timeFormater.Rd ├── tests └── tests │ ├── archive │ └── test-notifications.R │ ├── mpi │ ├── mpi.sh │ ├── simulation.R │ ├── slurm.slurm │ ├── slurm_par.slurm │ ├── slurm_test.R │ └── slurm_test_par.R │ ├── test-01-core.R │ ├── test-02-aggregate.R │ └── test-03-array.R └── vignettes ├── Catch_errors.Rmd ├── Fixed_obj_fun.Rmd ├── HPC-computing.Rmd ├── MultipleAnalyses.Rmd ├── Parallel-computing.Rmd ├── Saving-results.Rmd └── SimDesign-intro.Rmd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^SimDesign-logo\.png$ 4 | .Rprofile 5 | Makefile 6 | ^\.travis\.yml$ 7 | ^_pkgdown\.yml$ 8 | ^docs$ 9 | ^pkgdown$ 10 | ^\.github$ 11 | -------------------------------------------------------------------------------- /.Rprofile: -------------------------------------------------------------------------------- 1 | 2 | .First <- function(){ 3 | require(devtools, quietly=TRUE, warn.conflicts=FALSE) 4 | require(testthat, quietly=TRUE, warn.conflicts=FALSE) 5 | } 6 | 7 | # .Last <- function(){ 8 | # cat("\nGoodbye at ", date(), "\n") 9 | # } 10 | -------------------------------------------------------------------------------- /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /.github/workflows/checks.yml: -------------------------------------------------------------------------------- 1 | name: R-CMD-CHECK 2 | 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | workflow_dispatch: 9 | 10 | jobs: 11 | R-CMD-CHECK: 12 | runs-on: ubuntu-latest 13 | 14 | container: 15 | image: ghcr.io/philchalmers/container-simdesign:latest 16 | 17 | steps: 18 | - name: Check out the repository 19 | uses: actions/checkout@v4 20 | 21 | - name: R CMD CHECK 22 | run: | 23 | Rscript -e 'devtools::check(error_on = "warning")' 24 | -------------------------------------------------------------------------------- /.github/workflows/pkgdown.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | release: 9 | types: [published] 10 | workflow_dispatch: 11 | 12 | name: pkgdown 13 | 14 | permissions: read-all 15 | 16 | jobs: 17 | pkgdown: 18 | runs-on: ubuntu-latest 19 | # Only restrict concurrency for non-PR jobs 20 | concurrency: 21 | group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} 22 | env: 23 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 24 | permissions: 25 | contents: write 26 | steps: 27 | - uses: actions/checkout@v4 28 | 29 | - uses: r-lib/actions/setup-pandoc@v2 30 | 31 | - uses: r-lib/actions/setup-r@v2 32 | with: 33 | use-public-rspm: true 34 | 35 | - uses: r-lib/actions/setup-r-dependencies@v2 36 | with: 37 | extra-packages: any::pkgdown, local::. 38 | needs: website 39 | 40 | - name: Build site 41 | run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) 42 | shell: Rscript {0} 43 | 44 | - name: Deploy to GitHub pages 🚀 45 | if: github.event_name != 'pull_request' 46 | uses: JamesIves/github-pages-deploy-action@v4.5.0 47 | with: 48 | clean: false 49 | branch: gh-pages 50 | folder: docs 51 | -------------------------------------------------------------------------------- /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: Tests (Ubuntu-latest) 2 | 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | workflow_dispatch: 9 | 10 | jobs: 11 | Run-Tests: 12 | runs-on: ubuntu-latest 13 | 14 | container: 15 | image: ghcr.io/philchalmers/container-simdesign:latest 16 | 17 | steps: 18 | - name: Check out the repository 19 | uses: actions/checkout@v4 20 | 21 | - name: Run tests 22 | run: | 23 | Rscript -e 'options(warnPartialMatchDollar = TRUE); Sys.setenv("_R_CHECK_LENGTH_1_CONDITION_" = "TRUE", "_R_CHECK_LENGTH_1_LOGIC2_" = "TRUE"); devtools::test(stop_on_failure = TRUE)' 24 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | inst/doc/*_cache/ 5 | inst/doc/*_files/ 6 | inst/doc/*.html 7 | docs 8 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | # R for travis: see documentation at https://docs.travis-ci.com/user/languages/r 2 | 3 | language: R 4 | sudo: false 5 | cache: packages 6 | warnings_are_errors: true 7 | 8 | r: 9 | - devel 10 | 11 | notifications: 12 | email: 13 | on_success: change 14 | on_failure: change 15 | 16 | before_install: 17 | - sudo apt-get -qq update 18 | - sudo apt-get install -y openmpi-common openmpi-bin libopenmpi-dev libgsl-dev 19 | 20 | r_packages: 21 | - devtools 22 | - testthat 23 | - extraDistr 24 | - copula 25 | 26 | r_build_args: "--no-build-vignettes" 27 | r_check_args: "--no-build-vignettes --as-cran" 28 | 29 | script: 30 | - make install 31 | - make check 32 | - make test 33 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: SimDesign 2 | Title: Structure for Organizing Monte Carlo Simulation Designs 3 | Version: 2.19.3 4 | Authors@R: c(person("Phil", "Chalmers", email = "rphilip.chalmers@gmail.com", role = c("aut", "cre"), 5 | comment = c(ORCID="0000-0001-5332-2810")), 6 | person("Matthew", "Sigal", role = c("ctb")), 7 | person("Ogreden", family="Oguzhan", role = c("ctb")), 8 | person("Mikko ", family="Ronkko", role = c("ctb")), 9 | person("Moritz", family="Ketzer", role = c("ctb"))) 10 | Description: Provides tools to safely and efficiently organize and execute 11 | Monte Carlo simulation experiments in R. 12 | The package controls the structure and back-end of Monte Carlo simulation experiments 13 | by utilizing a generate-analyse-summarise workflow. The workflow safeguards against 14 | common simulation coding issues, such as automatically re-simulating non-convergent results, 15 | prevents inadvertently overwriting simulation files, catches error and warning messages 16 | during execution, implicitly supports parallel processing with high-quality random number 17 | generation, and provides tools for managing high-performance computing (HPC) array jobs 18 | submitted to schedulers such as SLURM. For a pedagogical introduction to the package see 19 | Sigal and Chalmers (2016) . For a more in-depth overview of 20 | the package and its design philosophy see Chalmers and Adkins (2020) . 21 | VignetteBuilder: knitr 22 | Depends: 23 | R (>= 4.1.0) 24 | Imports: 25 | methods, 26 | testthat, 27 | parallel, 28 | parallelly, 29 | dplyr, 30 | sessioninfo, 31 | beepr, 32 | pbapply (>= 1.3-0), 33 | future, 34 | future.apply, 35 | progressr, 36 | R.utils, 37 | stats 38 | Suggests: 39 | snow, 40 | knitr, 41 | ggplot2, 42 | tidyr, 43 | purrr, 44 | shiny, 45 | copula, 46 | extraDistr, 47 | renv, 48 | cli, 49 | job, 50 | future.batchtools, 51 | FrF2, 52 | rmarkdown, 53 | RPushbullet, 54 | httr 55 | License: GPL (>=2) 56 | ByteCompile: yes 57 | LazyData: true 58 | URL: http://philchalmers.github.io/SimDesign/, https://github.com/philchalmers/SimDesign/wiki 59 | RoxygenNote: 7.3.2 60 | Encoding: UTF-8 61 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | PKGNAME := $(shell sed -n "s/Package: *\([^ ]*\)/\1/p" DESCRIPTION) 2 | PKGVERS := $(shell sed -n "s/Version: *\([^ ]*\)/\1/p" DESCRIPTION) 3 | PKGSRC := $(shell basename `pwd`) 4 | 5 | all: install 6 | 7 | build: 8 | cd ..;\ 9 | R CMD build $(PKGSRC) 10 | 11 | install: 12 | cd ..;\ 13 | R CMD INSTALL $(PKGSRC) 14 | 15 | check: 16 | Rscript -e "devtools::check(document = FALSE, args = '--as-cran')" 17 | 18 | news: 19 | sed -e 's/^-/ -/' -e 's/^## *//' -e 's/^# //' NEWS 20 | 21 | pkgdown: 22 | Rscript -e "pkgdown::build_site()" 23 | 24 | test: 25 | Rscript -e "library('testthat',quietly=TRUE);library('SimDesign',quietly=TRUE);options(warn=2);test_dir('tests/tests')" 26 | 27 | clean: 28 | $(RM) ../$(PKGNAME)_$(PKGVERS).tar.gz 29 | $(RM) -r ../$(PKGNAME).Rcheck/ 30 | 31 | 32 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | S3method("[",Design) 4 | S3method(notify,PushbulletNotifier) 5 | S3method(notify,TelegramNotifier) 6 | S3method(plot,PBA) 7 | S3method(plot,RM) 8 | S3method(plot,SimSolve) 9 | S3method(print,Design) 10 | S3method(print,PBA) 11 | S3method(print,RM) 12 | S3method(print,SFA) 13 | S3method(print,SimDesign) 14 | S3method(rbind,SimDesign) 15 | S3method(summary,SimDesign) 16 | S3method(summary,SimSolve) 17 | export(AnalyseIf) 18 | export(Attach) 19 | export(Bradley1978) 20 | export(CC) 21 | export(ECR) 22 | export(EDR) 23 | export(ERR) 24 | export(GenerateIf) 25 | export(IRMSE) 26 | export(MAE) 27 | export(MSRSE) 28 | export(PBA) 29 | export(RAB) 30 | export(RD) 31 | export(RE) 32 | export(RMSD) 33 | export(RMSE) 34 | export(RSE) 35 | export(RobbinsMonro) 36 | export(SFA) 37 | export(Serlin2000) 38 | export(SimAnova) 39 | export(SimCheck) 40 | export(SimClean) 41 | export(SimCollect) 42 | export(SimExtract) 43 | export(SimFunctions) 44 | export(SimResults) 45 | export(SimShiny) 46 | export(SimSolve) 47 | export(addMissing) 48 | export(add_missing) 49 | export(aggregate_simulations) 50 | export(bias) 51 | export(bootPredict) 52 | export(boot_predict) 53 | export(clusterSetRNGSubStream) 54 | export(colSDs) 55 | export(colVars) 56 | export(createDesign) 57 | export(expandDesign) 58 | export(expandReplications) 59 | export(genSeeds) 60 | export(getArrayID) 61 | export(listAvailableNotifiers) 62 | export(manageMessages) 63 | export(manageWarnings) 64 | export(nc) 65 | export(new_PushbulletNotifier) 66 | export(new_TelegramNotifier) 67 | export(quiet) 68 | export(rHeadrick) 69 | export(rValeMaurelli) 70 | export(rbindDesign) 71 | export(reSummarise) 72 | export(rejectionSampling) 73 | export(rint) 74 | export(rinvWishart) 75 | export(rmgh) 76 | export(rmvnorm) 77 | export(rmvt) 78 | export(rtruncate) 79 | export(runArraySimulation) 80 | export(runSimulation) 81 | export(timeFormater) 82 | import(methods) 83 | import(parallel) 84 | import(stats) 85 | importFrom(R.utils,withTimeout) 86 | importFrom(beepr,beep) 87 | importFrom(dplyr,as_tibble) 88 | importFrom(dplyr,bind_rows) 89 | importFrom(dplyr,mutate) 90 | importFrom(dplyr,select) 91 | importFrom(future.apply,future_lapply) 92 | importFrom(graphics,abline) 93 | importFrom(parallelly,availableCores) 94 | importFrom(pbapply,pblapply) 95 | importFrom(pbapply,pboptions) 96 | importFrom(progressr,progressor) 97 | importFrom(sessioninfo,session_info) 98 | importFrom(testthat,capture_messages) 99 | importFrom(testthat,capture_output_lines) 100 | importFrom(utils,capture.output) 101 | importFrom(utils,flush.console) 102 | importFrom(utils,head) 103 | importFrom(utils,methods) 104 | importFrom(utils,object.size) 105 | importFrom(utils,packageVersion) 106 | importFrom(utils,recover) 107 | importFrom(utils,tail) 108 | -------------------------------------------------------------------------------- /R/AnalyseIf.R: -------------------------------------------------------------------------------- 1 | #' Perform a test that indicates whether a given \code{Analyse()} function should be executed 2 | #' 3 | #' This function is designed to prevent specific analysis function executions when the 4 | #' design conditions are not met. Primarily useful when the \code{analyse} argument to 5 | #' \code{\link{runSimulation}} was input as a named list object, however some of the 6 | #' analysis functions are not interesting/compatible with the generated data and should 7 | #' therefore be skipped. 8 | #' 9 | #' @param x logical statement to evaluate. If the statement evaluates to \code{TRUE} 10 | #' then the remainder of the defined function will be evaluated 11 | #' 12 | #' @param condition (optional) the current design condition. This does not need to be supplied 13 | #' if the expression in \code{x} evaluates to valid logical (e.g., use \code{Attach(condition)} 14 | #' prior to using \code{AnalyseIf}, or use \code{with(condition, AnalyseIf(someLogicalTest))}) 15 | #' 16 | #' @references 17 | #' 18 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 19 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 20 | #' \doi{10.20982/tqmp.16.4.p248} 21 | #' 22 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 23 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 24 | #' \doi{10.1080/10691898.2016.1246953} 25 | #' 26 | #' @export 27 | #' 28 | #' @seealso \code{\link{Analyse}}, \code{\link{runSimulation}} 29 | #' 30 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 31 | #' 32 | #' @examples 33 | #' \dontrun{ 34 | #' 35 | #' Design <- createDesign(N=c(10,20,30), var.equal = c(TRUE, FALSE)) 36 | #' 37 | #' Generate <- function(condition, fixed_objects) { 38 | #' Attach(condition) 39 | #' dat <- data.frame(DV = rnorm(N*2), IV = gl(2, N, labels=c('G1', 'G2'))) 40 | #' dat 41 | #' } 42 | #' 43 | #' # always run this analysis for each row in Design 44 | #' Analyse1 <- function(condition, dat, fixed_objects) { 45 | #' mod <- t.test(DV ~ IV, data=dat) 46 | #' mod$p.value 47 | #' } 48 | #' 49 | #' # Only perform analysis when variances are equal and N = 20 or 30 50 | #' Analyse2 <- function(condition, dat, fixed_objects) { 51 | #' AnalyseIf(var.equal && N %in% c(20, 30), condition) 52 | #' mod <- t.test(DV ~ IV, data=dat, var.equal=TRUE) 53 | #' mod$p.value 54 | #' } 55 | #' 56 | #' Summarise <- function(condition, results, fixed_objects) { 57 | #' ret <- EDR(results, alpha=.05) 58 | #' ret 59 | #' } 60 | #' 61 | #' #------------------------------------------------------------------- 62 | #' 63 | #' # append names 'Welch' and 'independent' to associated output 64 | #' res <- runSimulation(design=Design, replications=100, generate=Generate, 65 | #' analyse=list(Welch=Analyse1, independent=Analyse2), 66 | #' summarise=Summarise) 67 | #' res 68 | #' 69 | #' # leave results unnamed 70 | #' res <- runSimulation(design=Design, replications=100, generate=Generate, 71 | #' analyse=list(Analyse1, Analyse2), 72 | #' summarise=Summarise) 73 | #' 74 | #' 75 | #' } 76 | #' 77 | AnalyseIf <- function(x, condition = NULL){ 78 | e <- substitute(x) 79 | r <- eval(e, condition, parent.frame()) 80 | if (!is.logical(r) || length(r) != 1L) 81 | stop("AnalyseIf must return a single logical value", call.=FALSE) 82 | if(!isTRUE(r)) 83 | stop('ANALYSEIF RAISED ERROR', call.=FALSE) 84 | invisible(NULL) 85 | } 86 | -------------------------------------------------------------------------------- /R/Bradley1978.R: -------------------------------------------------------------------------------- 1 | #' Bradley's (1978) empirical robustness interval 2 | #' 3 | #' Robustness interval criteria for empirical detection rate estimates and 4 | #' empirical coverage estimates defined by Bradley (1978). 5 | #' See \code{\link{EDR}} and \code{\link{ECR}} to obtain such estimates. 6 | #' 7 | #' @param rate (optional) numeric vector containing the empirical detection 8 | #' rate(s) or empirical confidence interval estimates. 9 | #' If supplied a character vector with elements defined in 10 | #' \code{out.labels} or a logical vector will be returned indicating whether the 11 | #' detection rate estimate is considered 'robust'. 12 | #' 13 | #' When the input is an empirical coverage rate the argument \code{CI} must be 14 | #' set to \code{TRUE}. 15 | #' 16 | #' If this input is missing, the interval criteria will be printed to the console 17 | #' 18 | #' @param alpha Type I error rate to evaluated (default is .05) 19 | #' 20 | #' @param type character vector indicating the type of interval classification to use. 21 | #' Default is 'liberal', however can be 'stringent' to use Bradley's more 22 | #' stringent robustness criteria 23 | #' 24 | #' @param CI logical; should this robust interval be constructed on empirical detection 25 | #' rates (\code{FALSE}) or empirical coverage rates (\code{TRUE})? 26 | #' 27 | #' @param out.logical logical; should the output vector be TRUE/FALSE indicating whether 28 | #' the supplied empirical detection rate/CI should be considered "robust"? Default is 29 | #' FALSE, in which case the out.labels elements are used instead 30 | #' 31 | #' @param out.labels character vector of length three indicating the classification 32 | #' labels according to the desired robustness interval 33 | #' 34 | #' @param unname logical; apply \code{\link{unname}} to the results to remove any variable 35 | #' names? 36 | #' 37 | #' @seealso \code{\link{EDR}}, \code{\link{ECR}}, \code{\link{Serlin2000}} 38 | #' 39 | #' @references 40 | #' 41 | #' Bradley, J. V. (1978). Robustness? \emph{British Journal of Mathematical and 42 | #' Statistical Psychology, 31}, 144-152. 43 | #' 44 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 45 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 46 | #' \doi{10.20982/tqmp.16.4.p248} 47 | #' 48 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 49 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 50 | #' \doi{10.1080/10691898.2016.1246953} 51 | #' 52 | #' @export 53 | #' 54 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 55 | #' 56 | #' @examples 57 | #' 58 | #' # interval criteria used for empirical detection rates 59 | #' Bradley1978() 60 | #' Bradley1978(type = 'stringent') 61 | #' Bradley1978(alpha = .01, type = 'stringent') 62 | #' 63 | #' # intervals applied to empirical detection rate estimates 64 | #' edr <- c(test1 = .05, test2 = .027, test3 = .051, test4 = .076, test5 = .024) 65 | #' 66 | #' Bradley1978(edr) 67 | #' Bradley1978(edr, out.logical=TRUE) # is robust? 68 | #' 69 | #' ##### 70 | #' # interval criteria used for coverage estimates 71 | #' 72 | #' Bradley1978(CI = TRUE) 73 | #' Bradley1978(CI = TRUE, type = 'stringent') 74 | #' Bradley1978(CI = TRUE, alpha = .01, type = 'stringent') 75 | #' 76 | #' # intervals applied to empirical coverage rate estimates 77 | #' ecr <- c(test1 = .950, test2 = .973, test3 = .949, test4 = .924, test5 = .976) 78 | #' 79 | #' Bradley1978(ecr, CI=TRUE) 80 | #' Bradley1978(ecr, CI=TRUE, out.logical=TRUE) # is robust? 81 | #' 82 | Bradley1978 <- function(rate, alpha = .05, type = 'liberal', CI = FALSE, 83 | out.logical = FALSE, 84 | out.labels = c('conservative', 'robust', 'liberal'), 85 | unname = FALSE){ 86 | stopifnot(type %in% c('liberal', 'stringent')) 87 | stopifnot(length(alpha) == 1L) 88 | stopifnot(alpha <= 1 && alpha >= 0) 89 | if(type == 'stringent') bnds <- c(0.9, 1.1) 90 | if(type == 'liberal') bnds <- c(.5, 1.5) 91 | bounds <- bnds * alpha 92 | if(CI){ 93 | bounds <- sort(1 - bounds) 94 | out.labels <- c(out.labels[3L:1L]) 95 | } 96 | if(missing(rate)){ 97 | ret <- bounds 98 | names(ret) <- paste0(type, c('.lower', '.upper')) 99 | } else { 100 | if(is.data.frame(rate) || is.matrix(rate)) rate <- as.numeric(rate) 101 | stopifnot(all(rate <= 1 & rate >= 0)) 102 | if(out.logical){ 103 | ret <- rate >= bounds[1L] & rate <= bounds[2] 104 | } else { 105 | ret <- rep(out.labels[2], length(rate)) 106 | names(ret) <- names(rate) 107 | ret[rate < bounds[1L]] <- out.labels[1L] 108 | ret[rate > bounds[2L]] <- out.labels[3L] 109 | } 110 | if(unname) ret <- unname(ret) 111 | } 112 | ret 113 | } 114 | -------------------------------------------------------------------------------- /R/GenerateIf.R: -------------------------------------------------------------------------------- 1 | #' Perform a test that indicates whether a given \code{Generate()} function should be executed 2 | #' 3 | #' This function is designed to prevent specific generate function executions when the 4 | #' design conditions are not met. Primarily useful when the \code{generate} argument to 5 | #' \code{\link{runSimulation}} was input as a named list object, however should only be 6 | #' applied for some specific design condition (otherwise, the data generation moves to the 7 | #' next function in the list). 8 | #' 9 | #' @param x logical statement to evaluate. If the statement evaluates to \code{TRUE} 10 | #' then the remainder of the defined function will be evaluated 11 | #' 12 | #' @param condition (optional) the current design condition. This does not need to be supplied 13 | #' if the expression in \code{x} evaluates to valid logical (e.g., use \code{Attach(condition)} 14 | #' prior to using \code{AnalyseIf}, or use \code{with(condition, AnalyseIf(someLogicalTest))}) 15 | #' 16 | #' @references 17 | #' 18 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 19 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 20 | #' \doi{10.20982/tqmp.16.4.p248} 21 | #' 22 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 23 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 24 | #' \doi{10.1080/10691898.2016.1246953} 25 | #' 26 | #' @export 27 | #' 28 | #' @seealso \code{\link{Analyse}}, \code{\link{runSimulation}} 29 | #' 30 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 31 | #' 32 | #' @examples 33 | #' \dontrun{ 34 | #' 35 | #' # SimFunctions(nGenerate = 2) 36 | #' 37 | #' Design <- createDesign(N=c(10,20,30), var.equal = c(TRUE, FALSE)) 38 | #' 39 | #' Generate.G1 <- function(condition, fixed_objects) { 40 | #' GenerateIf(condition$var.equal == FALSE) # only run when unequal vars 41 | #' Attach(condition) 42 | #' dat <- data.frame(DV = c(rnorm(N), rnorm(N, sd=2)), 43 | #' IV = gl(2, N, labels=c('G1', 'G2'))) 44 | #' dat 45 | #' } 46 | #' 47 | #' Generate.G2 <- function(condition, fixed_objects) { 48 | #' Attach(condition) 49 | #' dat <- data.frame(DV = rnorm(N*2), IV = gl(2, N, labels=c('G1', 'G2'))) 50 | #' dat 51 | #' } 52 | #' 53 | #' # always run this analysis for each row in Design 54 | #' Analyse <- function(condition, dat, fixed_objects) { 55 | #' mod <- t.test(DV ~ IV, data=dat) 56 | #' mod$p.value 57 | #' } 58 | #' 59 | #' Summarise <- function(condition, results, fixed_objects) { 60 | #' ret <- EDR(results, alpha=.05) 61 | #' ret 62 | #' } 63 | #' 64 | #' #------------------------------------------------------------------- 65 | #' 66 | #' # append names 'Welch' and 'independent' to associated output 67 | #' res <- runSimulation(design=Design, replications=1000, 68 | #' generate=list(G1=Generate.G1, G2=Generate.G2), 69 | #' analyse=Analyse, 70 | #' summarise=Summarise) 71 | #' res 72 | #' 73 | #' } 74 | #' 75 | GenerateIf <- function(x, condition = NULL){ 76 | e <- substitute(x) 77 | r <- eval(e, condition, parent.frame()) 78 | if (!is.logical(r) || length(r) != 1L) 79 | stop("GenerateIf must return a single logical value", call.=FALSE) 80 | if(!isTRUE(r)) 81 | stop('GENERATEIF RAISED ERROR', call.=FALSE) 82 | invisible(NULL) 83 | } 84 | -------------------------------------------------------------------------------- /R/Serlin2000.R: -------------------------------------------------------------------------------- 1 | #' Empirical detection robustness method suggested by Serlin (2000) 2 | #' 3 | #' Hypothesis test to determine whether an observed empirical detection rate, 4 | #' coupled with a given robustness interval, statistically differs from the 5 | #' population value. Uses the methods described by Serlin (2000) as well to 6 | #' generate critical values (similar to confidence intervals, but define a fixed 7 | #' window of robustness). Critical values may be computed without performing the simulation 8 | #' experiment (hence, can be obtained a priori). 9 | #' 10 | #' @param p (optional) a vector containing the empirical detection rate(s) to be tested. 11 | #' Omitting this input will compute only the CV1 and CV2 values, while including this 12 | #' input will perform a one-sided hypothesis test for robustness 13 | #' 14 | #' @param R number of replications used in the simulation 15 | #' 16 | #' @param alpha Type I error rate (e.g., often set to .05) 17 | #' 18 | #' @param delta (optional) symmetric robustness interval around \code{alpha} (e.g., a value 19 | #' of .01 when \code{alpha = .05} would test the robustness window .04-.06) 20 | #' 21 | #' @param CI confidence interval for \code{alpha} as a proportion. Default of 0.95 22 | #' indicates a 95\% interval 23 | #' 24 | #' @references 25 | #' 26 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 27 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 28 | #' \doi{10.20982/tqmp.16.4.p248} 29 | #' 30 | #' Serlin, R. C. (2000). Testing for Robustness in Monte Carlo Studies. 31 | #' \emph{Psychological Methods, 5}, 230-240. 32 | #' 33 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 34 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 35 | #' \doi{10.1080/10691898.2016.1246953} 36 | #' 37 | #' @export 38 | #' 39 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 40 | #' 41 | #' @examples 42 | #' 43 | #' # Cochran's criteria at alpha = .05 (i.e., 0.5 +- .01), assuming N = 2000 44 | #' Serlin2000(p = .051, alpha = .05, delta = .01, R = 2000) 45 | #' 46 | #' # Bradley's liberal criteria given p = .06 and .076, assuming N = 1000 47 | #' Serlin2000(p = .060, alpha = .05, delta = .025, R = 1000) 48 | #' Serlin2000(p = .076, alpha = .05, delta = .025, R = 1000) 49 | #' 50 | #' # multiple p-values 51 | #' Serlin2000(p = c(.05, .06, .07), alpha = .05, delta = .025, R = 1000) 52 | #' 53 | #' # CV values computed before simulation performed 54 | #' Serlin2000(alpha = .05, R = 2500) 55 | #' 56 | Serlin2000 <- function(p, alpha, delta, R, CI = .95){ 57 | stopifnot(!missing(alpha)) 58 | stopifnot(!missing(R)) 59 | cs <- c(2, 1) 60 | if(alpha > .5) cs <- c(1, 2) 61 | z_crit <- abs(qnorm((1 - CI)/cs[1L])) 62 | fn <- function(val){ 63 | crit <- abs(val - alpha) / sqrt(val * (1 - val) / R) 64 | crit - z_crit 65 | } 66 | CV1 <- uniroot(fn, interval = c(0, alpha))$root 67 | z_crit <- abs(qnorm((1 - CI)/cs[2L])) 68 | CV2 <- uniroot(fn, interval = c(alpha, 1 - 1e-10))$root 69 | if(!missing(p)){ 70 | stopifnot(!missing(delta)) 71 | sigma2 <- alpha * (1 - alpha) / R 72 | crit <- (abs(p - alpha) - delta) / sqrt(sigma2) 73 | crit_p <- pnorm(abs(crit), lower.tail = FALSE) # one-tailed test 74 | robust <- ifelse(crit_p > .1, "no", 75 | ifelse(crit_p > .05, "maybe", "yes")) 76 | ret <- data.frame("p" = p, 77 | "z(|p-a| - d))" = crit, 78 | "Pr(>|z|)" = crit_p, 79 | "robust" = robust, 80 | "CV1" = CV1, 81 | "CV2" = CV2, check.names = FALSE) 82 | } else { 83 | ret <- data.frame("CV1" = CV1, "CV2" = CV2) 84 | } 85 | ret 86 | } 87 | -------------------------------------------------------------------------------- /R/SimBoot.R: -------------------------------------------------------------------------------- 1 | SimBoot <- function(results, summarise, condition, fixed_objects, boot_method, 2 | boot_draws, CI) 3 | { 4 | boot_fun <- function(r, dat, N, studentized = FALSE){ 5 | pick <- rint(n = N, min = 1L, max = N) 6 | tmp <- if(!is.data.frame(dat)) dat[pick] 7 | else dat[pick, , drop=FALSE] 8 | ret <- summarise(results=tmp, condition=condition, fixed_objects=fixed_objects) 9 | if(studentized){ 10 | ret2 <- vector('list', 50) 11 | for(i in 1L:50L){ 12 | pick2 <- rint(n = N, min = 1L, max = N) 13 | tmp2 <- if(!is.data.frame(dat)) tmp[pick2] 14 | else tmp[pick2, , drop=FALSE] 15 | ret2[[i]] <- summarise(results=tmp2, condition=condition, fixed_objects=fixed_objects) 16 | } 17 | ret2 <- do.call(rbind, ret2) 18 | SEb <- colSDs(ret2) 19 | attr(ret, 'SEb') <- SEb 20 | } 21 | ret 22 | } 23 | 24 | stopifnot(boot_method %in% c('basic', 'percentile', 'norm', 'studentized', 'CLT')) 25 | replications <- if(is.data.frame(results)) nrow(results) else length(results) 26 | t0 <- summarise(condition=condition, results=results, fixed_objects=fixed_objects) 27 | if(boot_method %in% c('basic', 'percentile', 'norm')) 28 | t <- do.call(rbind, lapply(1L:boot_draws, boot_fun, dat=results, N=replications)) 29 | if(boot_method == 'basic'){ 30 | ql <- apply(t, 2L, quantile, prob = (1 - CI)/2) 31 | qu <- apply(t, 2L, quantile, prob = 1 - (1 - CI)/2) 32 | lower <- 2*t0 - qu 33 | upper <- 2*t0 - ql 34 | } else if(boot_method == 'percentile'){ 35 | lower <- apply(t, 2L, quantile, prob = (1 - CI)/2) 36 | upper <- apply(t, 2L, quantile, prob = 1 - (1 - CI)/2) 37 | } else if(boot_method == 'norm'){ 38 | SEs <- colSDs(t) 39 | lower <- t0 + qnorm((1 - CI)/2) * SEs 40 | upper <- t0 + qnorm(1 - (1 - CI)/2) * SEs 41 | } else if(boot_method == 'studentized'){ 42 | tf <- lapply(1L:boot_draws, boot_fun, dat=results, N=replications, studentized=TRUE) 43 | SEb <- do.call(rbind, lapply(tf, function(x) attr(x, 'SEb'))) 44 | t <- do.call(rbind, tf) 45 | SEs <- colSDs(t) 46 | qs <- (t - t0) / SEb 47 | ql <- apply(qs, 2L, quantile, prob = (1-CI)/2) 48 | qu <- apply(qs, 2L, quantile, prob = 1 - (1-CI)/2) 49 | lower <- t0 + ql * SEs 50 | upper <- t0 + qu * SEs 51 | } else if(boot_method == 'CLT'){ 52 | SEs <- colSDs(results) / sqrt(replications) 53 | ql <- qnorm((1-CI)/2) 54 | qu <- qnorm(1 - (1-CI)/2) 55 | lower <- t0 + ql * SEs 56 | upper <- t0 + qu * SEs 57 | } 58 | CIs <- as.vector(rbind(lower, upper)) 59 | names(CIs) <- paste0(as.vector(sapply(paste0(ifelse(boot_method != 'CLT', "BOOT_", "CI_"), 60 | names(t0), "_"), function(x) 61 | paste0(x, c( (1 - CI)/2 * 100, (1 - (1 - CI)/2)*100))))) 62 | CIs 63 | } 64 | -------------------------------------------------------------------------------- /R/SimCheck.R: -------------------------------------------------------------------------------- 1 | #' Check for missing files in array simulations 2 | #' 3 | #' Given the saved files from a \code{\link{runArraySimulation}} remote 4 | #' evaluation check whether all \code{.rds} files have been saved. If missing 5 | #' the missing row condition numbers will be returned. 6 | #' 7 | #' @param dir character vector input indicating the directory 8 | #' containing the \code{.rds} files (see \code{files}) 9 | #' 10 | #' @param files vector of file names referring to the saved simulation files. 11 | #' E.g. \code{c('mysim-1.rds', 'mysim-2.rds', ...)} 12 | #' 13 | #' @param min minimum number after the \code{'-'} deliminator. Default is 1 14 | #' 15 | #' @param max maximum number after the \code{'-'} deliminator. If not specified 16 | #' is extracted from the attributes in the first file 17 | #' 18 | #' @seealso \code{\link{runArraySimulation}}, \code{\link{SimCollect}} 19 | #' 20 | #' @return returns an invisible list of indices of empty, missing and 21 | #' empty-and-missing row conditions. If no missing then an empty list is 22 | #' returned 23 | #' 24 | #' @references 25 | #' 26 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 27 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 28 | #' \doi{10.20982/tqmp.16.4.p248} 29 | #' 30 | #' @export 31 | #' 32 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 33 | #' 34 | #' @examples 35 | #' \dontrun{ 36 | #' 37 | #' # if files are in mysimfiles/ directory 38 | #' SimCheck('mysimfiles') 39 | #' 40 | #' # specifying files explicility 41 | #' setwd('mysimfiles/') 42 | #' SimCheck(files=dir()) 43 | #' 44 | #' } 45 | #' 46 | SimCheck <- function(dir = NULL, files = NULL, min = 1L, max = NULL){ 47 | if(is.null(dir) && is.null(files)) 48 | stop('either dir or files must be specified') 49 | if(!is.null(dir) && !is.null(files)) 50 | stop('dir OR files must be specified, not both') 51 | if(!is.null(dir)){ 52 | files <- dir(dir) 53 | } else dir <- './' 54 | files <- paste0(dir, files) 55 | filename <- strsplit(files[1], '-')[[1L]][1L] 56 | if(is.null(max)){ 57 | tmp <- readRDS(files[1]) 58 | max <- attr(tmp, 'extra_info')$number_of_conditions 59 | } 60 | minmax <- min:max 61 | mainlist <- paste0(filename, '-', minmax, '.rds') 62 | have <- mainlist %in% files 63 | notin <- !have 64 | names(have) <- mainlist 65 | ret <- list() 66 | if(any(notin)){ 67 | ret$Missing_Row_Conditions <- minmax[notin] 68 | warning(sprintf('The following row conditions were missing:\n%s\n', 69 | paste0(ret$Missing_Row_Conditions, collapse=','))) 70 | } 71 | empty_file <- (sapply(names(have)[have], file.size, USE.NAMES = FALSE) == 0) 72 | if(any(empty_file)) { 73 | ret$Empty_Row_Conditions <- minmax[empty_file] 74 | warning(sprintf('The following row conditions have nothing saved:\n%s\n', 75 | paste0(ret$Empty_Row_Conditions, collapse=','))) 76 | } 77 | if(any(notin) || any(empty_file)){ 78 | ret$Empty_Missing_Row_Conditions <- c(minmax[notin], minmax[empty_file]) |> 79 | unique() |> 80 | sort() 81 | } 82 | 83 | invisible(ret) 84 | } 85 | -------------------------------------------------------------------------------- /R/SimClean.R: -------------------------------------------------------------------------------- 1 | #' Removes/cleans files and folders that have been saved 2 | #' 3 | #' This function is mainly used in pilot studies where results and datasets have been temporarily saved 4 | #' by \code{\link{runSimulation}} but should be removed before beginning the full 5 | #' Monte Carlo simulation (e.g., remove files and folders which contained bugs/biased results). 6 | #' 7 | #' @param ... one or more character objects indicating which files to remove. Used to remove 8 | #' \code{.rds} files which were saved with \code{\link{saveRDS}} or when using the \code{save} 9 | #' and \code{filename} inputs to \code{\link{runSimulation}} 10 | #' 11 | #' @param dirs a character vector indicating which directories to remove 12 | #' 13 | # @param generate_data logical; remove the \code{.rds} data-set files 14 | # saved when passing \code{save_generate_data = TRUE}? 15 | #' 16 | #' @param results logical; remove the \code{.rds} results files 17 | #' saved when passing \code{save_results = TRUE}? 18 | #' 19 | #' @param seeds logical; remove the seed files 20 | #' saved when passing \code{save_seeds = TRUE}? 21 | #' 22 | #' @param temp logical; remove the temporary file saved when passing \code{save = TRUE}? 23 | #' 24 | #' @param save_details a list pertaining to information about how and where files were saved 25 | #' (see the corresponding list in \code{\link{runSimulation}}) 26 | #' 27 | #' @seealso \code{\link{runSimulation}} 28 | #' @references 29 | #' 30 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 31 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 32 | #' \doi{10.20982/tqmp.16.4.p248} 33 | #' 34 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 35 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 36 | #' \doi{10.1080/10691898.2016.1246953} 37 | #' 38 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 39 | #' 40 | #' @export 41 | #' 42 | #' @examples 43 | #' \dontrun{ 44 | #' 45 | #' # remove file called 'results.rds' 46 | #' SimClean('results.rds') 47 | #' 48 | #' # remove default temp file 49 | #' SimClean() 50 | #' 51 | #' # remove customized saved-results directory called 'mydir' 52 | #' SimClean(results = TRUE, save_details = list(save_results_dirname = 'mydir')) 53 | #' 54 | #' } 55 | SimClean <- function(..., dirs = NULL, temp = TRUE, results = FALSE, 56 | seeds = FALSE, save_details = list()){ 57 | generate_data <- FALSE 58 | compname <- save_details$compname; tmpfilename <- save_details$tmpfilename 59 | out_rootdir <- save_details$out_rootdir 60 | if(!is.null(out_rootdir)){ 61 | gtw <- getwd() 62 | setwd(out_rootdir) 63 | } 64 | save_results_dirname <- save_details$save_results_dirname 65 | save_seeds_dirname <- save_details$save_seeds_dirname 66 | save_generate_data_dirname <- save_details$save_generate_data_dirname 67 | if(is.null(compname)) compname <- Sys.info()['nodename'] 68 | if(is.null(save_results_dirname)) 69 | save_results_dirname <- paste0('SimDesign-results_', compname) 70 | if(is.null(save_generate_data_dirname)) 71 | save_generate_data_dirname <- paste0('SimDesign-generate-data_', compname) 72 | files <- list(...) 73 | if(length(files)) file.remove(...) 74 | if(!is.null(dirs)) 75 | for(d in dirs) unlink(d, recursive = TRUE, force = TRUE) 76 | if(is.null(save_seeds_dirname)) save_seeds_dirname <- paste0('SimDesign-seeds_', compname) 77 | if(generate_data) unlink(save_generate_data_dirname, recursive = TRUE, force = TRUE) 78 | if(results) unlink(save_results_dirname, recursive = TRUE, force = TRUE) 79 | if(seeds) unlink(save_seeds_dirname, recursive = TRUE, force = TRUE) 80 | if(temp){ 81 | fs <- dir() 82 | file.remove(fs[grepl('SIMDESIGN-TEMPFILE_', fs)]) 83 | file.remove(fs[grepl('SIMSOLVE-TEMPFILE_', fs)]) 84 | } 85 | if(!is.null(out_rootdir)) setwd(gtw) 86 | invisible(NULL) 87 | } 88 | -------------------------------------------------------------------------------- /R/SimResults.R: -------------------------------------------------------------------------------- 1 | #' Function to read in saved simulation results 2 | #' 3 | #' If \code{\link{runSimulation}} was passed the flag \code{save_results = TRUE} then the 4 | #' row results corresponding to the \code{design} object will be stored to a suitable 5 | #' sub-directory as individual \code{.rds} files. While users could use \code{\link{readRDS}} directly 6 | #' to read these files in themselves, this convenience function will read the desired rows in 7 | #' automatically given the returned object 8 | #' from the simulation. Can be used to read in 1 or more \code{.rds} files at once (if more than 1 file 9 | #' is read in then the result will be stored in a list). 10 | #' 11 | #' @param obj object returned from \code{\link{runSimulation}} where \code{save_results = TRUE} 12 | #' or \code{store_results} was used. If the former then the remaining function arguments can 13 | #' be useful for reading in specific files 14 | #' 15 | #' @param which a numeric vector indicating which rows should be read in. If missing, all rows will be 16 | #' read in 17 | #' 18 | #' @param prefix character indicating prefix used for stored files 19 | #' 20 | #' @param wd working directory; default is found with \code{\link{getwd}}. 21 | #' 22 | #' @export 23 | #' 24 | #' @return the returned result is either a nested list (when \code{length(which) > 1}) or a single list 25 | #' (when \code{length(which) == 1}) containing the simulation results. Each read-in result refers to 26 | #' a list of 4 elements: 27 | #' \describe{ 28 | #' \item{\code{condition}}{the associate row (ID) and conditions from the 29 | #' respective \code{design} object} 30 | #' \item{\code{results}}{the object with returned from the \code{analyse} function, potentially 31 | #' simplified into a matrix or data.frame} 32 | #' \item{\code{errors}}{a table containing the message and number of errors that caused 33 | #' the generate-analyse steps to be rerun. These should be inspected carefully as they 34 | #' could indicate validity issues with the simulation that should be noted} 35 | #' \item{\code{warnings}}{a table containing the message and number of non-fatal warnings 36 | #' which arose from the analyse step. These should be inspected carefully as they 37 | #' could indicate validity issues with the simulation that should be noted} 38 | #' } 39 | #' 40 | #' @references 41 | #' 42 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 43 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 44 | #' \doi{10.20982/tqmp.16.4.p248} 45 | #' 46 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 47 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 48 | #' \doi{10.1080/10691898.2016.1246953} 49 | #' 50 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 51 | #' 52 | #' @examples 53 | #' 54 | #' \dontrun{ 55 | #' 56 | #' # store results (default behaviour) 57 | #' sim <- runSimulation(..., store_results = TRUE) 58 | #' SimResults(sim) 59 | #' 60 | #' # store results to drive if RAM issues are present 61 | #' obj <- runSimulation(..., save_results = TRUE) 62 | #' 63 | #' # row 1 results 64 | #' row1 <- SimResults(obj, 1) 65 | #' 66 | #' # rows 1:5, stored in a named list 67 | #' rows_1to5 <- SimResults(obj, 1:5) 68 | #' 69 | #' # all results 70 | #' rows_all <- SimResults(obj) 71 | #' 72 | #' } 73 | SimResults <- function(obj, which, prefix = "results-row", wd = getwd()){ 74 | stopifnot(!missing(obj)) 75 | results <- SimExtract(obj, what='results') 76 | if(!is.null(results)) return(results) 77 | wdold <- getwd() 78 | on.exit(setwd(wdold)) 79 | so <- summary(obj) 80 | if(missing(which)) which <- 1L:so$number_of_conditions 81 | path <- so$save_info["save_results_dirname"] 82 | if(is.na(path)) 83 | stop('results object was not run with save_results = TRUE') 84 | setwd(paste0(wd, '/', path)) 85 | files <- file_nums <- dir() 86 | file_nums <- gsub(paste0(prefix, '-'), '', file_nums) 87 | file_nums <- as.numeric(gsub('.rds', '', file_nums)) 88 | files <- data.frame(file_nums, files, stringsAsFactors = FALSE) 89 | stored_Results_list <- vector('list', length(which)) 90 | for(i in seq_len(length(which))){ 91 | pick <- which(files$file_num == which[i]) 92 | stored_Results_list[[i]] <- readRDS(files$files[pick]) 93 | } 94 | design <- SimExtract(obj, 'design') 95 | if(is(stored_Results_list[[1L]]$results, 'data.frame') || 96 | is(stored_Results_list[[1L]]$results, 'matrix')){ 97 | for(i in seq_len(length(stored_Results_list))) 98 | stored_Results_list[[i]] <- cbind(design[i,], 99 | stored_Results_list[[i]]$results, row.names=NULL) 100 | stored_Results_list <- dplyr::bind_rows(stored_Results_list) 101 | stored_Results_list$ID <- NULL 102 | stored_Results_list <- dplyr::as_tibble(stored_Results_list) 103 | } 104 | stored_Results_list 105 | } 106 | -------------------------------------------------------------------------------- /R/addMissing.R: -------------------------------------------------------------------------------- 1 | #' Add missing values to a vector given a MCAR, MAR, or MNAR scheme 2 | #' 3 | #' Given an input vector, replace elements of this vector with missing values according to some scheme. 4 | #' Default method replaces input values with a MCAR scheme (where on average 10\% of the values will be 5 | #' replaced with \code{NA}s). MAR and MNAR are supported by replacing the default \code{FUN} argument. 6 | #' 7 | #' Given an input vector y, and other relevant variables 8 | #' inside (X) and outside (Z) the data-set, the three types of missingness are: 9 | #' 10 | #' \describe{ 11 | #' \item{MCAR}{Missing completely at random (MCAR). This is realized by randomly 12 | #' sampling the values of the 13 | #' input vector (y) irrespective of the possible values in X and Z. 14 | #' Therefore missing values are randomly sampled and do not depend on any data characteristics and 15 | #' are truly random} 16 | #' \item{MAR}{Missing at random (MAR). This is realized when values in the dataset (X) 17 | #' predict the missing data mechanism in y; conceptually this is equivalent to 18 | #' \eqn{P(y = NA | X)}. This requires the user to define a custom missing data function} 19 | #' \item{MNAR}{Missing not at random (MNAR). This is similar to MAR except 20 | #' that the missing mechanism comes 21 | #' from the value of y itself or from variables outside the working dataset; 22 | #' conceptually this is equivalent to \eqn{P(y = NA | X, Z, y)}. This requires 23 | #' the user to define a custom missing data function} 24 | #' } 25 | #' 26 | #' @param y an input vector that should contain missing data in the form of \code{NA}'s 27 | #' 28 | #' @param fun a user defined function indicating the missing data mechanism for each element in \code{y}. 29 | #' Function must return a vector of probability values with the length equal to the length of \code{y}. 30 | #' Each value in the returned vector indicates the probability that 31 | #' the respective element in y will be replaced with \code{NA}. 32 | #' Function must contain the argument \code{y}, representing the 33 | #' input vector, however any number of additional arguments can be included 34 | #' 35 | #' @param ... additional arguments to be passed to \code{FUN} 36 | #' 37 | #' @return the input vector \code{y} with the sampled \code{NA} values 38 | #' (according to the \code{FUN} scheme) 39 | #' 40 | #' @aliases add_missing 41 | #' @references 42 | #' 43 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 44 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 45 | #' \doi{10.20982/tqmp.16.4.p248} 46 | #' 47 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 48 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 49 | #' \doi{10.1080/10691898.2016.1246953} 50 | #' 51 | #' @export 52 | #' 53 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 54 | #' 55 | #' @examples 56 | #' \dontrun{ 57 | #' 58 | #' set.seed(1) 59 | #' y <- rnorm(1000) 60 | #' 61 | #' ## 10% missing rate with default FUN 62 | #' head(ymiss <- addMissing(y), 10) 63 | #' 64 | #' ## 50% missing with default FUN 65 | #' head(ymiss <- addMissing(y, rate = .5), 10) 66 | #' 67 | #' ## missing values only when female and low 68 | #' X <- data.frame(group = sample(c('male', 'female'), 1000, replace=TRUE), 69 | #' level = sample(c('high', 'low'), 1000, replace=TRUE)) 70 | #' head(X) 71 | #' 72 | #' fun <- function(y, X, ...){ 73 | #' p <- rep(0, length(y)) 74 | #' p[X$group == 'female' & X$level == 'low'] <- .2 75 | #' p 76 | #' } 77 | #' 78 | #' ymiss <- addMissing(y, X, fun=fun) 79 | #' tail(cbind(ymiss, X), 10) 80 | #' 81 | #' ## missingness as a function of elements in X (i.e., a type of MAR) 82 | #' fun <- function(y, X){ 83 | #' # missingness with a logistic regression approach 84 | #' df <- data.frame(y, X) 85 | #' mm <- model.matrix(y ~ group + level, df) 86 | #' cfs <- c(-5, 2, 3) #intercept, group, and level coefs 87 | #' z <- cfs %*% t(mm) 88 | #' plogis(z) 89 | #' } 90 | #' 91 | #' ymiss <- addMissing(y, X, fun=fun) 92 | #' tail(cbind(ymiss, X), 10) 93 | #' 94 | #' ## missing values when y elements are large (i.e., a type of MNAR) 95 | #' fun <- function(y) ifelse(abs(y) > 1, .4, 0) 96 | #' ymiss <- addMissing(y, fun=fun) 97 | #' tail(cbind(y, ymiss), 10) 98 | #' 99 | #' } 100 | #' 101 | addMissing <- function(y, fun = function(y, rate = .1, ...) rep(rate, length(y)), ...){ 102 | if(!('y' %in% names(formals(fun)))) 103 | stop('fun must include a y argument') 104 | probs <- fun(y=y, ...) 105 | stopifnot(length(probs) == length(y)) 106 | stopifnot(all(probs >= 0 & probs <= 1)) 107 | is_na <- sapply(probs, function(p) sample(c(FALSE, TRUE), 1L, prob = c(1-p, p))) 108 | y[is_na] <- NA 109 | y 110 | } 111 | 112 | #' @export 113 | add_missing <- function(...){ 114 | .Deprecated('addMissing') 115 | addMissing(...) 116 | } 117 | -------------------------------------------------------------------------------- /R/getArrayID.R: -------------------------------------------------------------------------------- 1 | #' Get job array ID (e.g., from SLURM or other HPC array distributions) 2 | #' 3 | #' Get the array ID from an HPC array distribution job (e.g., from SLURM or 4 | #' from optional command line arguments). 5 | #' The array ID is used to index the rows in the design 6 | #' object in \code{\link{runArraySimulation}}. For instance, 7 | #' a SLURM array with 10 independent jobs might have the following shell 8 | #' instructions. 9 | #' 10 | #' \describe{ 11 | #' \item{\code{#!/bin/bash -l}}{} 12 | #' \item{\code{#SBATCH --time=00:01:00}}{} 13 | #' \item{\code{#SBATCH --array=1-10}}{} 14 | #' } 15 | #' 16 | #' which names the associated jobs with the numbers 1 through 10. 17 | #' \code{getArrayID()} then extracts this information per array, which 18 | #' is used as the \code{runArraySimulation(design, ..., arrayID = getArrayID())} to 19 | #' pass specific rows for the \code{design} object. 20 | #' 21 | #' @param type an integer indicating the element from the result of 22 | #' \code{\link{commandArgs}} to extract, or a \code{character} specifying the 23 | #' the type of. Default is \code{'slurm'} 24 | #' 25 | #' @param trailingOnly logical value passed to \code{\link{commandArgs}}. 26 | #' Only used when \code{type} is an integer 27 | #' 28 | #' @param ID.shift single integer value used to shift the array ID by a constant. 29 | #' Useful when there are array range limitation that must be specified in the 30 | #' shell files (e.g., array can only be 10000 but there are more rows 31 | #' in the \code{design} object). For example, if the array ID should be 10000 through 32 | #' 12000, but the cluster computer enviroment does not allow these indices, then 33 | #' including the arrange range as 1-2000 in the shell file with \code{shift=9999} 34 | #' would add this constant to the detected arrayID, thereby indexing the remaining 35 | #' row elements in the \code{design} object 36 | #' 37 | #' @export 38 | #' 39 | #' @seealso \code{\link{runArraySimulation}} 40 | #' 41 | #' @examples 42 | #' 43 | #' \dontrun{ 44 | #' 45 | #' # get slurm array ID 46 | #' arrayID <- getArrayID() 47 | #' 48 | #' # get ID based on first optional argument in shell specification 49 | #' arrayID <- getArrayID(type = 1) 50 | #' 51 | #' # pass to 52 | #' # runArraySimulation(design, ...., arrayID = arrayID) 53 | #' 54 | #' # increase detected arrayID by constant 9999 (for array 55 | #' specification limitations) 56 | #' arrayID <- getArrayID(ID.shift=9999) 57 | #' 58 | #' } 59 | #' 60 | getArrayID <- function(type = 'slurm', trailingOnly = TRUE, ID.shift = 0L){ 61 | stopifnot(length(type) == 1L) 62 | ret <- if(is.numeric(type)){ 63 | args <- commandArgs(trailingOnly = trailingOnly) 64 | args[as.integer(type)] 65 | } else if(type == 'slurm'){ 66 | Sys.getenv("SLURM_ARRAY_TASK_ID") 67 | } else { 68 | stop('type not supported') 69 | } 70 | ret <- as.integer(ret) 71 | if(is.na(ret)) warning("array ID is missing") 72 | ret + ID.shift 73 | } 74 | -------------------------------------------------------------------------------- /R/rbind.SimDesign.R: -------------------------------------------------------------------------------- 1 | #' Combine two separate SimDesign objects by row 2 | #' 3 | #' This function combines two Monte Carlo simulations executed by 4 | #' \code{SimDesign}'s \code{\link{runSimulation}} function which, for all 5 | #' intents and purposes, could have been executed in a single run. 6 | #' This situation arises when a simulation has been completed, however 7 | #' the \code{Design} object was later modified to include more levels in the 8 | #' defined simulation factors. Rather than re-executing the previously completed 9 | #' simulation combinations, only the new combinations need to be evaluated 10 | #' into a different object and then \code{rbind} together to create the complete 11 | #' object combinations. 12 | #' 13 | #' @param ... two or more \code{SimDesign} objects that should be 14 | #' combined by rows 15 | #' 16 | #' @return same object that is returned by \code{\link{runSimulation}} 17 | #' 18 | #' @references 19 | #' 20 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 21 | #' with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 22 | #' \doi{10.20982/tqmp.16.4.p248} 23 | #' 24 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 25 | #' Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 26 | #' \doi{10.1080/10691898.2016.1246953} 27 | #' 28 | #' @export 29 | #' 30 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 31 | #' 32 | #' @examples 33 | #' \dontrun{ 34 | #' 35 | #' # modified example from runSimulation() 36 | #' 37 | #' Design <- createDesign(N = c(10, 20), 38 | #' SD = c(1, 2)) 39 | #' 40 | #' Generate <- function(condition, fixed_objects) { 41 | #' dat <- with(condition, rnorm(N, 10, sd=SD)) 42 | #' dat 43 | #' } 44 | #' 45 | #' Analyse <- function(condition, dat, fixed_objects) { 46 | #' ret <- mean(dat) # mean of the sample data vector 47 | #' ret 48 | #' } 49 | #' 50 | #' Summarise <- function(condition, results, fixed_objects) { 51 | #' ret <- c(mu=mean(results), SE=sd(results)) # mean and SD summary of the sample means 52 | #' ret 53 | #' } 54 | #' 55 | #' Final1 <- runSimulation(design=Design, replications=1000, 56 | #' generate=Generate, analyse=Analyse, summarise=Summarise) 57 | #' Final1 58 | #' 59 | #' ### 60 | #' # later decide that N = 30 should have also been investigated. Rather than 61 | #' # running the following object .... 62 | #' newDesign <- createDesign(N = c(10, 20, 30), 63 | #' SD = c(1, 2)) 64 | #' 65 | #' # ... only the new subset levels are executed to save time 66 | #' subDesign <- subset(newDesign, N == 30) 67 | #' subDesign 68 | #' 69 | #' Final2 <- runSimulation(design=subDesign, replications=1000, 70 | #' generate=Generate, analyse=Analyse, summarise=Summarise) 71 | #' Final2 72 | #' 73 | #' # glue results together by row into one object as though the complete 'Design' 74 | #' # object were run all at once 75 | #' Final <- rbind(Final1, Final2) 76 | #' Final 77 | #' 78 | #' summary(Final) 79 | #' 80 | #' } 81 | rbind.SimDesign <- function(...){ 82 | dots <- list(...) 83 | stopifnot(all(sapply(dots, function(x) is(x, 'SimDesign')))) 84 | ret <- as.data.frame(dots[[1L]]) 85 | extra_info <- attr(dots[[1L]], 'extra_info') 86 | design_names <- attr(dots[[1L]], 'design_names') 87 | for(i in 2L:length(dots)){ 88 | ret <- dplyr::bind_rows(ret, as.data.frame(dots[[i]])) 89 | tmp_design_names <- attr(dots[[i]], 'design_names') 90 | tmp_extra_info <- attr(dots[[i]], 'extra_info') 91 | design_names$errors <- unique(design_names$errors, tmp_design_names$errors) 92 | design_names$warnings <- unique(design_names$warnings, tmp_design_names$warnings) 93 | extra_info$number_of_conditions <- extra_info$number_of_conditions + tmp_extra_info$number_of_conditions 94 | extra_info$total_elapsed_time <- extra_info$total_elapsed_time + tmp_extra_info$total_elapsed_time 95 | extra_info$error_seeds <- c(extra_info$error_seeds, tmp_extra_info$error_seeds) 96 | 97 | # throw warning if package versions differ 98 | lapply(extra_info$sessionInfo$otherPkgs, function(x, tmp){ 99 | if(x$Version != tmp$sessionInfo$otherPkgs[[x$Package]]$Version) 100 | warning(sprintf('Different "%s" package used across simulation objects (%s and %s).', 101 | x$Package, x$Version, tmp$sessionInfo$otherPkgs[[x$Package]]$Version), call.=FALSE) 102 | }, tmp=tmp_extra_info) 103 | } 104 | 105 | ret <- dplyr::as_tibble(ret) 106 | attr(ret, 'extra_info') <- extra_info 107 | attr(ret, 'design_names') <- design_names 108 | class(ret) <- c('SimDesign', class(ret)) 109 | ret 110 | } 111 | -------------------------------------------------------------------------------- /R/rtruncate.R: -------------------------------------------------------------------------------- 1 | #' Generate a random set of values within a truncated range 2 | #' 3 | #' Function generates data given a supplied random number generating function that 4 | #' are constructed to fall within a particular range. Sampled values outside this 5 | #' range are discarded and re-sampled until the desired criteria has been met. 6 | #' 7 | #' In simulations it is often useful to draw numbers from truncated distributions 8 | #' rather than across the full theoretical range. For instance, sampling parameters 9 | #' within the range [-4,4] from a normal distribution. The \code{rtruncate} 10 | #' function has been designed to accept any sampling function, where the first 11 | #' argument is the number of values to sample, and will draw values iteratively 12 | #' until the number of values within the specified bound are obtained. 13 | #' In situations where it is unlikely for the bounds to be located 14 | #' (e.g., sampling from a standard normal distribution where all values are 15 | #' within [-10,-6]) then the sampling scheme will throw an error if too many 16 | #' re-sampling executions are required (default will stop if more that 100 17 | #' calls to \code{rfun} are required). 18 | #' 19 | #' @param n number of observations to generate. This should be the first argument 20 | #' passed to \code{rfun} 21 | #' 22 | #' @param range a numeric vector of length two, where the first element 23 | #' indicates the lower bound and the second the upper bound. When values are 24 | #' generated outside these two bounds then data are redrawn until the bounded 25 | #' criteria is met. When the output of \code{rfun} is a matrix then this input 26 | #' can be specified as a matrix with two rows, where each the first row 27 | #' corresponds to the lower bound and the second row the upper bound for 28 | #' each generated column in the output 29 | #' 30 | #' @param rfun a function to generate random values. Function can return 31 | #' a numeric/integer vector or matrix, and additional arguments 32 | #' requred for this function are passed through the argument \code{...} 33 | #' 34 | #' @param ... additional arguments to be passed to \code{rfun} 35 | #' 36 | #' @param redraws the maximum number of redraws to take before terminating the 37 | #' iterative sequence. This is in place as a safety in case the \code{range} 38 | #' is too small given the random number generator, causing too many 39 | #' consecutive rejections. Default is 100 40 | #' 41 | #' @return either a numeric vector or matrix, where all values are within the 42 | #' desired \code{range} 43 | #' 44 | #' @seealso \code{\link{runSimulation}} 45 | #' @references 46 | #' 47 | #' Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable 48 | #' Monte Carlo Simulations with the SimDesign Package. 49 | #' \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 50 | #' \doi{10.20982/tqmp.16.4.p248} 51 | #' 52 | #' Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics 53 | #' with Monte Carlo simulation. \code{Journal of Statistics Education, 24}(3), 54 | #' 136-156. \doi{10.1080/10691898.2016.1246953} 55 | #' 56 | #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com} 57 | #' 58 | #' @export 59 | #' 60 | #' @examples 61 | #' 62 | #' # n = 1000 truncated normal vector between [-2,3] 63 | #' vec <- rtruncate(1000, rnorm, c(-2,3)) 64 | #' summary(vec) 65 | #' 66 | #' # truncated correlated multivariate normal between [-1,4] 67 | #' mat <- rtruncate(1000, rmvnorm, c(-1,4), 68 | #' sigma = matrix(c(2,1,1,1),2)) 69 | #' summary(mat) 70 | #' 71 | #' # truncated correlated multivariate normal between [-1,4] for the 72 | #' # first column and [0,3] for the second column 73 | #' mat <- rtruncate(1000, rmvnorm, cbind(c(-1,4), c(0,3)), 74 | #' sigma = matrix(c(2,1,1,1),2)) 75 | #' summary(mat) 76 | #' 77 | #' # truncated chi-square with df = 4 between [2,6] 78 | #' vec <- rtruncate(1000, rchisq, c(2,6), df = 4) 79 | #' summary(vec) 80 | #' 81 | rtruncate <- function(n, rfun, range, ..., redraws = 100L){ 82 | ret <- rfun(n, ...) 83 | stopifnot(is.numeric(ret)) 84 | is_matrix <- is.matrix(ret) 85 | if(is_matrix && !is.matrix(range)) 86 | range <- matrix(range, nrow=2L, ncol=ncol(ret)) 87 | draw <- 1L 88 | while(draw < redraws){ 89 | if(is_matrix){ 90 | pick <- sapply(1L:ncol(ret), function(i){ 91 | ret[,i] > range[2L, i] | ret[,i] < range[1L, i] 92 | }) 93 | pick <- rowSums(pick) > 0L 94 | if(!any(pick)) break 95 | ret[pick, ] <- rfun(sum(pick), ...) 96 | } else { 97 | pick <- ret > range[2L] | ret < range[1L] 98 | if(!any(pick)) break 99 | ret[pick] <- rfun(sum(pick), ...) 100 | } 101 | draw <- draw + 1L 102 | } 103 | if(draw == redraws) 104 | stop("rtruncate() redrew data too often and was terminated", 105 | call.=FALSE) 106 | ret 107 | } 108 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | .onAttach <- function(libname, pkgname) { 2 | if(interactive()) 3 | packageStartupMessage("See ?SimFunctions to get started with SimDesign") 4 | } 5 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![](http://www.r-pkg.org/badges/version/SimDesign)](https://www.r-pkg.org:443/pkg/SimDesign) [![](http://cranlogs.r-pkg.org/badges/grand-total/SimDesign)](https://CRAN.R-project.org/package=SimDesign) 2 | 3 | 4 | # SimDesign 5 | 6 | Structure for Organizing Monte Carlo Simulation Designs 7 | 8 | ## Installation 9 | 10 | To install the latest stable version of the package from CRAN, please use the following in your R console: 11 | 12 | ```r 13 | install.packages('SimDesign') 14 | ``` 15 | 16 | To install the Github version of the package with `devtools`, type the following (assuming you have already installed the `devtools` package from CRAN). 17 | 18 | ```r 19 | library('devtools') 20 | install_github('philchalmers/SimDesign') 21 | ``` 22 | 23 | ## Getting started 24 | 25 | For a description pertaining to the philosophy and general workflow of the package it is helpful to first read through the following: [Chalmers, R. Philip, Adkins, Mark C. (2020) Writing Effective and Reliable Monte Carlo Simulations with the SimDesign Package, The Quantitative Methods for Psychology, 16(4), 248-280. doi: 10.20982/tqmp.16.4.p248](https://www.tqmp.org/RegularArticles/vol16-4/p248/index.html) 26 | 27 | Coding examples found within this article range from relatively simple (e.g., a re-implementation of one of [Hallgren's (2013) simulation study examples](https://www.tqmp.org/RegularArticles/vol09-2/p043/index.html), as well as possible extensions to the simulation design) to more advanced real-world simulation experiments (e.g., [Flora and Curran's (2004) simulation study](https://doi.org/10.1037/1082-989X.9.4.466)). For additional information and instructions about how to use the package please refer to the examples in the associated [Github wiki](https://github.com/philchalmers/SimDesign/wiki). 28 | -------------------------------------------------------------------------------- /SimDesign-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/philchalmers/SimDesign/7aa26d4dbd833a80827a646f1e08387e258a99a9/SimDesign-logo.png -------------------------------------------------------------------------------- /SimDesign.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | ProjectId: fe769c1e-d77f-4cb0-8cc9-a5d4a1fc8243 3 | 4 | RestoreWorkspace: No 5 | SaveWorkspace: No 6 | AlwaysSaveHistory: Default 7 | 8 | EnableCodeIndexing: Yes 9 | UseSpacesForTab: Yes 10 | NumSpacesForTab: 4 11 | Encoding: UTF-8 12 | 13 | RnwWeave: knitr 14 | LaTeX: pdfLaTeX 15 | 16 | AutoAppendNewline: Yes 17 | StripTrailingWhitespace: Yes 18 | 19 | BuildType: Package 20 | PackageUseDevtools: Yes 21 | PackageInstallArgs: --no-multiarch --with-keep.source 22 | PackageRoxygenize: rd,collate,namespace 23 | -------------------------------------------------------------------------------- /_pkgdown.yml: -------------------------------------------------------------------------------- 1 | url: http://philchalmers.github.io/SimDesign/ 2 | template: 3 | bootstrap: 5 4 | 5 | -------------------------------------------------------------------------------- /data/BF_sim.RData: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/philchalmers/SimDesign/7aa26d4dbd833a80827a646f1e08387e258a99a9/data/BF_sim.RData -------------------------------------------------------------------------------- /data/BF_sim_alternative.RData: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/philchalmers/SimDesign/7aa26d4dbd833a80827a646f1e08387e258a99a9/data/BF_sim_alternative.RData -------------------------------------------------------------------------------- /inst/CITATION: -------------------------------------------------------------------------------- 1 | bibentry( 2 | header = "To cite SimDesign in publications use:", 3 | bibtype = "Article", 4 | title = "Writing effective and reliable {Monte Carlo} simulations with the {SimDesign} package", 5 | author = c(person(given = "R. Philip", 6 | family = "Chalmers", 7 | email = "rphilip.chalmers@gmail.com"), 8 | person(given = "Mark C.", 9 | family = "Adkins")), 10 | journal = "The Quantitative Methods for Psychology", 11 | year = "2020", 12 | volume = "16", 13 | number = "4", 14 | pages = "248--280", 15 | doi = "10.20982/tqmp.16.4.p248", 16 | 17 | textVersion = 18 | paste("R.\ Philip Chalmers & Adkins, M. C. (2020).", 19 | "Writing effective and reliable Monte Carlo simulations with the SimDesign package.", 20 | "The Quantitative Methods for Psychology, 16(4), 248-280.", 21 | "doi:10.20982/tqmp.16.4.p248") 22 | ) 23 | -------------------------------------------------------------------------------- /man/Analyse.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/functions.R 3 | \name{Analyse} 4 | \alias{Analyse} 5 | \title{Compute estimates and statistics} 6 | \usage{ 7 | Analyse(condition, dat, fixed_objects) 8 | } 9 | \arguments{ 10 | \item{condition}{a single row from the design input (as a \code{data.frame}), indicating the 11 | simulation conditions} 12 | 13 | \item{dat}{the \code{dat} object returned from the \code{\link{Generate}} function 14 | (usually a \code{data.frame}, \code{matrix}, \code{vector}, or \code{list})} 15 | 16 | \item{fixed_objects}{object passed down from \code{\link{runSimulation}}} 17 | } 18 | \value{ 19 | returns a named \code{numeric} vector or \code{data.frame} with the values of interest 20 | (e.g., p-values, effects sizes, etc), or a \code{list} containing values of interest 21 | (e.g., separate matrix and vector of parameter estimates corresponding to elements in 22 | \code{parameters}). If a \code{data.frame} is returned with more than 1 row then these 23 | objects will be wrapped into suitable \code{list} objects 24 | } 25 | \description{ 26 | Compute all relevant test statistics, parameter estimates, detection rates, and so on. 27 | This is the computational heavy lifting portion of the Monte Carlo simulation. Users 28 | may define a single Analysis function to perform all the analyses in the same function environment, 29 | or may define a \code{list} of named functions to \code{\link{runSimulation}} to allow for a more 30 | modularized approach to performing the analyses in independent blocks (but that share the same generated 31 | data). Note that if a suitable \code{\link{Generate}} function was not supplied then this function 32 | can be used to be generate and analyse the Monte Carlo data (though in general this 33 | setup is not recommended for larger simulations). 34 | } 35 | \details{ 36 | In some cases, it may be easier to change the output to a named \code{list} containing 37 | different parameter configurations (e.g., when 38 | determining RMSE values for a large set of population parameters). 39 | 40 | The use of \code{\link{try}} functions is generally not required in this function because \code{Analyse} 41 | is internally wrapped in a \code{\link{try}} call. Therefore, if a function stops early 42 | then this will cause the function to halt internally, the message which triggered the \code{\link{stop}} 43 | will be recorded, and \code{\link{Generate}} will be called again to obtain a different dataset. 44 | That said, it may be useful for users to throw their own \code{\link{stop}} commands if the data 45 | should be re-drawn for other reasons (e.g., an estimated model terminated correctly 46 | but the maximum number of iterations were reached). 47 | } 48 | \examples{ 49 | \dontrun{ 50 | 51 | analyse <- function(condition, dat, fixed_objects) { 52 | 53 | # require packages/define functions if needed, or better yet index with the :: operator 54 | require(stats) 55 | mygreatfunction <- function(x) print('Do some stuff') 56 | 57 | #wrap computational statistics in try() statements to control estimation problems 58 | welch <- t.test(DV ~ group, dat) 59 | ind <- stats::t.test(DV ~ group, dat, var.equal=TRUE) 60 | 61 | # In this function the p values for the t-tests are returned, 62 | # and make sure to name each element, for future reference 63 | ret <- c(welch = welch$p.value, 64 | independent = ind$p.value) 65 | 66 | return(ret) 67 | } 68 | 69 | # A more modularized example approach 70 | 71 | analysis_welch <- function(condition, dat, fixed_objects) { 72 | welch <- t.test(DV ~ group, dat) 73 | ret <- c(p=welch$p.value) 74 | ret 75 | } 76 | 77 | analysis_ind <- function(condition, dat, fixed_objects) { 78 | ind <- t.test(DV ~ group, dat, var.equal=TRUE) 79 | ret <- c(p=ind$p.value) 80 | ret 81 | } 82 | 83 | # pass functions as a named list 84 | # runSimulation(..., analyse=list(welch=analyse_welch, independent=analysis_ind)) 85 | 86 | } 87 | } 88 | \references{ 89 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 90 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 91 | \doi{10.20982/tqmp.16.4.p248} 92 | 93 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 94 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 95 | \doi{10.1080/10691898.2016.1246953} 96 | } 97 | \seealso{ 98 | \code{\link{stop}}, \code{\link{AnalyseIf}}, \code{\link{manageWarnings}} 99 | } 100 | -------------------------------------------------------------------------------- /man/AnalyseIf.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/AnalyseIf.R 3 | \name{AnalyseIf} 4 | \alias{AnalyseIf} 5 | \title{Perform a test that indicates whether a given \code{Analyse()} function should be executed} 6 | \usage{ 7 | AnalyseIf(x, condition = NULL) 8 | } 9 | \arguments{ 10 | \item{x}{logical statement to evaluate. If the statement evaluates to \code{TRUE} 11 | then the remainder of the defined function will be evaluated} 12 | 13 | \item{condition}{(optional) the current design condition. This does not need to be supplied 14 | if the expression in \code{x} evaluates to valid logical (e.g., use \code{Attach(condition)} 15 | prior to using \code{AnalyseIf}, or use \code{with(condition, AnalyseIf(someLogicalTest))})} 16 | } 17 | \description{ 18 | This function is designed to prevent specific analysis function executions when the 19 | design conditions are not met. Primarily useful when the \code{analyse} argument to 20 | \code{\link{runSimulation}} was input as a named list object, however some of the 21 | analysis functions are not interesting/compatible with the generated data and should 22 | therefore be skipped. 23 | } 24 | \examples{ 25 | \dontrun{ 26 | 27 | Design <- createDesign(N=c(10,20,30), var.equal = c(TRUE, FALSE)) 28 | 29 | Generate <- function(condition, fixed_objects) { 30 | Attach(condition) 31 | dat <- data.frame(DV = rnorm(N*2), IV = gl(2, N, labels=c('G1', 'G2'))) 32 | dat 33 | } 34 | 35 | # always run this analysis for each row in Design 36 | Analyse1 <- function(condition, dat, fixed_objects) { 37 | mod <- t.test(DV ~ IV, data=dat) 38 | mod$p.value 39 | } 40 | 41 | # Only perform analysis when variances are equal and N = 20 or 30 42 | Analyse2 <- function(condition, dat, fixed_objects) { 43 | AnalyseIf(var.equal && N \%in\% c(20, 30), condition) 44 | mod <- t.test(DV ~ IV, data=dat, var.equal=TRUE) 45 | mod$p.value 46 | } 47 | 48 | Summarise <- function(condition, results, fixed_objects) { 49 | ret <- EDR(results, alpha=.05) 50 | ret 51 | } 52 | 53 | #------------------------------------------------------------------- 54 | 55 | # append names 'Welch' and 'independent' to associated output 56 | res <- runSimulation(design=Design, replications=100, generate=Generate, 57 | analyse=list(Welch=Analyse1, independent=Analyse2), 58 | summarise=Summarise) 59 | res 60 | 61 | # leave results unnamed 62 | res <- runSimulation(design=Design, replications=100, generate=Generate, 63 | analyse=list(Analyse1, Analyse2), 64 | summarise=Summarise) 65 | 66 | 67 | } 68 | 69 | } 70 | \references{ 71 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 72 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 73 | \doi{10.20982/tqmp.16.4.p248} 74 | 75 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 76 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 77 | \doi{10.1080/10691898.2016.1246953} 78 | } 79 | \seealso{ 80 | \code{\link{Analyse}}, \code{\link{runSimulation}} 81 | } 82 | \author{ 83 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 84 | } 85 | -------------------------------------------------------------------------------- /man/Attach.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/Attach.R 3 | \name{Attach} 4 | \alias{Attach} 5 | \title{Attach objects for easier reference} 6 | \usage{ 7 | Attach( 8 | ..., 9 | omit = NULL, 10 | check = TRUE, 11 | attach_listone = TRUE, 12 | RStudio_flags = FALSE 13 | ) 14 | } 15 | \arguments{ 16 | \item{...}{a comma separated list of \code{data.frame}, \code{tibble}, \code{list}, 17 | or \code{matrix} objects containing (column) elements that should be placed in the 18 | current working environment} 19 | 20 | \item{omit}{an optional character vector containing the names of objects that should not 21 | be attached to the current environment. For instance, if the objects named 'a' and 'b' should 22 | not be attached then use \code{omit = c('a', 'b')}. 23 | When NULL (default) all objects are attached} 24 | 25 | \item{check}{logical; check to see if the function will accidentally replace previously defined 26 | variables with the same names as in \code{condition}? Default is \code{TRUE}, which will avoid 27 | this error} 28 | 29 | \item{attach_listone}{logical; if the element to be assign is a list of length one 30 | then assign the first element of this list with the associated name. This generally avoids 31 | adding an often unnecessary list 1 index, such as \code{name <- list[[1L]]}} 32 | 33 | \item{RStudio_flags}{logical; print R script output comments that disable flagged 34 | missing variables in RStudio? Requires the form \code{Attach(Design, RStudio_flags=TRUE)} or 35 | in an interactive debugging session \code{Attach(condition, RStudio_flags=TRUE)}} 36 | } 37 | \description{ 38 | The behaviour of this function is very similar to \code{\link{attach}}, 39 | however it is environment specific, and 40 | therefore only remains defined in a given function rather than in the Global Environment. 41 | Hence, this function is much safer to use than the \code{\link{attach}}, which 42 | incidentally should never be used in your code. This 43 | is useful primarily as a convenience function when you prefer to call the variable names 44 | in \code{condition} directly rather than indexing with \code{condition$sample_size} or 45 | \code{with(condition, sample_size)}, for example. 46 | } 47 | \details{ 48 | Note that if you are using RStudio with the \emph{"Warn if variable used has no definition in scope"} 49 | diagnostic flag then using \code{Attach()} will raise suspensions. To suppress such issues, 50 | you can either disable such flags (the atomic solution) or evaluate the following output 51 | in the R console and place the output in your working simulation file. 52 | 53 | \code{Attach(Design, RStudio_flags = TRUE)} 54 | } 55 | \examples{ 56 | 57 | Design <- createDesign(N1=c(10,20), 58 | N2=c(10,20), 59 | sd=c(1,2)) 60 | Design 61 | 62 | # does not use Attach() 63 | Generate <- function(condition, fixed_objects ) { 64 | # condition = single row of Design input (e.g., condition <- Design[1,]) 65 | N1 <- condition$N1 66 | N2 <- condition$N2 67 | sd <- condition$sd 68 | 69 | group1 <- rnorm(N1) 70 | group2 <- rnorm(N2, sd=sd) 71 | dat <- data.frame(group = c(rep('g1', N1), rep('g2', N2)), 72 | DV = c(group1, group2)) 73 | dat 74 | } 75 | 76 | # similar to above, but using the Attach() function instead of indexing 77 | Generate <- function(condition, fixed_objects ) { 78 | Attach(condition) # N1, N2, and sd are now 'attached' and visible 79 | 80 | group1 <- rnorm(N1) 81 | group2 <- rnorm(N2, sd=sd) 82 | dat <- data.frame(group = c(rep('g1', N1), rep('g2', N2)), 83 | DV = c(group1, group2)) 84 | dat 85 | } 86 | 87 | ##################### 88 | # NOTE: if you're using RStudio with code diagnostics on then evaluate + add the 89 | # following output to your source file to manually support the flagged variables 90 | 91 | Attach(Design, RStudio_flags=TRUE) 92 | 93 | # Below is the same example, however with false positive missing variables suppressed 94 | # when # !diagnostics ... is added added to the source file(s) 95 | 96 | # !diagnostics suppress=N1,N2,sd 97 | Generate <- function(condition, fixed_objects ) { 98 | Attach(condition) # N1, N2, and sd are now 'attached' and visible 99 | 100 | group1 <- rnorm(N1) 101 | group2 <- rnorm(N2, sd=sd) 102 | dat <- data.frame(group = c(rep('g1', N1), rep('g2', N2)), 103 | DV = c(group1, group2)) 104 | dat 105 | } 106 | 107 | 108 | } 109 | \references{ 110 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 111 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 112 | \doi{10.20982/tqmp.16.4.p248} 113 | 114 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 115 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 116 | \doi{10.1080/10691898.2016.1246953} 117 | } 118 | \seealso{ 119 | \code{\link{runSimulation}}, \code{\link{Generate}} 120 | } 121 | \author{ 122 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 123 | } 124 | -------------------------------------------------------------------------------- /man/BF_sim.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimDesign.R 3 | \docType{data} 4 | \name{BF_sim} 5 | \alias{BF_sim} 6 | \title{Example simulation from Brown and Forsythe (1974)} 7 | \description{ 8 | Example results from the Brown and Forsythe (1974) article on robust estimators for 9 | variance ratio tests. Statistical tests are organized by columns and the unique design conditions 10 | are organized by rows. See \code{\link{BF_sim_alternative}} for an alternative form of the same 11 | simulation. Code for this simulation is available of the wiki 12 | (\url{https://github.com/philchalmers/SimDesign/wiki}). 13 | } 14 | \examples{ 15 | 16 | \dontrun{ 17 | data(BF_sim) 18 | head(BF_sim) 19 | 20 | #Type I errors 21 | subset(BF_sim, var_ratio == 1) 22 | } 23 | } 24 | \references{ 25 | Brown, M. B. and Forsythe, A. B. (1974). Robust tests for the equality of variances. 26 | \emph{Journal of the American Statistical Association, 69}(346), 364--367. 27 | 28 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 29 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 30 | \doi{10.20982/tqmp.16.4.p248} 31 | 32 | 33 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 34 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 35 | \doi{10.1080/10691898.2016.1246953} 36 | } 37 | \author{ 38 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 39 | } 40 | \keyword{data} 41 | -------------------------------------------------------------------------------- /man/BF_sim_alternative.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimDesign.R 3 | \docType{data} 4 | \name{BF_sim_alternative} 5 | \alias{BF_sim_alternative} 6 | \title{(Alternative) Example simulation from Brown and Forsythe (1974)} 7 | \description{ 8 | Example results from the Brown and Forsythe (1974) article on robust estimators for 9 | variance ratio tests. Statistical tests and distributions are organized by columns 10 | and the unique design conditions are organized by rows. See \code{\link{BF_sim}} for an alternative 11 | form of the same simulation where distributions are also included in the rows. 12 | Code for this simulation is available on the wiki (\url{https://github.com/philchalmers/SimDesign/wiki}). 13 | } 14 | \examples{ 15 | 16 | \dontrun{ 17 | data(BF_sim_alternative) 18 | head(BF_sim_alternative) 19 | 20 | #' #Type I errors 21 | subset(BF_sim_alternative, var_ratio == 1) 22 | } 23 | } 24 | \references{ 25 | Brown, M. B. and Forsythe, A. B. (1974). Robust tests for the equality of variances. 26 | \emph{Journal of the American Statistical Association, 69}(346), 364--367. 27 | 28 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 29 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 30 | \doi{10.20982/tqmp.16.4.p248} 31 | 32 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 33 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 34 | \doi{10.1080/10691898.2016.1246953} 35 | } 36 | \author{ 37 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 38 | } 39 | \keyword{data} 40 | -------------------------------------------------------------------------------- /man/Bradley1978.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/Bradley1978.R 3 | \name{Bradley1978} 4 | \alias{Bradley1978} 5 | \title{Bradley's (1978) empirical robustness interval} 6 | \usage{ 7 | Bradley1978( 8 | rate, 9 | alpha = 0.05, 10 | type = "liberal", 11 | CI = FALSE, 12 | out.logical = FALSE, 13 | out.labels = c("conservative", "robust", "liberal"), 14 | unname = FALSE 15 | ) 16 | } 17 | \arguments{ 18 | \item{rate}{(optional) numeric vector containing the empirical detection 19 | rate(s) or empirical confidence interval estimates. 20 | If supplied a character vector with elements defined in 21 | \code{out.labels} or a logical vector will be returned indicating whether the 22 | detection rate estimate is considered 'robust'. 23 | 24 | When the input is an empirical coverage rate the argument \code{CI} must be 25 | set to \code{TRUE}. 26 | 27 | If this input is missing, the interval criteria will be printed to the console} 28 | 29 | \item{alpha}{Type I error rate to evaluated (default is .05)} 30 | 31 | \item{type}{character vector indicating the type of interval classification to use. 32 | Default is 'liberal', however can be 'stringent' to use Bradley's more 33 | stringent robustness criteria} 34 | 35 | \item{CI}{logical; should this robust interval be constructed on empirical detection 36 | rates (\code{FALSE}) or empirical coverage rates (\code{TRUE})?} 37 | 38 | \item{out.logical}{logical; should the output vector be TRUE/FALSE indicating whether 39 | the supplied empirical detection rate/CI should be considered "robust"? Default is 40 | FALSE, in which case the out.labels elements are used instead} 41 | 42 | \item{out.labels}{character vector of length three indicating the classification 43 | labels according to the desired robustness interval} 44 | 45 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 46 | names?} 47 | } 48 | \description{ 49 | Robustness interval criteria for empirical detection rate estimates and 50 | empirical coverage estimates defined by Bradley (1978). 51 | See \code{\link{EDR}} and \code{\link{ECR}} to obtain such estimates. 52 | } 53 | \examples{ 54 | 55 | # interval criteria used for empirical detection rates 56 | Bradley1978() 57 | Bradley1978(type = 'stringent') 58 | Bradley1978(alpha = .01, type = 'stringent') 59 | 60 | # intervals applied to empirical detection rate estimates 61 | edr <- c(test1 = .05, test2 = .027, test3 = .051, test4 = .076, test5 = .024) 62 | 63 | Bradley1978(edr) 64 | Bradley1978(edr, out.logical=TRUE) # is robust? 65 | 66 | ##### 67 | # interval criteria used for coverage estimates 68 | 69 | Bradley1978(CI = TRUE) 70 | Bradley1978(CI = TRUE, type = 'stringent') 71 | Bradley1978(CI = TRUE, alpha = .01, type = 'stringent') 72 | 73 | # intervals applied to empirical coverage rate estimates 74 | ecr <- c(test1 = .950, test2 = .973, test3 = .949, test4 = .924, test5 = .976) 75 | 76 | Bradley1978(ecr, CI=TRUE) 77 | Bradley1978(ecr, CI=TRUE, out.logical=TRUE) # is robust? 78 | 79 | } 80 | \references{ 81 | Bradley, J. V. (1978). Robustness? \emph{British Journal of Mathematical and 82 | Statistical Psychology, 31}, 144-152. 83 | 84 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 85 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 86 | \doi{10.20982/tqmp.16.4.p248} 87 | 88 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 89 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 90 | \doi{10.1080/10691898.2016.1246953} 91 | } 92 | \seealso{ 93 | \code{\link{EDR}}, \code{\link{ECR}}, \code{\link{Serlin2000}} 94 | } 95 | \author{ 96 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 97 | } 98 | -------------------------------------------------------------------------------- /man/CC.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{CC} 4 | \alias{CC} 5 | \title{Compute congruence coefficient} 6 | \usage{ 7 | CC(x, y = NULL, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{a vector or \code{data.frame}/\code{matrix} containing the 11 | variables to use. If a vector then the input \code{y} is required, 12 | otherwise the congruence coefficient is computed for all bivariate 13 | combinations} 14 | 15 | \item{y}{(optional) the second vector input to use if 16 | \code{x} is a vector} 17 | 18 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 19 | names?} 20 | } 21 | \description{ 22 | Computes the congruence coefficient, also known as an "unadjusted" correlation 23 | or Tucker's congruence coefficient. 24 | } 25 | \examples{ 26 | 27 | vec1 <- runif(1000) 28 | vec2 <- runif(1000) 29 | 30 | CC(vec1, vec2) 31 | # compare to cor() 32 | cor(vec1, vec2) 33 | 34 | # column input 35 | df <- data.frame(vec1, vec2, vec3 = runif(1000)) 36 | CC(df) 37 | cor(df) 38 | 39 | } 40 | \references{ 41 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 42 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 43 | \doi{10.20982/tqmp.16.4.p248} 44 | 45 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 46 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 47 | \doi{10.1080/10691898.2016.1246953} 48 | } 49 | \seealso{ 50 | \code{\link{cor}} 51 | } 52 | \author{ 53 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 54 | } 55 | -------------------------------------------------------------------------------- /man/ECR.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{ECR} 4 | \alias{ECR} 5 | \title{Compute empirical coverage rates} 6 | \usage{ 7 | ECR( 8 | CIs, 9 | parameter, 10 | tails = FALSE, 11 | CI_width = FALSE, 12 | complement = FALSE, 13 | names = NULL, 14 | unname = FALSE 15 | ) 16 | } 17 | \arguments{ 18 | \item{CIs}{a \code{numeric} vector or \code{matrix} of confidence interval values for a 19 | given parameter value, where the first element/column indicates the lower confidence interval 20 | and the second element/column the upper confidence interval. If a 21 | vector of length 2 is passed instead then the returned value will be either a 1 or 0 to indicate 22 | whether the parameter value was or was not within the interval, respectively. Otherwise, 23 | the input must be a matrix with an even number of columns} 24 | 25 | \item{parameter}{a numeric scalar indicating the fixed parameter value. Alternative, a \code{numeric} 26 | vector object with length equal to the number of rows as \code{CIs} (use to compare sets of parameters 27 | at once)} 28 | 29 | \item{tails}{logical; when TRUE returns a vector of length 2 to indicate the proportion of times 30 | the parameter was lower or higher than the supplied interval, respectively. This is mainly only 31 | useful when the coverage region is not expected to be symmetric, and therefore is generally not 32 | required. Note that \code{1 - sum(ECR(CIs, parameter, tails=TRUE)) == ECR(CIs, parameter)}} 33 | 34 | \item{CI_width}{logical; rather than returning the overall coverage rate, return the 35 | average width of the CIs instead? Useful when comparing the efficiency of different CI 36 | estimators} 37 | 38 | \item{complement}{logical; rather than computing the proportion of 39 | population parameters within the CI, return the proportion outside the 40 | advertised CI (1 - ECR = alpha). In the case where only one value is provided, 41 | which normally would return a 0 if outside the CI or 1 if inside, the values 42 | will be switched (useful when using, for example, CI tests of for the significance 43 | of parameters)} 44 | 45 | \item{names}{an optional character vector used to name the returned object. Generally useful 46 | when more than one CI estimate is investigated at once} 47 | 48 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 49 | names?} 50 | } 51 | \description{ 52 | Computes the detection rate for determining empirical coverage rates given a set of estimated 53 | confidence intervals. Note that using \code{1 - ECR(CIs, parameter)} will provide the empirical 54 | detection rate. Also supports computing the average width of the CIs, which may be useful when comparing 55 | the efficiency of CI estimators. 56 | } 57 | \examples{ 58 | 59 | CIs <- matrix(NA, 100, 2) 60 | for(i in 1:100){ 61 | dat <- rnorm(100) 62 | CIs[i,] <- t.test(dat)$conf.int 63 | } 64 | 65 | ECR(CIs, 0) 66 | ECR(CIs, 0, tails = TRUE) 67 | ECR(CIs, 0, complement = TRUE) # proportion outside interval 68 | 69 | # single vector input 70 | CI <- c(-1, 1) 71 | ECR(CI, 0) 72 | ECR(CI, 0, complement = TRUE) 73 | ECR(CI, 2) 74 | ECR(CI, 2, complement = TRUE) 75 | ECR(CI, 2, tails = TRUE) 76 | 77 | # parameters of the same size as CI 78 | parameters <- 1:10 79 | CIs <- cbind(parameters - runif(10), parameters + runif(10)) 80 | parameters <- parameters + rnorm(10) 81 | ECR(CIs, parameters) 82 | 83 | # average width of CIs 84 | ECR(CIs, parameters, CI_width=TRUE) 85 | 86 | # ECR() for multiple CI estimates in the same object 87 | parameter <- 10 88 | CIs <- data.frame(lowerCI_1=parameter - runif(10), 89 | upperCI_1=parameter + runif(10), 90 | lowerCI_2=parameter - 2*runif(10), 91 | upperCI_2=parameter + 2*runif(10)) 92 | head(CIs) 93 | ECR(CIs, parameter) 94 | ECR(CIs, parameter, tails=TRUE) 95 | ECR(CIs, parameter, CI_width=TRUE) 96 | 97 | # often a good idea to provide names for the output 98 | ECR(CIs, parameter, names = c('this', 'that')) 99 | ECR(CIs, parameter, CI_width=TRUE, names = c('this', 'that')) 100 | ECR(CIs, parameter, tails=TRUE, names = c('this', 'that')) 101 | 102 | } 103 | \references{ 104 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 105 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 106 | \doi{10.20982/tqmp.16.4.p248} 107 | 108 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 109 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 110 | \doi{10.1080/10691898.2016.1246953} 111 | } 112 | \seealso{ 113 | \code{\link{EDR}} 114 | } 115 | \author{ 116 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 117 | } 118 | -------------------------------------------------------------------------------- /man/EDR.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{EDR} 4 | \alias{EDR} 5 | \alias{ERR} 6 | \title{Compute the empirical detection/rejection rate for Type I errors and Power} 7 | \usage{ 8 | EDR(p, alpha = 0.05, unname = FALSE) 9 | } 10 | \arguments{ 11 | \item{p}{a \code{numeric} vector or \code{matrix}/\code{data.frame} of p-values from the 12 | desired statistical estimator. If a \code{matrix}, each statistic must be organized by 13 | column, where the number of rows is equal to the number of replications} 14 | 15 | \item{alpha}{the detection threshold (typical values are .10, .05, and .01). 16 | Default is .05} 17 | 18 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 19 | names?} 20 | } 21 | \description{ 22 | Computes the detection/rejection rate for determining empirical 23 | Type I error and power rates using information from p-values. 24 | } 25 | \examples{ 26 | 27 | rates <- numeric(100) 28 | for(i in 1:100){ 29 | dat <- rnorm(100) 30 | rates[i] <- t.test(dat)$p.value 31 | } 32 | 33 | EDR(rates) 34 | EDR(rates, alpha = .01) 35 | 36 | # multiple rates at once 37 | rates <- cbind(runif(1000), runif(1000)) 38 | EDR(rates) 39 | 40 | } 41 | \references{ 42 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 43 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 44 | \doi{10.20982/tqmp.16.4.p248} 45 | 46 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 47 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 48 | \doi{10.1080/10691898.2016.1246953} 49 | } 50 | \seealso{ 51 | \code{\link{ECR}}, \code{\link{Bradley1978}} 52 | } 53 | \author{ 54 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 55 | } 56 | -------------------------------------------------------------------------------- /man/Generate.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/functions.R 3 | \name{Generate} 4 | \alias{Generate} 5 | \title{Generate data} 6 | \usage{ 7 | Generate(condition, fixed_objects) 8 | } 9 | \arguments{ 10 | \item{condition}{a single row from the \code{design} input (as a \code{data.frame}), indicating the 11 | simulation conditions} 12 | 13 | \item{fixed_objects}{object passed down from \code{\link{runSimulation}}} 14 | } 15 | \value{ 16 | returns a single object containing the data to be analyzed (usually a 17 | \code{vector}, \code{matrix}, or \code{data.frame}), 18 | or \code{list} 19 | } 20 | \description{ 21 | Generate data from a single row in the \code{design} input (see \code{\link{runSimulation}}). R contains 22 | numerous approaches to generate data, some of which are contained in the base package, as well 23 | as in \code{SimDesign} (e.g., \code{\link{rmgh}}, \code{\link{rValeMaurelli}}, \code{\link{rHeadrick}}). 24 | However the majority can be found in external packages. See CRAN's list of possible distributions here: 25 | \url{https://CRAN.R-project.org/view=Distributions}. Note that this function technically 26 | can be omitted if the data generation is provided in the \code{\link{Analyse}} step, though 27 | in general this is not recommended. 28 | } 29 | \details{ 30 | The use of \code{\link{try}} functions is generally not required in this function because \code{Generate} 31 | is internally wrapped in a \code{\link{try}} call. Therefore, if a function stops early 32 | then this will cause the function to halt internally, the message which triggered the \code{\link{stop}} 33 | will be recorded, and \code{Generate} will be called again to obtain a different dataset. 34 | That said, it may be useful for users to throw their own \code{\link{stop}} commands if the data 35 | should be re-drawn for other reasons (e.g., an estimated model terminated correctly 36 | but the maximum number of iterations were reached). 37 | } 38 | \examples{ 39 | \dontrun{ 40 | 41 | generate <- function(condition, fixed_objects) { 42 | N1 <- condition$sample_sizes_group1 43 | N2 <- condition$sample_sizes_group2 44 | sd <- condition$standard_deviations 45 | 46 | group1 <- rnorm(N1) 47 | group2 <- rnorm(N2, sd=sd) 48 | dat <- data.frame(group = c(rep('g1', N1), rep('g2', N2)), 49 | DV = c(group1, group2)) 50 | # just a silly example of a simulated parameter 51 | pars <- list(random_number = rnorm(1)) 52 | 53 | list(dat=dat, parameters=pars) 54 | } 55 | 56 | # similar to above, but using the Attach() function instead of indexing 57 | generate <- function(condition, fixed_objects) { 58 | Attach(condition) 59 | N1 <- sample_sizes_group1 60 | N2 <- sample_sizes_group2 61 | sd <- standard_deviations 62 | 63 | group1 <- rnorm(N1) 64 | group2 <- rnorm(N2, sd=sd) 65 | dat <- data.frame(group = c(rep('g1', N1), rep('g2', N2)), 66 | DV = c(group1, group2)) 67 | dat 68 | } 69 | 70 | generate2 <- function(condition, fixed_objects) { 71 | mu <- sample(c(-1,0,1), 1) 72 | dat <- rnorm(100, mu) 73 | dat #return simple vector (discard mu information) 74 | } 75 | 76 | generate3 <- function(condition, fixed_objects) { 77 | mu <- sample(c(-1,0,1), 1) 78 | dat <- data.frame(DV = rnorm(100, mu)) 79 | dat 80 | } 81 | 82 | } 83 | 84 | } 85 | \references{ 86 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 87 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 88 | \doi{10.20982/tqmp.16.4.p248} 89 | 90 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 91 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 92 | \doi{10.1080/10691898.2016.1246953} 93 | } 94 | \seealso{ 95 | \code{\link{addMissing}}, \code{\link{Attach}}, 96 | \code{\link{rmgh}}, \code{\link{rValeMaurelli}}, \code{\link{rHeadrick}} 97 | } 98 | -------------------------------------------------------------------------------- /man/GenerateIf.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/GenerateIf.R 3 | \name{GenerateIf} 4 | \alias{GenerateIf} 5 | \title{Perform a test that indicates whether a given \code{Generate()} function should be executed} 6 | \usage{ 7 | GenerateIf(x, condition = NULL) 8 | } 9 | \arguments{ 10 | \item{x}{logical statement to evaluate. If the statement evaluates to \code{TRUE} 11 | then the remainder of the defined function will be evaluated} 12 | 13 | \item{condition}{(optional) the current design condition. This does not need to be supplied 14 | if the expression in \code{x} evaluates to valid logical (e.g., use \code{Attach(condition)} 15 | prior to using \code{AnalyseIf}, or use \code{with(condition, AnalyseIf(someLogicalTest))})} 16 | } 17 | \description{ 18 | This function is designed to prevent specific generate function executions when the 19 | design conditions are not met. Primarily useful when the \code{generate} argument to 20 | \code{\link{runSimulation}} was input as a named list object, however should only be 21 | applied for some specific design condition (otherwise, the data generation moves to the 22 | next function in the list). 23 | } 24 | \examples{ 25 | \dontrun{ 26 | 27 | # SimFunctions(nGenerate = 2) 28 | 29 | Design <- createDesign(N=c(10,20,30), var.equal = c(TRUE, FALSE)) 30 | 31 | Generate.G1 <- function(condition, fixed_objects) { 32 | GenerateIf(condition$var.equal == FALSE) # only run when unequal vars 33 | Attach(condition) 34 | dat <- data.frame(DV = c(rnorm(N), rnorm(N, sd=2)), 35 | IV = gl(2, N, labels=c('G1', 'G2'))) 36 | dat 37 | } 38 | 39 | Generate.G2 <- function(condition, fixed_objects) { 40 | Attach(condition) 41 | dat <- data.frame(DV = rnorm(N*2), IV = gl(2, N, labels=c('G1', 'G2'))) 42 | dat 43 | } 44 | 45 | # always run this analysis for each row in Design 46 | Analyse <- function(condition, dat, fixed_objects) { 47 | mod <- t.test(DV ~ IV, data=dat) 48 | mod$p.value 49 | } 50 | 51 | Summarise <- function(condition, results, fixed_objects) { 52 | ret <- EDR(results, alpha=.05) 53 | ret 54 | } 55 | 56 | #------------------------------------------------------------------- 57 | 58 | # append names 'Welch' and 'independent' to associated output 59 | res <- runSimulation(design=Design, replications=1000, 60 | generate=list(G1=Generate.G1, G2=Generate.G2), 61 | analyse=Analyse, 62 | summarise=Summarise) 63 | res 64 | 65 | } 66 | 67 | } 68 | \references{ 69 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 70 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 71 | \doi{10.20982/tqmp.16.4.p248} 72 | 73 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 74 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 75 | \doi{10.1080/10691898.2016.1246953} 76 | } 77 | \seealso{ 78 | \code{\link{Analyse}}, \code{\link{runSimulation}} 79 | } 80 | \author{ 81 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 82 | } 83 | -------------------------------------------------------------------------------- /man/IRMSE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{IRMSE} 4 | \alias{IRMSE} 5 | \title{Compute the integrated root mean-square error} 6 | \usage{ 7 | IRMSE( 8 | estimate, 9 | parameter, 10 | fn, 11 | density = function(theta, ...) 1, 12 | lower = -Inf, 13 | upper = Inf, 14 | ... 15 | ) 16 | } 17 | \arguments{ 18 | \item{estimate}{a vector of parameter estimates} 19 | 20 | \item{parameter}{a vector of population parameters} 21 | 22 | \item{fn}{a continuous function where the first argument is to be integrated and the second argument is 23 | a vector of parameters or parameter estimates. This function 24 | represents a implied continuous function which uses the sample estimates or population parameters} 25 | 26 | \item{density}{(optional) a density function used to marginalize (i.e., average), where the first 27 | argument is to be integrated, and must be of the form \code{density(theta, ...)} or 28 | \code{density(theta, param1, param2)}, where \code{param1} is a placeholder name for the 29 | hyper-parameters associated with the probability density function. If omitted then 30 | the cumulative different between the respective functions will be computed instead} 31 | 32 | \item{lower}{lower bound to begin numerical integration from} 33 | 34 | \item{upper}{upper bound to finish numerical integration to} 35 | 36 | \item{...}{additional parameters to pass to \code{fnest}, \code{fnparam}, \code{density}, 37 | and \code{\link{integrate}},} 38 | } 39 | \value{ 40 | returns a single \code{numeric} term indicating the average/cumulative deviation 41 | given the supplied continuous functions 42 | } 43 | \description{ 44 | Computes the average/cumulative deviation given two continuous functions and an optional 45 | function representing the probability density function. Only one-dimensional integration 46 | is supported. 47 | } 48 | \details{ 49 | The integrated root mean-square error (IRMSE) is of the form 50 | \deqn{IRMSE(\theta) = \sqrt{\int [f(\theta, \hat{\psi}) - f(\theta, \psi)]^2 g(\theta, ...)}} 51 | where \eqn{g(\theta, ...)} is the density function used to marginalize the continuous sample 52 | (\eqn{f(\theta, \hat{\psi})}) and population (\eqn{f(\theta, \psi)}) functions. 53 | } 54 | \examples{ 55 | 56 | # logistic regression function with one slope and intercept 57 | fn <- function(theta, param) 1 / (1 + exp(-(param[1] + param[2] * theta))) 58 | 59 | # sample and population sets 60 | est <- c(-0.4951, 1.1253) 61 | pop <- c(-0.5, 1) 62 | 63 | theta <- seq(-10,10,length.out=1000) 64 | plot(theta, fn(theta, pop), type = 'l', col='red', ylim = c(0,1)) 65 | lines(theta, fn(theta, est), col='blue', lty=2) 66 | 67 | # cumulative result (i.e., standard integral) 68 | IRMSE(est, pop, fn) 69 | 70 | # integrated RMSE result by marginalizing over a N(0,1) distribution 71 | den <- function(theta, mean, sd) dnorm(theta, mean=mean, sd=sd) 72 | 73 | IRMSE(est, pop, fn, den, mean=0, sd=1) 74 | 75 | # this specification is equivalent to the above 76 | den2 <- function(theta, ...) dnorm(theta, ...) 77 | 78 | IRMSE(est, pop, fn, den2, mean=0, sd=1) 79 | 80 | } 81 | \references{ 82 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 83 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 84 | \doi{10.20982/tqmp.16.4.p248} 85 | 86 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 87 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 88 | \doi{10.1080/10691898.2016.1246953} 89 | } 90 | \seealso{ 91 | \code{\link{RMSE}} 92 | } 93 | \author{ 94 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 95 | } 96 | -------------------------------------------------------------------------------- /man/MAE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{MAE} 4 | \alias{MAE} 5 | \title{Compute the mean absolute error} 6 | \usage{ 7 | MAE(estimate, parameter = NULL, type = "MAE", percent = FALSE, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{estimate}{a \code{numeric} vector, \code{matrix}/\code{data.frame}, or \code{list} 11 | of parameter estimates. 12 | If a vector, the length is equal to the number of replications. If a 13 | \code{matrix}/\code{data.frame} the number of rows must equal the number of replications. 14 | \code{list} objects will be looped 15 | over using the same rules after above after first translating the information into one-dimensional 16 | vectors and re-creating the structure upon return} 17 | 18 | \item{parameter}{a \code{numeric} scalar/vector or \code{matrix} indicating the fixed parameter values. 19 | If a single value is supplied and \code{estimate} is a \code{matrix}/\code{data.frame} 20 | then the value will be 21 | recycled for each column; otherwise, each element will be associated 22 | with each respective column in the \code{estimate} input. 23 | If \code{NULL}, then it will be assumed that the \code{estimate} input is in a deviation 24 | form (therefore \code{mean(abs(estimate))} will be returned)} 25 | 26 | \item{type}{type of deviation to compute. Can be \code{'MAE'} (default) for the mean absolute error, 27 | \code{'NMSE'} for the normalized MAE (MAE / (max(estimate) - min(estimate))), or 28 | \code{'SMSE'} for the standardized MAE (MAE / sd(estimate))} 29 | 30 | \item{percent}{logical; change returned result to percentage by multiplying by 100? 31 | Default is FALSE} 32 | 33 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 34 | names?} 35 | } 36 | \value{ 37 | returns a numeric vector indicating the overall mean absolute error in the estimates 38 | } 39 | \description{ 40 | Computes the average absolute deviation of a sample estimate from the parameter value. 41 | Accepts estimate and parameter values, as well as estimate values which are in deviation form. 42 | } 43 | \examples{ 44 | 45 | pop <- 1 46 | samp <- rnorm(100, 1, sd = 0.5) 47 | MAE(samp, pop) 48 | 49 | dev <- samp - pop 50 | MAE(dev) 51 | MAE(samp, pop, type = 'NMAE') 52 | MAE(samp, pop, type = 'SMAE') 53 | 54 | # matrix input 55 | mat <- cbind(M1=rnorm(100, 2, sd = 0.5), M2 = rnorm(100, 2, sd = 1)) 56 | MAE(mat, parameter = 2) 57 | 58 | # same, but with data.frame 59 | df <- data.frame(M1=rnorm(100, 2, sd = 0.5), M2 = rnorm(100, 2, sd = 1)) 60 | MAE(df, parameter = c(2,2)) 61 | 62 | # parameters of the same size 63 | parameters <- 1:10 64 | estimates <- parameters + rnorm(10) 65 | MAE(estimates, parameters) 66 | 67 | } 68 | \references{ 69 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 70 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 71 | \doi{10.20982/tqmp.16.4.p248} 72 | 73 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 74 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 75 | \doi{10.1080/10691898.2016.1246953} 76 | } 77 | \seealso{ 78 | RMSE 79 | } 80 | \author{ 81 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 82 | } 83 | -------------------------------------------------------------------------------- /man/MSRSE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{MSRSE} 4 | \alias{MSRSE} 5 | \title{Compute the relative performance behavior of collections of standard errors} 6 | \usage{ 7 | MSRSE(SE, SD, percent = FALSE, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{SE}{a \code{numeric} scalar/vector indicating the average standard errors across 11 | the replications, or a \code{matrix} of collected standard error estimates themselves 12 | to be used to compute the average standard errors. Each column/element in this input 13 | corresponds to the column/element in \code{SD}} 14 | 15 | \item{SD}{a \code{numeric} scalar/vector indicating the standard deviation across 16 | the replications, or a \code{matrix} of collected parameter estimates themselves 17 | to be used to compute the standard deviations. Each column/element in this input 18 | corresponds to the column/element in \code{SE}} 19 | 20 | \item{percent}{logical; change returned result to percentage by multiplying by 100? 21 | Default is FALSE} 22 | 23 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 24 | names?} 25 | } 26 | \value{ 27 | returns a \code{vector} of ratios indicating the relative performance 28 | of the standard error estimates to the observed parameter standard deviation. 29 | Values less than 1 indicate that the standard errors were larger than the standard 30 | deviation of the parameters (hence, the SEs are interpreted as more conservative), 31 | while values greater than 1 were smaller than the standard deviation of the 32 | parameters (i.e., more liberal SEs) 33 | } 34 | \description{ 35 | The mean-square relative standard error (MSRSE) compares standard error 36 | estimates to the standard deviation of the respective 37 | parameter estimates. Values close to 1 indicate that the behavior of the standard errors 38 | closely matched the sampling variability of the parameter estimates. 39 | } 40 | \details{ 41 | Mean-square relative standard error (MSRSE) is expressed as 42 | 43 | \deqn{MSRSE = \frac{E(SE(\psi)^2)}{SD(\psi)^2} = 44 | \frac{1/R * \sum_{r=1}^R SE(\psi_r)^2}{SD(\psi)^2}} 45 | 46 | where \eqn{SE(\psi_r)} represents the estimate of the standard error at the \eqn{r}th 47 | simulation replication, and \eqn{SD(\psi)} represents the standard deviation estimate 48 | of the parameters across all \eqn{R} replications. Note that \eqn{SD(\psi)^2} is used, 49 | which corresponds to the variance of \eqn{\psi}. 50 | } 51 | \examples{ 52 | 53 | Generate <- function(condition, fixed_objects) { 54 | X <- rep(0:1, each = 50) 55 | y <- 10 + 5 * X + rnorm(100, 0, .2) 56 | data.frame(y, X) 57 | } 58 | 59 | Analyse <- function(condition, dat, fixed_objects) { 60 | mod <- lm(y ~ X, dat) 61 | so <- summary(mod) 62 | ret <- c(SE = so$coefficients[,"Std. Error"], 63 | est = so$coefficients[,"Estimate"]) 64 | ret 65 | } 66 | 67 | Summarise <- function(condition, results, fixed_objects) { 68 | MSRSE(SE = results[,1:2], SD = results[,3:4]) 69 | } 70 | 71 | results <- runSimulation(replications=500, generate=Generate, 72 | analyse=Analyse, summarise=Summarise) 73 | results 74 | 75 | 76 | } 77 | \references{ 78 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 79 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 80 | \doi{10.20982/tqmp.16.4.p248} 81 | 82 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 83 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 84 | \doi{10.1080/10691898.2016.1246953} 85 | } 86 | \author{ 87 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 88 | } 89 | -------------------------------------------------------------------------------- /man/RAB.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{RAB} 4 | \alias{RAB} 5 | \title{Compute the relative absolute bias of multiple estimators} 6 | \usage{ 7 | RAB(x, percent = FALSE, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{a \code{numeric} vector of bias estimates (see \code{\link{bias}}), 11 | where the first element will be used as the reference} 12 | 13 | \item{percent}{logical; change returned result to percentage by multiplying by 100? 14 | Default is FALSE} 15 | 16 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 17 | names?} 18 | } 19 | \value{ 20 | returns a \code{vector} of absolute bias ratios indicating the relative bias 21 | effects compared to the first estimator. Values less than 1 indicate better bias estimates 22 | than the first estimator, while values greater than 1 indicate worse bias than the first estimator 23 | } 24 | \description{ 25 | Computes the relative absolute bias given the bias estimates for multiple estimators. 26 | } 27 | \examples{ 28 | 29 | pop <- 1 30 | samp1 <- rnorm(5000, 1) 31 | bias1 <- bias(samp1, pop) 32 | samp2 <- rnorm(5000, 1) 33 | bias2 <- bias(samp2, pop) 34 | 35 | RAB(c(bias1, bias2)) 36 | RAB(c(bias1, bias2), percent = TRUE) # as a percentage 37 | 38 | } 39 | \references{ 40 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 41 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 42 | \doi{10.20982/tqmp.16.4.p248} 43 | 44 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 45 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 46 | \doi{10.1080/10691898.2016.1246953} 47 | } 48 | \author{ 49 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 50 | } 51 | -------------------------------------------------------------------------------- /man/RD.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{RD} 4 | \alias{RD} 5 | \title{Compute the relative difference} 6 | \usage{ 7 | RD(est, pop, as.vector = TRUE, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{est}{a \code{numeric} vector, \code{matrix/data.frame}, or \code{list} containing 11 | the parameter estimates} 12 | 13 | \item{pop}{a \code{numeric} vector or matrix containing the true parameter values. Must be 14 | of comparable dimension to \code{est}} 15 | 16 | \item{as.vector}{logical; always wrap the result in a \code{\link{as.vector}} function 17 | before returning?} 18 | 19 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 20 | names?} 21 | } 22 | \value{ 23 | returns a \code{vector} or \code{matrix} depending on the inputs and whether 24 | \code{as.vector} was used 25 | } 26 | \description{ 27 | Computes the relative difference statistic of the form \code{(est - pop)/ pop}, which 28 | is equivalent to the form \code{est/pop - 1}. If matrices are supplied then 29 | an equivalent matrix variant will be used of the form 30 | \code{(est - pop) * solve(pop)}. Values closer to 0 indicate better 31 | relative parameter recovery. Note that for single variable inputs this is equivalent to 32 | \code{bias(..., type = 'relative')}. 33 | } 34 | \examples{ 35 | 36 | # vector 37 | pop <- seq(1, 100, length.out=9) 38 | est1 <- pop + rnorm(9, 0, .2) 39 | (rds <- RD(est1, pop)) 40 | summary(rds) 41 | 42 | # matrix 43 | pop <- matrix(c(1:8, 10), 3, 3) 44 | est2 <- pop + rnorm(9, 0, .2) 45 | RD(est2, pop, as.vector = FALSE) 46 | (rds <- RD(est2, pop)) 47 | summary(rds) 48 | 49 | 50 | } 51 | \references{ 52 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 53 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 54 | \doi{10.20982/tqmp.16.4.p248} 55 | 56 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 57 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 58 | \doi{10.1080/10691898.2016.1246953} 59 | } 60 | \author{ 61 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 62 | } 63 | -------------------------------------------------------------------------------- /man/RE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{RE} 4 | \alias{RE} 5 | \title{Compute the relative efficiency of multiple estimators} 6 | \usage{ 7 | RE(x, MSE = FALSE, percent = FALSE, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{a \code{numeric} vector of root mean square error values (see \code{\link{RMSE}}), 11 | where the first element will be used as the reference. Otherwise, the object could contain 12 | MSE values if the flag \code{MSE = TRUE} is also included} 13 | 14 | \item{MSE}{logical; are the input value mean squared errors instead of root mean square errors?} 15 | 16 | \item{percent}{logical; change returned result to percentage by multiplying by 100? 17 | Default is FALSE} 18 | 19 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 20 | names?} 21 | } 22 | \value{ 23 | returns a \code{vector} of variance ratios indicating the relative efficiency compared 24 | to the first estimator. Values less than 1 indicate better efficiency than the first 25 | estimator, while values greater than 1 indicate worse efficiency than the first estimator 26 | } 27 | \description{ 28 | Computes the relative efficiency given the RMSE (default) or MSE values for multiple estimators. 29 | } 30 | \examples{ 31 | 32 | pop <- 1 33 | samp1 <- rnorm(100, 1, sd = 0.5) 34 | RMSE1 <- RMSE(samp1, pop) 35 | samp2 <- rnorm(100, 1, sd = 1) 36 | RMSE2 <- RMSE(samp2, pop) 37 | 38 | RE(c(RMSE1, RMSE2)) 39 | RE(c(RMSE1, RMSE2), percent = TRUE) # as a percentage 40 | 41 | # using MSE instead 42 | mse <- c(RMSE1, RMSE2)^2 43 | RE(mse, MSE = TRUE) 44 | 45 | } 46 | \references{ 47 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 48 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 49 | \doi{10.20982/tqmp.16.4.p248} 50 | 51 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 52 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 53 | \doi{10.1080/10691898.2016.1246953} 54 | } 55 | \author{ 56 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 57 | } 58 | -------------------------------------------------------------------------------- /man/RMSE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{RMSE} 4 | \alias{RMSE} 5 | \alias{RMSD} 6 | \title{Compute the (normalized) root mean square error} 7 | \usage{ 8 | RMSE( 9 | estimate, 10 | parameter = NULL, 11 | type = "RMSE", 12 | MSE = FALSE, 13 | percent = FALSE, 14 | unname = FALSE 15 | ) 16 | 17 | RMSD( 18 | estimate, 19 | parameter = NULL, 20 | type = "RMSE", 21 | MSE = FALSE, 22 | percent = FALSE, 23 | unname = FALSE 24 | ) 25 | } 26 | \arguments{ 27 | \item{estimate}{a \code{numeric} vector, \code{matrix}/\code{data.frame}, or \code{list} 28 | of parameter estimates. 29 | If a vector, the length is equal to the number of replications. If a 30 | \code{matrix}/\code{data.frame}, the number of rows must equal the number of replications. 31 | \code{list} objects will be looped 32 | over using the same rules after above after first translating the information into one-dimensional 33 | vectors and re-creating the structure upon return} 34 | 35 | \item{parameter}{a \code{numeric} scalar/vector indicating the fixed parameter values. 36 | If a single value is supplied and \code{estimate} is a \code{matrix}/\code{data.frame} then 37 | the value will be recycled for each column; otherwise, each element will be associated 38 | with each respective column in the \code{estimate} input. 39 | If \code{NULL} then it will be assumed that the \code{estimate} input is in a deviation 40 | form (therefore \code{sqrt(mean(estimate^2))} will be returned)} 41 | 42 | \item{type}{type of deviation to compute. Can be \code{'RMSE'} (default) for the root mean square-error, 43 | \code{'NRMSE'} for the normalized RMSE (RMSE / (max(estimate) - min(estimate))), 44 | \code{'SRMSE'} for the standardized RMSE (RMSE / sd(estimate)), 45 | \code{'CV'} for the coefficient of variation, or \code{'RMSLE'} for the root mean-square log-error} 46 | 47 | \item{MSE}{logical; return the mean square error equivalent of the results instead of the root 48 | mean-square error (in other words, the result is squared)? Default is \code{FALSE}} 49 | 50 | \item{percent}{logical; change returned result to percentage by multiplying by 100? 51 | Default is FALSE} 52 | 53 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 54 | names?} 55 | } 56 | \value{ 57 | returns a \code{numeric} vector indicating the overall average deviation in the estimates 58 | } 59 | \description{ 60 | Computes the average deviation (root mean square error; also known as the root mean square deviation) 61 | of a sample estimate from the parameter value. Accepts estimate and parameter values, 62 | as well as estimate values which are in deviation form. 63 | } 64 | \examples{ 65 | 66 | pop <- 1 67 | samp <- rnorm(100, 1, sd = 0.5) 68 | RMSE(samp, pop) 69 | 70 | dev <- samp - pop 71 | RMSE(dev) 72 | 73 | RMSE(samp, pop, type = 'NRMSE') 74 | RMSE(dev, type = 'NRMSE') 75 | RMSE(dev, pop, type = 'SRMSE') 76 | RMSE(samp, pop, type = 'CV') 77 | RMSE(samp, pop, type = 'RMSLE') 78 | 79 | # percentage reported 80 | RMSE(samp, pop, type = 'NRMSE') 81 | RMSE(samp, pop, type = 'NRMSE', percent = TRUE) 82 | 83 | # matrix input 84 | mat <- cbind(M1=rnorm(100, 2, sd = 0.5), M2 = rnorm(100, 2, sd = 1)) 85 | RMSE(mat, parameter = 2) 86 | RMSE(mat, parameter = c(2, 3)) 87 | 88 | # different parameter associated with each column 89 | mat <- cbind(M1=rnorm(1000, 2, sd = 0.25), M2 = rnorm(1000, 3, sd = .25)) 90 | RMSE(mat, parameter = c(2,3)) 91 | 92 | # same, but with data.frame 93 | df <- data.frame(M1=rnorm(100, 2, sd = 0.5), M2 = rnorm(100, 2, sd = 1)) 94 | RMSE(df, parameter = c(2,2)) 95 | 96 | # parameters of the same size 97 | parameters <- 1:10 98 | estimates <- parameters + rnorm(10) 99 | RMSE(estimates, parameters) 100 | 101 | } 102 | \references{ 103 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 104 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 105 | \doi{10.20982/tqmp.16.4.p248} 106 | 107 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 108 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 109 | \doi{10.1080/10691898.2016.1246953} 110 | } 111 | \seealso{ 112 | \code{\link{bias}} 113 | 114 | MAE 115 | } 116 | \author{ 117 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 118 | } 119 | -------------------------------------------------------------------------------- /man/RSE.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/summary_functions.R 3 | \name{RSE} 4 | \alias{RSE} 5 | \title{Compute the relative standard error ratio} 6 | \usage{ 7 | RSE(SE, ests, unname = FALSE) 8 | } 9 | \arguments{ 10 | \item{SE}{a \code{numeric} matrix of SE estimates across the replications (extracted 11 | from the \code{results} object in the Summarise step). Alternatively, can be a vector containing 12 | the mean of the SE estimates across the R simulation replications} 13 | 14 | \item{ests}{a \code{numeric} matrix object containing the parameter estimates under investigation 15 | found within the \code{\link{Summarise}} function. This input is used to compute the 16 | standard deviation/variance estimates for each column to evaluate how well the expected SE 17 | matches the standard deviation} 18 | 19 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 20 | names?} 21 | } 22 | \value{ 23 | returns vector of variance ratios, (RSV = SE^2/SD^2) 24 | } 25 | \description{ 26 | Computes the relative standard error ratio given the set of estimated standard errors (SE) and the 27 | deviation across the R simulation replications (SD). The ratio is formed by finding the expectation 28 | of the SE terms, and compares this expectation to the general variability of their respective parameter 29 | estimates across the R replications (ratio should equal 1). This is used to roughly evaluate whether the 30 | SEs being advertised by a given estimation method matches the sampling variability of the respective 31 | estimates across samples. 32 | } 33 | \examples{ 34 | 35 | R <- 10000 36 | par_ests <- cbind(rnorm(R), rnorm(R, sd=1/10), 37 | rnorm(R, sd=1/15)) 38 | colnames(par_ests) <- paste0("par", 1:3) 39 | (SDs <- colSDs(par_ests)) 40 | 41 | SEs <- cbind(1 + rnorm(R, sd=.01), 42 | 1/10 + + rnorm(R, sd=.01), 43 | 1/15 + rnorm(R, sd=.01)) 44 | (E_SEs <- colMeans(SEs)) 45 | RSE(SEs, par_ests) 46 | 47 | # equivalent to the form 48 | colMeans(SEs) / SDs 49 | 50 | 51 | } 52 | \references{ 53 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 54 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 55 | \doi{10.20982/tqmp.16.4.p248} 56 | 57 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 58 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 59 | \doi{10.1080/10691898.2016.1246953} 60 | } 61 | \author{ 62 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 63 | } 64 | -------------------------------------------------------------------------------- /man/RobbinsMonro.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/RobbinsMonro.R 3 | \name{RobbinsMonro} 4 | \alias{RobbinsMonro} 5 | \alias{print.RM} 6 | \alias{plot.RM} 7 | \title{Robbins-Monro (1951) stochastic root-finding algorithm} 8 | \usage{ 9 | RobbinsMonro( 10 | f, 11 | p, 12 | ..., 13 | Polyak_Juditsky = FALSE, 14 | maxiter = 500L, 15 | miniter = 100L, 16 | k = 3L, 17 | tol = 1e-05, 18 | verbose = TRUE, 19 | fn.a = function(iter, a = 1, b = 1/2, c = 0, ...) a/(iter + c)^b 20 | ) 21 | 22 | \method{print}{RM}(x, ...) 23 | 24 | \method{plot}{RM}(x, par = 1, main = NULL, Polyak_Juditsky = FALSE, ...) 25 | } 26 | \arguments{ 27 | \item{f}{noisy function for which the root is sought} 28 | 29 | \item{p}{vector of starting values to be passed as \code{f(p, ...)}} 30 | 31 | \item{...}{additional named arguments to be passed to \code{f}} 32 | 33 | \item{Polyak_Juditsky}{logical; apply the Polyak and Juditsky (1992) 34 | running-average method? Returns the final running average estimate 35 | using the Robbins-Monro updates (also applies to \code{plot}). 36 | Note that this should only be 37 | used when the step-sizes are sufficiently large so that the Robbins-Monro 38 | have the ability to stochastically explore around the root (not just 39 | approach it from one side, which occurs when using small steps)} 40 | 41 | \item{maxiter}{the maximum number of iterations (default 500)} 42 | 43 | \item{miniter}{minimum number of iterations (default 100)} 44 | 45 | \item{k}{number of consecutive \code{tol} criteria required before terminating} 46 | 47 | \item{tol}{tolerance criteria for convergence on the changes in the 48 | updated \code{p} elements. Must be achieved on \code{k} (default 3) 49 | successive occasions} 50 | 51 | \item{verbose}{logical; should the iterations and estimate be printed to the 52 | console?} 53 | 54 | \item{fn.a}{function to create the \code{a} coefficient in the Robbins-Monro 55 | noise filter. Requires the first argument is the current iteration (\code{iter}), 56 | provide one or more arguments, and (optionally) the \code{...}. Sequence function 57 | is of the form recommended by Spall (2000). 58 | 59 | Note that if a different function is provided it must satisfy the property 60 | that \eqn{\sum^\infty_{i=1} a_i = \infty} and 61 | \eqn{\sum^\infty_{i=1} a_i^2 < \infty}} 62 | 63 | \item{x}{an object of class \code{RM}} 64 | 65 | \item{par}{which parameter in the original vector \code{p} to include in the plot} 66 | 67 | \item{main}{plot title} 68 | } 69 | \description{ 70 | Function performs stochastic root solving for the provided \code{f(x)} 71 | using the Robbins-Monro (1951) algorithm. Differs from deterministic 72 | cousins such as \code{\link{uniroot}} in that \code{f} may contain stochastic error 73 | components, where the root is obtained through the running average method 74 | provided by noise filter (see also \code{\link{PBA}}). 75 | Assumes that \code{E[f(x)]} is non-decreasing in \code{x}. 76 | } 77 | \examples{ 78 | 79 | # find x that solves f(x) - b = 0 for the following 80 | f.root <- function(x, b = .6) 1 / (1 + exp(-x)) - b 81 | f.root(.3) 82 | 83 | xs <- seq(-3,3, length.out=1000) 84 | plot(xs, f.root(xs), type = 'l', ylab = "f(x)", xlab='x') 85 | abline(h=0, col='red') 86 | 87 | retuni <- uniroot(f.root, c(0,1)) 88 | retuni 89 | abline(v=retuni$root, col='blue', lty=2) 90 | 91 | # Robbins-Monro without noisy root, start with p=.9 92 | retrm <- RobbinsMonro(f.root, .9) 93 | retrm 94 | plot(retrm) 95 | 96 | # Same problem, however root function is now noisy. Hence, need to solve 97 | # fhat(x) - b + e = 0, where E(e) = 0 98 | f.root_noisy <- function(x) 1 / (1 + exp(-x)) - .6 + rnorm(1, sd=.02) 99 | sapply(rep(.3, 10), f.root_noisy) 100 | 101 | # uniroot "converges" unreliably 102 | set.seed(123) 103 | uniroot(f.root_noisy, c(0,1))$root 104 | uniroot(f.root_noisy, c(0,1))$root 105 | uniroot(f.root_noisy, c(0,1))$root 106 | 107 | # Robbins-Monro provides better convergence 108 | retrm.noise <- RobbinsMonro(f.root_noisy, .9) 109 | retrm.noise 110 | plot(retrm.noise) 111 | 112 | # different power (b) for fn.a() 113 | retrm.b2 <- RobbinsMonro(f.root_noisy, .9, b = .01) 114 | retrm.b2 115 | plot(retrm.b2) 116 | 117 | # use Polyak-Juditsky averaging (b should be closer to 0 to work well) 118 | retrm.PJ <- RobbinsMonro(f.root_noisy, .9, b = .01, 119 | Polyak_Juditsky = TRUE) 120 | retrm.PJ # final Polyak_Juditsky estimate 121 | plot(retrm.PJ) # Robbins-Monro history 122 | plot(retrm.PJ, Polyak_Juditsky = TRUE) # Polyak_Juditsky history 123 | 124 | } 125 | \references{ 126 | Polyak, B. T. and Juditsky, A. B. (1992). Acceleration of Stochastic 127 | Approximation by Averaging. SIAM Journal on Control and Optimization, 128 | 30(4):838. 129 | 130 | Robbins, H. and Monro, S. (1951). A stochastic approximation method. 131 | Ann.Math.Statistics, 22:400-407. 132 | 133 | Spall, J.C. (2000). Adaptive stochastic approximation by the simultaneous 134 | perturbation method. IEEE Trans. Autom. Control 45, 1839-1853. 135 | } 136 | \seealso{ 137 | \code{\link{uniroot}}, \code{\link{PBA}} 138 | } 139 | -------------------------------------------------------------------------------- /man/Serlin2000.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/Serlin2000.R 3 | \name{Serlin2000} 4 | \alias{Serlin2000} 5 | \title{Empirical detection robustness method suggested by Serlin (2000)} 6 | \usage{ 7 | Serlin2000(p, alpha, delta, R, CI = 0.95) 8 | } 9 | \arguments{ 10 | \item{p}{(optional) a vector containing the empirical detection rate(s) to be tested. 11 | Omitting this input will compute only the CV1 and CV2 values, while including this 12 | input will perform a one-sided hypothesis test for robustness} 13 | 14 | \item{alpha}{Type I error rate (e.g., often set to .05)} 15 | 16 | \item{delta}{(optional) symmetric robustness interval around \code{alpha} (e.g., a value 17 | of .01 when \code{alpha = .05} would test the robustness window .04-.06)} 18 | 19 | \item{R}{number of replications used in the simulation} 20 | 21 | \item{CI}{confidence interval for \code{alpha} as a proportion. Default of 0.95 22 | indicates a 95\% interval} 23 | } 24 | \description{ 25 | Hypothesis test to determine whether an observed empirical detection rate, 26 | coupled with a given robustness interval, statistically differs from the 27 | population value. Uses the methods described by Serlin (2000) as well to 28 | generate critical values (similar to confidence intervals, but define a fixed 29 | window of robustness). Critical values may be computed without performing the simulation 30 | experiment (hence, can be obtained a priori). 31 | } 32 | \examples{ 33 | 34 | # Cochran's criteria at alpha = .05 (i.e., 0.5 +- .01), assuming N = 2000 35 | Serlin2000(p = .051, alpha = .05, delta = .01, R = 2000) 36 | 37 | # Bradley's liberal criteria given p = .06 and .076, assuming N = 1000 38 | Serlin2000(p = .060, alpha = .05, delta = .025, R = 1000) 39 | Serlin2000(p = .076, alpha = .05, delta = .025, R = 1000) 40 | 41 | # multiple p-values 42 | Serlin2000(p = c(.05, .06, .07), alpha = .05, delta = .025, R = 1000) 43 | 44 | # CV values computed before simulation performed 45 | Serlin2000(alpha = .05, R = 2500) 46 | 47 | } 48 | \references{ 49 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 50 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 51 | \doi{10.20982/tqmp.16.4.p248} 52 | 53 | Serlin, R. C. (2000). Testing for Robustness in Monte Carlo Studies. 54 | \emph{Psychological Methods, 5}, 230-240. 55 | 56 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 57 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 58 | \doi{10.1080/10691898.2016.1246953} 59 | } 60 | \author{ 61 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 62 | } 63 | -------------------------------------------------------------------------------- /man/SimAnova.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimAnova.R 3 | \name{SimAnova} 4 | \alias{SimAnova} 5 | \title{Function for decomposing the simulation into ANOVA-based effect sizes} 6 | \usage{ 7 | SimAnova(formula, dat, subset = NULL, rates = TRUE) 8 | } 9 | \arguments{ 10 | \item{formula}{an R formula generally of a form suitable for \code{\link{lm}} or 11 | \code{\link{aov}}. However, if the dependent variable (left size of the equation) is omitted 12 | then all the dependent variables in the simulation will be used and the result will return 13 | a list of analyses} 14 | 15 | \item{dat}{an object returned from \code{\link{runSimulation}} of class \code{'SimDesign'}} 16 | 17 | \item{subset}{an optional argument to be passed to \code{\link{subset}} with the same name. Used to 18 | subset the results object while preserving the associated attributes} 19 | 20 | \item{rates}{logical; does the dependent variable consist of rates (e.g., returned from 21 | \code{\link{ECR}} or \code{\link{EDR}})? Default is TRUE, which will use the logit of the DV 22 | to help stabilize the proportion-based summary statistics when computing the parameters and 23 | effect sizes} 24 | } 25 | \description{ 26 | Given the results from a simulation with \code{\link{runSimulation}} form an ANOVA table (without 27 | p-values) with effect sizes based on the eta-squared statistic. These results provide approximate 28 | indications of observable simulation effects, therefore these ANOVA-based results are generally useful 29 | as exploratory rather than inferential tools. 30 | } 31 | \examples{ 32 | 33 | data(BF_sim) 34 | 35 | # all results (not usually good to mix Power and Type I results together) 36 | SimAnova(alpha.05.F ~ (groups_equal + distribution)^2, BF_sim) 37 | 38 | # only use anova for Type I error conditions 39 | SimAnova(alpha.05.F ~ (groups_equal + distribution)^2, BF_sim, subset = var_ratio == 1) 40 | 41 | # run all DVs at once using the same formula 42 | SimAnova(~ groups_equal * distribution, BF_sim, subset = var_ratio == 1) 43 | 44 | } 45 | \references{ 46 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 47 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 48 | \doi{10.20982/tqmp.16.4.p248} 49 | 50 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 51 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 52 | \doi{10.1080/10691898.2016.1246953} 53 | } 54 | \author{ 55 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 56 | } 57 | -------------------------------------------------------------------------------- /man/SimCheck.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimCheck.R 3 | \name{SimCheck} 4 | \alias{SimCheck} 5 | \title{Check for missing files in array simulations} 6 | \usage{ 7 | SimCheck(dir = NULL, files = NULL, min = 1L, max = NULL) 8 | } 9 | \arguments{ 10 | \item{dir}{character vector input indicating the directory 11 | containing the \code{.rds} files (see \code{files})} 12 | 13 | \item{files}{vector of file names referring to the saved simulation files. 14 | E.g. \code{c('mysim-1.rds', 'mysim-2.rds', ...)}} 15 | 16 | \item{min}{minimum number after the \code{'-'} deliminator. Default is 1} 17 | 18 | \item{max}{maximum number after the \code{'-'} deliminator. If not specified 19 | is extracted from the attributes in the first file} 20 | } 21 | \value{ 22 | returns an invisible list of indices of empty, missing and 23 | empty-and-missing row conditions. If no missing then an empty list is 24 | returned 25 | } 26 | \description{ 27 | Given the saved files from a \code{\link{runArraySimulation}} remote 28 | evaluation check whether all \code{.rds} files have been saved. If missing 29 | the missing row condition numbers will be returned. 30 | } 31 | \examples{ 32 | \dontrun{ 33 | 34 | # if files are in mysimfiles/ directory 35 | SimCheck('mysimfiles') 36 | 37 | # specifying files explicility 38 | setwd('mysimfiles/') 39 | SimCheck(files=dir()) 40 | 41 | } 42 | 43 | } 44 | \references{ 45 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 46 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 47 | \doi{10.20982/tqmp.16.4.p248} 48 | } 49 | \seealso{ 50 | \code{\link{runArraySimulation}}, \code{\link{SimCollect}} 51 | } 52 | \author{ 53 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 54 | } 55 | -------------------------------------------------------------------------------- /man/SimClean.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimClean.R 3 | \name{SimClean} 4 | \alias{SimClean} 5 | \title{Removes/cleans files and folders that have been saved} 6 | \usage{ 7 | SimClean( 8 | ..., 9 | dirs = NULL, 10 | temp = TRUE, 11 | results = FALSE, 12 | seeds = FALSE, 13 | save_details = list() 14 | ) 15 | } 16 | \arguments{ 17 | \item{...}{one or more character objects indicating which files to remove. Used to remove 18 | \code{.rds} files which were saved with \code{\link{saveRDS}} or when using the \code{save} 19 | and \code{filename} inputs to \code{\link{runSimulation}}} 20 | 21 | \item{dirs}{a character vector indicating which directories to remove} 22 | 23 | \item{temp}{logical; remove the temporary file saved when passing \code{save = TRUE}?} 24 | 25 | \item{results}{logical; remove the \code{.rds} results files 26 | saved when passing \code{save_results = TRUE}?} 27 | 28 | \item{seeds}{logical; remove the seed files 29 | saved when passing \code{save_seeds = TRUE}?} 30 | 31 | \item{save_details}{a list pertaining to information about how and where files were saved 32 | (see the corresponding list in \code{\link{runSimulation}})} 33 | } 34 | \description{ 35 | This function is mainly used in pilot studies where results and datasets have been temporarily saved 36 | by \code{\link{runSimulation}} but should be removed before beginning the full 37 | Monte Carlo simulation (e.g., remove files and folders which contained bugs/biased results). 38 | } 39 | \examples{ 40 | \dontrun{ 41 | 42 | # remove file called 'results.rds' 43 | SimClean('results.rds') 44 | 45 | # remove default temp file 46 | SimClean() 47 | 48 | # remove customized saved-results directory called 'mydir' 49 | SimClean(results = TRUE, save_details = list(save_results_dirname = 'mydir')) 50 | 51 | } 52 | } 53 | \references{ 54 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 55 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 56 | \doi{10.20982/tqmp.16.4.p248} 57 | 58 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 59 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 60 | \doi{10.1080/10691898.2016.1246953} 61 | } 62 | \seealso{ 63 | \code{\link{runSimulation}} 64 | } 65 | \author{ 66 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 67 | } 68 | -------------------------------------------------------------------------------- /man/SimDesign.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimDesign.R 3 | \name{SimDesign} 4 | \alias{SimDesign} 5 | \alias{SimDesign-package} 6 | \title{Structure for Organizing Monte Carlo Simulation Designs} 7 | \description{ 8 | Structure for Organizing Monte Carlo Simulation Designs 9 | } 10 | \details{ 11 | Provides tools to help organize Monte Carlo simulations in R. The package 12 | controls the structure and back-end of Monte Carlo simulations 13 | by utilizing a general generate-analyse-summarise strategy. The functions provided control common 14 | simulation issues such as re-simulating non-convergent results, support parallel 15 | back-end computations with proper random number generation within each simulation 16 | condition, 17 | save and restore temporary files, 18 | aggregate results across independent nodes, and provide native support for debugging. 19 | The primary function for organizing the simulations is \code{\link{runSimulation}}, while 20 | for array jobs submitting to HPC clusters (e.g., SLURM) see \code{\link{runArraySimulation}} 21 | and the associated package vignettes. 22 | 23 | For an in-depth tutorial of the package please refer to 24 | Chalmers and Adkins (2020; \doi{10.20982/tqmp.16.4.p248}). 25 | For an earlier didactic presentation of the package users can refer to Sigal and Chalmers 26 | (2016; \doi{10.1080/10691898.2016.1246953}). Finally, see the associated 27 | wiki on Github (\url{https://github.com/philchalmers/SimDesign/wiki}) 28 | for other tutorial material, examples, and applications of \code{SimDesign} to real-world simulations. 29 | } 30 | \references{ 31 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 32 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 33 | \doi{10.20982/tqmp.16.4.p248} 34 | 35 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 36 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 37 | \doi{10.1080/10691898.2016.1246953} 38 | } 39 | \author{ 40 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 41 | } 42 | \keyword{package} 43 | -------------------------------------------------------------------------------- /man/SimExtract.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimExtract.R 3 | \name{SimExtract} 4 | \alias{SimExtract} 5 | \title{Function to extract extra information from SimDesign objects} 6 | \usage{ 7 | SimExtract(object, what, fuzzy = TRUE, append = TRUE) 8 | } 9 | \arguments{ 10 | \item{object}{object returned from \code{\link{runSimulation}}} 11 | 12 | \item{what}{character vector indicating what information to extract, written in agnostic casing 13 | (e.g., \code{'ERRORS'} and \code{'errors'} are equivalent). 14 | 15 | Possible inputs include \code{'errors'} to return a \code{tibble} object containing counts of any 16 | error messages, \code{'warnings'} to return a \code{data.frame} object containing 17 | counts of any warning messages, \code{'seeds'} for the specified random number 18 | generation seeds, \code{'Random.seeds'} for the complete list of 19 | \code{.Random.seed} states across replications (only stored when 20 | \code{runSimulation(..., control = list(store_Random.seeds=TRUE))}), 21 | \code{'error_seeds'} and \code{'warning_seeds'} 22 | to extract the associated \code{.Random.seed} values associated with the ERROR/WARNING messages, 23 | \code{'results'} to extract the simulation results if the option \code{store_results} was passed to 24 | \code{\link{runSimulation}}, \code{'filename'} and \code{'save_results_dirname'} for extracting 25 | the saved file/directory name information (if used), \code{'functions'} to extract the defined functions 26 | used in the experiment, and \code{'design'} to extract the original design object 27 | 28 | Note that \code{'warning_seeds'} are not stored automatically in 29 | simulations and require passing \code{store_warning_seeds = TRUE} to \code{\link{runSimulation}}.} 30 | 31 | \item{fuzzy}{logical; use fuzzy string matching to reduce effectively identical messages? 32 | For example, when attempting to invert a matrix the error message 33 | \emph{"System is computationally singular: reciprocal condition number = 1.92747e-17"} and 34 | \emph{"System is computationally singular: reciprocal condition number = 2.15321e-16"} are 35 | effectively the same, and likely should be reported in the same columns of the extracted output} 36 | 37 | \item{append}{logical; append the design conditions when extracting error/warning messages?} 38 | } 39 | \description{ 40 | Function used to extract any error or warnings messages, the seeds associated 41 | with any error or warning messages, and any analysis results that were stored in the 42 | final simulation object. 43 | } 44 | \examples{ 45 | 46 | \dontrun{ 47 | 48 | Generate <- function(condition, fixed_objects) { 49 | int <- sample(1:10, 1) 50 | if(int > 5) warning('GENERATE WARNING: int greater than 5') 51 | if(int == 1) stop('GENERATE ERROR: integer is 1') 52 | rnorm(5) 53 | } 54 | 55 | Analyse <- function(condition, dat, fixed_objects) { 56 | int <- sample(1:10, 1) 57 | if(int > 5) warning('ANALYSE WARNING: int greater than 5') 58 | if(int == 1) stop('ANALYSE ERROR: int is 1') 59 | c(ret = 1) 60 | } 61 | 62 | Summarise <- function(condition, results, fixed_objects) { 63 | mean(results) 64 | } 65 | 66 | res <- runSimulation(replications = 100, seed=1234, verbose=FALSE, 67 | generate=Generate, analyse=Analyse, summarise=Summarise) 68 | res 69 | 70 | SimExtract(res, what = 'errors') 71 | SimExtract(res, what = 'warnings') 72 | seeds <- SimExtract(res, what = 'error_seeds') 73 | seeds[,1:3] 74 | 75 | # replicate a specific error for debugging (type Q to exit debugger) 76 | res <- runSimulation(replications = 100, load_seed=seeds[,1], debug='analyse', 77 | generate=Generate, analyse=Analyse, summarise=Summarise) 78 | 79 | 80 | 81 | } 82 | } 83 | \references{ 84 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 85 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 86 | \doi{10.20982/tqmp.16.4.p248} 87 | 88 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 89 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 90 | \doi{10.1080/10691898.2016.1246953} 91 | } 92 | \author{ 93 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 94 | } 95 | -------------------------------------------------------------------------------- /man/SimResults.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimResults.R 3 | \name{SimResults} 4 | \alias{SimResults} 5 | \title{Function to read in saved simulation results} 6 | \usage{ 7 | SimResults(obj, which, prefix = "results-row", wd = getwd()) 8 | } 9 | \arguments{ 10 | \item{obj}{object returned from \code{\link{runSimulation}} where \code{save_results = TRUE} 11 | or \code{store_results} was used. If the former then the remaining function arguments can 12 | be useful for reading in specific files} 13 | 14 | \item{which}{a numeric vector indicating which rows should be read in. If missing, all rows will be 15 | read in} 16 | 17 | \item{prefix}{character indicating prefix used for stored files} 18 | 19 | \item{wd}{working directory; default is found with \code{\link{getwd}}.} 20 | } 21 | \value{ 22 | the returned result is either a nested list (when \code{length(which) > 1}) or a single list 23 | (when \code{length(which) == 1}) containing the simulation results. Each read-in result refers to 24 | a list of 4 elements: 25 | \describe{ 26 | \item{\code{condition}}{the associate row (ID) and conditions from the 27 | respective \code{design} object} 28 | \item{\code{results}}{the object with returned from the \code{analyse} function, potentially 29 | simplified into a matrix or data.frame} 30 | \item{\code{errors}}{a table containing the message and number of errors that caused 31 | the generate-analyse steps to be rerun. These should be inspected carefully as they 32 | could indicate validity issues with the simulation that should be noted} 33 | \item{\code{warnings}}{a table containing the message and number of non-fatal warnings 34 | which arose from the analyse step. These should be inspected carefully as they 35 | could indicate validity issues with the simulation that should be noted} 36 | } 37 | } 38 | \description{ 39 | If \code{\link{runSimulation}} was passed the flag \code{save_results = TRUE} then the 40 | row results corresponding to the \code{design} object will be stored to a suitable 41 | sub-directory as individual \code{.rds} files. While users could use \code{\link{readRDS}} directly 42 | to read these files in themselves, this convenience function will read the desired rows in 43 | automatically given the returned object 44 | from the simulation. Can be used to read in 1 or more \code{.rds} files at once (if more than 1 file 45 | is read in then the result will be stored in a list). 46 | } 47 | \examples{ 48 | 49 | \dontrun{ 50 | 51 | # store results (default behaviour) 52 | sim <- runSimulation(..., store_results = TRUE) 53 | SimResults(sim) 54 | 55 | # store results to drive if RAM issues are present 56 | obj <- runSimulation(..., save_results = TRUE) 57 | 58 | # row 1 results 59 | row1 <- SimResults(obj, 1) 60 | 61 | # rows 1:5, stored in a named list 62 | rows_1to5 <- SimResults(obj, 1:5) 63 | 64 | # all results 65 | rows_all <- SimResults(obj) 66 | 67 | } 68 | } 69 | \references{ 70 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 71 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 72 | \doi{10.20982/tqmp.16.4.p248} 73 | 74 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 75 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 76 | \doi{10.1080/10691898.2016.1246953} 77 | } 78 | \author{ 79 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 80 | } 81 | -------------------------------------------------------------------------------- /man/SimShiny.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/SimShiny.R 3 | \name{SimShiny} 4 | \alias{SimShiny} 5 | \title{Generate a basic Monte Carlo simulation GUI template} 6 | \usage{ 7 | SimShiny(filename = NULL, dir = getwd(), design, ...) 8 | } 9 | \arguments{ 10 | \item{filename}{an optional name of a text file to save the server and UI components 11 | (e.g., 'mysimGUI.R'). If omitted, the code will be printed to the R console instead} 12 | 13 | \item{dir}{the directory to write the files to. Default is the working directory} 14 | 15 | \item{design}{\code{design} object from \code{\link{runSimulation}}} 16 | 17 | \item{...}{arguments to be passed to \code{\link{runSimulation}}. Note that the 18 | \code{design} object is not used directly, and instead provides options to be 19 | selected in the GUI} 20 | } 21 | \description{ 22 | This function generates suitable stand-alone code from the \code{shiny} package to create simple 23 | web-interfaces for performing single condition Monte Carlo simulations. The template 24 | generated is relatively minimalistic, but allows the user to quickly and easily 25 | edit the saved files to customize the associated shiny elements as they see fit. 26 | } 27 | \examples{ 28 | \dontrun{ 29 | 30 | Design <- createDesign(sample_size = c(30, 60, 90, 120), 31 | group_size_ratio = c(1, 4, 8), 32 | standard_deviation_ratio = c(.5, 1, 2)) 33 | 34 | Generate <- function(condition, fixed_objects) { 35 | N <- condition$sample_size 36 | grs <- condition$group_size_ratio 37 | sd <- condition$standard_deviation_ratio 38 | if(grs < 1){ 39 | N2 <- N / (1/grs + 1) 40 | N1 <- N - N2 41 | } else { 42 | N1 <- N / (grs + 1) 43 | N2 <- N - N1 44 | } 45 | group1 <- rnorm(N1) 46 | group2 <- rnorm(N2, sd=sd) 47 | dat <- data.frame(group = c(rep('g1', N1), rep('g2', N2)), DV = c(group1, group2)) 48 | dat 49 | } 50 | 51 | Analyse <- function(condition, dat, fixed_objects) { 52 | welch <- t.test(DV ~ group, dat) 53 | ind <- t.test(DV ~ group, dat, var.equal=TRUE) 54 | 55 | # In this function the p values for the t-tests are returned, 56 | # and make sure to name each element, for future reference 57 | ret <- c(welch = welch$p.value, independent = ind$p.value) 58 | ret 59 | } 60 | 61 | Summarise <- function(condition, results, fixed_objects) { 62 | #find results of interest here (e.g., alpha < .1, .05, .01) 63 | ret <- EDR(results, alpha = .05) 64 | ret 65 | } 66 | 67 | # test that it works 68 | # Final <- runSimulation(design=Design, replications=5, 69 | # generate=Generate, analyse=Analyse, summarise=Summarise) 70 | 71 | # print code to console 72 | SimShiny(design=Design, generate=Generate, analyse=Analyse, 73 | summarise=Summarise, verbose=FALSE) 74 | 75 | # save shiny code to file 76 | SimShiny('app.R', design=Design, generate=Generate, analyse=Analyse, 77 | summarise=Summarise, verbose=FALSE) 78 | 79 | # run the application 80 | shiny::runApp() 81 | shiny::runApp(launch.browser = TRUE) # in web-browser 82 | 83 | } 84 | } 85 | \references{ 86 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 87 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 88 | \doi{10.20982/tqmp.16.4.p248} 89 | 90 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 91 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 92 | \doi{10.1080/10691898.2016.1246953} 93 | } 94 | \seealso{ 95 | \code{\link{runSimulation}} 96 | } 97 | \author{ 98 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 99 | } 100 | -------------------------------------------------------------------------------- /man/Summarise.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/functions.R 3 | \name{Summarise} 4 | \alias{Summarise} 5 | \title{Summarise simulated data using various population comparison statistics} 6 | \usage{ 7 | Summarise(condition, results, fixed_objects) 8 | } 9 | \arguments{ 10 | \item{condition}{a single row from the \code{design} input from \code{\link{runSimulation}} 11 | (as a \code{data.frame}), indicating the simulation conditions} 12 | 13 | \item{results}{a \code{tibble} data frame (if \code{Analyse} returned a named numeric vector of any 14 | length) or a \code{list} (if \code{Analyse} returned a \code{list} or multi-rowed \code{data.frame}) 15 | containing the analysis results from \code{\link{Analyse}}, 16 | where each cell is stored in a unique row/list element} 17 | 18 | \item{fixed_objects}{object passed down from \code{\link{runSimulation}}} 19 | } 20 | \value{ 21 | for best results should return a named \code{numeric} vector or \code{data.frame} 22 | with the desired meta-simulation results. Named \code{list} objects can also be returned, 23 | however the subsequent results must be extracted via \code{\link{SimExtract}} 24 | } 25 | \description{ 26 | This collapses the simulation results within each condition to composite 27 | estimates such as RMSE, bias, Type I error rates, coverage rates, etc. See the 28 | \code{See Also} section below for useful functions to be used within \code{Summarise}. 29 | } 30 | \examples{ 31 | \dontrun{ 32 | 33 | summarise <- function(condition, results, fixed_objects) { 34 | 35 | #find results of interest here (alpha < .1, .05, .01) 36 | lessthan.05 <- EDR(results, alpha = .05) 37 | 38 | # return the results that will be appended to the design input 39 | ret <- c(lessthan.05=lessthan.05) 40 | ret 41 | } 42 | 43 | } 44 | 45 | } 46 | \references{ 47 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 48 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 49 | \doi{10.20982/tqmp.16.4.p248} 50 | 51 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 52 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 53 | \doi{10.1080/10691898.2016.1246953} 54 | } 55 | \seealso{ 56 | \code{\link{bias}}, \code{\link{RMSE}}, \code{\link{RE}}, \code{\link{EDR}}, 57 | \code{\link{ECR}}, \code{\link{MAE}}, \code{\link{SimExtract}} 58 | } 59 | -------------------------------------------------------------------------------- /man/addMissing.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/addMissing.R 3 | \name{addMissing} 4 | \alias{addMissing} 5 | \alias{add_missing} 6 | \title{Add missing values to a vector given a MCAR, MAR, or MNAR scheme} 7 | \usage{ 8 | addMissing(y, fun = function(y, rate = 0.1, ...) rep(rate, length(y)), ...) 9 | } 10 | \arguments{ 11 | \item{y}{an input vector that should contain missing data in the form of \code{NA}'s} 12 | 13 | \item{fun}{a user defined function indicating the missing data mechanism for each element in \code{y}. 14 | Function must return a vector of probability values with the length equal to the length of \code{y}. 15 | Each value in the returned vector indicates the probability that 16 | the respective element in y will be replaced with \code{NA}. 17 | Function must contain the argument \code{y}, representing the 18 | input vector, however any number of additional arguments can be included} 19 | 20 | \item{...}{additional arguments to be passed to \code{FUN}} 21 | } 22 | \value{ 23 | the input vector \code{y} with the sampled \code{NA} values 24 | (according to the \code{FUN} scheme) 25 | } 26 | \description{ 27 | Given an input vector, replace elements of this vector with missing values according to some scheme. 28 | Default method replaces input values with a MCAR scheme (where on average 10\% of the values will be 29 | replaced with \code{NA}s). MAR and MNAR are supported by replacing the default \code{FUN} argument. 30 | } 31 | \details{ 32 | Given an input vector y, and other relevant variables 33 | inside (X) and outside (Z) the data-set, the three types of missingness are: 34 | 35 | \describe{ 36 | \item{MCAR}{Missing completely at random (MCAR). This is realized by randomly 37 | sampling the values of the 38 | input vector (y) irrespective of the possible values in X and Z. 39 | Therefore missing values are randomly sampled and do not depend on any data characteristics and 40 | are truly random} 41 | \item{MAR}{Missing at random (MAR). This is realized when values in the dataset (X) 42 | predict the missing data mechanism in y; conceptually this is equivalent to 43 | \eqn{P(y = NA | X)}. This requires the user to define a custom missing data function} 44 | \item{MNAR}{Missing not at random (MNAR). This is similar to MAR except 45 | that the missing mechanism comes 46 | from the value of y itself or from variables outside the working dataset; 47 | conceptually this is equivalent to \eqn{P(y = NA | X, Z, y)}. This requires 48 | the user to define a custom missing data function} 49 | } 50 | } 51 | \examples{ 52 | \dontrun{ 53 | 54 | set.seed(1) 55 | y <- rnorm(1000) 56 | 57 | ## 10\% missing rate with default FUN 58 | head(ymiss <- addMissing(y), 10) 59 | 60 | ## 50\% missing with default FUN 61 | head(ymiss <- addMissing(y, rate = .5), 10) 62 | 63 | ## missing values only when female and low 64 | X <- data.frame(group = sample(c('male', 'female'), 1000, replace=TRUE), 65 | level = sample(c('high', 'low'), 1000, replace=TRUE)) 66 | head(X) 67 | 68 | fun <- function(y, X, ...){ 69 | p <- rep(0, length(y)) 70 | p[X$group == 'female' & X$level == 'low'] <- .2 71 | p 72 | } 73 | 74 | ymiss <- addMissing(y, X, fun=fun) 75 | tail(cbind(ymiss, X), 10) 76 | 77 | ## missingness as a function of elements in X (i.e., a type of MAR) 78 | fun <- function(y, X){ 79 | # missingness with a logistic regression approach 80 | df <- data.frame(y, X) 81 | mm <- model.matrix(y ~ group + level, df) 82 | cfs <- c(-5, 2, 3) #intercept, group, and level coefs 83 | z <- cfs \%*\% t(mm) 84 | plogis(z) 85 | } 86 | 87 | ymiss <- addMissing(y, X, fun=fun) 88 | tail(cbind(ymiss, X), 10) 89 | 90 | ## missing values when y elements are large (i.e., a type of MNAR) 91 | fun <- function(y) ifelse(abs(y) > 1, .4, 0) 92 | ymiss <- addMissing(y, fun=fun) 93 | tail(cbind(y, ymiss), 10) 94 | 95 | } 96 | 97 | } 98 | \references{ 99 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 100 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 101 | \doi{10.20982/tqmp.16.4.p248} 102 | 103 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 104 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 105 | \doi{10.1080/10691898.2016.1246953} 106 | } 107 | \author{ 108 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 109 | } 110 | -------------------------------------------------------------------------------- /man/bootPredict.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/bootPredict.R 3 | \name{bootPredict} 4 | \alias{bootPredict} 5 | \alias{boot_predict} 6 | \title{Compute prediction estimates for the replication size using bootstrap MSE estimates} 7 | \usage{ 8 | bootPredict( 9 | condition, 10 | generate, 11 | analyse, 12 | summarise, 13 | fixed_objects = NULL, 14 | ..., 15 | Rstar = seq(100, 500, by = 100), 16 | boot_draws = 1000 17 | ) 18 | 19 | boot_predict(...) 20 | } 21 | \arguments{ 22 | \item{condition}{a \code{data.frame} consisting of one row from the original \code{design} 23 | input object used within \code{\link{runSimulation}}} 24 | 25 | \item{generate}{see \code{\link{runSimulation}}} 26 | 27 | \item{analyse}{see \code{\link{runSimulation}}} 28 | 29 | \item{summarise}{see \code{\link{runSimulation}}} 30 | 31 | \item{fixed_objects}{see \code{\link{runSimulation}}} 32 | 33 | \item{...}{additional arguments to be passed to \code{\link{runSimulation}}} 34 | 35 | \item{Rstar}{a vector containing the size of the bootstrap subsets to obtain. Default 36 | investigates the vector [100, 200, 300, 400, 500] to compute the respective MSE terms} 37 | 38 | \item{boot_draws}{number of bootstrap replications to draw. Default is 1000} 39 | } 40 | \value{ 41 | returns a list of linear model objects (via \code{\link{lm}}) for each 42 | meta-statistics returned by the \code{summarise()} function 43 | } 44 | \description{ 45 | This function computes bootstrap mean-square error estimates to approximate the sampling behavior 46 | of the meta-statistics in SimDesign's \code{summarise} functions. A single design condition is 47 | supplied, and a simulation with \code{max(Rstar)} replications is performed whereby the 48 | generate-analyse results are collected. After obtaining these replication values, the 49 | replications are further drawn from (with replacement) using the differing sizes in \code{Rstar} 50 | to approximate the bootstrap MSE behavior given different replication sizes. Finally, given these 51 | bootstrap estimates linear regression models are fitted using the predictor term 52 | \code{one_sqrtR = 1 / sqrt(Rstar)} to allow extrapolation to replication sizes not observed in 53 | \code{Rstar}. For more information about the method and subsequent bootstrap MSE plots, 54 | refer to Koehler, Brown, and Haneuse (2009). 55 | } 56 | \examples{ 57 | 58 | set.seed(4321) 59 | Design <- createDesign(sigma = c(1, 2)) 60 | 61 | #------------------------------------------------------------------- 62 | 63 | Generate <- function(condition, fixed_objects) { 64 | dat <- rnorm(100, 0, condition$sigma) 65 | dat 66 | } 67 | 68 | Analyse <- function(condition, dat, fixed_objects) { 69 | CIs <- t.test(dat)$conf.int 70 | names(CIs) <- c('lower', 'upper') 71 | ret <- c(mean = mean(dat), CIs) 72 | ret 73 | } 74 | 75 | Summarise <- function(condition, results, fixed_objects) { 76 | ret <- c(mu_bias = bias(results[,"mean"], 0), 77 | mu_coverage = ECR(results[,c("lower", "upper")], parameter = 0)) 78 | ret 79 | } 80 | 81 | \dontrun{ 82 | # boot_predict supports only one condition at a time 83 | out <- bootPredict(condition=Design[1L, , drop=FALSE], 84 | generate=Generate, analyse=Analyse, summarise=Summarise) 85 | out # list of fitted linear model(s) 86 | 87 | # extract first meta-statistic 88 | mu_bias <- out$mu_bias 89 | 90 | dat <- model.frame(mu_bias) 91 | print(dat) 92 | 93 | # original R metric plot 94 | R <- 1 / dat$one_sqrtR^2 95 | plot(R, dat$MSE, type = 'b', ylab = 'MSE', main = "Replications by MSE") 96 | 97 | plot(MSE ~ one_sqrtR, dat, main = "Bootstrap prediction plot", xlim = c(0, max(one_sqrtR)), 98 | ylim = c(0, max(MSE)), ylab = 'MSE', xlab = expression(1/sqrt(R))) 99 | beta <- coef(mu_bias) 100 | abline(a = 0, b = beta, lty = 2, col='red') 101 | 102 | # what is the replication value when x-axis = .02? What's its associated expected MSE? 103 | 1 / .02^2 # number of replications 104 | predict(mu_bias, data.frame(one_sqrtR = .02)) # y-axis value 105 | 106 | # approximately how many replications to obtain MSE = .001? 107 | (beta / .001)^2 108 | } 109 | 110 | } 111 | \references{ 112 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 113 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 114 | \doi{10.20982/tqmp.16.4.p248} 115 | 116 | Koehler, E., Brown, E., & Haneuse, S. J.-P. A. (2009). On the Assessment of Monte Carlo Error in 117 | Simulation-Based Statistical Analyses. \emph{The American Statistician, 63}, 155-162. 118 | 119 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 120 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 121 | \doi{10.1080/10691898.2016.1246953} 122 | } 123 | \author{ 124 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 125 | } 126 | -------------------------------------------------------------------------------- /man/clusterSetRNGSubStream.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/util.R 3 | \name{clusterSetRNGSubStream} 4 | \alias{clusterSetRNGSubStream} 5 | \title{Set RNG sub-stream for Pierre L'Ecuyer's RngStreams} 6 | \usage{ 7 | clusterSetRNGSubStream(cl, seed) 8 | } 9 | \arguments{ 10 | \item{cl}{A cluster from the \code{parallel} package, or 11 | (if \code{NULL}) the registered cluster} 12 | 13 | \item{seed}{An integer vector of length 7 as given by \code{.Random.seed} when 14 | the L'Ecuyer-CMR RNG is in use. See\code{\link{RNG}} for the valid values} 15 | } 16 | \value{ 17 | invisible NULL 18 | } 19 | \description{ 20 | Sets the sub-stream RNG state within for Pierre L'Ecuyer's (1999) 21 | algorithm. Should be used within distributed array jobs 22 | after suitable L'Ecuyer's (1999) have been distributed to each array, and 23 | each array is further defined to use multi-core processing. See 24 | \code{\link[parallel]{clusterSetRNGStream}} for further information. 25 | } 26 | -------------------------------------------------------------------------------- /man/colVars.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/util.R 3 | \name{colVars} 4 | \alias{colVars} 5 | \alias{colSDs} 6 | \title{Form Column Standard Deviation and Variances} 7 | \usage{ 8 | colVars(x, na.rm = FALSE, unname = FALSE) 9 | 10 | colSDs(x, na.rm = FALSE, unname = FALSE) 11 | } 12 | \arguments{ 13 | \item{x}{an array of two dimensions containing numeric, complex, integer or logical values, 14 | or a numeric data frame} 15 | 16 | \item{na.rm}{logical; remove missing values in each respective column?} 17 | 18 | \item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable 19 | names?} 20 | } 21 | \description{ 22 | Form column standard deviation and variances for numeric arrays (or data frames). 23 | } 24 | \examples{ 25 | 26 | results <- matrix(rnorm(100), ncol=4) 27 | colnames(results) <- paste0('stat', 1:4) 28 | 29 | colVars(results) 30 | colSDs(results) 31 | 32 | results[1,1] <- NA 33 | colSDs(results) 34 | colSDs(results, na.rm=TRUE) 35 | colSDs(results, na.rm=TRUE, unname=TRUE) 36 | 37 | } 38 | \seealso{ 39 | \code{\link{colMeans}} 40 | } 41 | \author{ 42 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 43 | } 44 | -------------------------------------------------------------------------------- /man/expandDesign.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/Design.R 3 | \name{expandDesign} 4 | \alias{expandDesign} 5 | \title{Expand the simulation design object for array computing} 6 | \usage{ 7 | expandDesign(Design, repeat_conditions) 8 | } 9 | \arguments{ 10 | \item{Design}{object created by \code{\link{createDesign}} which should have 11 | its rows repeated for optimal HPC schedulers} 12 | 13 | \item{repeat_conditions}{integer vector used to repeat each design row 14 | the specified number of times. Can either be a single integer, which repeats 15 | each row this many times, or an integer vector equal to the number of total 16 | rows in the created object. 17 | 18 | This argument is useful when distributing independent row conditions to 19 | cluster computing environments, particularly with different \code{replication} 20 | information. For example, if 1000 replications in total are the target but 21 | the condition is repeated over 4 rows then only 250 replications per row 22 | would be required across the repeated conditions. See 23 | \code{\link{SimCollect}} for combining the simulation objects 24 | once complete} 25 | } 26 | \value{ 27 | a \code{tibble} or \code{data.frame} containing the simulation experiment 28 | conditions to be evaluated in \code{\link{runSimulation}} 29 | } 30 | \description{ 31 | Repeat each design row the specified number of times. This is primarily used 32 | for cluster computing where jobs are distributed with batches of replications 33 | and later aggregated into a complete simulation object 34 | (see \code{\link{runArraySimulation}} and \code{\link{SimCollect}}). 35 | } 36 | \examples{ 37 | \dontrun{ 38 | 39 | # repeat each row 4 times (for cluster computing) 40 | Design <- createDesign(N = c(10, 20), 41 | SD.equal = c(TRUE, FALSE)) 42 | Design4 <- expandDesign(Design, 4) 43 | Design4 44 | 45 | # repeat first two rows 2x and the rest 4 times (for cluster computing 46 | # where first two conditions are faster to execute) 47 | Design <- createDesign(SD.equal = c(TRUE, FALSE), 48 | N = c(10, 100, 1000)) 49 | Design24 <- expandDesign(Design, c(2,2,rep(4, 4))) 50 | Design24 51 | 52 | } 53 | } 54 | \references{ 55 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 56 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 57 | \doi{10.20982/tqmp.16.4.p248} 58 | 59 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 60 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 61 | \doi{10.1080/10691898.2016.1246953} 62 | } 63 | \seealso{ 64 | \code{\link{expandReplications}}, 65 | \code{\link{createDesign}}, \code{\link{SimCollect}}, 66 | \code{\link{runArraySimulation}} 67 | } 68 | \author{ 69 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 70 | } 71 | -------------------------------------------------------------------------------- /man/expandReplications.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/Design.R 3 | \name{expandReplications} 4 | \alias{expandReplications} 5 | \title{Expand the replications to match \code{expandDesign}} 6 | \usage{ 7 | expandReplications(replications, repeat_conditions) 8 | } 9 | \arguments{ 10 | \item{replications}{number of replications. Can be a scalar to reflect the same 11 | replications overall, or a vector of unequal replication bugets.} 12 | 13 | \item{repeat_conditions}{integer vector used to repeat each design row 14 | the specified number of times. Can either be a single integer, which repeats 15 | each row this many times, or an integer vector equal to the number of total 16 | rows in the created object.} 17 | } 18 | \value{ 19 | an integer vector of the replication budget matching 20 | the expanded structure in \code{\link{expandDesign}} 21 | } 22 | \description{ 23 | Expands the replication budget to match the \code{\link{expandDesign}} 24 | structure. 25 | } 26 | \examples{ 27 | \dontrun{ 28 | 29 | # repeat each row 4 times (for cluster computing) 30 | Design <- createDesign(N = c(10, 20), 31 | SD.equal = c(TRUE, FALSE)) 32 | Design4 <- expandDesign(Design, 4) 33 | Design4 34 | 35 | # match the replication budget. Target is 1000 replications 36 | (replications4 <- expandReplications(1000, 4)) 37 | 38 | # hence, evaluate each row in Design4 250 times 39 | cbind(Design4, replications4) 40 | 41 | #### 42 | # Unequal Design intensities 43 | 44 | Design24 <- createDesign(SD.equal = c(TRUE, FALSE), 45 | N = c(10, 100, 1000)) 46 | # split first two conditions into half rows, next two conditions into quarters, 47 | # while N=1000 condition into tenths 48 | expand <- c(2,2,4,4,10,10) 49 | eDesign <- expandDesign(Design, expand) 50 | eDesign 51 | 52 | # target replications is R=1000 per condition 53 | (replications24 <- expandReplications(1000, expand)) 54 | cbind(eDesign, replications24) 55 | 56 | } 57 | } 58 | \references{ 59 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 60 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 61 | \doi{10.20982/tqmp.16.4.p248} 62 | 63 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 64 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 65 | \doi{10.1080/10691898.2016.1246953} 66 | } 67 | \seealso{ 68 | \code{\link{expandDesign}} 69 | } 70 | \author{ 71 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 72 | } 73 | -------------------------------------------------------------------------------- /man/genSeeds.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/util.R 3 | \name{genSeeds} 4 | \alias{genSeeds} 5 | \alias{gen_seeds} 6 | \title{Generate random seeds} 7 | \usage{ 8 | genSeeds(design = 1L, iseed = NULL, arrayID = NULL, old.seeds = NULL) 9 | 10 | gen_seeds(...) 11 | } 12 | \arguments{ 13 | \item{design}{design matrix that requires a unique seed per condition, or 14 | a number indicating the number of seeds to generate. Default generates one 15 | number} 16 | 17 | \item{iseed}{the initial \code{set.seed} number used to generate a sequence 18 | of independent seeds according to the L'Ecuyer-CMRG (2002) method. This 19 | is recommended whenever quality random number generation is required 20 | across similar (if not identical) simulation jobs 21 | (e.g., see \code{\link{runArraySimulation}}). If \code{arrayID} is not 22 | specified then this will return a list of the associated seed for the 23 | full \code{design}} 24 | 25 | \item{arrayID}{(optional) single integer input corresponding to the specific 26 | row in the \code{design} object when using the \code{iseed} input. 27 | This is used in functions such as \code{\link{runArraySimulation}} 28 | to pull out the specific seed rather than manage a complete list, and 29 | is therefore more memory efficient} 30 | 31 | \item{old.seeds}{(optional) vector or matrix of last seeds used in 32 | previous simulations to avoid repeating the same seed on a subsequent run. 33 | Note that this approach should be used sparingly as seeds set more frequently 34 | are more likely to correlate, and therefore provide less optimal random 35 | number behaviour (e.g., if performing a simulation on two runs to achieve 36 | 5000 * 2 = 10,000 replications this is likely reasonable, 37 | but for simulations with 100 * 2 = 200 replications this is more 38 | likely to be sub-optimal). 39 | Length must be equal to the number of rows in \code{design}} 40 | 41 | \item{...}{does nothing} 42 | } 43 | \description{ 44 | Generate seeds to be passed to \code{runSimulation}'s \code{seed} input. Values 45 | are sampled from 1 to 2147483647, or are generated using L'Ecuyer-CMRG's (2002) 46 | method (returning either a list if \code{arrayID} is omitted, or the specific 47 | row value from this list if \code{arrayID} is included). 48 | } 49 | \examples{ 50 | 51 | # generate 1 seed (default) 52 | genSeeds() 53 | 54 | # generate 5 unique seeds 55 | genSeeds(5) 56 | 57 | # generate from nrow(design) 58 | design <- createDesign(factorA=c(1,2,3), 59 | factorB=letters[1:3]) 60 | seeds <- genSeeds(design) 61 | seeds 62 | 63 | # construct new seeds that are independent from original (use this sparingly) 64 | newseeds <- genSeeds(design, old.seeds=seeds) 65 | newseeds 66 | 67 | # can be done in batches too 68 | newseeds2 <- genSeeds(design, old.seeds=cbind(seeds, newseeds)) 69 | cbind(seeds, newseeds, newseeds2) # all unique 70 | 71 | ############ 72 | # generate seeds for runArraySimulation() 73 | (iseed <- genSeeds()) # initial seed 74 | seed_list <- genSeeds(design, iseed=iseed) 75 | seed_list 76 | 77 | # expand number of unique seeds given iseed (e.g., in case more replications 78 | # are required at a later date) 79 | seed_list_tmp <- genSeeds(nrow(design)*2, iseed=iseed) 80 | str(seed_list_tmp) # first 9 seeds identical to seed_list 81 | 82 | # more usefully for HPC, extract only the seed associated with an arrayID 83 | arraySeed.15 <- genSeeds(nrow(design)*2, iseed=iseed, arrayID=15) 84 | arraySeed.15 85 | 86 | } 87 | \author{ 88 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 89 | } 90 | -------------------------------------------------------------------------------- /man/getArrayID.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/getArrayID.R 3 | \name{getArrayID} 4 | \alias{getArrayID} 5 | \title{Get job array ID (e.g., from SLURM or other HPC array distributions)} 6 | \usage{ 7 | getArrayID(type = "slurm", trailingOnly = TRUE, ID.shift = 0L) 8 | } 9 | \arguments{ 10 | \item{type}{an integer indicating the element from the result of 11 | \code{\link{commandArgs}} to extract, or a \code{character} specifying the 12 | the type of. Default is \code{'slurm'}} 13 | 14 | \item{trailingOnly}{logical value passed to \code{\link{commandArgs}}. 15 | Only used when \code{type} is an integer} 16 | 17 | \item{ID.shift}{single integer value used to shift the array ID by a constant. 18 | Useful when there are array range limitation that must be specified in the 19 | shell files (e.g., array can only be 10000 but there are more rows 20 | in the \code{design} object). For example, if the array ID should be 10000 through 21 | 12000, but the cluster computer enviroment does not allow these indices, then 22 | including the arrange range as 1-2000 in the shell file with \code{shift=9999} 23 | would add this constant to the detected arrayID, thereby indexing the remaining 24 | row elements in the \code{design} object} 25 | } 26 | \description{ 27 | Get the array ID from an HPC array distribution job (e.g., from SLURM or 28 | from optional command line arguments). 29 | The array ID is used to index the rows in the design 30 | object in \code{\link{runArraySimulation}}. For instance, 31 | a SLURM array with 10 independent jobs might have the following shell 32 | instructions. 33 | } 34 | \details{ 35 | \describe{ 36 | \item{\code{#!/bin/bash -l}}{} 37 | \item{\code{#SBATCH --time=00:01:00}}{} 38 | \item{\code{#SBATCH --array=1-10}}{} 39 | } 40 | 41 | which names the associated jobs with the numbers 1 through 10. 42 | \code{getArrayID()} then extracts this information per array, which 43 | is used as the \code{runArraySimulation(design, ..., arrayID = getArrayID())} to 44 | pass specific rows for the \code{design} object. 45 | } 46 | \examples{ 47 | 48 | \dontrun{ 49 | 50 | # get slurm array ID 51 | arrayID <- getArrayID() 52 | 53 | # get ID based on first optional argument in shell specification 54 | arrayID <- getArrayID(type = 1) 55 | 56 | # pass to 57 | # runArraySimulation(design, ...., arrayID = arrayID) 58 | 59 | # increase detected arrayID by constant 9999 (for array 60 | specification limitations) 61 | arrayID <- getArrayID(ID.shift=9999) 62 | 63 | } 64 | 65 | } 66 | \seealso{ 67 | \code{\link{runArraySimulation}} 68 | } 69 | -------------------------------------------------------------------------------- /man/listAvailableNotifiers.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/notifications.R 3 | \name{listAvailableNotifiers} 4 | \alias{listAvailableNotifiers} 5 | \title{List All Available Notifiers} 6 | \usage{ 7 | listAvailableNotifiers() 8 | } 9 | \value{ 10 | A character vector of class names that have \code{notify.} methods. 11 | } 12 | \description{ 13 | Automatically detects all S3 classes that have a specialized \code{notify()} method 14 | (like \code{notify.MyNotifier}) and prints them as a character vector of class names 15 | (e.g., \code{"PushbulletNotifier"}, \code{"TelegramNotifier"}). 16 | 17 | Note that only classes defined and loaded at the time you call this function will 18 | appear. If you just created a new notifier in another file or package, ensure it's 19 | sourced/loaded first. 20 | } 21 | \examples{ 22 | \dontrun{ 23 | listAvailableNotifiers() 24 | # [1] "PushbulletNotifier" "TelegramNotifier" 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /man/manageMessages.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/manageMessages.R 3 | \name{manageMessages} 4 | \alias{manageMessages} 5 | \title{Increase the intensity or suppress the output of an observed message} 6 | \usage{ 7 | manageMessages( 8 | expr, 9 | allow = NULL, 10 | message2warning = NULL, 11 | message2error = NULL, 12 | ... 13 | ) 14 | } 15 | \arguments{ 16 | \item{expr}{expression to be evaluated (e.g., ret <- \code{myfun(args)}). 17 | Function should either be used as a wrapper, 18 | such as \code{manageMassages(ret <- myfun(args), ...)} or 19 | \code{ret <- manageMassages(myfun(args), ...)}, or more 20 | readably as a pipe, \code{ret <- myfun(args) |> manageMassages(...)}} 21 | 22 | \item{allow}{(optional) a \code{character} vector indicating messages that 23 | should still appear, while all other messages should remain suppressed. 24 | Each supplied message is matched using a \code{\link{grepl}} expression, so partial matching 25 | is supported (though more specific messages are less likely to throw 26 | false positives). If \code{NULL}, all messages will be suppressed unless 27 | they appear in \code{message2error} or \code{message2warning}} 28 | 29 | \item{message2warning}{(optional) Input can be a \code{character} vector containing 30 | messages that should probably be considered warning messages for the current application 31 | instead. Each supplied \code{character} vector element is matched using 32 | a \code{\link{grepl}} expression, 33 | so partial matching is supported (though more specific messages are less 34 | likely to throw false positives).} 35 | 36 | \item{message2error}{(optional) Input can be a \code{character} vector containing known-to-be-severe 37 | messages that should be converted to errors for the current application. 38 | See \code{message2warning} for details.} 39 | 40 | \item{...}{additional arguments passed to \code{\link{grepl}}} 41 | } 42 | \value{ 43 | returns the original result of \code{eval(expr)}, with warning 44 | messages either left the same, increased to errors, or suppressed (depending 45 | on the input specifications) 46 | } 47 | \description{ 48 | Function provides more nuanced management of known message outputs 49 | messages that appear in function calls outside the front-end users control 50 | (e.g., functions written in third-party packages). Specifically, 51 | this function provides a less nuclear approach than 52 | \code{\link{quiet}} and friends, which suppresses all \code{cat} and 53 | \code{message}s raised, and instead allows for specific messages to be 54 | raised either to warnings or, even more extremely, to errors. Note that for 55 | messages that are not suppressed the order with which the output and message 56 | calls appear in the original function is not retained. 57 | } 58 | \examples{ 59 | \dontrun{ 60 | 61 | myfun <- function(x, warn=FALSE){ 62 | message('This function is rather chatty') 63 | cat("It even prints in different output forms!\n") 64 | message('And even at different ') 65 | cat(" many times!\n") 66 | cat("Too many messages can be annoying \n") 67 | if(warn) 68 | warning('It may even throw warnings ') 69 | x 70 | } 71 | 72 | out <- myfun(1) 73 | out 74 | 75 | # tell the function to shhhh 76 | out <- quiet(myfun(1)) 77 | out 78 | 79 | # same default behaviour as quiet(), but potential for nuance 80 | out2 <- manageMessages(myfun(1)) 81 | identical(out, out2) 82 | 83 | # allow some messages to still get printed 84 | out2 <- manageMessages(myfun(1), allow = "many times!") 85 | out2 <- manageMessages(myfun(1), allow = "This function is rather chatty") 86 | 87 | # note: . matches single character (regex) 88 | out2 <- manageMessages(myfun(1), allow = c("many times.", 89 | "This function is rather chatty")) 90 | 91 | # convert specific message to warning 92 | out3 <- manageMessages(myfun(1), message2warning = "many times!") 93 | identical(out, out3) 94 | 95 | # other warnings also get through 96 | out3 <- manageMessages(myfun(1, warn=TRUE), message2warning = "times!") 97 | identical(out, out3) 98 | 99 | # convert message to error 100 | manageMessages(myfun(1), message2error = "m... times!") 101 | 102 | # multiple message intensity changes 103 | manageMessages(myfun(1), 104 | message2warning = "It even prints in different output forms", 105 | message2error = "many times!") 106 | 107 | manageMessages(myfun(1), 108 | allow = c("This function is rather chatty", 109 | "Too many messages can be annoying"), 110 | message2warning = "It even prints in different output forms", 111 | message2error = "many times!") 112 | 113 | } 114 | 115 | } 116 | \references{ 117 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 118 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 119 | \doi{10.20982/tqmp.16.4.p248} 120 | } 121 | \seealso{ 122 | \code{\link{manageWarnings}}, \code{\link{quiet}} 123 | } 124 | \author{ 125 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 126 | } 127 | -------------------------------------------------------------------------------- /man/nc.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/util.R 3 | \name{nc} 4 | \alias{nc} 5 | \title{Auto-named Concatenation of Vector or List} 6 | \usage{ 7 | nc(..., use.names = FALSE, error.on.duplicate = TRUE) 8 | } 9 | \arguments{ 10 | \item{...}{objects to be concatenated} 11 | 12 | \item{use.names}{logical indicating if \code{names} should be preserved (unlike \code{\link{c}}, 13 | default is \code{FALSE})} 14 | 15 | \item{error.on.duplicate}{logical; if the same object name appears in the returning object 16 | should an error be thrown? Default is \code{TRUE}} 17 | } 18 | \description{ 19 | This is a wrapper to the function \code{\link{c}}, however names the respective elements 20 | according to their input object name. For this reason, nesting \code{nc()} calls 21 | is not recommended (joining independent \code{nc()} calls via \code{c()} 22 | is however reasonable). 23 | } 24 | \examples{ 25 | 26 | A <- 1 27 | B <- 2 28 | C <- 3 29 | 30 | names(C) <- 'LetterC' 31 | 32 | # compare the following 33 | c(A, B, C) # unnamed 34 | 35 | nc(A, B, C) # named 36 | nc(this=A, B, C) # respects override named (same as c() ) 37 | nc(this=A, B, C, use.names = TRUE) # preserve original name 38 | 39 | \dontrun{ 40 | # throws errors if names not unique 41 | nc(this=A, this=B, C) 42 | nc(LetterC=A, B, C, use.names=TRUE) 43 | } 44 | 45 | # poor input choice names 46 | nc(t.test(c(1:2))$p.value, t.test(c(3:4))$p.value) 47 | 48 | # better to explicitly provide name 49 | nc(T1 = t.test(c(1:2))$p.value, 50 | T2 = t.test(c(3:4))$p.value) 51 | 52 | # vector of unnamed inputs 53 | A <- c(5,4,3,2,1) 54 | B <- c(100, 200) 55 | 56 | nc(A, B, C) # A's and B's numbered uniquely 57 | c(A, B, C) # compare 58 | nc(beta=A, B, C) # replacement of object name 59 | 60 | # retain names attributes (but append object name, when appropriate) 61 | names(A) <- letters[1:5] 62 | nc(A, B, C) 63 | nc(beta=A, B, C) 64 | nc(A, B, C, use.names=TRUE) 65 | 66 | # mix and match if some named elements work while others do not 67 | c( nc(A, B, use.names=TRUE), nc(C)) 68 | 69 | \dontrun{ 70 | # error, 'b' appears twice 71 | names(B) <- c('b', 'b2') 72 | nc(A, B, C, use.names=TRUE) 73 | } 74 | 75 | # List input 76 | A <- list(1) 77 | B <- list(2:3) 78 | C <- list('C') 79 | 80 | names(C) <- 'LetterC' 81 | 82 | # compare the following 83 | c(A, B, C) # unnamed 84 | 85 | nc(A, B, C) # named 86 | nc(this=A, B, C) # respects override named (same as c() and list() ) 87 | nc(this=A, B, C, use.names = TRUE) # preserve original name 88 | 89 | 90 | } 91 | \references{ 92 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 93 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 94 | \doi{10.20982/tqmp.16.4.p248} 95 | 96 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 97 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 98 | \doi{10.1080/10691898.2016.1246953} 99 | } 100 | -------------------------------------------------------------------------------- /man/new_PushbulletNotifier.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/notifications.R 3 | \name{new_PushbulletNotifier} 4 | \alias{new_PushbulletNotifier} 5 | \title{Create a Pushbullet Notifier} 6 | \usage{ 7 | new_PushbulletNotifier( 8 | config_path = "~/.rpushbullet.json", 9 | verbose_issues = FALSE 10 | ) 11 | } 12 | \arguments{ 13 | \item{config_path}{A character string specifying the path to the Pushbullet configuration file. 14 | Defaults to \code{"~/.rpushbullet.json"}.} 15 | 16 | \item{verbose_issues}{Logical. If \code{TRUE}, includes detailed information about warnings 17 | and errors in notifications. Default is \code{FALSE}.} 18 | } 19 | \value{ 20 | An S3 object of class \code{"PushbulletNotifier"} and \code{"Notifier"}. 21 | } 22 | \description{ 23 | Constructs a notifier object for sending messages via Pushbullet. This requires a 24 | Pushbullet account, the Pushbullet application installed on both a mobile device 25 | and computer, and a properly configured JSON file (typically \code{~/.rpushbullet.json}, 26 | using \code{RPushbullet::pbSetup()}). 27 | } 28 | \details{ 29 | To use \code{RPushbullet} in \code{SimDesign}, create a \code{PushbulletNotifier} 30 | object using \code{new_PushbulletNotifier()} and pass it to the \code{notifier} 31 | argument in \code{runSimulation()}. 32 | } 33 | \examples{ 34 | \dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} 35 | # Create a Pushbullet notifier (requires a valid configuration file) 36 | pushbullet_notifier <- new_PushbulletNotifier(verbose_issues = TRUE) 37 | \dontshow{\}) # examplesIf} 38 | } 39 | -------------------------------------------------------------------------------- /man/new_TelegramNotifier.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/notifications.R 3 | \name{new_TelegramNotifier} 4 | \alias{new_TelegramNotifier} 5 | \title{Create a Telegram Notifier} 6 | \usage{ 7 | new_TelegramNotifier(bot_token, chat_id, verbose_issues = FALSE) 8 | } 9 | \arguments{ 10 | \item{bot_token}{A character string representing your Telegram bot token, typically 11 | something like \code{"123456:ABC-xxxx"}.} 12 | 13 | \item{chat_id}{A character string or numeric representing the chat/group to send 14 | messages to.} 15 | 16 | \item{verbose_issues}{Logical. If TRUE, provides detailed information about warnings and errors in the notifications.} 17 | } 18 | \value{ 19 | An S3 object of class \code{"TelegramNotifier"}. 20 | } 21 | \description{ 22 | Constructs a notifier object for sending messages via Telegram. 23 | Requires a valid Telegram bot token and chat ID. 24 | } 25 | \details{ 26 | To use send notifications over Telegram with \code{httr} in \code{SimDesign}, 27 | install \code{httr}, set set up a Telegram bot, and obtain a bot token and chat ID. 28 | For more information, see the \href{https://core.telegram.org/bots}{Telegram Bots API}. 29 | Then use the \code{new_TelegramNotifier()} function to create a \code{TelegramNotifier} 30 | object and pass it to the \code{notifier} argument in \code{runSimulation()}. 31 | } 32 | \examples{ 33 | \dontshow{if (interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} 34 | # Create a Telegram notifier (requires setting up a Telegram Bot) 35 | telegram_notifier <- new_TelegramNotifier(bot_token = "123456:ABC-xyz", chat_id = "987654321") 36 | \dontshow{\}) # examplesIf} 37 | } 38 | -------------------------------------------------------------------------------- /man/notify.PushbulletNotifier.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/notifications.R 3 | \name{notify.PushbulletNotifier} 4 | \alias{notify.PushbulletNotifier} 5 | \title{S3 method to send notifications via Pushbullet} 6 | \usage{ 7 | \method{notify}{PushbulletNotifier}(notifier, event, event_data) 8 | } 9 | \arguments{ 10 | \item{notifier}{A TelegramNotifier object created with new_TelegramNotifier()} 11 | 12 | \item{event}{Character string indicating the notification trigger ("condition" or "complete")} 13 | 14 | \item{event_data}{List containing context information for the notification} 15 | } 16 | \value{ 17 | Invisibly returns NULL 18 | } 19 | \description{ 20 | S3 method to send notifications via Pushbullet 21 | } 22 | \keyword{internal} 23 | -------------------------------------------------------------------------------- /man/notify.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/notifications.R 3 | \name{notify} 4 | \alias{notify} 5 | \title{Send a simulation notification} 6 | \usage{ 7 | notify(notifier, event, event_data) 8 | } 9 | \arguments{ 10 | \item{notifier}{The notifier object} 11 | 12 | \item{event}{Character string indicating the notification trigger ("condition" or "complete")} 13 | 14 | \item{event_data}{List containing context information for the notification} 15 | } 16 | \description{ 17 | Package extensions can implement custom notifiers by creating S3 methods 18 | for this generic. 19 | } 20 | \keyword{internal} 21 | -------------------------------------------------------------------------------- /man/notify.TelegramNotifier.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/notifications.R 3 | \name{notify.TelegramNotifier} 4 | \alias{notify.TelegramNotifier} 5 | \title{S3 method to send notifications through the Telegram API.} 6 | \usage{ 7 | \method{notify}{TelegramNotifier}(notifier, event, event_data) 8 | } 9 | \arguments{ 10 | \item{notifier}{A TelegramNotifier object created with new_TelegramNotifier()} 11 | 12 | \item{event}{Character string indicating the notification trigger ("condition" or "complete")} 13 | 14 | \item{event_data}{List containing context information for the notification} 15 | } 16 | \value{ 17 | Invisibly returns NULL 18 | } 19 | \description{ 20 | S3 method to send notifications through the Telegram API. 21 | } 22 | \keyword{internal} 23 | -------------------------------------------------------------------------------- /man/quiet.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/util.R 3 | \name{quiet} 4 | \alias{quiet} 5 | \title{Suppress verbose function messages} 6 | \usage{ 7 | quiet(..., cat = TRUE, keep = FALSE, attr.name = "quiet.messages") 8 | } 9 | \arguments{ 10 | \item{...}{the functional expression to be evaluated} 11 | 12 | \item{cat}{logical; also capture calls from \code{\link{cat}}? If 13 | \code{FALSE} only \code{\link{message}} will be suppressed} 14 | 15 | \item{keep}{logical; return a character vector of the messages/concatenate 16 | and print strings as an attribute to the resulting object from \code{expr(...)}?} 17 | 18 | \item{attr.name}{attribute name to use when \code{keep = TRUE}} 19 | } 20 | \description{ 21 | This function is used to suppress information printed from external functions 22 | that make internal use of \code{\link{message}} and \code{\link{cat}}, which 23 | provide information in interactive R sessions. For simulations, the session 24 | is not interactive, and therefore this type of output should be suppressed. 25 | For similar behaviour for suppressing warning messages, see 26 | \code{\link{manageWarnings}}. 27 | } 28 | \examples{ 29 | 30 | myfun <- function(x, warn=FALSE){ 31 | message('This function is rather chatty') 32 | cat("It even prints in different output forms!\n") 33 | message('And even at different....') 34 | cat("...times!\n") 35 | if(warn) 36 | warning('It may even throw warnings!') 37 | x 38 | } 39 | 40 | out <- myfun(1) 41 | out 42 | 43 | # tell the function to shhhh 44 | out <- quiet(myfun(1)) 45 | out 46 | 47 | # which messages are suppressed? Extract stored attribute 48 | out <- quiet(myfun(1), keep = TRUE) 49 | attr(out, 'quiet.messages') 50 | 51 | # Warning messages still get through (see manageWarnings(suppress) 52 | # for better alternative than using suppressWarnings()) 53 | out2 <- myfun(2, warn=TRUE) |> quiet() # warning gets through 54 | out2 55 | 56 | # suppress warning message explicitly, allowing others to be raised if present 57 | myfun(2, warn=TRUE) |> quiet() |> 58 | manageWarnings(suppress='It may even throw warnings!') 59 | 60 | } 61 | \references{ 62 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 63 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 64 | \doi{10.20982/tqmp.16.4.p248} 65 | 66 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 67 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 68 | \doi{10.1080/10691898.2016.1246953} 69 | } 70 | \seealso{ 71 | \code{\link{manageWarnings}} 72 | } 73 | -------------------------------------------------------------------------------- /man/rHeadrick.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rHeadrick} 4 | \alias{rHeadrick} 5 | \title{Generate non-normal data with Headrick's (2002) method} 6 | \usage{ 7 | rHeadrick( 8 | n, 9 | mean = rep(0, nrow(sigma)), 10 | sigma = diag(length(mean)), 11 | skew = rep(0, nrow(sigma)), 12 | kurt = rep(0, nrow(sigma)), 13 | gam3 = NaN, 14 | gam4 = NaN, 15 | return_coefs = FALSE, 16 | coefs = NULL, 17 | control = list(trace = FALSE, max.ntry = 15, obj.tol = 1e-10, n.valid.sol = 1) 18 | ) 19 | } 20 | \arguments{ 21 | \item{n}{number of samples to draw} 22 | 23 | \item{mean}{a vector of k elements for the mean of the variables} 24 | 25 | \item{sigma}{desired k x k covariance matrix between bivariate non-normal variables} 26 | 27 | \item{skew}{a vector of k elements for the skewness of the variables} 28 | 29 | \item{kurt}{a vector of k elements for the kurtosis of the variables} 30 | 31 | \item{gam3}{(optional) explicitly supply the gamma 3 value? Default computes this internally} 32 | 33 | \item{gam4}{(optional) explicitly supply the gamma 4 value? Default computes this internally} 34 | 35 | \item{return_coefs}{logical; return the estimated coefficients only? See below regarding why this is useful.} 36 | 37 | \item{coefs}{(optional) supply previously estimated coefficients? This is useful when there must be multiple 38 | data sets drawn and will avoid repetitive computations. Must be the object returned after passing 39 | \code{return_coefs = TRUE}} 40 | 41 | \item{control}{a list of control parameters when locating the polynomial coefficients} 42 | } 43 | \description{ 44 | Generate multivariate non-normal distributions using the fifth-order polynomial 45 | method described by Headrick (2002). 46 | } 47 | \details{ 48 | This function is primarily a wrapper for the code written by Oscar L. Olvera Astivia 49 | (last edited Feb 26, 2015) with some modifications (e.g., better starting values 50 | for the Newton optimizer, passing previously saved coefs, etc). 51 | } 52 | \examples{ 53 | 54 | \dontrun{ 55 | set.seed(1) 56 | 57 | N <- 200 58 | mean <- c(rep(0,4)) 59 | Sigma <- matrix(.49, 4, 4) 60 | diag(Sigma) <- 1 61 | skewness <- c(rep(1,4)) 62 | kurtosis <- c(rep(2,4)) 63 | 64 | nonnormal <- rHeadrick(N, mean, Sigma, skewness, kurtosis) 65 | # cor(nonnormal) 66 | # psych::describe(nonnormal) 67 | 68 | #----------- 69 | # compute the coefficients, then supply them back to the function to avoid 70 | # extra computations 71 | 72 | cfs <- rHeadrick(N, mean, Sigma, skewness, kurtosis, return_coefs = TRUE) 73 | cfs 74 | 75 | # compare 76 | system.time(nonnormal <- rHeadrick(N, mean, Sigma, skewness, kurtosis)) 77 | system.time(nonnormal <- rHeadrick(N, mean, Sigma, skewness, kurtosis, 78 | coefs=cfs)) 79 | } 80 | 81 | } 82 | \references{ 83 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 84 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 85 | \doi{10.20982/tqmp.16.4.p248} 86 | 87 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 88 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 89 | \doi{10.1080/10691898.2016.1246953} 90 | 91 | Headrick, T. C. (2002). Fast fifth-order polynomial transforms for generating univariate and 92 | multivariate nonnormal distributions. \emph{Computational Statistics & Data Analysis, 40}, 685-711. 93 | 94 | Olvera Astivia, O. L., & Zumbo, B. D. (2015). A Cautionary Note on the Use of the Vale and Maurelli 95 | Method to Generate Multivariate, Nonnormal Data for Simulation Purposes. 96 | \emph{Educational and Psychological Measurement, 75}, 541-567. 97 | } 98 | \author{ 99 | Oscar L. Olvera Astivia and Phil Chalmers \email{rphilip.chalmers@gmail.com} 100 | } 101 | -------------------------------------------------------------------------------- /man/rValeMaurelli.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rValeMaurelli} 4 | \alias{rValeMaurelli} 5 | \title{Generate non-normal data with Vale & Maurelli's (1983) method} 6 | \usage{ 7 | rValeMaurelli( 8 | n, 9 | mean = rep(0, nrow(sigma)), 10 | sigma = diag(length(mean)), 11 | skew = rep(0, nrow(sigma)), 12 | kurt = rep(0, nrow(sigma)) 13 | ) 14 | } 15 | \arguments{ 16 | \item{n}{number of samples to draw} 17 | 18 | \item{mean}{a vector of k elements for the mean of the variables} 19 | 20 | \item{sigma}{desired k x k covariance matrix between bivariate non-normal variables} 21 | 22 | \item{skew}{a vector of k elements for the skewness of the variables} 23 | 24 | \item{kurt}{a vector of k elements for the kurtosis of the variables} 25 | } 26 | \description{ 27 | Generate multivariate non-normal distributions using the third-order polynomial method described 28 | by Vale & Maurelli (1983). If only a single variable is generated then this function 29 | is equivalent to the method described by Fleishman (1978). 30 | } 31 | \examples{ 32 | 33 | set.seed(1) 34 | 35 | # univariate with skew 36 | nonnormal <- rValeMaurelli(10000, mean=10, sigma=5, skew=1, kurt=3) 37 | # psych::describe(nonnormal) 38 | 39 | # multivariate with skew and kurtosis 40 | n <- 10000 41 | r12 <- .4 42 | r13 <- .9 43 | r23 <- .1 44 | cor <- matrix(c(1,r12,r13,r12,1,r23,r13,r23,1),3,3) 45 | sk <- c(1.5,1.5,0.5) 46 | ku <- c(3.75,3.5,0.5) 47 | 48 | nonnormal <- rValeMaurelli(n, sigma=cor, skew=sk, kurt=ku) 49 | # cor(nonnormal) 50 | # psych::describe(nonnormal) 51 | 52 | } 53 | \references{ 54 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 55 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 56 | \doi{10.20982/tqmp.16.4.p248} 57 | 58 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 59 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 60 | \doi{10.1080/10691898.2016.1246953} 61 | 62 | Fleishman, A. I. (1978). A method for simulating non-normal distributions. 63 | \emph{Psychometrika, 43}, 521-532. 64 | 65 | Vale, C. & Maurelli, V. (1983). Simulating multivariate nonnormal distributions. 66 | \emph{Psychometrika, 48}(3), 465-471. 67 | } 68 | \author{ 69 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 70 | } 71 | -------------------------------------------------------------------------------- /man/rbind.SimDesign.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rbind.SimDesign.R 3 | \name{rbind.SimDesign} 4 | \alias{rbind.SimDesign} 5 | \title{Combine two separate SimDesign objects by row} 6 | \usage{ 7 | \method{rbind}{SimDesign}(...) 8 | } 9 | \arguments{ 10 | \item{...}{two or more \code{SimDesign} objects that should be 11 | combined by rows} 12 | } 13 | \value{ 14 | same object that is returned by \code{\link{runSimulation}} 15 | } 16 | \description{ 17 | This function combines two Monte Carlo simulations executed by 18 | \code{SimDesign}'s \code{\link{runSimulation}} function which, for all 19 | intents and purposes, could have been executed in a single run. 20 | This situation arises when a simulation has been completed, however 21 | the \code{Design} object was later modified to include more levels in the 22 | defined simulation factors. Rather than re-executing the previously completed 23 | simulation combinations, only the new combinations need to be evaluated 24 | into a different object and then \code{rbind} together to create the complete 25 | object combinations. 26 | } 27 | \examples{ 28 | \dontrun{ 29 | 30 | # modified example from runSimulation() 31 | 32 | Design <- createDesign(N = c(10, 20), 33 | SD = c(1, 2)) 34 | 35 | Generate <- function(condition, fixed_objects) { 36 | dat <- with(condition, rnorm(N, 10, sd=SD)) 37 | dat 38 | } 39 | 40 | Analyse <- function(condition, dat, fixed_objects) { 41 | ret <- mean(dat) # mean of the sample data vector 42 | ret 43 | } 44 | 45 | Summarise <- function(condition, results, fixed_objects) { 46 | ret <- c(mu=mean(results), SE=sd(results)) # mean and SD summary of the sample means 47 | ret 48 | } 49 | 50 | Final1 <- runSimulation(design=Design, replications=1000, 51 | generate=Generate, analyse=Analyse, summarise=Summarise) 52 | Final1 53 | 54 | ### 55 | # later decide that N = 30 should have also been investigated. Rather than 56 | # running the following object .... 57 | newDesign <- createDesign(N = c(10, 20, 30), 58 | SD = c(1, 2)) 59 | 60 | # ... only the new subset levels are executed to save time 61 | subDesign <- subset(newDesign, N == 30) 62 | subDesign 63 | 64 | Final2 <- runSimulation(design=subDesign, replications=1000, 65 | generate=Generate, analyse=Analyse, summarise=Summarise) 66 | Final2 67 | 68 | # glue results together by row into one object as though the complete 'Design' 69 | # object were run all at once 70 | Final <- rbind(Final1, Final2) 71 | Final 72 | 73 | summary(Final) 74 | 75 | } 76 | } 77 | \references{ 78 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 79 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 80 | \doi{10.20982/tqmp.16.4.p248} 81 | 82 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 83 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 84 | \doi{10.1080/10691898.2016.1246953} 85 | } 86 | \author{ 87 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 88 | } 89 | -------------------------------------------------------------------------------- /man/rint.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rint} 4 | \alias{rint} 5 | \title{Generate integer values within specified range} 6 | \usage{ 7 | rint(n, min, max, replace = TRUE, prob = NULL) 8 | } 9 | \arguments{ 10 | \item{n}{number of samples to draw} 11 | 12 | \item{min}{lower limit of the distribution. Must be finite} 13 | 14 | \item{max}{upper limit of the distribution. Must be finite} 15 | 16 | \item{replace}{should sampling be with replacement?} 17 | 18 | \item{prob}{a vector of probability weights for obtaining the elements of the vector being sampled} 19 | } 20 | \description{ 21 | Efficiently generate positive and negative integer values with (default) or without replacement. 22 | This function is mainly a wrapper to the \code{\link{sample.int}} function (which itself is much 23 | more efficient integer sampler than the more general \code{\link{sample}}), however is intended 24 | to work with both positive and negative integer ranges since \code{sample.int} only returns 25 | positive integer values that must begin at \code{1L}. 26 | } 27 | \examples{ 28 | 29 | set.seed(1) 30 | 31 | # sample 1000 integer values within 20 to 100 32 | x <- rint(1000, min = 20, max = 100) 33 | summary(x) 34 | 35 | # sample 1000 integer values within 100 to 10 billion 36 | x <- rint(1000, min = 100, max = 1e8) 37 | summary(x) 38 | 39 | # compare speed to sample() 40 | system.time(x <- rint(1000, min = 100, max = 1e8)) 41 | system.time(x2 <- sample(100:1e8, 1000, replace = TRUE)) 42 | 43 | # sample 1000 integer values within -20 to 20 44 | x <- rint(1000, min = -20, max = 20) 45 | summary(x) 46 | 47 | } 48 | \references{ 49 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 50 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 51 | \doi{10.20982/tqmp.16.4.p248} 52 | 53 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 54 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 55 | \doi{10.1080/10691898.2016.1246953} 56 | } 57 | \author{ 58 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 59 | } 60 | -------------------------------------------------------------------------------- /man/rinvWishart.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rinvWishart} 4 | \alias{rinvWishart} 5 | \title{Generate data with the inverse Wishart distribution} 6 | \usage{ 7 | rinvWishart(n = 1, df, sigma) 8 | } 9 | \arguments{ 10 | \item{n}{number of matrix observations to generate. By default \code{n = 1}, which returns a single 11 | symmetric matrix. If \code{n > 1} then a list of \code{n} symmetric matrices are returned instead} 12 | 13 | \item{df}{degrees of freedom} 14 | 15 | \item{sigma}{positive definite covariance matrix} 16 | } 17 | \value{ 18 | a numeric matrix with columns equal to \code{ncol(sigma)} when \code{n = 1}, or a list 19 | of \code{n} matrices with the same properties 20 | } 21 | \description{ 22 | Function generates data in the form of symmetric matrices from the inverse 23 | Wishart distribution given a covariance matrix and degrees of freedom. 24 | } 25 | \examples{ 26 | 27 | # random inverse Wishart matrix given variances [3,6], covariance 2, and df=15 28 | sigma <- matrix(c(3,2,2,6), 2, 2) 29 | x <- rinvWishart(sigma = sigma, df = 15) 30 | x 31 | 32 | # list of matrices 33 | x <- rinvWishart(20, sigma = sigma, df = 15) 34 | x 35 | 36 | } 37 | \references{ 38 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 39 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 40 | \doi{10.20982/tqmp.16.4.p248} 41 | 42 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 43 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 44 | \doi{10.1080/10691898.2016.1246953} 45 | } 46 | \seealso{ 47 | \code{\link{runSimulation}} 48 | } 49 | \author{ 50 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 51 | } 52 | -------------------------------------------------------------------------------- /man/rmgh.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rmgh} 4 | \alias{rmgh} 5 | \title{Generate data with the multivariate g-and-h distribution} 6 | \usage{ 7 | rmgh(n, g, h, mean = rep(0, length(g)), sigma = diag(length(mean))) 8 | } 9 | \arguments{ 10 | \item{n}{number of samples to draw} 11 | 12 | \item{g}{the g parameter(s) which control the skew of a distribution in terms of both direction 13 | and magnitude} 14 | 15 | \item{h}{the h parameter(s) which control the tail weight or elongation of a distribution and 16 | is positively related with kurtosis} 17 | 18 | \item{mean}{a vector of k elements for the mean of the variables} 19 | 20 | \item{sigma}{desired k x k covariance matrix between bivariate non-normal variables} 21 | } 22 | \description{ 23 | Generate non-normal distributions using the multivariate g-and-h distribution. Can be used to 24 | generate several different classes of univariate and multivariate distributions. 25 | } 26 | \examples{ 27 | 28 | set.seed(1) 29 | 30 | # univariate 31 | norm <- rmgh(10000,1e-5,0) 32 | hist(norm) 33 | 34 | skew <- rmgh(10000,1/2,0) 35 | hist(skew) 36 | 37 | neg_skew_platykurtic <- rmgh(10000,-1,-1/2) 38 | hist(neg_skew_platykurtic) 39 | 40 | # multivariate 41 | sigma <- matrix(c(2,1,1,4), 2) 42 | mean <- c(-1, 1) 43 | twovar <- rmgh(10000, c(-1/2, 1/2), c(0,0), 44 | mean=mean, sigma=sigma) 45 | hist(twovar[,1]) 46 | hist(twovar[,2]) 47 | plot(twovar) 48 | 49 | } 50 | \references{ 51 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 52 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 53 | \doi{10.20982/tqmp.16.4.p248} 54 | 55 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 56 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 57 | \doi{10.1080/10691898.2016.1246953} 58 | } 59 | \author{ 60 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 61 | } 62 | -------------------------------------------------------------------------------- /man/rmvnorm.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rmvnorm} 4 | \alias{rmvnorm} 5 | \title{Generate data with the multivariate normal (i.e., Gaussian) distribution} 6 | \usage{ 7 | rmvnorm(n, mean = rep(0, nrow(sigma)), sigma = diag(length(mean))) 8 | } 9 | \arguments{ 10 | \item{n}{number of observations to generate} 11 | 12 | \item{mean}{mean vector, default is \code{rep(0, length = ncol(sigma))}} 13 | 14 | \item{sigma}{positive definite covariance matrix, default is \code{diag(length(mean))}} 15 | } 16 | \value{ 17 | a numeric matrix with columns equal to \code{length(mean)} 18 | } 19 | \description{ 20 | Function generates data from the multivariate normal distribution given some mean vector and/or 21 | covariance matrix. 22 | } 23 | \examples{ 24 | 25 | # random normal values with mean [5, 10] and variances [3,6], and covariance 2 26 | sigma <- matrix(c(3,2,2,6), 2, 2) 27 | mu <- c(5,10) 28 | x <- rmvnorm(1000, mean = mu, sigma = sigma) 29 | head(x) 30 | summary(x) 31 | plot(x[,1], x[,2]) 32 | 33 | 34 | } 35 | \references{ 36 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 37 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 38 | \doi{10.20982/tqmp.16.4.p248} 39 | 40 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 41 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 42 | \doi{10.1080/10691898.2016.1246953} 43 | } 44 | \seealso{ 45 | \code{\link{runSimulation}} 46 | } 47 | \author{ 48 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 49 | } 50 | -------------------------------------------------------------------------------- /man/rmvt.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rgenerate.R 3 | \name{rmvt} 4 | \alias{rmvt} 5 | \title{Generate data with the multivariate t distribution} 6 | \usage{ 7 | rmvt(n, sigma, df, delta = rep(0, nrow(sigma)), Kshirsagar = FALSE) 8 | } 9 | \arguments{ 10 | \item{n}{number of observations to generate} 11 | 12 | \item{sigma}{positive definite covariance matrix} 13 | 14 | \item{df}{degrees of freedom. \code{df = 0} and \code{df = Inf} 15 | corresponds to the multivariate normal distribution} 16 | 17 | \item{delta}{the vector of non-centrality parameters of length \code{n} 18 | which specifies the either the modes (default) or non-centrality parameters} 19 | 20 | \item{Kshirsagar}{logical; triggers whether to generate data with non-centrality parameters 21 | or to adjust the simulated data to the mode of the distribution. The default uses the mode} 22 | } 23 | \value{ 24 | a numeric matrix with columns equal to \code{ncol(sigma)} 25 | } 26 | \description{ 27 | Function generates data from the multivariate t distribution given a covariance matrix, 28 | non-centrality parameter (or mode), and degrees of freedom. 29 | } 30 | \examples{ 31 | 32 | # random t values given variances [3,6], covariance 2, and df = 15 33 | sigma <- matrix(c(3,2,2,6), 2, 2) 34 | x <- rmvt(1000, sigma = sigma, df = 15) 35 | head(x) 36 | summary(x) 37 | plot(x[,1], x[,2]) 38 | 39 | 40 | } 41 | \references{ 42 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations 43 | with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 44 | \doi{10.20982/tqmp.16.4.p248} 45 | 46 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte 47 | Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156. 48 | \doi{10.1080/10691898.2016.1246953} 49 | } 50 | \seealso{ 51 | \code{\link{runSimulation}} 52 | } 53 | \author{ 54 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 55 | } 56 | -------------------------------------------------------------------------------- /man/rtruncate.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rtruncate.R 3 | \name{rtruncate} 4 | \alias{rtruncate} 5 | \title{Generate a random set of values within a truncated range} 6 | \usage{ 7 | rtruncate(n, rfun, range, ..., redraws = 100L) 8 | } 9 | \arguments{ 10 | \item{n}{number of observations to generate. This should be the first argument 11 | passed to \code{rfun}} 12 | 13 | \item{rfun}{a function to generate random values. Function can return 14 | a numeric/integer vector or matrix, and additional arguments 15 | requred for this function are passed through the argument \code{...}} 16 | 17 | \item{range}{a numeric vector of length two, where the first element 18 | indicates the lower bound and the second the upper bound. When values are 19 | generated outside these two bounds then data are redrawn until the bounded 20 | criteria is met. When the output of \code{rfun} is a matrix then this input 21 | can be specified as a matrix with two rows, where each the first row 22 | corresponds to the lower bound and the second row the upper bound for 23 | each generated column in the output} 24 | 25 | \item{...}{additional arguments to be passed to \code{rfun}} 26 | 27 | \item{redraws}{the maximum number of redraws to take before terminating the 28 | iterative sequence. This is in place as a safety in case the \code{range} 29 | is too small given the random number generator, causing too many 30 | consecutive rejections. Default is 100} 31 | } 32 | \value{ 33 | either a numeric vector or matrix, where all values are within the 34 | desired \code{range} 35 | } 36 | \description{ 37 | Function generates data given a supplied random number generating function that 38 | are constructed to fall within a particular range. Sampled values outside this 39 | range are discarded and re-sampled until the desired criteria has been met. 40 | } 41 | \details{ 42 | In simulations it is often useful to draw numbers from truncated distributions 43 | rather than across the full theoretical range. For instance, sampling parameters 44 | within the range [-4,4] from a normal distribution. The \code{rtruncate} 45 | function has been designed to accept any sampling function, where the first 46 | argument is the number of values to sample, and will draw values iteratively 47 | until the number of values within the specified bound are obtained. 48 | In situations where it is unlikely for the bounds to be located 49 | (e.g., sampling from a standard normal distribution where all values are 50 | within [-10,-6]) then the sampling scheme will throw an error if too many 51 | re-sampling executions are required (default will stop if more that 100 52 | calls to \code{rfun} are required). 53 | } 54 | \examples{ 55 | 56 | # n = 1000 truncated normal vector between [-2,3] 57 | vec <- rtruncate(1000, rnorm, c(-2,3)) 58 | summary(vec) 59 | 60 | # truncated correlated multivariate normal between [-1,4] 61 | mat <- rtruncate(1000, rmvnorm, c(-1,4), 62 | sigma = matrix(c(2,1,1,1),2)) 63 | summary(mat) 64 | 65 | # truncated correlated multivariate normal between [-1,4] for the 66 | # first column and [0,3] for the second column 67 | mat <- rtruncate(1000, rmvnorm, cbind(c(-1,4), c(0,3)), 68 | sigma = matrix(c(2,1,1,1),2)) 69 | summary(mat) 70 | 71 | # truncated chi-square with df = 4 between [2,6] 72 | vec <- rtruncate(1000, rchisq, c(2,6), df = 4) 73 | summary(vec) 74 | 75 | } 76 | \references{ 77 | Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable 78 | Monte Carlo Simulations with the SimDesign Package. 79 | \code{The Quantitative Methods for Psychology, 16}(4), 248-280. 80 | \doi{10.20982/tqmp.16.4.p248} 81 | 82 | Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics 83 | with Monte Carlo simulation. \code{Journal of Statistics Education, 24}(3), 84 | 136-156. \doi{10.1080/10691898.2016.1246953} 85 | } 86 | \seealso{ 87 | \code{\link{runSimulation}} 88 | } 89 | \author{ 90 | Phil Chalmers \email{rphilip.chalmers@gmail.com} 91 | } 92 | -------------------------------------------------------------------------------- /man/timeFormater.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/util.R 3 | \name{timeFormater} 4 | \alias{timeFormater} 5 | \title{Format time string to suitable numeric output} 6 | \usage{ 7 | timeFormater(time, output = "sec") 8 | } 9 | \arguments{ 10 | \item{time}{a character string to be formatted. If a numeric vector is supplied 11 | then this will be interpreted as minutes due to character coercion.} 12 | 13 | \item{output}{type of numeric output to convert time into. 14 | Currently supported are \code{'sec'} for seconds (default), 15 | \code{'min'} for minutes, \code{'hour'}, and \code{'day'}} 16 | } 17 | \description{ 18 | Format time input string into suitable numeric output metric (e.g., seconds). 19 | Input follows the \code{SBATCH} utility specifications. 20 | Accepted time formats include \code{"minutes"}, 21 | \code{"minutes:seconds"}, \code{"hours:minutes:seconds"}, 22 | \code{"days-hours"}, \code{"days-hours:minutes"} and 23 | \code{"days-hours:minutes:seconds"}. 24 | } 25 | \details{ 26 | For example, \code{time = "60"} indicates a maximum time of 60 minutes, 27 | \code{time = "03:00:00"} a maximum time of 3 hours, 28 | \code{time = "4-12"} a maximum of 4 days and 12 hours, and 29 | \code{time = "2-02:30:00"} a maximum of 2 days, 2 hours and 30 minutes. 30 | } 31 | \examples{ 32 | 33 | # Test cases (outputs in seconds) 34 | timeFormater("4-12") # day-hours 35 | timeFormater("4-12:15") # day-hours:minutes 36 | timeFormater("4-12:15:30") # day-hours:minutes:seconds 37 | 38 | timeFormater("30") # minutes 39 | timeFormater("30:30") # minutes:seconds 40 | timeFormater("4:30:30") # hours:minutes:seconds 41 | 42 | # output in hours 43 | timeFormater("4-12", output = 'hour') 44 | timeFormater("4-12:15", output = 'hour') 45 | timeFormater("4-12:15:30", output = 'hour') 46 | 47 | timeFormater("30", output = 'hour') 48 | timeFormater("30:30", output = 'hour') 49 | timeFormater("4:30:30", output = 'hour') 50 | 51 | # numeric input is understood as minutes 52 | timeFormater(42) # seconds 53 | timeFormater(42, output='min') # minutes 54 | 55 | } 56 | -------------------------------------------------------------------------------- /tests/tests/mpi/mpi.sh: -------------------------------------------------------------------------------- 1 | mpirun -np 4 R --slave -f simulation.R -------------------------------------------------------------------------------- /tests/tests/mpi/simulation.R: -------------------------------------------------------------------------------- 1 | library(SimDesign) 2 | 3 | Design <- createDesign(N = c(10, 20, 30)) 4 | 5 | # help(Generate) 6 | Generate <- function(condition, fixed_objects) { 7 | dat <- with(condition, rnorm(N, 10, 5)) # distributed N(10, 5) 8 | dat 9 | } 10 | 11 | # help(Analyse) 12 | Analyse <- function(condition, dat, fixed_objects) { 13 | ret <- mean(dat) # mean of the sample data vector 14 | ret 15 | } 16 | 17 | # help(Summarise) 18 | Summarise <- function(condition, results, fixed_objects) { 19 | ret <- c(mu=mean(results), SE=sd(results)) # mean and SD summary of the sample means 20 | ret 21 | } 22 | 23 | 24 | if(FALSE){ 25 | # approach is now deprecated in favour of using parallel="future" 26 | library(doMPI) 27 | cl <- startMPIcluster() 28 | registerDoMPI(cl) 29 | 30 | runSimulation(design=Design, replications=12, filename='mysimulation', 31 | generate=Generate, analyse=Analyse, summarise=Summarise, 32 | control = list(MPI=TRUE)) 33 | 34 | closeCluster(cl) 35 | mpi.quit() 36 | } 37 | -------------------------------------------------------------------------------- /tests/tests/mpi/slurm.slurm: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | #SBATCH --job-name="SLURM test (serial)" 3 | #SBATCH --mail-type=ALL 4 | #SBATCH --mail-user=chalmrp@yorku.ca 5 | #SBATCH --output=/dev/null 6 | #SBATCH --time=00:30:00 7 | #SBATCH --mem-per-cpu=2G 8 | #SBATCH --cpus-per-task=1 9 | #SBATCH --array=1-3 10 | 11 | module load r 12 | Rscript --vanilla slurm_test.R -------------------------------------------------------------------------------- /tests/tests/mpi/slurm_par.slurm: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | #SBATCH --job-name="SLURM test (parallel)" 3 | #SBATCH --mail-type=ALL 4 | #SBATCH --mail-user=chalmrp@yorku.ca 5 | #SBATCH --output=/dev/null 6 | #SBATCH --time=00:30:00 7 | #SBATCH --mem-per-cpu=2G 8 | #SBATCH --cpus-per-task=5 9 | #SBATCH --array=1-3 10 | 11 | module load r 12 | Rscript --vanilla slurm_test_par.R -------------------------------------------------------------------------------- /tests/tests/mpi/slurm_test.R: -------------------------------------------------------------------------------- 1 | library(SimDesign) 2 | 3 | Design <- createDesign(N = c(10, 20, 30)) 4 | 5 | Generate <- function(condition, fixed_objects) { 6 | dat <- with(condition, rnorm(N, 10, 5)) # distributed N(10, 5) 7 | dat 8 | } 9 | 10 | Analyse <- function(condition, dat, fixed_objects) { 11 | ret <- c(mean=mean(dat), median=median(dat)) # mean/median of sample data 12 | ret 13 | } 14 | 15 | Summarise <- function(condition, results, fixed_objects){ 16 | colMeans(results) 17 | } 18 | 19 | # iseed <- genSeeds() 20 | iseed <- 554184288 21 | 22 | ### On cluster submission, the active array ID is obtained via getArrayID(), 23 | ### and therefore should be used in real SLURM submissions 24 | arrayID <- getArrayID(type = 'slurm') 25 | 26 | # run the simulation (results not caught on job submission, only files saved) 27 | res <- runArraySimulation(design=Design, replications=50, 28 | generate=Generate, analyse=Analyse, 29 | summarise=Summarise, arrayID=arrayID, dirname = 'serial', 30 | iseed=iseed, filename='mysim') # saved as 'mysim-1.rds' 31 | -------------------------------------------------------------------------------- /tests/tests/mpi/slurm_test_par.R: -------------------------------------------------------------------------------- 1 | library(SimDesign) 2 | 3 | Design <- createDesign(N = c(10, 20, 30)) 4 | 5 | Generate <- function(condition, fixed_objects) { 6 | dat <- with(condition, rnorm(N, 10, 5)) # distributed N(10, 5) 7 | dat 8 | } 9 | 10 | Analyse <- function(condition, dat, fixed_objects) { 11 | ret <- c(mean=mean(dat), median=median(dat)) # mean/median of sample data 12 | ret 13 | } 14 | 15 | Summarise <- function(condition, results, fixed_objects){ 16 | colMeans(results) 17 | } 18 | 19 | # iseed <- genSeeds() 20 | iseed <- 554184288 21 | 22 | ### On cluster submission, the active array ID is obtained via getArrayID(), 23 | ### and therefore should be used in real SLURM submissions 24 | arrayID <- getArrayID(type = 'slurm') 25 | 26 | # run the simulation (results not caught on job submission, only files saved) 27 | res <- runArraySimulation(design=Design, replications=50, 28 | generate=Generate, analyse=Analyse, parallel=TRUE, 29 | summarise=Summarise, arrayID=arrayID,dirname = 'parallel', 30 | iseed=iseed, filename='mysim') 31 | --------------------------------------------------------------------------------