jamovi-module

Developing jamovi modules

This skill describes conventions common to every jamovi module. The current repository's CLAUDE.md covers anything specific to this module (what it does, its test commands, its analysis inheritance, its commit rules) and takes precedence where the two differ.

What a jamovi module is

A jamovi module is an R package that is also a jamovi module. Each analysis is therefore reachable two ways, and both must work:

• called directly from R (e.g. jmv::ttestIS(data, ...)), and
• driven interactively through the jamovi UI.

Keep this dual interface in mind: an analysis cannot rely on the UI being present, and error handling must read sensibly both as a jamovi notice and as a plain R error.

Per-analysis file anatomy

An analysis named <name> is defined across several files that belong together:

• jamovi/<name>.a.yaml — options (the analysis arguments).
• jamovi/<name>.r.yaml — results definition: tables, columns, images, groups, and their visibility rules.
• jamovi/<name>.u.yaml (+ jamovi/js/<name>.events.js) — the UI layout and its interactive events.
• R/<name>.h.R — generated R6 Options and Base classes. Never edit these by hand; they are overwritten on every compile.
• R/<name>.b.R — the analysis body: an R6 class inheriting <name>Base. This is where you write code.

When you change options or results, you edit the .yaml, not the .h.R.

The compile step

The .h.R files are regenerated from the yaml definitions by the jamovi-compiler (jmc). After editing any .a.yaml / .r.yaml / .u.yaml, recompile so the generated classes match (commonly jmc . --install-to <module>; check the module's package.json / CLAUDE.md for the exact invocation). Treat R/*.h.R as build output: review it, but don't hand-edit it.

The .init() / .run() lifecycle

The body class implements two phases driven by jmvcore:

• .init() — runs before data is available. Build the result skeleton here: create table rows/columns based on the chosen options and factor levels. Anything whose shape is known without the data belongs in .init().
• .run() — data is available. Validate it, compute, and populate the skeleton, e.g. table$setRow(rowKey=..., values=list(...)).

A common mistake is computing in .init() or building structure in .run(); keep the split clean so partial/empty states render correctly.

Cross-file conventions

These hold across analyses in a typical jamovi module:

• Factor levels are base64-encoded with toB64() before they go into R formulas / model fitting, so special characters survive. Decode with fromB64() for anything user-facing (table labels, messages).
• Data problems are rejected, not stopped: jmvcore::reject(.("message"), code=exceptions$dataError, ...). Rejections surface as ordinary R errors for R users, so they are testable with expect_error(...).
• Non-fatal warnings use jmvcore::Notice (often via a helper such as setAnalysisNotice()), not warning().
• All user-facing strings are wrapped in .() for translation: .("Some text"). The .() lookup needs a self in scope — which is why package-level helper functions often take a self argument even when they otherwise wouldn't need one. Translation catalogs usually live in a jamovi/i18n git submodule and are regenerated separately, so flag any new translatable strings you introduce.

House code style

jamovi R code conventionally uses:

• 4-space indentation.
• No spaces around = in named arguments: setRow(rowNo=i, values=v).
• A spaced negation style: if ( ! is.null(x)).

There is usually no autoformatter — match the surrounding code. Defer to the repo's CLAUDE.md if it states otherwise.