Skip to contents

nomo_report() renders a self-contained HTML document from a nomo_run object. The report archives researcher inputs, sample roles, item and factor evidence, EFA/CFA results, reliability, convergent/discriminant evidence, optional invariance and nomological-network results, researcher decisions, deviations and post hoc decisions, method citations, an evidence trace, and session information.

Usage

nomo_report(
  x,
  file,
  title = "nomologR reproducible analysis report",
  include_plots = TRUE,
  include_session = TRUE,
  max_table_rows = 50L,
  overwrite = FALSE,
  quiet = TRUE,
  apa_tables = FALSE
)

Arguments

x

An object created by nomo_run().

file

Output path. Required: nomo_report() has no default path, so it writes a report only where you ask, and stops with an error when file is not given. The extension chooses the format: .html or .htm for a self-contained HTML report, .docx for a Word document. The Word report carries the same tables, figures, and interpretation contract as the HTML one; collapsible sections are shown expanded, and it uses Word's default styles.

title

Report title.

include_plots

Logical; include a compact set of component plots when those plots are available.

include_session

Logical; include full sessionInfo() output.

max_table_rows

Positive integer used for ordinary display tables. The final evidence-trace appendix is not truncated.

overwrite

Logical; replace an existing file.

quiet

Logical passed to rmarkdown::render().

apa_tables

Logical; if TRUE, append a Manuscript tables appendix with the nomo_apa_table() tables for the results the run holds. These are the CFA loadings and fit; reliability; the validity stage's average variance extracted and construct pairs (without a validity stage, the CFA factor correlations take the pairs' place, after the fit); and, when present, invariance and the network's hypotheses and fit. They are numbered in that order. Default FALSE, which leaves the report unchanged.

Value

The normalized report file path, invisibly.

Details

The report is a presentation and provenance layer. It does not refit models, alter data, free parameters, remove items, or manufacture additional statistical conclusions.

Its tables are the ones nomo_table() returns, with values rounded for display by the rules printed output follows (p values to three decimals and "< .001" below that, proportions stored as pct_* shown as percentages, counts as whole numbers), flags in the shared wording ("Review", "Concern", "Not computed", blank for no flag), and each cell shown exactly as written, so lavaan syntax such as ~~ and a*x1 survives. The workflow's calls are printed as R code, and a table at the end defines every abbreviation the report shows.

Reports can be rendered from complete, paused, or blocked nomo_run objects. Incomplete stages are labeled as such rather than silently omitted.

nomo_report() writes one file, the report named by file, and creates that file's directory when it does not exist. The working files of the render (the copy of the template, the intermediate files, and the figures) are written to a temporary directory under tempdir() and removed when the call returns, whether or not it succeeds. The working directory, the options, and the graphics device are left as they were. The report is rendered in an environment of its own, so objects in the global environment are neither read nor changed.

nomo_report() behaves the same from the console, a script, or a chunk inside another R Markdown or Quarto document, such as a thesis chapter. Rendering from inside a document nests two renders that share knitr's global state, so the report is rendered with knitr's default chunk options, which its own template then sets, and the calling document's options are restored afterwards. The calling document's chunk options therefore cannot change the report, and rendering the report does not change the calling document.

Examples

# \donttest{
# Rendering requires the rmarkdown package and pandoc, which RStudio and
# Quarto installations include.
if (requireNamespace("rmarkdown", quietly = TRUE) &&
    rmarkdown::pandoc_available()) {
  run <- nomo_run(
    data = nomo_demo_network,
    scales = list(Agency = c("ag1", "ag2", "ag3", "ag4")),
    settings = list(factors = list(n_iter = 20, seed = 2026)),
    decisions = list(
      factor_count = 1L,
      cfa_model = "Agency =~ ag1 + ag2 + ag3 + ag4",
      measurement_model = "proceed"
    )
  )

  report_file <- nomo_report(
    run,
    file = tempfile(fileext = ".html")
  )
  file.exists(report_file)
  DONTSHOW({unlink(report_file)})
}
# }