|
| 1 | +#' Create New DCE Experiment |
| 2 | +#' |
| 3 | +#' Scaffolds a new experiment directory with all necessary template files. |
| 4 | +#' Creates a complete, ready-to-configure experiment structure. |
| 5 | +#' |
| 6 | +#' @param path Character. Path where the experiment directory will be created. |
| 7 | +#' @param open Logical. Open the directory in file explorer after creation. |
| 8 | +#' Defaults to `TRUE` in interactive sessions. |
| 9 | +#' |
| 10 | +#' @return Invisibly returns the path to the created experiment directory. |
| 11 | +#' |
| 12 | +#' @details |
| 13 | +#' Creates an experiment directory with the following structure: |
| 14 | +#' ``` |
| 15 | +#' path/ |
| 16 | +#' ├── app.R # Shiny application |
| 17 | +#' ├── utils.R # App utility functions |
| 18 | +#' ├── config.yaml # Experiment configuration |
| 19 | +#' ├── attributes.csv # Attribute definitions |
| 20 | +#' ├── intro.txt # Introduction text |
| 21 | +#' ├── outro.txt # Closing text |
| 22 | +#' └── www/ # Static assets directory |
| 23 | +#' ``` |
| 24 | +#' |
| 25 | +#' After creation, edit `config.yaml` and `attributes.csv` to define your |
| 26 | +#' experiment, then run [prepare_experiment()] to generate the design. |
| 27 | +#' |
| 28 | +#' @seealso [prepare_experiment()], [run_experiment()], [deploy_experiment()] |
| 29 | +#' |
| 30 | +#' @examples |
| 31 | +#' \dontrun{ |
| 32 | +#' # Create a new experiment |
| 33 | +#' create_experiment("my_study") |
| 34 | +#' |
| 35 | +#' # Edit config.yaml and attributes.csv, then: |
| 36 | +#' prepare_experiment("my_study") |
| 37 | +#' run_experiment("my_study") |
| 38 | +#' } |
| 39 | +#' |
| 40 | +#' @export |
| 41 | +create_experiment <- function(path, open = interactive()) { |
| 42 | + # Validate path |
| 43 | + checkmate::assert_character(path, len = 1, min.chars = 1) |
| 44 | + |
| 45 | + # Check if directory already exists |
| 46 | + |
| 47 | + if (dir.exists(path)) { |
| 48 | + cli::cli_abort("Directory already exists: {.path {path}}") |
| 49 | + } |
| 50 | + |
| 51 | + # Get template directory |
| 52 | + |
| 53 | + template_dir <- system.file("templates", package = "dcelab") |
| 54 | + if (template_dir == "") { |
| 55 | + cli::cli_abort( |
| 56 | + "Template directory not found. Is dcelab installed correctly?" |
| 57 | + ) |
| 58 | + } |
| 59 | + |
| 60 | + # Create experiment directory |
| 61 | + dir.create(path, recursive = TRUE, showWarnings = FALSE) |
| 62 | + dir.create(file.path(path, "www"), showWarnings = FALSE) |
| 63 | + |
| 64 | + # Copy template files |
| 65 | + template_files <- list.files(template_dir, full.names = TRUE) |
| 66 | + file.copy(template_files, path, recursive = TRUE) |
| 67 | + |
| 68 | + cli::cli_alert_success("Created experiment at {.path {path}}") |
| 69 | + cli::cli_bullets(c( |
| 70 | + "i" = "Next steps:", |
| 71 | + " " = "1. Edit {.file config.yaml} to configure your experiment", |
| 72 | + " " = "2. Edit {.file attributes.csv} to define attributes and levels", |
| 73 | + " " = "3. Run {.code prepare_experiment(\"{path}\")} to generate design", |
| 74 | + " " = "4. Run {.code run_experiment(\"{path}\")} to test locally" |
| 75 | + )) |
| 76 | + |
| 77 | + # Open directory if requested |
| 78 | + |
| 79 | + if (open && interactive()) { |
| 80 | + utils::browseURL(path) |
| 81 | + } |
| 82 | + |
| 83 | + invisible(path) |
| 84 | +} |
0 commit comments