Generates an HTML report that includes the instrument codebook, data quality summary, reliability diagnostics, and analysis-plan content. Quarto is the report engine. Without Quarto, surveyframe writes a short plain results page with the numbers, tables, charts and APA result lines, under a banner that links to the Quarto installation page. That page gets no new features and is not promised to match the Quarto report.
Usage
render_report(
instrument,
data = NULL,
output_file = NULL,
output_path = NULL,
format = c("html", "pdf", "docx", "odt", "qmd"),
include_quality = TRUE,
include_reliability = TRUE,
include_codebook = TRUE,
include_missing = TRUE,
include_descriptives = TRUE,
include_analysis = TRUE,
include_models = TRUE,
plot_palette = c("web", "print"),
interpretations = NULL,
show_code = TRUE,
references = NULL,
csl = NULL,
title = NULL,
authors = NULL,
figures = getOption("surveyframe.figures"),
figure_dir = NULL,
open = interactive()
)Arguments
- instrument
An
sframeobject.- data
A
tibbleordata.frameof responses, orNULLfor the pre-analysis plan: a document to submit to OSF, Zenodo or an ethics committee before collecting data. It holds a title page with the instrument's hash and how to verify it, the study, the participant information, the questionnaire in order with its branching in words, the scales and their scoring, each research question with its hypotheses, method in words, reference, variables, significance level and decision rule, the models and amendments, the references, and a section, "To complete before submission", that prompts for what a preregistration asks and the instrument does not hold. Quarto writes it in every format, and the built-in engine writes a plain HTML version.- output_file
Character or NULL. The output file path. When NULL, a temporary file is written and its path returned.
- output_path
Character or NULL. Alias for
output_file. If both are supplied,output_filetakes precedence.- format
Character. Output format:
"html"(default),"pdf","docx"(Word),"odt"(OpenDocument) or"qmd"(the Quarto source). Word and OpenDocument go through Quarto, styled by bundled APA 7 reference documents (Times New Roman 12, double spacing, APA headings), and stop with a message when Quarto is not found. PDF goes through Quarto and LaTeX when a LaTeX engine is found (TinyTeX, or xelatex, lualatex or pdflatex on the PATH), through the Typst Quarto bundles otherwise, and without Quarto prints the built-in HTML page throughpagedown::chrome_print(), which needs the pagedown package (in Suggests) and a local Chrome or Chromium. The returned path's"converter"attribute names the route:"quarto-latex","quarto-typst","pagedown", or"quarto"for Word and OpenDocument. Every route renders offline."qmd"writes the Quarto source of the report as a folder, named byoutput_file(a trailing.qmdis dropped), which must be new or empty:report.qmd, the.sframe,responses.csv, the bibliography and its style, the results record andmanifest.json, and no_quarto.yml. Openreport.qmdin RStudio or Positron and render it. It recomputes every number from the folder's files and checks them, throughsframe_report_source(). Writing the folder needs no Quarto.- include_quality
Logical. Whether to include the data quality report. Requires
data. Defaults toTRUE.- include_reliability
Logical. Whether to include reliability diagnostics. Requires
data. Defaults toTRUE.- include_codebook
Logical. Whether to include the instrument codebook. Defaults to
TRUE.- include_missing
Logical. Whether to include the missing-data report. Requires
data. Defaults toTRUE.- include_descriptives
Logical. Whether to include descriptive statistics. Requires
data. Defaults toTRUE.- include_analysis
Logical. Whether to include analysis-plan results when
dataare supplied and the instrument has ananalysis_plan.- include_models
Logical. Whether to include saved model JSON and generated syntax blocks. Defaults to
TRUE.- plot_palette
One of
"web"(brand colours, for on-screen reading) or"print"(black, grey, and white, for a journal-ready or print-friendly report). Applied to every chart the report embeds. Seesframe_brand().- interpretations
Named list or NULL. Written interpretations keyed by analysis-plan block id, added after the results are known. Each block's section prints the hypotheses and planned decision rule it declared before its result, with or without an entry. An entry prints after the result under "Interpretation (written after the results)", in place of any interpretation the block holds. Interpretations are report content only and are never written into the instrument.
- show_code
Logical. Whether each result carries a folded "Show R code" block with the statistical call that produced it, built by
sframe_syntax_result()from the same resolved specification the analysis ran. Defaults toTRUE. A methodsframe_syntax_result()does not cover shows no block, rather than a guess at the call.- references
Optional further
sframe_reference()records, for example the works a host cites in the written interpretations, which are cited in text as[@id]. The instrument's own references (sframe_add_references()) and the methods' references are always included.- csl
The citation style of the references: a bundled style name,
"apa"(APA 7, the default),"chicago-author-date","harvard"(Cite Them Right),"ieee"or"mla", or the path to a Citation Style Language (.csl) file, such as one saved from https://www.zotero.org/styles. Styles are never fetched from the network. The style's name and sha256 go into the results record and the manifest, and a.qmdreport folder holds a copy named for it, so a rerun uses that copy. The built-in engine formats APA 7 only and says so when another style is asked for. An unknown name stops with the list of the 5.- title
Character or
NULL. The report's title. Defaults to the instrument's title.Character vector or
NULL. The report's authors, shown under the title. Defaults to the instrument's authors, and is left out when there are none.- figures
List or
NULL. Size, resolution and format for every figure in the report: any ofwidthandheightin inches,dpi, andformat,"png"or"svg"inside the report. For examplelist(width = 6.5, height = 4, dpi = 300). Absent entries keep each engine's own default. Defaults to thesurveyframe.figuresoption, so a host can set it once withoptions(surveyframe.figures = list(dpi = 300)).- figure_dir
Character or
NULL. A directory to write each analysis plan chart into as its own file, throughsframe_save_figures(), at the size, resolution and format infigures, whereformatmay also be"tiff","jpeg"or"pdf". Needsdata. Defaults to 300 dpi at 7 by 4.5 inches wherefiguresnames none.- open
Logical. Whether to show the finished report: in the viewer pane of RStudio, Positron or VS Code, and in the web browser otherwise. Defaults to
TRUEin an interactive session andFALSEin a script. Nothing opens during a knitr or Quarto render.
Which Quarto
The first copy of Quarto that runs quarto --version is used, searched in
this order: the executable named by the QUARTO_PATH environment
variable, quarto on the PATH, RSTUDIO_QUARTO (set inside RStudio), the
copy bundled with RStudio, then the copy bundled with Positron. RStudio and
Positron do not put their copies on the PATH, so a report rendered outside
them found none before 0.4.3. QUARTO_PATH takes the path of the
executable itself, as in the quarto package. The Quarto report gives the
version used and where it was found, and the returned path carries the
executable as its "quarto" attribute. options(surveyframe.use_quarto = FALSE) uses the built-in engine whatever is installed.
Quarto 1.7.0 or later supplies Typst 0.12 or later, which keeps a long
table's number and title together at a page break. An older Quarto copy
continues to render and reports that this caption may split across pages.
Markdown in text fields
A research question, H0, H1, decision rule, interpretation, study problem
or deviation report may hold Markdown: bold, italic, bulleted and numbered
lists, links, [@key] citations, ~sub~, ^sup^, footnotes ^[...] and
equations, $...$ inline and $$...$$ display (an opening $ needs a
non-space on its right and a closing $ a non-space on its left and no
digit after it, so "costs $5 and $10" stays prose). The .sframe keeps
the text as typed. The Quarto report renders it, with equations as
MathML, which needs no script or network. The built-in page renders it
with commonmark and prints each equation's TeX in monospace. Shortcodes,
raw blocks, ::: fences, heading lines, a --- line and HTML tags print
as typed, R code in a field is never run, and @word is a citation only
when word is the key of a reference the report holds.
Results record, manifest and provenance
Beside every report render_report() writes 2 files named after it. For
report.html they are report_results.json, the plan results as
canonical JSON (sorted keys, full precision, no timestamp, so the same
instrument and responses give the same file), and report_manifest.json,
the sha256 of the instrument content, the responses, the results record and
the report as generated, with the surveyframe and R versions and the time.
A report edited later, as a Word copy is meant to be, no longer matches
its recorded hash, while the results record still does. The Provenance
section at the top of the report gives the instrument hash and whether
read_sframe() verified it, the number of amendments, the responses sha256
and the results record's sha256. The responses are hashed as JSON by
column, so the hash belongs to the values, not to a file.
References
The Quarto report cites in text, author and year, and lists every work it
cites once, in a References section at the end, formatted by pandoc's
citation processor in the chosen style. That covers the methods' own
references, the sources the instrument cites for its items, scales, plan
blocks and models, and references. The built-in HTML engine, used when
Quarto is unavailable, lists the methods' references the same way.
Examples
instr <- read_sframe(
system.file("extdata", "tourism_services_demo.sframe",
package = "surveyframe")
)
responses <- read_responses(
system.file("extdata", "tourism_services_responses.csv",
package = "surveyframe"),
instr,
respondent_id = "respondent_id",
submitted_at = "submitted_at",
meta_cols = "started_at"
)
# \donttest{
old <- options(surveyframe.use_quarto = FALSE)
out <- tryCatch(
render_report(
instr,
data = responses,
output_file = tempfile(fileext = ".html"),
include_reliability = FALSE,
include_analysis = FALSE
),
finally = options(old)
)
sframe_show(out)
# }