version 1.0.0

DESCRIPTION

@@ -0,0 +1,43 @@
+Package: jlmerclusterperm
+Title: Cluster-Based Permutation Analysis for Densely Sampled Time Data
+Version: 1.0.0
+Authors@R: 
+    person("June", "Choe", , "jchoe001@gmail.com", role = c("aut", "cre", "cph"),
+           comment = c(ORCID = "0000-0002-0701-921X"))
+Description: An implementation of fast cluster-based permutation analysis
+    (CPA) for densely-sampled time data developed in Maris & Oostenveld,
+    2007 <doi:10.1016/j.jneumeth.2007.03.024>. Supports (generalized,
+    mixed-effects) regression models for the calculation of timewise
+    statistics. Provides both a wholesale and a piecemeal interface to the
+    CPA procedure with an emphasis on interpretability and diagnostics.
+    Integrates 'Julia' libraries 'MixedModels.JL' and 'GLM.JL' for
+    performance improvements, with additional functionalities for
+    interfacing with 'Julia' from 'R' powered by the 'JuliaConnectoR'
+    package.
+License: MIT + file LICENSE
+URL: https://github.com/yjunechoe/jlmerclusterperm,
+        https://yjunechoe.github.io/jlmerclusterperm/
+BugReports: https://github.com/yjunechoe/jlmerclusterperm/issues
+Depends: R (>= 3.5)
+Imports: cli, generics, JuliaConnectoR, lme4, parallel, stats, utils
+Suggests: broom, broom.mixed, covr, dplyr, eyetrackingR, forcats,
+        future, ggplot2, knitr, MASS, patchwork, readr, rmarkdown,
+        scales, testthat (>= 3.0.0), tibble
+VignetteBuilder: knitr
+Config/testthat/edition: 3
+Encoding: UTF-8
+RoxygenNote: 7.2.3
+SystemRequirements: Julia (>= 1.8)
+Collate: 'jlmerclusterperm-package.R' 'aaa.R' 'utils.R'
+        'interop-utils.R' 'interop-utils-unexported.R' 'julia_rng.R'
+        'jlmer_spec.R' 'jlmer.R' 'compute_timewise_statistics.R'
+        'permute.R' 'permute_timewise_statistics.R'
+        'clusters_methods.R' 'extract_clusters.R' 'calculate_pvalue.R'
+        'clusterpermute.R' 'threshold_search.R' 'tidy.R' 'zzz.R'
+        'srr-stats-standards.R'
+NeedsCompilation: no
+Packaged: 2023-06-26 13:50:44 UTC; jchoe
+Author: June Choe [aut, cre, cph] (<https://orcid.org/0000-0002-0701-921X>)
+Maintainer: June Choe <jchoe001@gmail.com>
+Repository: CRAN
+Date/Publication: 2023-06-27 17:00:02 UTC

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2023
+COPYRIGHT HOLDER: June Choe

MD5

@@ -0,0 +1,79 @@
+99d065d3766d0bd95ccbbefd6ff86652 *DESCRIPTION
+d37c99895d661b1cbb1434dba60e554f *LICENSE
+ae8ed6d1e62154d0b44af768c246591c *NAMESPACE
+4970923336423f93a9132d3810cf5d1b *NEWS.md
+be49ecf1db6646c104427d1d426a03dd *R/aaa.R
+dded6ecb8f14127b62d5cc9f73bef825 *R/calculate_pvalue.R
+4d0a6389674d0dbc27f54be5c92a9095 *R/clusterpermute.R
+d7d7d78d410138ec1626903f2237fd15 *R/clusters_methods.R
+4867888cfb27a9cd98871505c524deb0 *R/compute_timewise_statistics.R
+08484587b9e29e9bbf90ced3d90863c0 *R/extract_clusters.R
+9ee9ded7d3f71dd858888ccb00fd86b1 *R/interop-utils-unexported.R
+dc50d0ccb8d23819a95f446d18c380e1 *R/interop-utils.R
+253cc215491df9bdea3ccbd790c1c275 *R/jlmer.R
+5ce0a812aaa2ac392b554292e2da9059 *R/jlmer_spec.R
+7e418f869c12eff57a7a089cde1d8327 *R/jlmerclusterperm-package.R
+94e4d066934fac9ef9db48b4eff084b8 *R/julia_rng.R
+543078391edd55b6f0b0f8daf84e7f88 *R/permute.R
+40d4dc2f70fca23e5945b6eabb0c6ece *R/permute_timewise_statistics.R
+1709a3f2998bb778fdb579b7bef162d6 *R/srr-stats-standards.R
+04dbb3190c9e1fa236853de886d1d4d6 *R/threshold_search.R
+28eadc273b5c00bfb4fd0d01b0cacd8d *R/tidy.R
+41792612dc2971527fa11a6cf7e9a47a *R/utils.R
+c87c2d9619a96ec469efd6c2e01e34ee *R/zzz.R
+990403547621e4727898f19b5c4910e1 *README.md
+f01682ffd9d5582c0d3b8a226f3c2b16 *build/partial.rdb
+adb9de191af250848e0dc03c194aeb6f *build/vignette.rds
+e8c98e39c7a9fcb4b53cb90eb37e61cc *inst/doc/jlmerclusterperm.R
+2eeeaca67c6a13b0217035742cecf79e *inst/doc/jlmerclusterperm.Rmd
+715c28b5a1198d707dcc3a0f4f302057 *inst/doc/jlmerclusterperm.html
+9ed999be829541c377dd352b9088af7a *inst/julia/01-utils.jl
+c881972c1846a7f2733b9ffd56b8666b *inst/julia/02-jlmer.jl
+f4bbbc7613bc8d374c333b05e4a27ef3 *inst/julia/03-compute_timewise_statistics.jl
+dfa1f3efae35458bf2a0f171ea8d3a74 *inst/julia/04-extract_clusters.jl
+8a6fb995580ca2b59f2b64b76d6dc428 *inst/julia/05-permute.jl
+465e79b47e376ff369e2528b0ec6c080 *inst/julia/06-permute_timewise_statistics.jl
+11370675fd52536178ae9ce38146c9a7 *inst/julia/Manifest.toml
+40c09ab1d240715bffa775b03686ea4e *inst/julia/Project.toml
+cc2bf4ca77c78822aaf3e9039c65c3fd *inst/julia/load-pkgs.jl
+16d7f1d4183d6f9ac89ab3b5472e662c *man/calculate_clusters_pvalues.Rd
+78b8eed1cb045b77ad0994fd71a4c633 *man/cluster_permutation_tidiers.Rd
+f391f90b43b90031a7bd47ec847e3bb0 *man/clusterpermute.Rd
+f869639236e67e253bf8b689001eb550 *man/compute_timewise_statistics.Rd
+d90a37c13fdd54bba8821253c3c910fc *man/extract_empirical_clusters.Rd
+82b8dd2ae5b21aed081c026dffda631a *man/extract_null_cluster_dists.Rd
+185842332c9c3cf20e477e28ec50f3e9 *man/figures/README-chickweight-1.png
+34eb6e9a2cd58064a651364eeb7ba524 *man/figures/README-empirical_statistics-1.png
+34eb6e9a2cd58064a651364eeb7ba524 *man/figures/README-plot-empirical_statistics-1.png
+37b23af74265d7a1a439baefb5bb2c1d *man/figures/clusterpermute_animation.gif
+568eb5f08bc3bc9853ed25d4473ff086 *man/figures/clusterpermute_slice.png
+ac2234ede8656d52d22a679fcad79b99 *man/figures/deCarvalho_fig7.jpg
+da15c86688a5645b0a4162997a3e9c63 *man/figures/desktop.ini
+6523b4232feb1248139e0347b693835b *man/figures/jlmerclusterperm_fn_design.png
+15549a03a42c7dd0ff5b8eb78f1c9c33 *man/figures/jlmerclusterperm_logo_plot.png
+9ddeb882f552b0d88e63dfee434e2a72 *man/figures/logo.png
+2e1a60a70886a0bb890351085236920f *man/jlmer.Rd
+92b8f3fb941d7c233447c845f4cb77ab *man/jlmerclusterperm-package.Rd
+9cfd94a83e341a8240c97b371a561613 *man/jlmerclusterperm_setup.Rd
+cb5fd7110a0f6cfc3ded1ae54c1a75de *man/julia_model_tidiers.Rd
+30de1302d68fddc2cc303514d6cabcd0 *man/julia_progress.Rd
+1e375a7369ffe57045421faaa498e95d *man/julia_rng.Rd
+4131b937b7bf17a5c574ce029f9348a6 *man/make_jlmer_spec.Rd
+6b344f72f28d84837c831ec2714d2c07 *man/permute_by_predictor.Rd
+de4ba66fc4a2fb339ac15914fe754ee3 *man/permute_timewise_statistics.Rd
+e6bee05432e598a82c88b34229fe1d39 *man/reexports.Rd
+f8a486bd6e9ce06479b0e9db3799b09f *man/to_jlmer.Rd
+fd59a0e73dc78e189c0ddd00ab298b32 *man/walk_threshold_steps.Rd
+be9f777cc0c27c3e38da655f9d5b8a3b *tests/testthat.R
+0a8ac524aa68f037650976f6da70f475 *tests/testthat/helper-skip.R
+ffc32b75d42ee62a5029e05a62e3bcea *tests/testthat/test-aaa.R
+cce80002cf27b7242cd6016dd7f37487 *tests/testthat/test-clusterpermute.R
+0673653e4f6c707ea9a7f9d952939d3e *tests/testthat/test-jlmer.R
+0d186c205ba8dd25d3f5e169fba286de *tests/testthat/test-jlmer_spec.R
+e615f953a14780626768f54f1ee9c38b *tests/testthat/test-julia_rng.R
+f80ff490f1cbf4a792508d5b48a0cfef *tests/testthat/test-permute.R
+5767147d5fd0e5e7f0d30c2fe3e62123 *tests/testthat/test-progress.R
+af6c7b09b65113c6554129be6631192b *tests/testthat/test-singularity.R
+5a0c129f5d65a9a286e1b99f6102bd18 *tests/testthat/test-threshold_search.R
+2499641f7105e7c1b41ac40c9a913318 *tests/testthat/test-timewise_statistics.R
+2eeeaca67c6a13b0217035742cecf79e *vignettes/jlmerclusterperm.Rmd

NAMESPACE

@@ -0,0 +1,41 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(format,empirical_clusters)
+S3method(format,jlmer_mod)
+S3method(format,jlmer_spec)
+S3method(format,null_cluster_dists)
+S3method(glance,jlmer_mod)
+S3method(print,CPA_out)
+S3method(print,empirical_clusters)
+S3method(print,jlmer_mod)
+S3method(print,jlmer_spec)
+S3method(print,null_cluster_dists)
+S3method(print,timewise_statistics)
+S3method(tidy,empirical_clusters)
+S3method(tidy,jlmer_mod)
+S3method(tidy,null_cluster_dists)
+S3method(tidy,timewise_statistics)
+export(calculate_clusters_pvalues)
+export(clusterpermute)
+export(clusters_are_comparable)
+export(compute_timewise_statistics)
+export(extract_empirical_clusters)
+export(extract_null_cluster_dists)
+export(get_rng_seed)
+export(get_rng_state)
+export(glance)
+export(jlmer)
+export(jlmerclusterperm_setup)
+export(julia_progress)
+export(make_jlmer_spec)
+export(permute_by_predictor)
+export(permute_timewise_statistics)
+export(reset_rng_state)
+export(set_rng_seed)
+export(set_rng_state)
+export(tidy)
+export(to_jlmer)
+export(walk_threshold_steps)
+importFrom(generics,glance)
+importFrom(generics,tidy)
+importFrom(stats,setNames)

NEWS.md

@@ -0,0 +1,21 @@
+# jlmerclusterperm 1.0.0
+
+### Breaking changes
+
+- The `threshold_steps` argument of `walk_threshold_steps()` is renamed to `steps`.
+
+### New features
+
+- New functions to interface with Julia RNG seed: `get_rng_seed()` and `set_rng_seed()`
+
+### Other improvements
+
+- `jlmerclusterperm_setup()` now echos `Pkg.instantiate()` to print precompilation information upon the first setup call
+
+# jlmerclusterperm 0.2.0
+
+Added vignettes. Significant usability improvements
+
+# jlmerclusterperm 0.1.0
+
+Initial release

R/aaa.R

@@ -0,0 +1,115 @@
+#' @keywords internal
+.jlmerclusterperm <- new.env(parent = emptyenv())
+.jlmerclusterperm$cli_theme <- list(
+  h1 = list(
+    `font-weight` = "regular",
+    `margin-top` = 0,
+    fmt = function(x) cli::rule(x, line_col = "white")
+  ),
+  span.lemph = list(color = "grey", `font-style` = "italic"),
+  span.el = list(color = "green"),
+  span.fm = list()
+)
+
+is_setup <- function() isTRUE(.jlmerclusterperm$is_setup)
+
+#' Initial setup for the jlmerclusterperm package
+#'
+#' @param ... Ignored.
+#' @param restart Whether to set up a fresh Julia session, given that one is already running.
+#'   If `FALSE` and `jlmerclusterperm_setup()` has already been called, nothing happens.
+#' @param verbose Print progress and messages from Julia in the console
+#'
+#' @examplesIf JuliaConnectoR::juliaSetupOk()
+#' \donttest{
+#' options("jlmerclusterperm.nthreads" = 2)
+#' jlmerclusterperm_setup(verbose = FALSE)
+#'
+#' \dontshow{
+#' JuliaConnectoR::stopJulia()
+#' }
+#' }
+#'
+#' @export
+#' @return TRUE
+jlmerclusterperm_setup <- function(..., restart = TRUE, verbose = TRUE) {
+  if (!JuliaConnectoR::juliaSetupOk()) cli::cli_abort("Cannot set up Julia for {.pkg jlmerclusterperm}.")
+  if (restart || !is_setup()) {
+    JuliaConnectoR::stopJulia()
+    setup_with_progress(verbose = verbose)
+    .jlmerclusterperm$is_setup <- TRUE
+  } else {
+    if (verbose) cli::cli_inform("Julia instance already running - skipping setup.")
+  }
+  invisible(TRUE)
+}
+
+setup_with_progress <- function(..., verbose = TRUE) {
+  start_with_threads(verbose = verbose)
+  set_projenv(verbose = verbose)
+  source_jl(verbose = verbose)
+}
+
+start_with_threads <- function(..., max_threads = 7, verbose = TRUE) {
+  JULIA_NUM_THREADS <- Sys.getenv("JULIA_NUM_THREADS")
+  nthreads <- getOption("jlmerclusterperm.nthreads", JULIA_NUM_THREADS) %|0|%
+    (min(max_threads, parallel::detectCores() - 1))
+  if (verbose) cli::cli_progress_step("Starting Julia with {nthreads} thread{?s}")
+  if (nthreads > 1) {
+    Sys.setenv("JULIA_NUM_THREADS" = nthreads)
+    suppressMessages(JuliaConnectoR::startJuliaServer())
+    Sys.setenv("JULIA_NUM_THREADS" = JULIA_NUM_THREADS)
+  } else {
+    suppressMessages(JuliaConnectoR::startJuliaServer())
+  }
+  .jlmerclusterperm$opts$nthreads <- nthreads
+}
+
+set_projenv <- function(..., verbose = TRUE) {
+  if (verbose) cli::cli_progress_step("Activating package environment")
+  pkgdir <- system.file("julia/", package = "jlmerclusterperm")
+  seed <- as.integer(getOption("jlmerclusterperm.seed", 1L))
+  JuliaConnectoR::juliaCall("cd", pkgdir)
+  JuliaConnectoR::juliaEval("using Pkg")
+  JuliaConnectoR::juliaEval('Pkg.activate(".", io = devnull)')
+  JuliaConnectoR::juliaEval("Pkg.instantiate()") # io = devnull
+  JuliaConnectoR::juliaEval("Pkg.resolve(io = devnull)")
+  JuliaConnectoR::juliaCall("cd", getwd())
+  JuliaConnectoR::juliaEval(paste0("pg_width = ", max(1L, cli::console_width() - 44L)))
+  JuliaConnectoR::juliaEval("pg_io = stderr")
+  JuliaConnectoR::juliaEval(paste0("using Random123; const rng = Threefry2x((", seed, ", 20))"))
+  .jlmerclusterperm$opts$seed <- seed
+  .jlmerclusterperm$opts$pkgdir <- pkgdir
+}
+
+source_jl <- function(..., verbose = TRUE) {
+  jl_pkgs <- readLines(file.path(.jlmerclusterperm$opts$pkgdir, "load-pkgs.jl"))
+  jl_scripts <- list.files(.jlmerclusterperm$opts$pkgdir, pattern = "\\d{2}-.*\\.jl$", full.names = TRUE)
+  load_steps <- c(jl_pkgs, jl_scripts)
+  i <- 1L
+  if (verbose) cli::cli_progress_step("Running package setup scripts ({i}/{length(load_steps)})")
+  for (i in seq_along(load_steps)) {
+    if (verbose) cli::cli_progress_update()
+    jl_load <- load_steps[i]
+    if (grepl("^using ", jl_load)) {
+      JuliaConnectoR::juliaEval(jl_load)
+    } else {
+      JuliaConnectoR::juliaCall("include", jl_load)
+    }
+  }
+  exported_fns <- c(
+    "jlmer", "compute_timewise_statistics",
+    "extract_clusters", "permute_timewise_statistics",
+    "guess_shuffle_as", "permute_by_predictor"
+  )
+  for (jl_fn in exported_fns) {
+    .jlmerclusterperm[[jl_fn]] <- JuliaConnectoR::juliaFun(jl_fn)
+  }
+  .jlmerclusterperm$exported_fns <- exported_fns
+}
+
+#' @keywords internal
+dev_source <- function() { # nocov start
+  .jlmerclusterperm$opts$pkgdir <- system.file("julia/", package = "jlmerclusterperm")
+  source_jl()
+} # nocov end