appendix-skeleton.qmd

---
title: "Analysis Skeleton (R Template)"
---

Copy-paste starting point for a new JASP analysis file. This follows the patterns described in @sec-r-backend. Assumes `preloadData: true` (the default) in `Description.qml`, so the `dataset` argument is already loaded.

```r
#
# Copyright (C) 2024 University of Amsterdam
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#

# Main entry point ----
# The function name must match the `func` field in Description.qml.
# Receives: jaspResults (persistent output container),
#           dataset     (preloaded data frame),
#           options     (named list of user selections from QML).
MyAnalysis <- function(jaspResults, dataset, options) {

  # 1. Can we compute?
  ready <- length(options[["variables"]]) > 0

  # 2. Validate
  if (ready)
    .myAnalysisCheckErrors(dataset, options)

  # 3. Compute (stores result in jaspResults)
  if (ready)
    .myAnalysisComputeResults(jaspResults, dataset, options)

  # 4. Create output — each function writes to jaspResults in place
  .myAnalysisMainTable(jaspResults, options, ready)
  .myAnalysisPlot(     jaspResults, options, ready)

  return()
}

# Error checking ----
.myAnalysisCheckErrors <- function(dataset, options) {
  .hasErrors(dataset,
    type                 = c("observations", "variance", "infinity"),
    all.target           = options[["variables"]],
    observations.amount  = "< 2",
    exitAnalysisIfErrors = TRUE
  )
}

# Compute (cached) ----
.myAnalysisComputeResults <- function(jaspResults, dataset, options) {
  # Already cached? Nothing to do.
  if (!is.null(jaspResults[["myAnalysisState"]]))
    return()

  # --- expensive computation goes here ---
  results <- list(
    model = lm(as.formula(paste(options[["dependent"]], "~ .")),
               data = dataset)
  )

  # Store in jaspResults — invalidated automatically when dependencies change
  state <- createJaspState(results)
  state$dependOn(c("dependent", "variables"))
  jaspResults[["myAnalysisState"]] <- state
}

# Table ----
.myAnalysisMainTable <- function(jaspResults, options, ready) {
  # 1. Skip if already cached
  if (!is.null(jaspResults[["mainTable"]])) return()

  # 2. Create & configure
  table <- createJaspTable(title = gettext("Results"))
  table$dependOn(c("variables", "dependent"))

  # 3. Define columns
  table$addColumnInfo(name = "term",     title = gettext("Term"),     type = "string")
  table$addColumnInfo(name = "estimate", title = gettext("Estimate"), type = "number")
  table$addColumnInfo(name = "se",       title = gettext("Std. Error"), type = "number")
  table$addColumnInfo(name = "p",        title = "p",                 type = "pvalue")

  # 4. Attach — displays an empty placeholder immediately
  jaspResults[["mainTable"]] <- table

  # 5. Not ready yet? Show the placeholder (dots)
  if (!ready) return()

  # 6. Retrieve cached results and fill
  results  <- jaspResults[["myAnalysisState"]]$object
  coefTab  <- summary(results$model)$coefficients

  for (i in seq_len(nrow(coefTab))) {
    table$addRows(list(
      term     = rownames(coefTab)[i],
      estimate = coefTab[i, "Estimate"],
      se       = coefTab[i, "Std. Error"],
      p        = coefTab[i, "Pr(>|t|)"]
    ))
  }
}

# Plot ----
.myAnalysisPlot <- function(jaspResults, options, ready) {
  # Only create when the user enables the checkbox
  if (!options[["residualPlot"]]) return()
  if (!is.null(jaspResults[["residualPlot"]])) return()

  plot <- createJaspPlot(title = gettext("Residuals vs. Fitted"),
                         width = 480, height = 320)
  plot$dependOn(c("variables", "dependent", "residualPlot"))
  jaspResults[["residualPlot"]] <- plot

  if (!ready) return()

  # Retrieve cached results
  results <- jaspResults[["myAnalysisState"]]$object

  plotData <- data.frame(
    fitted    = fitted(results$model),
    residuals = residuals(results$model)
  )

  plot$plotObject <- ggplot2::ggplot(plotData,
      ggplot2::aes(x = .data[["fitted"]], y = .data[["residuals"]])) +
    ggplot2::geom_point() +
    ggplot2::geom_hline(yintercept = 0, linetype = "dashed") +
    ggplot2::labs(x = gettext("Fitted values"), y = gettext("Residuals"))
}
```

### Key patterns

| Pattern | Why |
|---------|-----|
| Public function (`MyAnalysis`) has **no** `.` prefix | Called from QML via `Description.qml` |
| Private helpers start with `.myAnalysis` | Hidden from `NAMESPACE`; prefix avoids name collisions across modules |
| `ready` flag checked first | Lets output functions show empty placeholders before input is complete |
| `dataset` provided by JASP | `preloadData: true` in `Description.qml` — data arrives ready to use, no read function needed |
| `.myAnalysisComputeResults()` stores model in `jaspResults` | Called once from main function; table and plot retrieve it via `jaspResults[["myAnalysisState"]]$object` |
| `if (!is.null(...)) return()` at start of output functions | Avoids recreating cached output |
| Table attached **before** filling it | User sees a placeholder immediately; data fills in after computation |
| `$dependOn(...)` on every element | Tells JASP when to invalidate and recompute |
| `gettext()` on all user-visible strings | Enables translation (see @sec-i18n) |
| `options[["x"]]` (double brackets) | Avoids partial-matching bugs from `$` or `[` |