Package 'surveyframe'

Description

Add a model specification to an instrument

Usage

add_model(instrument, model, validate = TRUE, replace = TRUE)

Arguments

Value

The updated sframe object.

Description

Performs common assumption checks for survey analyses using base R where possible: Shapiro-Wilk tests, skewness/kurtosis screening, Levene and Brown-Forsythe tests, regression residual checks, VIF, Cook's distance, expected-count checks, and sparse-cell warnings.

Usage

assumption_report(
  data,
  variables = NULL,
  group = NULL,
  outcome = NULL,
  predictors = NULL,
  table_vars = NULL
)

Arguments

Value

An object of class sframe_assumption_report.

Description

Resamples x with replacement R times, applies FUN to each resample, and returns the percentile interval of the resampled statistics together with the observed value.

Usage

bootstrap_ci(x, FUN = stats::median, R = 2000, conf.level = 0.95, seed = NULL)

Arguments

Value

A named numeric vector: estimate, lower, upper. The bounds are NA when x has fewer than 3 finite values.

See Also

cohens_d_ci(), cramers_v_ci(), eta_sq_ci()

Examples

bootstrap_ci(mtcars$mpg, seed = 42)
bootstrap_ci(mtcars$mpg, FUN = mean, conf.level = 0.90, seed = 42)

Description

Generate lavaan CFA syntax

Usage

cfa_lavaan_syntax(
  instrument = NULL,
  model = NULL,
  scales = NULL,
  ordered = FALSE,
  std_lv = TRUE,
  residual_covariances = NULL,
  latent_covariances = TRUE
)

Arguments

Value

A lavaan syntax string.

Description

Produces a character string of lavaan model syntax derived from the scale structure in the instrument. The syntax can be passed directly to lavaan::cfa(). Reverse-coded items are noted in a comment but are not transformed in the syntax; recoding should be applied to the data before fitting the model.

Usage

cfa_syntax(instrument, scales = NULL, std_lv = TRUE)

Arguments

Value

A character string of lavaan CFA model syntax.

See Also

efa_report(), reliability_report()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Item 1", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i2    <- sf_item("sat_2", "Item 2", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i3    <- sf_item("sat_3", "Item 3 (reverse)", type = "likert",
                 choice_set = "ag5", scale_id = "sat", reverse = TRUE)
scale <- sf_scale("sat", "Satisfaction",
                  items = c("sat_1", "sat_2", "sat_3"))
instr <- sf_instrument("Demo Survey", components = list(cs, i1, i2, i3, scale))

syntax <- cfa_syntax(instr)
cat(syntax)

## Not run: 
# lavaan is not installed by default; install it before fitting.
demo   <- sframe_demo_data()
scored <- score_scales(demo$responses, demo$instrument)
fit    <- lavaan::cfa(syntax, data = scored, std.lv = TRUE)
summary(fit, fit.measures = TRUE)

## End(Not run)

Description

Produces a structured codebook listing all items, their types, choice sets, scale membership, and reverse-coding status. The codebook can be rendered as HTML or Markdown.

Usage

codebook_report(instrument, format = c("html", "md"))

Arguments

Value

An object of class sframe_codebook, a list with elements instrument_meta, items_table, choices_table, and scales_table. Call print() to display a compact summary or use render_report() to include the codebook in a full report.

See Also

render_report()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Item 1", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i2    <- sf_item("sat_2", "Item 2", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
scale <- sf_scale("sat", "Satisfaction", items = c("sat_1", "sat_2"))
instr <- sf_instrument("Demo Survey", components = list(cs, i1, i2, scale))

cb <- codebook_report(instr)
print(cb)
nrow(cb$items_table)
nrow(cb$scales_table)

Description

Percentile bootstrap for the standardised mean difference between two independent groups. Each resample draws within each group, preserving the group sizes.

Usage

cohens_d_ci(x, y, R = 2000, conf.level = 0.95, seed = NULL)

Arguments

Value

A named numeric vector: estimate, lower, upper. The bounds are NA when either group has fewer than 3 finite values.

See Also

bootstrap_ci()

Examples

cohens_d_ci(mtcars$mpg[mtcars$am == 1], mtcars$mpg[mtcars$am == 0],
            seed = 42)

Description

Percentile bootstrap for the association strength in a contingency table. The table is expanded back to individual observations, which are resampled jointly. For a 2 by 2 table the statistic equals phi.

Usage

cramers_v_ci(tab, R = 2000, conf.level = 0.95, seed = NULL)

Arguments

Value

A named numeric vector: estimate, lower, upper. The bounds are NA when the table holds fewer than 3 observations.

See Also

bootstrap_ci()

Examples

cramers_v_ci(table(mtcars$am, mtcars$cyl), seed = 42)

Description

Computes survey descriptives for numeric, Likert, and scale-score columns, including missingness, mean, standard deviation, median, IQR, range, skewness, kurtosis, standard error, and confidence intervals.

Usage

descriptives_report(
  data,
  variables = NULL,
  split_by = NULL,
  conf_level = 0.95,
  weights = NULL
)

Arguments

Value

An object of class sframe_descriptives_report.

Description

Reports KMO sampling adequacy, Bartlett's test of sphericity, and a parallel analysis scree plot to inform factor number selection. The suggested number of factors from parallel analysis is returned in ⁠$suggested_nfactors⁠. The report prepares the researcher to estimate an EFA solution with a separate package such as psych or lavaan.

Usage

efa_report(
  data,
  instrument,
  scales = NULL,
  nfactors = NULL,
  rotation = "oblimin"
)

Arguments

Value

An object of class sframe_efa_report with elements kmo, bartlett, parallel, and suggested_nfactors.

See Also

reliability_report(), cfa_syntax()

Examples

if (requireNamespace("psych", quietly = TRUE)) {
  demo <- sframe_demo_data()
  er <- efa_report(demo$responses, demo$instrument)
  print(er)
}

Description

Runs psych::fa() on selected item columns and returns loadings, communalities, uniqueness, variance summaries, and simple item retention flags. The psych package is optional and is only required when this function is called.

Usage

efa_solution(
  data,
  instrument,
  items = NULL,
  scales = NULL,
  nfactors = 1L,
  extraction = c("minres", "pa", "ml"),
  rotation = c("oblimin", "promax", "varimax"),
  min_loading = 0.3,
  cross_loading = 0.3
)

Arguments

Value

An object of class sframe_efa_solution. Alongside the psych objects it carries three tidy data frames ready for plotting and reporting: loadings_long (item_id, factor, loading), communalities_table (item_id, communality, uniqueness), and variance_table (factor, ss_loadings, proportion_var, cumulative_var).

Description

Generate EFA planning syntax

Usage

efa_syntax(
  items,
  nfactors = 1L,
  extraction = c("minres", "pa", "ml"),
  rotation = c("oblimin", "promax", "varimax"),
  data_name = "data"
)

Arguments

Value

A character string with R syntax.

Description

Percentile bootstrap for the proportion of variance in outcome explained by group, resampling observations jointly so the group structure travels with each resample.

Usage

eta_sq_ci(outcome, group, R = 2000, conf.level = 0.95, seed = NULL)

Arguments

Value

A named numeric vector: estimate, lower, upper. The bounds are NA with fewer than 3 complete observations or fewer than 2 groups.

See Also

bootstrap_ci()

Examples

eta_sq_ci(mtcars$mpg, mtcars$cyl, seed = 42)

Description

Generates a Google Apps Script file that, when run in a Google Sheet, creates a response collection endpoint for a survey instrument. The builder can store the deployed Apps Script URL in survey metadata, and the same sheet can be read back with read_sheet_responses().

Usage

export_google_sheet(instrument, sheet_url, output_dir = ".")

Arguments

Value

The path to the generated .gs Apps Script file, invisibly.

See Also

read_sheet_responses(), read_responses(), write_sframe()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
script <- export_google_sheet(
  instr,
  sheet_url = "https://docs.google.com/spreadsheets/d/demo",
  output_dir = tempdir()
)
file.exists(script)

Description

Generates a single HTML file that presents the survey instrument in a browser without requiring a Shiny server or any internet connection. All thirteen item types, branching logic, required-field validation, and multi-page navigation are handled entirely in client-side JavaScript.

Usage

export_static_survey(
  instrument,
  output_path = NULL,
  open = interactive(),
  endpoint_url = NULL,
  overwrite = FALSE
)

Arguments

Details

When output_path is NULL, the file is written to tempdir(). Supply an explicit output_path for any production export that should be kept.

When a respondent clicks the submit button, the browser downloads a one-row CSV file named ⁠<survey_title>_response_<id>.csv⁠. If endpoint_url is supplied, the same payload is also sent as a JSON POST request to that URL (for example a Google Apps Script web app or a serverless function). The two mechanisms are independent: the download happens regardless, so responses are never lost if the POST fails.

The exported file works offline. It can be hosted on GitHub Pages, Netlify, any static file server, or e-mailed as an attachment for opening directly from disk.

Value

The output path, invisibly.

See Also

launch_studio(), launch_builder(), render_survey()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Overall I am satisfied with the service.",
                 type = "likert", choice_set = "ag5", required = TRUE)
i2    <- sf_item("comments", "Any additional comments?", type = "textarea")
instr <- sf_instrument("Customer Satisfaction Survey",
                       components = list(cs, i1, i2))

# Write to a temp file without opening the browser
out <- export_static_survey(instr,
                             output_path = file.path(tempdir(), "sat.html"),
                             open = FALSE)
file.exists(out)


# Write to a temp file and open in the default browser
export_static_survey(instr,
                     output_path = file.path(tempdir(), "sat_browser.html"),
                     overwrite = TRUE)

# Write with a Google Apps Script endpoint for server-side collection
export_static_survey(
  instr,
  output_path  = file.path(tempdir(), "sat_endpoint.html"),
  endpoint_url = "https://script.google.com/macros/s/XXXXX/exec",
  open         = FALSE,
  overwrite    = TRUE
)

Description

Format an sf_branch object as a string

Usage

## S3 method for class 'sf_branch'
format(x, ...)

Arguments

Value

A single character string.

Description

Format an sf_check object as a string

Usage

## S3 method for class 'sf_check'
format(x, ...)

Arguments

Value

A single character string.

Description

Format an sf_choices object as a string

Usage

## S3 method for class 'sf_choices'
format(x, ...)

Arguments

Value

A single character string.

Description

Format an sf_item object as a string

Usage

## S3 method for class 'sf_item'
format(x, ...)

Arguments

Value

A single character string.

Description

Format an sf_model object as a string

Usage

## S3 method for class 'sf_model'
format(x, ...)

Arguments

Value

A single character string.

Description

Format an sf_scale object as a string

Usage

## S3 method for class 'sf_scale'
format(x, ...)

Arguments

Value

A single character string.

Description

Format an sframe instrument object as a string

Usage

## S3 method for class 'sframe'
format(x, ...)

Arguments

Value

A single character string.

Description

Produces item-total correlations, floor and ceiling effect proportions, and item means and standard deviations for each item within each scale.

Usage

item_report(data, instrument, scales = NULL)

Arguments

Value

An object of class sframe_item_report, a list with one data.frame per scale.

See Also

reliability_report(), sf_scale()

Examples

demo <- sframe_demo_data()
ir <- item_report(demo$responses, demo$instrument)
print(ir)

Description

Opens the SurveyBuilder, a self-contained HTML application for visual survey design. The builder runs client-side without an R session or Shiny server. Save instruments as .sframe files from the browser and load them into R with read_sframe().

Usage

launch_builder(open = TRUE)

Arguments

Details

The builder includes a three-mode interface.

Build

An item editor with a persistent inspector panel, drag-to-reorder, undo/redo, and autosave to browser localStorage.

Preview

A full live render of the survey showing welcome, body, and thank-you pages.

Analyse

A role-based analysis planner with method-specific options, planned outputs, reporting references, and decision rules.

The builder includes a pure-JavaScript SHA-256 fallback for browsers or security policies where crypto.subtle is unavailable on ⁠file://⁠ origins. Saved .sframe files can be loaded and validated with read_sframe().

Value

The path to the bundled builder HTML file, invisibly.

See Also

launch_studio(), read_sframe(), run_analysis_plan()

Examples

# Retrieve the builder path for inspection without opening the browser
path <- launch_builder(open = FALSE)
file.exists(path)

Description

Opens a temporary copy of the SurveyBuilder with the bundled input-types instrument already injected into the JavaScript state. The demo questions, scales, and analysis plan are visible immediately — no manual file-load step is required.

Usage

launch_builder_demo(open = TRUE)

Arguments

Value

Invisibly returns a list with builder_path, demo_file, and responses_path.

Description

Opens a Shiny dashboard to explore collected response data alongside the instrument definition. Use this interface after response collection for analysis and quality control. Use launch_builder() to design new questionnaires. The dashboard includes five panels:

Usage

launch_dashboard(
  instrument = NULL,
  responses = NULL,
  port = NULL,
  host = "127.0.0.1",
  launch.browser = interactive()
)

Arguments

Details

Overview

Response count, date range, and instrument metadata.

Items

Per-item frequency bar charts, histograms, and tabulated frequency counts for choice-type questions.

Scales

Scale score distributions with mean overlay, and a summary table of scale definitions.

Quality

Attention check pass rates for each check defined in the instrument.

Raw data

Scrollable response table with a CSV download button.

The dashboard is read-only and takes its data from R. It has no upload screen, so pass instrument and responses directly. To open and upload data interactively, use launch_studio(), which includes this same dashboard as its Dashboard tab. For a quick look at bundled demo data, use launch_dashboard_demo().

Value

Called for its side effect. Returns nothing.

See Also

run_analysis_plan(), quality_report(), score_scales()

Examples

## Not run: 
# For the bundled demo, use launch_dashboard_demo().
# To upload data interactively, use launch_studio().

# Open the dashboard with your own instrument and responses
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"
)
launch_dashboard(instr, responses)

## End(Not run)

Description

Opens the dashboard with the bundled input-types questionnaire and 120 simulated responses already loaded. The browser is opened automatically by default.

Usage

launch_dashboard_demo(port = NULL, host = "127.0.0.1", launch.browser = TRUE)

Arguments

Value

Called for its side effect.

Description

Opens the SurveyStudio Shiny application, a visual interface for the complete surveyframe workflow. The studio includes screens to build a survey draft, open an existing instrument, preview the survey, upload responses, review data quality, inspect reliability, plan analyses, and export outputs.

Usage

launch_studio(
  instrument = NULL,
  responses = NULL,
  respondent_id = NULL,
  submitted_at = NULL,
  meta_cols = NULL,
  strict = TRUE,
  screen = c("auto", "build", "preview", "data", "quality", "analysis", "dashboard"),
  port = NULL,
  host = "127.0.0.1",
  launch.browser = interactive()
)

Arguments

Value

Called for its side effect.

See Also

launch_builder(), launch_dashboard(), read_sframe(), read_responses()

Examples

## Not run: 
launch_studio()

demo <- sframe_demo_data()
launch_studio(instrument = demo$instrument, launch.browser = FALSE)

launch_studio(
  instrument    = demo$instrument,
  responses     = demo$responses,
  respondent_id = "respondent_id",
  submitted_at  = "submitted_at"
)

## End(Not run)

Description

Opens SurveyStudio with the bundled input-types questionnaire and simulated response data already loaded. The browser is opened automatically by default.

Usage

launch_studio_demo(
  screen = "preview",
  port = NULL,
  host = "127.0.0.1",
  launch.browser = TRUE
)

Arguments

Value

Called for its side effect.

Description

Reports item-wise missingness, respondent-wise missingness, missing-data patterns, listwise and pairwise deletion counts, and scale scoring missing rules. No imputation is performed.

Usage

missing_data_report(data, instrument = NULL, variables = NULL)

Arguments

Value

An object of class sframe_missing_data_report.

Description

Serialise a model specification to JSON

Usage

model_json(model, pretty = TRUE)

Arguments

Value

A JSON string.

Description

Create a model reporting template

Usage

model_report_template(model, include_json = TRUE)

Arguments

Value

A character string.

Description

Uses transparent screening rules for numeric survey response variables. The report supports data review before modelling, not automatic deletion.

Usage

outlier_report(
  data,
  variables = NULL,
  method = c("zscore", "iqr", "mahalanobis"),
  z_cut = 3,
  iqr_multiplier = 1.5,
  p_cut = 0.975
)

Arguments

Value

An object of class sframe_outlier_report with the method, screened variables, a result table, flagged row numbers, and a reporting prompt.

Examples

demo <- sframe_demo_data()
outliers <- outlier_report(
  demo$responses,
  variables = c("dm_1", "dm_2", "sat_1"),
  method = "zscore"
)
outliers$flagged_rows

Description

Draws the charts that run_analysis_plan() attaches when called with plots = TRUE. With which supplied, returns that single chart. With which omitted, prints every attached chart in queue order and returns the list invisibly. Regression diagnostic panels stay on the result's diagnostic_plots element and are not drawn here.

Usage

## S3 method for class 'sframe_analysis_results'
plot(x, ..., which = NULL)

Arguments

Value

A ggplot2 object when which is supplied, otherwise an invisible named list of ggplot2 objects keyed by plan block id.

Description

Post-hoc and pairwise comparison report

Usage

posthoc_report(
  data,
  method = c("anova", "kruskal_wallis", "chi_square", "cochran_q"),
  outcome = NULL,
  group = NULL,
  table_vars = NULL,
  measures = NULL,
  correction = c("holm", "bonferroni", "BH")
)

Arguments

Value

An object of class sframe_posthoc_report.

Description

Print an sf_branch object

Usage

## S3 method for class 'sf_branch'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

br <- sf_branch("q2", depends_on = "q1", operator = "==",
                value = "yes", action = "show")
print(br)

Description

Print an sf_check object

Usage

## S3 method for class 'sf_check'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

ck <- sf_check("attn1", item_id = "q5", type = "attention",
               pass_values = 3)
print(ck)

Description

Print an sf_choices object

Usage

## S3 method for class 'sf_choices'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

cs <- sf_choices("agree5", 1:5,
                 c("Strongly disagree", "Disagree", "Neutral",
                   "Agree", "Strongly agree"))
print(cs)

Description

Print an sf_item object

Usage

## S3 method for class 'sf_item'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

it <- sf_item("q1", "How satisfied are you?", type = "likert",
              choice_set = "agree5")
print(it)

Description

Print an sf_model object

Usage

## S3 method for class 'sf_model'
print(x, ...)

Arguments

Value

x, invisibly.

Description

Print an sf_scale object

Usage

## S3 method for class 'sf_scale'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

sc <- sf_scale("sat", "Satisfaction", items = c("q1", "q2", "q3"))
print(sc)

Description

Displays a compact summary of an sframe instrument object, showing the title, version, item count, scale count, and validation status.

Usage

## S3 method for class 'sframe'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

item <- sf_item("q1", "How satisfied are you?", type = "likert",
                choice_set = "agree5")
instr <- sf_instrument("My Survey", components = list(item))
print(instr)

Description

Evaluates collected response data against the instrument specification and produces a structured quality report. The report covers attention check performance, completion time, straight-lining within scale blocks, item-level missingness, respondent-level missingness, and duplicate respondent IDs where supplied.

Usage

quality_report(
  data,
  instrument,
  respondent_id = NULL,
  submitted_at = NULL,
  started_at = NULL,
  time_min = NULL,
  straightline_scales = TRUE,
  missing_threshold = 0.2
)

Arguments

Details

Timing analysis is available when the data contain a submission timestamp column and either an explicit started_at column or one of the recognised defaults: started_at, start_time, started, or .started_at.

Value

An object of class sframe_quality_report, a named list with elements: summary, attention, timing, straightline, missing, and duplicates. Use print() for a formatted summary.

See Also

sf_check(), read_responses(), score_scales()

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"
)
qr <- quality_report(
  responses,
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  started_at = "started_at",
  straightline_scales = FALSE
)
print(qr)

Description

Loads survey response data and checks that it conforms to the instrument specification. Column names in the response file must match item IDs defined in the instrument. Non-item columns are allowed only when declared through respondent_id, submitted_at, or meta_cols.

Usage

read_responses(
  x,
  instrument,
  respondent_id = NULL,
  submitted_at = NULL,
  meta_cols = NULL,
  strict = TRUE
)

Arguments

Value

A data.frame with columns ordered as: metadata columns first, then item columns in instrument order. Unrecognised columns are dropped when strict = TRUE or appended with a warning when strict = FALSE.

See Also

quality_report(), score_scales()

Examples

responses <- read_responses(
  x = system.file("extdata", "tourism_services_responses.csv",
                  package = "surveyframe"),
  instrument = read_sframe(
    system.file("extdata", "tourism_services_demo.sframe",
                package = "surveyframe")
  ),
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
head(responses[, c("respondent_id", "visit_type", "dm_1")])

Description

Reads a .sframe JSON file and reconstructs an sframe instrument object. The SHA-256 integrity hash is verified on load unless validate = FALSE.

Usage

read_sframe(path, validate = TRUE)

Arguments

Value

An sframe object.

See Also

write_sframe(), validate_sframe()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
print(instr)

Description

Reads response data collected by the surveyframe Google Apps Script endpoint and returns a validated data frame ready for the surveyframe analysis pipeline.

Usage

read_sheet_responses(
  sheet_id,
  instrument,
  sheet_name = "Responses",
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = NULL
)

Arguments

Value

A data.frame validated against the instrument, ready for quality_report(), score_scales(), and reliability_report().

See Also

export_google_sheet(), read_responses(), quality_report()

Examples

## Not run: 
responses <- read_sheet_responses(
  sheet_id   = "your-sheet-id",
  instrument = instr
)
qr <- quality_report(responses, instr, respondent_id = "respondent_id")

## End(Not run)

Description

Produces Cronbach's alpha and McDonald's omega for each scale defined in the instrument, along with the number of items and sample size.

Usage

reliability_report(data, instrument, scales = NULL, alpha = TRUE, omega = TRUE)

Arguments

Value

An object of class sframe_reliability_report, a list with one element per scale. Each element is a list of statistics and a summary tibble.

See Also

sf_scale(), item_report()

Examples

if (requireNamespace("psych", quietly = TRUE)) {
  demo <- sframe_demo_data()
  rr <- reliability_report(demo$responses, demo$instrument, omega = FALSE)
  print(rr)
}

Description

Generates an HTML report that includes the instrument codebook, data quality summary, reliability diagnostics, and analysis-plan content. When Quarto and the bundled template are available, the report is rendered through Quarto. Otherwise, surveyframe writes an internal HTML fallback so the reporting workflow still runs on machines without Quarto.

Usage

render_report(
  instrument,
  data = NULL,
  output_file = NULL,
  output_path = NULL,
  format = c("html", "pdf"),
  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
)

Arguments

Value

The output file path, invisibly.

See Also

codebook_report(), quality_report(), reliability_report()

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"
)
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)
)
file.exists(out)

Description

Generates a self-contained HTML report from the output of run_analysis_plan(). Each section corresponds to one research question and includes the APA-formatted statistical result, an interpretation space, and a reference list.

Usage

render_results(
  results = NULL,
  instrument,
  output_file = NULL,
  output_path = NULL,
  citation_format = c("apa", "ama", "vancouver"),
  title = NULL,
  interpretations = NULL
)

Arguments

Value

The output file path, invisibly.

See Also

run_analysis_plan(), render_report()

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"
)

results <- run_analysis_plan(responses, instr)
out <- render_results(results, instr,
                      output_file = tempfile(fileext = ".html"))
file.exists(out)

Description

Launches a Shiny survey with a welcome page, configurable header, all item types, branching logic, required-field enforcement, progress tracking, standard and conversational (one-question-at-a-time) display modes, and a customisable thank-you page. Responses can be persisted to CSV or passed to a callback.

Usage

render_survey(
  instrument,
  mode = c("shiny"),
  title = NULL,
  theme = NULL,
  save_responses = c("none", "csv"),
  output_path = NULL,
  on_submit = NULL
)

Arguments

Value

A shiny.appobj.

See Also

launch_studio(), read_responses()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
item  <- sf_item("sat_1", "How satisfied are you?",
                 type = "likert", choice_set = "ag5")
instr <- sf_instrument("My Survey", components = list(cs, item))
app <- render_survey(instr)
app <- render_survey(instr, save_responses = "csv", output_path = tempfile(fileext = ".csv"))

Description

Executes every analysis block defined in the instrument's analysis_plan slot against the supplied response data. Each block corresponds to one research question defined during instrument design in the SurveyBuilder. Results include APA-formatted statistics, effect sizes, interpretation prompts, and reporting references.

Usage

run_analysis_plan(
  data,
  instrument,
  scored = TRUE,
  plots = FALSE,
  plot_palette = c("web", "print")
)

Arguments

Value

An object of class sframe_analysis_results, a list with one element per analysis block. Each element contains the test result, APA string, interpretation prompt, and reporting-reference metadata. Inferential blocks also carry a ⁠$table⁠ data frame suitable for knitr::kable(). Pass to render_results() to generate a formatted report.

See Also

render_results(), read_sheet_responses()

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"
)

results <- run_analysis_plan(responses, instr)
print(results)

Description

Sample-size and power planning helper

Usage

sample_size_plan(
  type = c("proportion", "mean", "correlation", "t_test", "anova", "regression", "sem"),
  margin_error = NULL,
  sd = NULL,
  p = 0.5,
  r = NULL,
  alpha = 0.05,
  power = 0.8,
  groups = 2L,
  predictors = NULL
)

Arguments

Value

A list of planning estimates and warnings.

Description

Applies scale scoring rules from the instrument to response data. Handles reverse coding, optional weighted composite score computation, and minimum valid item thresholds. Returns a data frame with one scored column per scale.

Usage

score_scales(data, instrument, keep_items = TRUE, keep_meta = TRUE)

Arguments

Value

A data.frame with scored scale columns appended. Scale columns are named using the scale id.

See Also

sf_scale(), reliability_report()

Examples

cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sf_item("sat_1", "Item 1", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i2    <- sf_item("sat_2", "Item 2", type = "likert",
                 choice_set = "ag5", scale_id = "sat")
i3    <- sf_item("sat_3", "Item 3 (reverse)", type = "likert",
                 choice_set = "ag5", scale_id = "sat", reverse = TRUE)
scale <- sf_scale("sat", "Satisfaction",
                  items = c("sat_1", "sat_2", "sat_3"), min_valid = 2L)
instr <- sf_instrument("Demo", components = list(cs, i1, i2, i3, scale))

responses <- data.frame(
  sat_1 = c(4, 5, 3),
  sat_2 = c(4, 4, 3),
  sat_3 = c(2, 1, 3),
  stringsAsFactors = FALSE
)

scored <- score_scales(responses, instr)
scored$sat

Description

Generate lavaan CB-SEM syntax

Usage

sem_lavaan_syntax(model, instrument = NULL, standardised = TRUE)

Arguments

Value

A lavaan syntax string.

Description

Generate seminr PLS-SEM syntax

Usage

seminr_syntax(model, data_name = "data", nboot = NULL, seed = 123)

Arguments

Value

An R syntax string for seminr.

Description

Creates a single-condition branching rule that shows or hides a survey item depending on the value of a preceding item. Only single-condition rules are supported. Multi-condition AND/OR logic is planned for a later release.

Usage

sf_branch(
  item_id,
  depends_on,
  operator = c("==", "!=", "%in%", ">", ">=", "<", "<="),
  value,
  action = c("show", "hide")
)

Arguments

Value

An object of class sf_branch (a named list).

See Also

sf_instrument(), validate_sframe()

Examples

# Show an open-text follow-up only when the respondent selects "Other"
rule <- sf_branch(
  item_id    = "gender_other",
  depends_on = "gender",
  operator   = "==",
  value      = "other",
  action     = "show"
)

Description

Specifies an attention, instructional, or trap check item at instrument design time. The check is stored in the instrument object and evaluated against collected response data by quality_report(). This function only defines the check. Evaluation happens later in quality_report().

Usage

sf_check(
  id,
  item_id,
  type = c("attention", "instructional", "trap"),
  pass_values = NULL,
  fail_action = c("flag", "exclude"),
  label = NULL,
  notes = NULL
)

Arguments

Value

An object of class sf_check (a named list).

See Also

sf_item(), sf_instrument(), quality_report()

Examples

# An attention check: respondent must select 4
chk <- sf_check(
  id          = "attn_1",
  item_id     = "attention_check_q",
  type        = "attention",
  pass_values = 4,
  fail_action = "flag",
  label       = "Attention check 1"
)

Description

Creates a named set of response options that can be referenced by one or more items. Defining choices once and referencing them by id keeps the instrument consistent and reduces the risk of label mismatches across items that share the same response format.

Usage

sf_choices(id, values, labels, allow_other = FALSE, randomise = FALSE)

Arguments

Value

An object of class sf_choices (a named list).

See Also

sf_item(), sf_instrument()

Examples

# A five-point agreement scale
agree5 <- sf_choices(
  id     = "agree5",
  values = 1:5,
  labels = c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree")
)

# A yes/no set
yn <- sf_choices(
  id     = "yn",
  values = c("yes", "no"),
  labels = c("Yes", "No")
)

Description

Define a latent or composite construct

Usage

sf_construct(
  id,
  label = NULL,
  items = character(0),
  mode = c("reflective", "composite", "formative", "single_item"),
  weights = NULL
)

Arguments

Value

An object of class sf_construct.

Description

Define a covariance between constructs

Usage

sf_covariance(from, to, label = NULL)

Arguments

Value

An object of class sf_covariance.

Description

Define an indirect effect path

Usage

sf_indirect(from, through, to, label = NULL)

Arguments

Value

An object of class sf_indirect.

Description

Assembles a survey instrument from its component objects. This is the top-level constructor for the sframe class. All other constructors (sf_item(), sf_choices(), sf_scale(), sf_branch(), sf_check()) produce components that are passed into this function via components.

Usage

sf_instrument(
  title,
  version = "0.1.0",
  description = NULL,
  authors = NULL,
  languages = "en",
  components = list(),
  render = NULL,
  analysis_plan = list(),
  models = list()
)

Arguments

Value

An object of class sframe with slots meta, items, choices, scales, branching, checks, analysis_plan, models, and render.

See Also

sf_item(), sf_choices(), sf_scale(), sf_branch(), sf_check(), validate_sframe(), write_sframe()

Examples

choices <- sf_choices("agree5", 1:5,
  c("Strongly disagree", "Disagree", "Neutral", "Agree", "Strongly agree"))

visitor_cs <- sf_choices("visitor", c("new", "returning"),
                          c("New visitor", "Returning visitor"))

item1 <- sf_item("sat_1", "The service met my expectations.",
                 type = "likert", choice_set = "agree5",
                 scale_id = "sat", required = TRUE)
item2 <- sf_item("sat_2", "I would recommend this service.",
                 type = "likert", choice_set = "agree5",
                 scale_id = "sat", required = TRUE)
item3 <- sf_item("visitor_type", "I am a",
                 type = "single_choice", choice_set = "visitor")

scale <- sf_scale("sat", "Satisfaction", items = c("sat_1", "sat_2"))

# The analysis_plan binds each research question to a statistical method
# and the variable roles it needs. Declare it before any data arrive.
plan <- list(
  list(
    id               = "RQ1",
    research_question = "Do new and returning visitors differ in satisfaction?",
    family           = "group_comparison",
    method           = "mann_whitney",
    roles            = list(group = "visitor_type", outcome = "sat"),
    options          = list(alpha = 0.05)
  )
)

instr <- sf_instrument(
  title         = "Service Quality Survey",
  version       = "1.0.0",
  components    = list(choices, visitor_cs, item1, item2, item3, scale),
  analysis_plan = plan
)
print(instr)
length(instr$analysis_plan)

Description

Creates a single survey item object for inclusion in an sframe instrument. Items are the atomic units of a survey instrument. Every item must have a unique id within the instrument it is added to.

Usage

sf_item(
  id,
  label,
  type = c("likert", "single_choice", "multiple_choice", "numeric", "text", "textarea",
    "date", "matrix", "slider", "ranking", "rating", "section_break", "text_block"),
  required = FALSE,
  choice_set = NULL,
  scale_id = NULL,
  reverse = FALSE,
  help = NULL,
  placeholder = NULL,
  matrix_items = NULL,
  slider_min = NULL,
  slider_max = NULL,
  slider_step = NULL,
  rating_max = NULL,
  rating_icon = NULL,
  date_min = NULL,
  date_max = NULL,
  section_intro = NULL,
  page = NULL
)

Arguments

Value

An object of class sf_item (a named list).

See Also

sf_instrument(), sf_choices(), sf_scale()

Examples

item <- sf_item(
  id = "sat_overall", label = "Overall, how satisfied are you?",
  type = "likert", required = TRUE, choice_set = "agree5",
  scale_id = "satisfaction"
)

sec <- sf_item("sec_1", "Demographic Information", type = "section_break",
               section_intro = "Please answer the following questions.")

Description

Create a surveyframe model specification

Usage

sf_model(
  id,
  label = NULL,
  type = c("efa", "cfa", "cb_sem", "pls_sem"),
  engine = NULL,
  constructs = list(),
  paths = list(),
  covariances = list(),
  indirect = list(),
  options = list()
)

Arguments

Value

An object of class sf_model.

Description

Define a structural path between constructs

Usage

sf_path(from, to, label = NULL)

Arguments

Value

An object of class sf_path.

Description

Creates a scale definition that groups items and specifies how composite scores are computed. The scale carries scoring rules used by score_scales() and measurement structure used by reliability_report(), item_report(), and cfa_syntax().

Usage

sf_scale(
  id,
  label,
  items,
  method = c("mean", "sum"),
  min_valid = NULL,
  reverse_items = NULL,
  weights = NULL
)

Arguments

Value

An object of class sf_scale (a named list).

See Also

sf_item(), score_scales(), reliability_report()

Examples

sat_scale <- sf_scale(
  id            = "satisfaction",
  label         = "Customer Satisfaction",
  items         = c("sat_overall", "sat_speed", "sat_quality"),
  method        = "mean",
  min_valid     = 2,
  reverse_items = NULL
)

Description

Create an empty SurveyStudio builder state

Usage

sframe_builder_empty_state()

Value

A list containing empty metadata, choice, item, scale, branching, and check collections suitable for SurveyStudio.

Description

Convert an instrument into a SurveyStudio builder state

Usage

sframe_builder_state_from_instrument(instrument = NULL)

Arguments

Value

A builder state list. Component classes are restored so the state can be edited or validated by SurveyStudio.

Description

Validate a SurveyStudio draft state

Usage

sframe_builder_validate_draft(
  meta,
  choices = list(),
  items = list(),
  scales = list(),
  branching = list(),
  checks = list(),
  analysis_plan = list(),
  models = list(),
  render = list()
)

Arguments

Value

A list with valid, problems, and instrument.

Description

Replaces items_table's choice_set id with the choice set's actual response options ("1 = Strongly disagree; 2 = Disagree; ...") and its scale_id with the scale's label, so each row of the printed codebook is self-contained. codebook_report() itself keeps the raw ids (for joining items_table to choices_table/scales_table programmatically); this is for the rendered document, where a reader should not need to cross-reference a separate table just to see what "1" means on a scale shared by many items.

Usage

sframe_codebook_items_display(cb)

Arguments

Value

A data.frame, cb$items_table with choice_set and scale_id replaced by display text.

See Also

codebook_report()

Description

Loads the bundled tourism-services .sframe instrument and simulated response dataset used in package examples and statistical workflow demos.

Usage

sframe_demo_data()

Value

A list with instrument, responses, instrument_path, and responses_path.

Description

Base-graphics mosaic plot (via graphics::mosaicplot()), matching the existing base-graphics precedent in this file (sframe_draw_likert_diverging()) so it renders without ggplot2. An alternative view of the same crosstab data sframe_plot_crosstab() renders as a grouped bar; use whichever reads better for the table's shape (mosaic scales better to unbalanced group sizes).

Usage

sframe_draw_mosaic(result, palette = c("web", "print"))

Arguments

Value

Invisibly NULL; called for its plotting side effect on the current graphics device.

See Also

sframe_plot_crosstab()

Description

Loads the bundled .sframe instrument and simulated response dataset that cover all main survey input types supported by surveyframe.

Usage

sframe_input_types_demo_data()

Value

A list with instrument, responses, instrument_path, and responses_path.

Description

Identifies which of an instrument's scales are eligible for one grouped diverging chart across their member items (sframe_plot_likert_scale()), the same way a "matrix" question's rows are grouped (sframe_plot_likert_matrix()): every member item is "likert" type and all share one choice set. Scales that mix response scales, that resolve to fewer than 2 qualifying items, or whose choice set cannot be found are left out and fall back to one chart per item in the report's Response distributions section.

Usage

sframe_likert_scale_groups(instrument)

Arguments

Value

A named list, one entry per eligible scale (named by scale id), each a list with scale_id, title (the scale's label), items (the member item objects, in scale order), and choice_set (the shared choice set object). Empty list if no scale qualifies.

See Also

sframe_plot_likert_scale(), sf_scale()

Description

Computes and plots a full pairwise correlation matrix, independent of run_analysis_plan()'s pairwise correlation_pearson/⁠_spearman⁠/ ⁠_kendall⁠ runners (which plot one variable pair at a time via sframe_plot_correlation()). Useful directly, and as the visual companion to validity_report()'s discriminant-validity checks.

Usage

sframe_plot_correlation_matrix(
  data,
  vars,
  method = "pearson",
  palette = c("web", "print")
)

Arguments

Value

A ggplot2 object.

See Also

validity_report()

Description

One violin per variable in a descriptives_report() table, built from the underlying response data rather than from the summary skewness and kurtosis numbers, so the reader sees the actual shape (asymmetry, multimodality, tails) instead of reading it off a bar height. Each variable is standardised (z-scored) before plotting so variables on different original scales (a 5-point Likert item next to a 0-100 slider) share one comparable y-axis; standardising is a linear transform and does not change skewness. Each violin's subtitle-free panel keeps the variable's skewness value in its axis label. Grouped descriptives_report() output (one row per variable per split_by group) is faceted by group.

Usage

sframe_plot_descriptives(x, data, palette = c("web", "print"))

Arguments

Value

A ggplot2 object, or NULL if none of the report's variables have enough data to draw.

See Also

descriptives_report()

Description

Loadings heatmap from a fitted EFA solution

Usage

sframe_plot_efa_loadings(x, palette = c("web", "print"))

Arguments

Value

A ggplot2 object.

See Also

efa_solution()

Description

Plots the parallel-analysis eigenvalues from efa_report() (both the observed factor-analysis eigenvalues and the simulated comparison line), with the suggested factor count marked.

Usage

sframe_plot_efa_scree(x, palette = c("web", "print"))

Arguments

Value

A ggplot2 object.

See Also

efa_report()

Description

Boxplot with jittered points, shared across every runner whose result carries vars = c(group_column, outcome_column): t_test_ind, mann_whitney, kruskal_wallis, and anova_one. One function instead of four, since the underlying comparison (an outcome split by a grouping factor) and the data shape needed to plot it are identical across all four tests; only the inferential statistic differs.

Usage

sframe_plot_group_comparison(result, data, palette = c("web", "print"))

Arguments

Value

A ggplot2 object, or NULL if the columns are missing, fewer than two groups remain after removing missing values, or ggplot2 is unavailable.

See Also

run_analysis_plan()

Description

A matrix question asks several rows against one shared response scale (a "grid" of Likert items). Plotting each row as its own separate sframe_draw_likert_diverging() chart loses the grouping the question was designed with, so this draws every row as one diverging bar inside a single chart, sharing one x scale and one legend, the standard way a Likert matrix is reported (compare a typical multi-item satisfaction grid). Same diverging-stack convention as the single-item chart: the middle category of an odd-length scale is neutral and split evenly across the zero line, and colour saturation increases toward each pole.

Usage

sframe_plot_likert_matrix(item, data, choice_set, palette = c("web", "print"))

Arguments

Value

A ggplot2 object, or NULL if no row has response data.

See Also

sframe_draw_likert_diverging()

Description

Several separate Likert items that make up one sf_scale() (unlike a "matrix" item's rows, which are one question) are, by default, each reported as their own single-item diverging chart. That scatters a related batch of items (a satisfaction scale's 2-3 items, say) across several charts instead of showing them the way a Likert matrix or a typical multi-item satisfaction grid is reported: one grouped chart, one diverging bar per item, sharing an x scale and a legend. Applies only when every item in the scale shares the same choice set; scales that mix response scales fall back to one chart per item.

Usage

sframe_plot_likert_scale(
  items,
  data,
  choice_set,
  title,
  palette = c("web", "print")
)

Arguments

Value

A ggplot2 object, or NULL if no item has response data.

See Also

sframe_plot_likert_matrix(), sf_scale()

Description

Missing-data report plot: missingness rate by item

Usage

sframe_plot_missingness(x, palette = c("web", "print"))

Arguments

Value

A ggplot2 object. When no item has missing values, this is a short "no missing responses" message rather than an empty bar chart.

See Also

missing_data_report()

Description

One line per respondent connecting their two paired values, shared by t_test_pair and wilcoxon_pair (both carry vars = c(x_column, y_column) on the same respondents). The standard visual for a paired design: it shows the direction and consistency of individual change, which a plain bar-of-means would hide.

Usage

sframe_plot_paired_comparison(result, data, palette = c("web", "print"))

Arguments

Value

A ggplot2 object, or NULL if fewer than two complete pairs remain, or ggplot2 is unavailable.

See Also

run_analysis_plan()

Description

Quality report plot: straight-lining flag rate by scale

Usage

sframe_plot_quality(x, palette = c("web", "print"))

Arguments

Value

A ggplot2 object.

See Also

quality_report()

Description

The four standard diagnostic panels (residuals vs fitted, normal Q-Q, scale-location, residuals vs leverage), built from the plain data frame run_analysis_plan() attaches to a regression_linear result rather than the lm object itself, so the result stays JSON-serialisable.

Usage

sframe_plot_regression_diagnostics(result, palette = c("web", "print"))

Arguments

Value

A named list of four ggplot2 objects (residuals_fitted, qq, scale_location, leverage), or NULL if diagnostics are unavailable.

See Also

run_analysis_plan()

Description

Reliability plot: alpha and omega by scale

Usage

sframe_plot_reliability(x, palette = c("web", "print"))

Arguments

Value

A ggplot2 object.

See Also

reliability_report()

Description

Validity report plot: composite reliability and AVE by construct

Usage

sframe_plot_validity(x, palette = c("web", "print"))

Arguments

Value

A ggplot2 object.

See Also

validity_report()

Description

Unlike sframe_plot_descriptives(), which summarises skewness and kurtosis across the variables in a descriptives_report() table, this operates on one variable's raw values directly (the report table only stores summary statistics, not the underlying vector), matching the pattern sframe_plot_correlation_matrix() already uses for report-independent, data-driven plots.

Usage

sframe_plot_variable_distribution(data, variable, palette = c("web", "print"))

Arguments

Value

A named list of three ggplot2 objects (histogram, boxplot, qq), or NULL if fewer than two complete values remain.

See Also

descriptives_report(), sframe_plot_descriptives()

Description

Summarise an sf_branch object

Usage

## S3 method for class 'sf_branch'
summary(object, ...)

Arguments

Value

object, invisibly.

Description

Summarise an sf_check object

Usage

## S3 method for class 'sf_check'
summary(object, ...)

Arguments

Value

object, invisibly.

Description

Summarise an sf_choices object

Usage

## S3 method for class 'sf_choices'
summary(object, ...)

Arguments

Value

object, invisibly.

Description

Summarise an sf_item object

Usage

## S3 method for class 'sf_item'
summary(object, ...)

Arguments

Value

object, invisibly.

Description

Summarise an sf_model object

Usage

## S3 method for class 'sf_model'
summary(object, ...)

Arguments

Value

object, invisibly.

Description

Summarise an sf_scale object

Usage

## S3 method for class 'sf_scale'
summary(object, ...)

Arguments

Value

object, invisibly.

Description

Prints a structured summary of an sframe object including metadata, item type counts, scale definitions, branching rules, and check specifications.

Usage

## S3 method for class 'sframe'
summary(object, ...)

Arguments

Value

object, invisibly.

Examples

item <- sf_item("q1", "How satisfied are you?", type = "likert",
                choice_set = "agree5")
instr <- sf_instrument("My Survey", components = list(item))
summary(instr)

Description

Renders the survey instrument and collects the respondent's answers. Returns a reactive that holds NULL until the form is submitted, then returns the response as a named list (one element per visible item).

Usage

survey_module_server(id, instrument, on_submit = NULL)

Arguments

Value

A reactive that returns NULL before submission and the response list after.

See Also

survey_module_ui()

Examples

# See survey_module_ui() for a complete example.

Description

Places a survey rendered by surveyframe inside a larger Shiny application. Pair with survey_module_server() in the server function. The module renders the full instrument including welcome page, all item types, branching logic, required-field validation, and a thank-you screen.

Usage

survey_module_ui(id, width = "100%")

Arguments

Value

A shiny.tag object.

See Also

survey_module_server(), launch_studio(), export_static_survey()

Examples

## Not run: 
# Minimal embedding example:
library(shiny)
library(surveyframe)

cs    <- sf_choices("ag5", 1:5, c("SD", "D", "N", "A", "SA"))
item  <- sf_item("q1", "Rate your experience.", type = "likert",
                 choice_set = "ag5", required = TRUE)
instr <- sf_instrument("Quick Survey", components = list(cs, item))

ui <- fluidPage(
  survey_module_ui("demo"),
  verbatimTextOutput("result")
)

server <- function(input, output, session) {
  resp <- survey_module_server("demo", instrument = instr)
  output$result <- renderPrint({
    req(resp())
    resp()
  })
}

shinyApp(ui, server)

## End(Not run)

Description

A theme_classic()-based ggplot2 theme (visible axis lines, no floating panel), verified against WCAG 2.2 contrast minimums: 4.5:1 for text, 3:1 for non-text graphical objects. Apply it to any ggplot object, including the plots returned by run_analysis_plan() when plots = TRUE.

Usage

theme_surveyframe(
  base_size = 12,
  base_family = "",
  palette = c("web", "print")
)

Arguments

Value

A ggplot2 theme object.

See Also

run_analysis_plan()

Examples

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(colour = "#0E9694") +
  theme_surveyframe()

Description

Checks model IDs, construct IDs, indicators, structural path endpoints, duplicate paths, indirect paths, and engine/type compatibility.

Usage

validate_model(model, instrument = NULL, strict = TRUE)

Arguments

Value

The model invisibly when valid and strict = TRUE, otherwise a validation result list.

Description

Checks the internal consistency of an sframe instrument object and reports all detected problems. Validation is performed automatically by write_sframe() and optionally by read_sframe(). It can also be run independently at any point during instrument construction.

Usage

validate_sframe(instrument, strict = TRUE)

Arguments

Details

The following checks are performed:

• Duplicate item IDs

• Invalid item IDs

• Duplicate choice-set IDs

• Duplicate scale IDs

• Items with missing labels

• Items referencing a missing choice_set in the instrument

• Items referencing a missing scale_id in the instrument

• Items marked reverse = TRUE without a scale_id

• Choice sets referenced by items but not present in the instrument

• Scale items vectors containing IDs not present in the instrument

• Branching rules referencing item IDs not present in the instrument

• Attention checks referencing item IDs not present in the instrument

• Analysis plan roles referencing missing variables or models

• Model specifications referencing missing indicators or constructs

Value

When strict = TRUE and the instrument is valid, the instrument is returned invisibly with meta$validated set to TRUE. When strict = FALSE, a named list with elements valid (logical) and problems (character vector) is returned.

See Also

sf_instrument(), write_sframe()

Examples

# Build a minimal valid instrument and validate it
cs    <- sf_choices("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
item  <- sf_item("sat_1", "The service met my expectations.",
                 type = "likert", choice_set = "ag5", scale_id = "sat")
scale <- sf_scale("sat", "Satisfaction", items = "sat_1")
instr <- sf_instrument("Demo Survey", components = list(cs, item, scale))

# Non-strict: returns a list without stopping
result <- validate_sframe(instr, strict = FALSE)
result$valid
result$problems

# Strict: returns instrument invisibly when valid
validated <- validate_sframe(instr, strict = TRUE)
isTRUE(validated$meta$validated)

Description

Validity report for construct models

Usage

validity_report(loadings, construct_scores = NULL, items_by_construct = NULL)

Arguments