Package {surveyframe}

Title:	Survey Instrument Workflows
Version:	0.4.2
Description:	Provides a design-first survey research workflow. An instrument, an analysis plan declared before data collection, and a measurement or structural model are held together in one typed, integrity-checked object (the 'sframe'), so a study's confirmatory tests are fixed before responses arrive rather than chosen afterward. Includes visual instrument design via a browser-based builder or 'Shiny' studio, export to a self-contained static HTML survey, an embeddable 'Shiny' module, SHA-256 integrity-checked serialisation to the '.sframe' format, multi-page survey rendering with branching logic, response quality checking, scale scoring, psychometric diagnostics, analysis-plan execution, model syntax generation for EFA, CFA, CB-SEM, and PLS-SEM, an interactive response dashboard, codebook generation, and reproducible HTML reporting. Also supports multi-criteria decision analysis (AHP, ANP, DEMATEL, TOPSIS, VIKOR, MOORA, SMART, WASPAS, PROMETHEE II, ELECTRE I), small-sample survey helpers, and text and open-ended response analysis (term and n-gram frequency, keyword in context, co-occurrence and co-occurrence networks, sentiment, document-feature matrices, and topic modelling via LDA or structural topic models).
License:	MIT + file LICENSE
URL:	https://mohammedalisharafuddin.github.io/surveyframe/, https://github.com/MohammedAliSharafuddin/surveyframe
BugReports:	https://github.com/MohammedAliSharafuddin/surveyframe/issues
Encoding:	UTF-8
Language:	en-GB
Depends:	R (≥ 4.1.0)
Imports:	jsonlite (≥ 1.8.0), rlang (≥ 1.1.0), openssl (≥ 2.1.0)
Suggests:	ggplot2 (≥ 3.4.0), googlesheets4 (≥ 1.1.0), shiny (≥ 1.7.0), psych (≥ 2.3.0), MASS, nnet, logistf (≥ 1.24.0), digest (≥ 0.6.0), lavaan (≥ 0.6-0), seminr (≥ 2.3.0), testthat (≥ 3.0.0), knitr, rmarkdown, naniar (≥ 1.0.0), pagedown (≥ 0.20), RMCDA (≥ 0.3.1), rstudioapi (≥ 0.13), jmv (≥ 2.4.0), tidytext (≥ 0.4.0), quanteda (≥ 3.0.0), stm (≥ 1.3.0), topicmodels, igraph (≥ 1.5.0), V8 (≥ 4.0.0), haven (≥ 2.5.0), callr, chromote, httpuv, pkgload
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-09-25 13:25:11 UTC; maxx
Author:	Mohammed Ali Sharafuddin [aut, cre]
Maintainer:	Mohammed Ali Sharafuddin <mohammedali.page@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-25 21:30:02 UTC

surveyframe: Survey Instrument Workflows for R

Description

surveyframe defines a survey instrument as a first-class R object and supports a complete workflow from questionnaire design through data collection, quality checking, scoring, psychometric diagnostics, and reproducible reporting. The package covers static HTML survey export, an embeddable Shiny survey module, an interactive response dashboard, a role-based analysis planner with pre-declared research questions, common survey statistics with small-sample alternatives (Hodges-Lehmann, pseudomedian, exact odds-ratio, and Firth logistic regression), multi- criteria decision analysis (AHP, ANP, DEMATEL, VIKOR, MOORA, SMART, WASPAS, PROMETHEE, ELECTRE, and TOPSIS), and model syntax planning for EFA, CFA, CB-SEM, and PLS-SEM.

Core workflow

1. Design an instrument with launch_builder() or sf_instrument() and its component constructors: sf_item(), sf_choices(), sf_scale(), sf_branch(), sf_check().

2. Validate and save with validate_sframe() and write_sframe(). validate_sframe() returns an sframe_validation diagnostic rather than the instrument itself. Recover a validated instrument with as_sframe().

3. Deploy a Shiny survey with render_survey().

4. Load responses with read_responses() or read_sheet_responses().

5. Check quality with quality_report().

6. Score and analyse with score_scales(), descriptives_report(), missing_data_report(), reliability_report(), item_report(), efa_report(), cfa_syntax(), and run_analysis_plan(), which also runs any decision-analysis blocks in the plan.

7. Report with codebook_report(), render_report(), and render_results().

The instrument object

The workflow runs on an sframe object. It is the single source of truth for item definitions, scale structure, reverse-coding keys, branching rules, check specifications, analysis plans, and optional model specifications. Accessors such as sf_meta(), sf_items(), sf_scales(), sf_plan(), and sf_models() read its parts without reaching into the object directly.

Some helpers work on plain vectors, for use beside that workflow or on their own: the text helpers such as term_frequency(), and the interval helpers bootstrap_ci(), cohens_d_ci(), cramers_v_ci() and eta_sq_ci().

A first session

sframe_demos() lists 22 worked demos, each one instrument, its responses and the results surveyframe produced. sframe_demo("two_group") loads one, and sframe_demo_qmd("two_group") writes a notebook to edit. vignette("learn-by-example") teaches from the same library.

How functions are named

Three families, which the prefix tells apart.

• sf_ builds or reads the instrument object model: the constructors sf_item() and sf_scale(), the accessors sf_items() and sf_plan(), and the replacement forms such as ⁠sf_plan<-⁠.

• sframe_ covers everything the package adds around that object: the plots such as sframe_plot_reliability(), the demo library through sframe_demos(), the decision helpers, and the builder's own state.

• The workflow verbs carry no prefix, because they name the step a researcher is taking: validate_sframe(), score_scales(), run_analysis_plan(), render_report(), and the ⁠_report()⁠ family.

The prefixes group functions; they do not pair them. No name stem appears under both, so there is no sframe_ twin of an sf_ function to look for.

File format

Instruments are stored as UTF-8 JSON files with the .sframe extension. Each file includes a SHA-256 integrity hash for reproducibility auditing.

Author(s)

Maintainer: Mohammed Ali Sharafuddin mohammedali.page@gmail.com (ORCID)

Authors:

• Mohammed Ali Sharafuddin mohammedali.page@gmail.com (ORCID)

See Also

Useful links:

• https://mohammedalisharafuddin.github.io/surveyframe/

• https://github.com/MohammedAliSharafuddin/surveyframe

• Report bugs at https://github.com/MohammedAliSharafuddin/surveyframe/issues

The .sframe format version, written into every file as sframe_format.

Description

Tracks the shape of the serialised object, not the package version and not the instrument's own version. Bump it only when the file's structure changes in a way a consumer must react to. sframe-schema conformance profiles are keyed to this value.

Usage

SFRAME_FORMAT_VERSION

Add a model specification to an instrument

Description

Add a model specification to an instrument

Usage

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

Arguments

Value

The updated sframe object.

Examples

demo <- sframe_demo_data()
m <- sf_model("cb1", type = "cb_sem",
              constructs = list(sf_construct("sat", items = c("sat_1", "sat_2"))))
instr <- add_model(demo$instrument, m)
length(instr$models)

Record a disclosed amendment to an instrument

Description

Appends a structured, disclosed-revision entry to an instrument's amendment log, comparing previous against instrument to record what changed and why: a data-entry correction, bot-response removal, or a documented model respecification. The record is kept inside the file, beside the content it explains.

Usage

amend_sframe(
  previous,
  instrument,
  reason_code,
  reason_text,
  tier = NULL,
  author = NULL,
  deviation_report = NULL,
  second_signoff = NULL
)

Arguments

Details

write_sframe() refuses to write an instrument read from a file whose content has changed with no amendment recorded, one that changed after its last amendment, and one whose amendment log was shortened or reordered. read_sframe() refuses a file edited on disk without its hash being recomputed. These checks are local and the hashes are unsigned: someone who rewrites both a file and its log, and recomputes the hashes, is not detected, and nothing here establishes who made a change or when.

Amendments come in two tiers. A "pipeline" amendment (data corrections, bot removal) needs only a reason. A "design" amendment also requires a deviation_report describing what changed in the research question, method or model, and why. The tier follows the change itself: an amendment that changes the analysis plan, a model or a conjoint design is always design tier, whatever reason_code or tier says. second_signoff is optional. When omitted, the entry records signoff = "none", so the absence of a named reviewer is visible. The tier, report and signoff are what the author records. None of them is independent approval.

previous_hash and new_hash on each entry are a content fingerprint: a SHA-256 over a canonical serialisation of the instrument, with the hash and amendments fields excluded, taken after validation, so new_hash is the content that is written. It is distinct from the file's own integrity hash from write_sframe(), which also covers the amendment log. Both identify content. Neither is byte identity.

Value

The amended sframe object, with the new entry appended to its amendment log. Call write_sframe() to persist it.

See Also

amendment_log(), write_sframe(), read_sframe()

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "text")
instr <- sf_instrument("Demo", components = list(item))
item2 <- sf_item("q1", "How satisfied are you overall?", type = "text")
revised <- sf_instrument("Demo", components = list(item2))
amended <- amend_sframe(
  instr, revised,
  reason_code = "instrument_revision",
  reason_text = "Clarified item wording after a pilot round.",
  deviation_report = "Wording only; no change to the construct measured."
)
nrow(amendment_log(amended))

Read an instrument's amendment log

Description

Returns the disclosed-amendment history recorded by amend_sframe() as a data frame, one row per amendment in the order they were recorded.

Usage

amendment_log(instrument)

Arguments

Value

A data frame with columns timestamp, reason_code, reason_text, tier, author, deviation_report, signoff, previous_hash, new_hash, and changed_fields (a comma-joined string). Zero rows if the instrument has no recorded amendments. Export with write.csv() for an external audit trail.

See Also

amend_sframe()

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "text")
instr <- sf_instrument("Demo", components = list(item))
amendment_log(instr)

The R code behind an analysis result

Description

Returns the statistical call that produced a result, as R code a reader can copy and run. This is what lets a report show t.test() or cor.test() with the variables and options resolved, rather than only the run_analysis_plan() call that dispatched it.

Usage

analysis_syntax(x, which = NULL, data_expr = "scored", header = FALSE)

Arguments

Details

The code is built from the same resolved specification the runner executed: the variables in the order it resolved them, and the options after defaults were applied. Running it reproduces the statistic, degrees of freedom and p value the package reports, which the package's own tests check by running the generated code and comparing.

Value

A character vector of R code lines, or NULL for a method this does not cover. For several blocks, a named list of such vectors.

What it covers

The 2-group, paired, k-group, correlation, regression and categorical families, and descriptives. sframe_syntax_methods lists them. A method outside that list returns NULL: the model families carry their own syntax already, through cfa_syntax() and its neighbours, and for the rest the computation has no single base-R equivalent to show honestly.

See Also

run_analysis_plan(), cfa_syntax(), render_report()

Examples

instr <- sf_instrument("Syntax demo", components = list(
  sf_item("score", "Score", type = "numeric"),
  sf_item("arm", "Arm", type = "text")
))
sf_plan(instr) <- list(list(
  id = "RQ1", research_question = "Do the arms differ?",
  family = "inferential", method = "t_test_ind",
  roles = list(group = "arm", outcome = "score")
))

set.seed(1)
responses <- data.frame(
  arm   = rep(c("control", "treatment"), each = 15),
  score = c(rnorm(15, 10), rnorm(15, 12))
)
results <- run_analysis_plan(responses, instr)

# the call behind the number, with the variables and options resolved
cat(analysis_syntax(results, which = "RQ1"), sep = "\n")

Coerce a choice set to a data frame

Description

Returns the stored values and respondent-facing labels in a choice set.

Usage

## S3 method for class 'sf_choices'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame with value and label columns.

See Also

sframe_as_data_frame, sf_choices()

Coerce an instrument to its item summary

Description

Returns one row per item in a surveyframe instrument.

Usage

## S3 method for class 'sframe'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame summarising the instrument's items.

See Also

sframe_as_data_frame, sf_items(), codebook_report()

Summarise analysis-plan results as a data frame

Description

Returns one row per analysis block, including its research question, method, APA summary, and any error.

Usage

## S3 method for class 'sframe_analysis_results'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame with one row per analysis block.

See Also

sframe_as_data_frame, run_analysis_plan()

Coerce an assumption report to a data frame

Description

Combines the available normality, homogeneity, and regression checks into a long-form summary.

Usage

## S3 method for class 'sframe_assumption_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame naming each assumption family, variable, and statistic.

See Also

sframe_as_data_frame, assumption_report()

Extract the item table from a codebook report

Description

Extract the item table from a codebook report

Usage

## S3 method for class 'sframe_codebook'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The codebook report's item table as a data frame.

See Also

sframe_as_data_frame, codebook_report()

Extract the descriptives results table

Description

Extract the descriptives results table

Usage

## S3 method for class 'sframe_descriptives_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The primary table from a descriptives report.

See Also

sframe_as_data_frame, descriptives_report()

Coerce an EFA readiness report to a data frame

Description

Coerce an EFA readiness report to a data frame

Usage

## S3 method for class 'sframe_efa_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A one-row data frame containing readiness measures and the suggested number of factors.

See Also

sframe_as_data_frame, efa_report()

Extract the loading table from an EFA solution

Description

Extract the loading table from an EFA solution

Usage

## S3 method for class 'sframe_efa_solution'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The solution's long-form factor-loading data frame.

See Also

sframe_as_data_frame, efa_solution()

Coerce an item report to a data frame

Description

Stacks item diagnostics from every reported scale into one table.

Usage

## S3 method for class 'sframe_item_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame of item-level diagnostics.

See Also

sframe_as_data_frame, item_report()

Extract item missingness results

Description

Extract item missingness results

Usage

## S3 method for class 'sframe_missing_data_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The item-level missingness table from a missing-data report.

See Also

sframe_as_data_frame, missing_data_report()

Coerce a response-quality report to a data frame

Description

Coerce a response-quality report to a data frame

Usage

## S3 method for class 'sframe_quality_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A one-row data frame summarising respondents, items, and quality flags.

See Also

sframe_as_data_frame, quality_report()

Coerce a reliability report to a data frame

Description

Returns one row per scale with alpha and omega estimates.

Usage

## S3 method for class 'sframe_reliability_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame of scale reliability statistics.

See Also

sframe_as_data_frame, reliability_report()

Coerce a sample-size plan to a data frame

Description

Coerce a sample-size plan to a data frame

Usage

## S3 method for class 'sframe_sample_size_plan'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A one-row data frame containing the analysis type, estimated sample size, alpha, and power.

See Also

sframe_as_data_frame, sample_size_plan()

Extract a sensitivity-analysis results table

Description

Extract a sensitivity-analysis results table

Usage

## S3 method for class 'sframe_sensitivity'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The primary results table from a sensitivity analysis.

See Also

sframe_as_data_frame

Coerce validation problems to a data frame

Description

Coerce validation problems to a data frame

Usage

## S3 method for class 'sframe_validation'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame with one row per validation problem and columns check and problem.

See Also

sframe_validation, sf_problems()

Extract reliability evidence from a validity report

Description

Extract reliability evidence from a validity report

Usage

## S3 method for class 'sframe_validity_report'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

The reliability table stored in a validity report.

See Also

sframe_as_data_frame, validity_report()

Coerce to an instrument

Description

Recovers the sframe instrument from a validation diagnostic. This is the migration path for code that used the strict = TRUE return of validate_sframe() as an instrument, which it no longer is.

Usage

as_sframe(x, ...)

Arguments

Value

An sframe object. When the validation passed, its meta$validated is TRUE.

See Also

validate_sframe(), sframe_validation

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "text")
instr <- sf_instrument("Demo", components = list(item))

validated <- as_sframe(validate_sframe(instr, strict = TRUE))
isTRUE(sf_meta(validated)$validated)

Assumption-check report

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.

Examples

demo <- sframe_demo_data()
ar <- assumption_report(demo$responses, variables = c("sat_1", "sat_2"),
                         group = "visit_type")
print(ar)

Percentile bootstrap confidence interval for a statistic

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, with attributes resamples, valid_resamples and, when the interval is withheld, reason. The bounds are NA when fewer than 90% of resamples give a value, or when every resample gives the same value, since neither leaves a sampling distribution to read. 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)

Generate lavaan CFA syntax from an instrument or a declared model

Description

The general entry point for CFA syntax. It takes an instrument, and derives the constructs from its scales, or an sf_model() declaring constructs that cut across them, and it accepts correlated residuals and latent covariances.

Usage

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

Arguments

Details

cfa_syntax() is the instrument-only convenience wrapper, kept for the scripts that call it. Start here when a model is declared, when residual covariances are needed, or when the constructs differ from the scales.

Each generator emits the language its engine reads, so they stay separate: this one and sem_lavaan_syntax() write lavaan, seminr_syntax() writes seminr, and efa_syntax() writes an exploratory plan.

Value

A lavaan syntax string.

Examples

demo <- sframe_demo_data()
syntax <- cfa_lavaan_syntax(demo$instrument,
                             scales = c("satisfaction", "behavioural_intention"))
cat(syntax)

Generate lavaan CFA syntax from an instrument object

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.

Which of the two to use

This is the instrument-only convenience wrapper: one call, constructs taken from the instrument's scales. cfa_lavaan_syntax() is the general entry point, and takes those same arguments plus a declared sf_model(), correlated residuals and latent covariances. Reach for it where the constructs differ from the scales. This wrapper stays supported, so a script calling it keeps working.

See Also

cfa_lavaan_syntax(), 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)

Clean open-ended text responses for analysis

Description

Extracts one text/textarea item's responses from a response data frame and applies light, configurable cleaning: lower-casing, punctuation removal, and optional number stripping. Blank and missing responses are dropped rather than kept as empty strings, since they carry no term-frequency signal and would otherwise inflate downstream response counts.

Usage

clean_text_responses(
  data,
  item_id,
  lowercase = TRUE,
  remove_punct = TRUE,
  strip_numbers = FALSE,
  instrument = NULL
)

Arguments

Value

A character vector of cleaned responses, with an integer "respondent" attribute giving each entry's original row index in data, so quotes extracted later can cite a respondent.

Examples

demo <- sframe_demo_data()
cleaned <- clean_text_responses(demo$responses, "comments")
head(cleaned)
attr(cleaned, "respondent")[1:5]

Generate a survey codebook from an instrument object

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(sf_items(cb))
nrow(sf_scales(cb))

Bootstrap confidence interval for Cohen's d

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, with attributes resamples, valid_resamples and, when the interval is withheld, reason. The bounds are NA when fewer than 90% of resamples give a value, or when every resample gives the same value, since neither leaves a sampling distribution to read. 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)

Bootstrap confidence interval for Cramer's V

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, with attributes resamples, valid_resamples and, when the interval is withheld, reason. The bounds are NA when fewer than 90% of resamples give a value, or when every resample gives the same value, since neither leaves a sampling distribution to read. 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)

Descriptive statistics report

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.

Examples

demo <- sframe_demo_data()
dr <- descriptives_report(demo$responses, variables = c("sat_1", "sat_2"),
                           split_by = "visit_type")
dr$table

Prepare a survey instrument for exploratory factor analysis

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.

Fitting the solution

This report says whether the data suit a factor analysis and how many factors to extract. efa_solution() then fits that solution and returns the loadings, so the whole route stays in surveyframe. Take the result to another package when you want a method surveyframe leaves out.

See Also

efa_solution(), reliability_report(), cfa_syntax()

Examples

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

Estimate an exploratory factor solution

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

Examples

if (requireNamespace("psych", quietly = TRUE)) {
  demo <- sframe_demo_data()
  fit <- efa_solution(demo$responses, demo$instrument,
                       scales = "service_quality", nfactors = 1)
  fit$loadings
}

Generate EFA planning syntax

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.

Examples

syntax <- efa_syntax(c("sq_1", "sq_2", "sq_3"), nfactors = 1)
cat(syntax)

Bootstrap confidence interval for eta squared

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, with attributes resamples, valid_resamples and, when the interval is withheld, reason. The bounds are NA when fewer than 90% of resamples give a value, or when every resample gives the same value, since neither leaves a sampling distribution to read. 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)

Export a survey instrument to Google Sheets collection format

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.

Changing the instrument mid-collection

Regenerating and redeploying the collector after an instrument change is safe, and it is what a pilot study normally does after a face-validity pass. The collector maps every response to the sheet's own header by name, so a column that already exists never moves and rows collected before the change stay valid. An item added to the instrument gets a new column at the right-hand end of the sheet, and rows collected before it existed are left blank in that column.

Before surveyframe 0.4.1 this was not true. The header was written once, at sheet creation, and rows were built positionally, so an item added mid-collection shifted every value from the insertion point onward into the wrong column, silently. If you collected responses through a redeployed collector generated by 0.4.0 or earlier, check the sheet's header against the instrument before analysing it.

Who can reach the collected responses

Keep the sheet private. The collector is an Apps Script bound to the sheet and writes through SpreadsheetApp.getActiveSpreadsheet(), so it runs with the access of whoever deployed it. No sharing change is needed for collection to work.

Step 5 of the generated setup sets the web app's "Who has access" to "Anyone". That setting belongs to the web app endpoint, which accepts submissions. It grants no access to the sheet itself.

Sharing the sheet so that any link holder can edit would expose every collected response, personal data included, to anyone holding the URL, and would let them alter or delete it. Before surveyframe 0.4.2 this help advised exactly that. If you followed it, review the sharing settings on any sheet you collected into.

read_sheet_responses() reads through googlesheets4, which authenticates as you, so a private sheet is readable with no sharing change.

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)

Export a self-contained static HTML survey

Description

Generates a single HTML file that presents the survey instrument in a browser, with no Shiny server and no internet connection. Every item type, branching, required-item checks and multi-page navigation run in the browser's own JavaScript.

Usage

export_static_survey(
  instrument,
  output_path = NULL,
  open = interactive(),
  endpoint_url = NULL,
  overwrite = FALSE,
  preview = 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.

Value

The output path, invisibly.

How a response reaches you

On submission the survey builds a one-row CSV in the browser's memory and shows the thank-you screen. When endpoint_url is supplied, it also sends the response as a POST request to that URL, for example a Google Apps Script web app. The browser reports nothing back from that request, so the survey treats it as sent and the respondent sees the thank-you screen either way.

The thank-you screen offers the CSV as a download button, which the respondent chooses to use. It appears when the instrument's thank-you settings ask for it, and whenever there is no endpoint_url, where that file is the only copy of the response.

Plan for both parts. Test the endpoint with a pilot submission and confirm the row arrives before collecting, and treat the download as a route a respondent may decline.

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.

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
)

Extract representative quotes for each STM topic

Description

Takes the result of sframe_run_stm_topics() (not a raw stm model object) and, for each topic, pulls the top n_quotes documents by topic-document probability using stm::findThoughts(), then maps each one back to its original respondent row via the mapping sframe_run_stm_topics() stored on result$fit.

Usage

extract_quotes(model, text, n_quotes = 3L)

Arguments

Value

A data.frame with columns topic, rank, respondent (the original row index in the data the model's text argument came from, not a document-matrix or corpus row index), and quote.

Examples

if (requireNamespace("stm", quietly = TRUE) &&
    requireNamespace("tidytext", quietly = TRUE)) {
  demo <- sframe_demo_data()
  sf_plan(demo$instrument) <- list(list(
    id = "RQ1", research_question = "What themes appear in the comments?",
    family = "text_analysis", method = "stm_topics",
    roles = list(item = "comments"), options = list(k = 3, seed = 42)
  ))
  res <- run_analysis_plan(demo$responses, demo$instrument)
  quotes <- extract_quotes(res$RQ1, demo$responses$comments, n_quotes = 2)
  quotes
}

Format an sf_branch object as a string

Description

Format an sf_branch object as a string

Usage

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

Arguments

Value

A single character string.

Format an sf_check object as a 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.

Format an sf_choices object as a 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.

Format an sf_item object as a 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.

Format an sf_model object as a 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.

Format an sf_scale object as a 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.

Format an sframe instrument object as a string

Description

Format an sframe instrument object as a string

Usage

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

Arguments

Value

A single character string.

Generate item-level diagnostics

Description

Produces, for each item within each scale, the item-rest correlation, floor and ceiling proportions, and the item mean and standard deviation.

Usage

item_report(data, instrument, scales = NULL)

Arguments

Details

Diagnostics use the scale's scoring orientation, so an item the scale reverse-codes is reversed first, as in score_scales() and reliability_report(). The item-rest correlation is the correlation between an item and the sum of the scale's other items. It is computed on respondents who answered every item in the scale, the same rows reliability_report() uses, and n_missing counts the item's own missing values in data.

Floor and ceiling are the proportions at the item's declared lowest and highest response, taken from its choice set, slider limits or rating maximum. They are NA for an item that declares no bounds, since the sample's own extremes say nothing about a floor or ceiling effect.

Value

An object of class sframe_item_report: a named list with one element per scale, each a list holding scale_id, label and diagnostics, a data frame with one row per item and columns item_id, mean, sd, item_rest_r, floor_pct, ceiling_pct and n_missing. as.data.frame() stacks every scale's diagnostics into one table.

See Also

reliability_report(), sf_scale()

Examples

demo <- sframe_demo_data()
ir <- item_report(demo$responses, demo$instrument)
print(ir)
# one scale's diagnostics
ir[[1]]$diagnostics
# every scale in one table
as.data.frame(ir)

Launch the surveyframe visual survey builder

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 layout preview of the welcome, body and thank-you pages, showing wording, order and branding. It renders from the builder's own markup, so answering, required checks and branching are left out. Use export_static_survey() and open the file to test the respondent's path, or SurveyStudio's Preview screen, which exports the real survey with collection switched off.

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)

Launch SurveyBuilder with the bundled input-types demo preloaded

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, with no manual file-load step required.

Usage

launch_builder_demo(open = TRUE)

Arguments

Value

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

Examples

demo <- sframe_input_types_demo_data()
nrow(demo$responses)
## Not run: 
launch_builder_demo()

## End(Not run)

Launch the interactive response dashboard

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)

Launch the response dashboard with the bundled input-types demo

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.

Examples

demo <- sframe_input_types_demo_data()
nrow(demo$responses)
## Not run: 
launch_dashboard_demo()

## End(Not run)

Launch the SurveyStudio interface

Description

Opens the SurveyStudio Shiny application, the visual interface for working with an instrument that already exists. Its screens open an instrument, record and read amendments, preview the survey, upload responses, review data quality, inspect reliability, work on the analysis plan, read the dashboard, and export.

Usage

launch_studio(
  instrument = NULL,
  responses = NULL,
  respondent_id = NULL,
  submitted_at = NULL,
  meta_cols = NULL,
  strict = TRUE,
  screen = "auto",
  port = NULL,
  host = "127.0.0.1",
  launch.browser = interactive()
)

Arguments

Details

Studio reads and analyses an instrument. To author one, question by question, use launch_builder(), and open the result here.

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)

Launch SurveyStudio with the bundled input-types demo

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.

Examples

demo <- sframe_input_types_demo_data()
nrow(demo$responses)
## Not run: 
launch_studio_demo()

## End(Not run)

Link an instrument to its current Git commit

Description

Records the current Git commit SHA and subject line for repo_path. It is a pointer into Git history, where a reviewer reads what changed and why.

Usage

link_git_commit(instrument, repo_path = ".", path = NULL)

Arguments

Details

Given path, the tracked .sframe file, it also compares the instrument with that file as committed at HEAD, and sets verified = TRUE only when their content hashes match. Without path, nothing is compared and verified is FALSE. A verified link shows the instrument matches a committed file. It does not show who wrote the instrument or when, beyond what the commit itself records.

Git is entirely optional. When repo_path is not inside a Git repository, or the git executable is not on the PATH, this returns a clear, non-error result with linked = FALSE rather than aborting – the rest of surveyframe never requires Git.

Value

A list with linked (logical), and when linked is TRUE, commit (the full commit SHA), message (the commit's subject line), path, and verified (logical). reason explains an unlinked result ("git not found" or "not a git repository") or an unverified one.

See Also

amend_sframe(), write_sframe()

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "text")
instr <- sf_instrument("Demo", components = list(item))
link_git_commit(instr, repo_path = tempdir())

Missing-data report

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.

Examples

demo <- sframe_demo_data()
mr <- missing_data_report(demo$responses, demo$instrument)
mr$item_missing

Serialise a model specification to JSON

Description

Serialise a model specification to JSON

Usage

model_json(model, pretty = TRUE)

Arguments

Value

A JSON string.

Examples

m <- sf_model("cb1", type = "cb_sem",
              constructs = list(sf_construct("sq", items = c("sq_1", "sq_2"))))
cat(model_json(m))

Create a model reporting template

Description

Create a model reporting template

Usage

model_report_template(model, include_json = TRUE)

Arguments

Value

A character string.

Examples

m <- sf_model("cb1", type = "cb_sem",
              constructs = list(sf_construct("sat", items = c("sat_1", "sat_2"))))
cat(model_report_template(m, include_json = FALSE))

N-gram frequency for open-ended text

Description

Tokenises text via the same tokeniser as term_frequency() (whitespace splitting, lower-casing, punctuation stripping, and stop-word removal), then slides a window of n tokens across each response's token vector and counts how often each resulting n-gram occurs. n = 2 (the default) gives bigrams, and n = 3 gives trigrams.

Usage

ngram_frequency(text, n = 2L, stop_words = NULL, top_n = 30L)

Arguments

Details

An n-gram never straddles a removed stop word. Where "but" and "not" are filtered, "clean but not comfortable" yields no bigram at all, because "clean" and "comfortable" were never next to each other. This is what makes the output phrases respondents actually wrote.

Value

A data.frame with columns term (the space-joined n-gram), n, and pct.

Examples

demo <- sframe_demo_data()
cleaned <- clean_text_responses(demo$responses, "comments")
head(ngram_frequency(cleaned, n = 2, top_n = 10))

Flag univariate and multivariate outliers

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

Plot analysis-plan results

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.

Post-hoc and pairwise comparison report

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.

Examples

demo <- sframe_demo_data()
pr <- posthoc_report(demo$responses, method = "kruskal_wallis",
                      outcome = "sat_1", group = "visit_type")
pr$tables$pairwise_wilcox

Print an sf_branch object

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)

Print an sf_check object

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)

Print an sf_choices object

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)

Print an sf_item object

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)

Print an sf_model object

Description

Print an sf_model object

Usage

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

Arguments

Value

x, invisibly.

Print an sf_scale object

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)

Print an sframe instrument object

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)

Generate a data quality report for survey responses

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,
  straightline_min_items = 4L,
  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)

Read and validate survey responses

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, each item followed by its expansion columns, then any undeclared columns kept under strict = FALSE. To keep an extra column under strict = TRUE, name it in meta_cols, or select the columns you need before reading.

Columns

A single-answer item has one column named by its ID. A matrix, ranking, multiple-choice or decision item has one column per row, option, pair or criterion, named item__sub, and each is checked: a battery with some of its columns absent is reported by name. Two columns with the same name are refused, since one would otherwise be lost.

Values

A CSV file is read as text, so identifiers such as 001, dates and text answers arrive exactly as written, a literal NA included. Columns of items with numeric responses (numeric, slider and rating items, choice items whose codes are all numbers, and ranking, multiple-choice and decision expansion columns) are then converted to numbers, with an empty cell or NA read as missing. A column that does not convert cleanly is kept as text. Data frames go through the same conversion, so a CSV file and a data frame holding the same responses read the same.

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

Read an instrument from a .sframe file

Description

Reads a .sframe JSON file and reconstructs an sframe instrument object. The SHA-256 integrity hash is always verified, and a file whose content does not match its hash is refused. The hash covers a canonical form of the content, so it detects a change to the content of a written file, and it ignores whitespace and key order. It is unsigned, so anyone who edits a file can also recompute it.

Usage

read_sframe(path, validate = TRUE)

Arguments

Details

The instrument remembers the content and amendment log it was read with, so write_sframe() can refuse an undisclosed revision.

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)

Read survey responses from a Google Sheet

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)

Estimate scale reliability from item responses

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

Render a reproducible survey report

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,
  show_code = TRUE
)

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)

Render analysis results to a formatted HTML report

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)

Render a survey from an instrument object

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

Run a pre-planned analysis from an instrument's analysis plan

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"),
  seed = 20260828L,
  strict = FALSE
)

Arguments

Value

An object of class sframe_analysis_results, a list with one element per analysis block, named by block id. Its status attribute holds blocks, succeeded, failed, failed_blocks and scoring, the outcome of scoring scales before analysis. A normal return can hold failed blocks, so check attr(results, "status")$failed or use strict = TRUE. Each block element 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)

Sample-size and power planning helper

Description

Estimates a total sample size for a planned analysis. The targets use 3 different methods, and the result says which one applied.

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,
  d = NULL,
  f = NULL,
  f2 = NULL
)

Arguments

Value

An sframe_sample_size_plan list holding type, estimated_n (total sample size), method ("power", "precision", "rule_of_thumb" or "none"), alpha, power, effect_size, warnings, advisory and prompt.

Power calculations

"t_test", "anova" and "correlation" are power calculations, so alpha, power and the expected effect size all change the result. The t test uses stats::power.t.test() for 2 independent groups with Cohen's d. ANOVA uses stats::power.anova.test() with Cohen's f. Correlation uses the Fisher z approximation with r. "regression" is a power calculation when f2 is supplied, from the noncentral F distribution for the overall test of predictors predictors.

When the effect size is left NULL, a conventional medium effect is assumed (d 0.5, f 0.25, r 0.30) and a warning names it. An assumed effect is a placeholder. Supply the effect you expect from prior studies or a pilot.

Precision targets and rules of thumb

"proportion" and "mean" size a confidence interval to a margin of error, and use alpha for its confidence level. power has no bearing on them. "regression" without f2 returns the larger of 2 published rules of thumb, ⁠50 + 8k⁠ and 104 + k, which ignore alpha and power. "sem" returns no estimate. Both say so in the returned warnings.

Examples

plan <- sample_size_plan("t_test", d = 0.5, power = 0.80)
plan$estimated_n
plan$method

Score defined scales from survey responses

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

Generate lavaan CB-SEM syntax

Description

Generate lavaan CB-SEM syntax

Usage

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

Arguments

Value

A lavaan syntax string.

Examples

m <- sf_model(
  "cb1", type = "cb_sem",
  constructs = list(
    sf_construct("sq", items = c("sq_1", "sq_2", "sq_3")),
    sf_construct("sat", items = c("sat_1", "sat_2")),
    sf_construct("bi", items = c("bi_1", "bi_2"))
  ),
  paths = list(sf_path("sq", "sat"), sf_path("sat", "bi")),
  indirect = list(sf_indirect("sq", through = "sat", to = "bi"))
)
cat(sem_lavaan_syntax(m))

Generate seminr PLS-SEM syntax

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.

Examples

m <- sf_model(
  "pls1", type = "pls_sem",
  constructs = list(
    sf_construct("sq", items = c("sq_1", "sq_2", "sq_3")),
    sf_construct("sat", items = c("sat_1", "sat_2"))
  ),
  paths = list(sf_path("sq", "sat"))
)
cat(seminr_syntax(m))

Test how far a decision ranking moves when the weights are perturbed

Description

Perturbs each criterion weight up and down by delta, renormalises the weight vector to sum to 1, reruns the same ranking method, and compares the perturbed ranking against the base ranking. A ranking that survives this unchanged is one a reviewer can be told is robust to the weights. A ranking whose leader changes under a 5 percent nudge is not.

Usage

sensitivity_analysis(
  x,
  weights,
  criteria_types,
  method = "topsis",
  delta = 0.05,
  alternatives = NULL,
  criteria = NULL,
  ...
)

Arguments

Value

An object of class sframe_sensitivity, a list with ⁠$table⁠ (one row per criterion and direction, carrying criterion, direction, rho, rank_changed, and top_changed), ⁠$base_ranks⁠, ⁠$method⁠, ⁠$delta⁠, ⁠$stable⁠, ⁠$degenerate⁠, ⁠$n_perturbations⁠, ⁠$n_effective⁠ and ⁠$n_failed⁠. ⁠$stable⁠ is TRUE when at least one perturbation moved the weights and none of those that did changed the ranking. A perturbation that leaves the renormalised weights unchanged, as every one does for weights such as c(1, 0), is not effective and tests nothing. ⁠$degenerate⁠ marks a base ranking that places every alternative at the same rank, which no perturbation can move.

See Also

run_analysis_plan(), sframe_decision_options()

Examples

x <- matrix(c(4.1, 3.0, 210, 3.6, 4.5, 180, 4.8, 2.5, 260),
            nrow = 3, byrow = TRUE)
sa <- sensitivity_analysis(
  x,
  weights        = c(0.4, 0.3, 0.3),
  criteria_types = c("benefit", "benefit", "cost"),
  method         = "topsis",
  alternatives   = c("Alpha", "Basilica", "Coral"),
  criteria       = c("service", "location", "price")
)
sa$stable
as.data.frame(sa)

Explore a surveyframe object

Description

Accessors for the parts of an instrument, a codebook, or a report. They replace reaching into the object with $, which ties user code to the internal layout.

Details

What each one gives back depends on what it is asked. Given an instrument, the component accessors return the component objects as an sf_component_list, which prints as a list and is subset with [ and [[. Given a codebook, the same verbs return the table the codebook already holds, a plain data frame with one row per item, scale, choice set, model or plan block.

as.data.frame() on an instrument gives its items as a table, which is one part of it, and a component list has no coercion of its own. For every table an instrument can produce, use codebook_report().

Value

A list for sf_meta() and sf_plan() on an instrument, an sf_component_list for the component accessors on an instrument, and a data frame for any of them on a codebook. See the table above.

See Also

as_sframe(), sf_problems(), sframe_validation

Examples

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

sf_meta(instr)$title
sf_items(instr)
sf_scales(instr)[["sat"]]
as.data.frame(instr)

Extract APA-formatted result summaries

Description

Returns the report-ready sentence attached to each analysis result.

Usage

sf_apa(x, ...)

Arguments

Value

A character vector containing one APA-formatted summary per result.

See Also

sf_report_accessors, run_analysis_plan()

Examples

results <- structure(
  list(RQ1 = list(apa = "Mean satisfaction was 4.20.")),
  class = c("sframe_analysis_results", "list")
)
sf_apa(results)

Define a branching rule

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

Get branching rules

Description

Returns the rules that control whether conditional items are shown.

Usage

sf_branches(x, ...)

Arguments

Value

An sf_component_list of branching rules.

See Also

sf_accessors

Examples

sf_branches(sframe_demo_data()$instrument)

Define a design-time survey check

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

Get response-quality checks

Description

Returns declared attention and other response-quality checks.

Usage

sf_checks(x, ...)

Arguments

Value

An sf_component_list of declared checks.

See Also

sf_accessors

Examples

sf_checks(sframe_demo_data()$instrument)

Get choice sets

Description

Returns the reusable value-and-label sets referenced by closed-response items.

Usage

sf_choice_sets(x, ...)

Arguments

Value

An sf_component_list for an instrument or a choice-set data frame for a codebook.

See Also

sf_accessors

Examples

sf_choice_sets(sframe_demo_data()$instrument)

Define a reusable choice set

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

A list of instrument components

Description

The value returned by sf_items(), sf_scales(), sf_choice_sets(), sf_branches(), sf_checks() and sf_models(). It is a list of component objects named by their IDs, so a single component is reached with [[.

Value

print() returns x invisibly. [ returns an sf_component_list.

Examples

item1 <- sf_item("q1", "First question", type = "text")
item2 <- sf_item("q2", "Second question", type = "text")
instr <- sf_instrument("Demo", components = list(item1, item2))

sf_items(instr)
sf_items(instr)[["q2"]]

Declare a choice-experiment (conjoint) design

Description

Generates and stores a conjoint profile set and task schedule as part of the instrument's pre-declared contract. This is a design generator, not an estimator: it fixes what respondents will be shown, and it does not fit or analyse choice models.

Usage

sf_conjoint_design(
  id,
  attributes,
  method = c("full", "balanced", "random"),
  n_profiles = NULL,
  n_alternatives = 2L,
  n_tasks = NULL,
  blocks = 1L,
  seed = NULL,
  profiles = NULL,
  label = NULL
)

Arguments

Details

The design is reproducible by construction. seed is always recorded, and generated when not supplied, so regenerating from the stored declaration returns the identical profiles and tasks.

Value

An object of class sf_conjoint_design with ⁠$profiles⁠, ⁠$tasks⁠ (long format, one row per block, task, and alternative, ready for a choice model), ⁠$balance⁠, and the declaration that produced them.

Choosing a method

"full" enumerates every combination, which is exact but grows fast: 4 attributes at 3 levels each is 81 profiles. "random" takes a seeded random subset of that size. "balanced" samples repeatedly and keeps the subset with the most even level spread and the weakest association between attributes.

"balanced" is a search, not a construction. It does not produce a catalogued orthogonal fractional factorial and does not claim the guarantees of one. The achieved balance is reported in ⁠$balance⁠ so the design can be inspected rather than trusted. A study needing a specific D-optimal or orthogonal design should generate it elsewhere and pass it in through profiles, which keeps the declaration in the contract either way.

See Also

sf_instrument()

Examples

design <- sf_conjoint_design(
  "hotel_dce",
  attributes = list(
    price    = c("50", "100", "150"),
    board    = c("room only", "breakfast"),
    distance = c("beachfront", "10 min walk")
  ),
  method = "balanced", n_profiles = 6, n_alternatives = 2, seed = 42
)
design$profiles
design$tasks

Define a latent or composite construct

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.

Examples

sq <- sf_construct("sq", "Service Quality",
                    items = c("sq_1", "sq_2", "sq_3"))
sq$mode
sq$items

Define a covariance between constructs

Description

Define a covariance between constructs

Usage

sf_covariance(from, to, label = NULL)

Arguments

Value

An object of class sf_covariance.

Examples

cov <- sf_covariance("sq", "sus", label = "cov1")
cov$from
cov$to

Get rows flagged by response-quality checks

Description

Pools failed attention checks, straight-lining, excess missingness, timing, and duplicate checks into one set of response-row positions.

Usage

sf_flagged(x, ...)

Arguments

Value

A sorted integer vector of unique response-row positions.

See Also

sf_report_accessors, quality_report()

Examples

demo <- sframe_demo_data()
qr <- quality_report(demo$responses, demo$instrument)
sf_flagged(qr)

Get an instrument component ID

Description

Reads the stable identifier used to refer to a component elsewhere in the instrument.

Usage

sf_id(x, ...)

Arguments

Value

A single character identifier.

See Also

sf_identity, sf_label()

Examples

sf_id(sf_item("q1", "Satisfaction", type = "numeric"))

The ID and label of an instrument component

Description

The ID and label of an instrument component

Value

A single character string. sf_label() returns "" when the component carries no label.

Examples

item <- sf_item("q1", "How satisfied are you?", type = "likert",
                choice_set = "agree5")
sf_id(item)
sf_label(item)

Define an indirect effect path

Description

Define an indirect effect path

Usage

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

Arguments

Value

An object of class sf_indirect.

Examples

ind <- sf_indirect("sq", through = "sat", to = "bi", label = "mediation")
ind$through

Create a survey instrument object

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(sf_plan(instr))

Test whether validation passed

Description

Reads the overall pass/fail result without inspecting validation internals.

Usage

sf_is_valid(x, ...)

Arguments

Value

A single logical value.

See Also

sf_validation_accessors, validate_sframe()

Examples

v <- validate_sframe(sframe_demo_data()$instrument, strict = FALSE)
sf_is_valid(v)

Define a survey item

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",
    "pairwise_comparison", "criteria_weight", "section_break",
    "text_block"),
  required = FALSE,
  choice_set = NULL,
  scale_id = NULL,
  reverse = FALSE,
  help = NULL,
  placeholder = NULL,
  matrix_items = NULL,
  comparison_items = NULL,
  comparison_scale = 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.")

Get survey items

Description

Returns the declared question items in instrument order.

Usage

sf_items(x, ...)

Arguments

Value

An sf_component_list for an instrument or an item data frame for a codebook.

See Also

sf_accessors

Examples

sf_items(sframe_demo_data()$instrument)

Get an instrument component label

Description

Reads the respondent- or analyst-facing label attached to a component.

Usage

sf_label(x, ...)

Arguments

Value

A single character label, or "" when none is declared.

See Also

sf_identity, sf_id()

Examples

sf_label(sf_item("q1", "Satisfaction", type = "numeric"))

Get survey metadata

Description

Reads the title, version, description, language, validation state, and other metadata without depending on the object's internal list layout.

Usage

sf_meta(x, ...)

Arguments

Value

A list of instrument or codebook metadata.

See Also

sf_accessors

Examples

sf_meta(sframe_demo_data()$instrument)

Columns the instrument declares that the responses left out

Description

A partial export gives a quality report every column it holds, and none of the ones it dropped. This names the declared columns that never arrived, so a missingness figure can be read against what was expected. They count as missing for every respondent in quality_report()'s rates.

Usage

sf_missing_columns(x, ...)

Arguments

Value

A character vector of column names, empty where the export carried every declared column.

See Also

quality_report(), sf_flagged()

Examples

demo <- sframe_demo_data()
qr   <- quality_report(demo$responses, demo$instrument)
sf_missing_columns(qr)

Create a surveyframe model specification

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.

Examples

m <- sf_model(
  "cb1", "Quality drives intention", type = "cb_sem",
  constructs = list(
    sf_construct("sq", "Service Quality", items = c("sq_1", "sq_2", "sq_3")),
    sf_construct("sat", "Satisfaction", items = c("sat_1", "sat_2")),
    sf_construct("bi", "Behavioural Intention", items = c("bi_1", "bi_2"))
  ),
  paths = list(sf_path("sq", "sat"), sf_path("sat", "bi")),
  indirect = list(sf_indirect("sq", through = "sat", to = "bi"))
)
m$type
m$engine

Get model specifications

Description

Returns declared CFA, SEM, PLS-SEM, mediation, and related model objects.

Usage

sf_models(x, ...)

Arguments

Value

An sf_component_list for an instrument or a model data frame for a codebook.

See Also

sf_accessors

Examples

sf_models(sframe_demo_data()$instrument)

Recover the validated object

Description

Returns the original object carried by a validation result, whether or not validation passed.

Usage

sf_object(x, ...)

Arguments

Value

The object held by a validation result.

See Also

sf_validation_accessors, as_sframe()

Examples

v <- validate_sframe(sframe_demo_data()$instrument, strict = FALSE)
sf_object(v)

Define a structural path between constructs

Description

Define a structural path between constructs

Usage

sf_path(from, to, label = NULL)

Arguments

Value

An object of class sf_path.

Examples

p <- sf_path("sq", "sat", label = "H1")
p$from
p$to

Get the pre-declared analysis plan

Description

Returns the ordered analysis blocks attached to an instrument or codebook.

Usage

sf_plan(x, ...)

Arguments

Value

A list of analysis blocks for an instrument or a plan data frame for a codebook.

See Also

sf_accessors, sf_plan<-

Examples

sf_plan(sframe_demo_data()$instrument)

Set the pre-declared analysis plan

Description

The replacement counterpart to sf_plan(). Declaring the plan is the step the whole workflow turns on, so it has a named function rather than assignment into the object's internals.

Usage

sf_plan(x) <- value

Arguments

Value

The updated sframe object.

See Also

sf_plan(), validate_sframe(), run_analysis_plan()

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "numeric")
instr <- sf_instrument("Demo", components = list(item))

sf_plan(instr) <- list(
  list(id = "RQ1", research_question = "What is the average?",
       family = "descriptive", method = "descriptives",
       roles = list(variables = "q1"))
)
length(sf_plan(instr))

Get validation problems

Description

Returns every actionable validation message in check order.

Usage

sf_problems(x, ...)

Arguments

Value

A character vector, empty when validation passed.

See Also

sf_validation_accessors, validate_sframe()

Examples

v <- validate_sframe(sframe_demo_data()$instrument, strict = FALSE)
sf_problems(v)

Read the reportable parts of an analysis or quality result

Description

sf_apa() returns the APA-formatted sentence a result carries. sf_flagged() returns the rows a quality report flagged.

Details

Given analysis results, sf_apa() answers for every block at once, as a character vector named by block. Given one of the standalone reports that carry a sentence of their own, an assumption report, a descriptives report, a missing-data report or a validity report, it returns that single sentence. A result with no sentence gives an empty string, so the shape of the answer follows the number of blocks asked about.

The sentence is plain text. APA 7 asks for italic Latin statistical symbols, so a manuscript needs t, F, p, r, d and the rest italicised after pasting: a character vector cannot carry that styling. Numbers are already APA-formatted, including no leading zero on p and a labelled confidence interval.

sf_flagged() returns row positions in the response data, as one sorted vector with each row once, pooling every check the quality report ran: failed attention checks, straight-lining, excess missingness, timing and duplicates. Read the report itself for which check flagged a row.

Value

sf_apa() returns a character vector: one element per block, named by block, for analysis results, and one element for a single report. sf_flagged() returns an integer vector of row positions, sorted, each row once.

Examples

demo <- sframe_demo_data()
qr <- quality_report(demo$responses, demo$instrument)
head(sf_flagged(qr))

Define a scored scale

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
)

Get survey scales

Description

Returns the scale definitions, including their item membership and scoring settings.

Usage

sf_scales(x, ...)

Arguments

Value

An sf_component_list for an instrument or a scale data frame for a codebook.

See Also

sf_accessors

Examples

sf_scales(sframe_demo_data()$instrument)

Read a validation diagnostic

Description

sf_is_valid() reports whether the object passed. sf_problems() returns the problem messages. sf_object() returns the object that was validated.

Value

sf_is_valid() returns a single logical. sf_problems() returns a character vector, empty when the object is valid. sf_object() returns the validated object.

See Also

validate_sframe(), sframe_validation, as_sframe()

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "text")
instr <- sf_instrument("Demo", components = list(item))
v <- validate_sframe(instr, strict = FALSE)

sf_is_valid(v)
sf_problems(v)

Abort with a branching error

Description

Abort with a branching error

Usage

sframe_abort_branching(message, item_id = NULL, ...)

Arguments

Abort with an import error

Description

Abort with an import error

Usage

sframe_abort_import(message, path = NULL, ...)

Arguments

Abort with a validation error

Description

Abort with a validation error

Usage

sframe_abort_validation(message, instrument_title = NULL, ...)

Arguments

Aggregate individual judgement matrices

Description

Aggregation of individual judgements (AIJ) across respondents. The element-wise geometric mean is the standard choice for reciprocal AHP matrices, because it is the only mean that preserves reciprocity: the arithmetic mean of m[a, b] and the arithmetic mean of m[b, a] are not reciprocals of each other. DEMATEL matrices are not reciprocal, so they aggregate arithmetically.

Usage

sframe_aggregate_judgements(
  matrices,
  method = c("geometric", "arithmetic"),
  cr_filter = FALSE
)

Arguments

Value

A list with matrix, method, n_respondents, n_dropped, n_dropped_consistency, and consistency (the per-respondent CR distribution, or NULL for a non-reciprocal set).

See Also

sframe_assemble_pairwise()

Examples

m1 <- matrix(c(1, 3, 1 / 3, 1), 2, 2)
m2 <- matrix(c(1, 5, 1 / 5, 1), 2, 2)
sframe_aggregate_judgements(list(m1, m2))$matrix

Write a Quarto analysis notebook for any instrument

Description

Unlike sframe_demo_qmd(), which only works for one of the bundled demo instruments (it looks name up in sframe_demos()), this writes a runnable Quarto notebook for any instrument, using its own responses. It exposes the complete ordered plan, screening, run status, detailed results, plots and reports. The notebook reads the instrument and its responses back from 2 companion files written alongside it, so all 3 files must stay together.

Usage

sframe_analysis_qmd(
  instrument,
  data,
  dir = ".",
  basename = NULL,
  overwrite = FALSE
)

Arguments

Value

A list with qmd, sframe, and csv paths, invisibly.

See Also

sframe_demo_qmd(), write_sframe(), read_responses()

Examples

item  <- sf_item("q1", "How satisfied are you?", type = "text")
instr <- sf_instrument("Demo", components = list(item))
resp  <- data.frame(q1 = c("Great", "Fine"))
out <- sframe_analysis_qmd(instr, resp, dir = tempdir())
basename(out$qmd)

Coerce a surveyframe object to a data frame

Description

Every surveyframe class returns its primary table, and each class has its own columns. Where an object holds more than one table, the others are reachable through the named accessors in sf_accessors, or, for a full tabular record of an instrument, through codebook_report().

Value

A data frame, with the columns listed above for the class given.

What each class gives

• sframe: one row per item, with id, label, type, choice_set, scale_id, reverse and required.

• sframe_codebook: one row per item, the codebook's item table.

• sframe_validation: one row per problem, with check and problem.

• sframe_analysis_results: one row per block, with block, research_question, method and apa.

• sframe_reliability_report: one row per scale, with scale_id, label, n_items, n, alpha and omega.

• sframe_item_report: one row per item, with scale_id and the item diagnostics.

• sframe_quality_report: one row per check, the flattened quality checks.

• sframe_efa_report: one row per measure, the readiness measures.

• sframe_sensitivity: one row per perturbation, with criterion, direction, weight, rho, rank_changed and top_changed.

A summary, and where the full record is

These tables are a summary of the columns a reader scans first. The item table leaves out help text, placeholder, matrix rows, comparison items and scale, slider and rating settings, date bounds, section introduction and page; the scale table leaves out min_valid, the reverse key and the weights. Read the stored declaration in full through sf_items(), sf_scales() and the rest of sf_accessors, each of which returns the component objects themselves, or through write_sframe() for the interchange record.

A class holding one table returns it directly, so it keeps that table's own row names and row.names has no effect. Pass row.names to base::as.data.frame() on the returned frame where you need to set them. The coercion gives one view of an object. An instrument, for example, returns its items, and its choice sets and scales come from sf_choice_sets(), sf_scales() or codebook_report().

See Also

sf_accessors, codebook_report()

Examples

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

as.data.frame(instr)
as.data.frame(cs)

Assemble per-respondent comparison matrices

Description

Builds one square judgement matrix per respondent from the pair columns of a "pairwise_comparison" item. A "saaty" item stores one signed integer per unordered pair, so the reciprocal half of each matrix is reconstructed here rather than stored (a collected value of +5 becomes m[a, b] = 5 and m[b, a] = 1/5, and the diagonal is 1). An "influence" item stores one unsigned integer per ordered pair, fills the directed cell only, and has a zero diagonal, because the influence of a on b says nothing about the influence of b on a.

Usage

sframe_assemble_pairwise(data, instrument, item_id)

Arguments

Details

Respondents who left any pair blank, or whose answer falls outside the declared scale, are dropped whole and counted. Completing partial matrices (the Harker approach) is deliberately out of scope.

Value

A list with matrices (a list of square numeric matrices with dimnames), n_respondents, n_dropped, dropped (a data frame of row number and reason), items, and scale.

See Also

sframe_aggregate_judgements(), sframe_collected_weights()

Examples

crits <- c("price", "speed")
study <- sf_instrument(
  title = "Demo", components = list(
    sf_item("pairs", "Compare the criteria", type = "pairwise_comparison",
            comparison_items = crits)
  )
)
responses <- data.frame(pairs__price__vs__speed = c(3, -5))
sframe_assemble_pairwise(responses, study, "pairs")$matrices[[1]]

Create an empty SurveyStudio builder state

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.

Examples

state <- sframe_builder_empty_state()
state$meta$title
length(state$items)

Convert an instrument into a SurveyStudio builder state

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.

Examples

demo <- sframe_demo_data()
state <- sframe_builder_state_from_instrument(demo$instrument)
length(state$items)
length(state$scales)

Validate a SurveyStudio draft state

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(),
  amendments = list(),
  designs = list(),
  origin = NULL
)

Arguments

Value

A list with valid, problems, instrument, and revision_problem: the reason write_sframe() would refuse the draft as an undisclosed revision, or NULL.

Examples

demo  <- sframe_demo_data()
state <- sframe_builder_state_from_instrument(demo$instrument)
draft <- sframe_builder_validate_draft(
  meta = state$meta, choices = state$choices, items = state$items,
  scales = state$scales, branching = state$branching, checks = state$checks
)
draft$valid

Enrich a codebook's items table for display

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 enrichment 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()

Examples

demo <- sframe_demo_data()
cb <- codebook_report(demo$instrument)
head(sframe_codebook_items_display(cb))

Criterion weights collected from respondents

Description

Resolves a weight vector from either kind of collected weight item, so that a ranking runner never has to know which one the researcher used. A "criteria_weight" item is renormalised to sum 1 per respondent before the arithmetic mean is taken, so a respondent who allocated 90 points in total carries the same influence as one who allocated exactly 100. A "pairwise_comparison" item is assembled, aggregated geometrically, and reduced to its principal eigenvector.

Usage

sframe_collected_weights(data, instrument, item_id, cr_filter = FALSE)

Arguments

Value

A list with weights (a named numeric vector summing to 1), criteria, source, item_id, n_respondents, n_dropped, and consistency (pairwise items only).

See Also

sframe_assemble_pairwise()

Examples

study <- sf_instrument(
  title = "Demo", components = list(
    sf_item("pts", "Divide 100 points", type = "criteria_weight",
            comparison_items = c("price", "speed"))
  )
)
sframe_collected_weights(
  data.frame(pts__price = c(60, 40), pts__speed = c(40, 60)), study, "pts"
)$weights

Normalise the decision options of an analysis-plan block

Description

A researcher-supplied performance matrix round-trips through JSON as a list of numeric row vectors with its dimnames dropped, so it is stored as options$matrix plus the options$alternatives and options$criteria label vectors and rebuilt here. Every length agreement between the matrix, its labels, the weights, and the criterion types is checked once, in one place, with the exact mismatch named.

Usage

sframe_decision_options(options)

Arguments

Value

The same list with matrix rebuilt as a numeric matrix carrying dimnames, and weights and criteria_types coerced and checked.

PROMETHEE preference functions

A PROMETHEE block takes options$preference_function, one of "usual", "linear", or "level", and options$thresholds for the 2 that need them. The default is "usual", Brans and Vincke's type I step function, which needs no thresholds and so adds no researcher degrees of freedom.

This default differs from several other MCDM implementations, which default to the linear (V-shape) function and derive its thresholds from the range of the supplied data. Deriving thresholds that way makes the result depend on choices the researcher never declared, which is what this package exists to prevent, so surveyframe requires a threshold-bearing preference function to be asked for explicitly.

The choice changes the answer. Net flows always differ between the 2 functions, and the ranking itself changed in 226 of 400 randomly drawn 4-alternative by 3-criterion matrices. So a ranking cross-checked against an implementation that defaults to "linear" will often disagree unless preference_function = "linear" is set here and the same thresholds are supplied on both sides. The preference function actually used is always named in the block's APA sentence. Note also that "usual" produces tied ranks readily, because a step function scores every non-zero difference identically.

See Also

run_analysis_plan()

Examples

sframe_decision_options(list(
  matrix = list(c(4, 210), c(3, 180)),
  alternatives = c("Alpha", "Basilica"),
  criteria = c("service", "price"),
  criteria_types = c("benefit", "cost")
))$matrix

The DEMATEL total-relation classification

Description

Normalises the direct-influence matrix X by the larger of its greatest row sum and its greatest column sum (the standard DEMATEL normalisation, which keeps the Neumann series N + N^2 + N^3 + ... convergent), then solves the total-relation matrix T = N(I - N)^-1 in closed form rather than by truncating the series. D is each criterion's row sum of T (how much it influences the others, direct and indirect combined) and R its column sum (how much it is influenced). Prominence D + R is overall involvement in the system, while relation D - R is net direction, positive for a net cause and negative or zero for a net effect. The threshold is the arithmetic mean of every entry of T: relations at or above it are considered significant enough to draw in an influence diagram.

Usage

sframe_dematel_compute(x)

Arguments

Details

The series converges only when the spectral radius of N is below 1. Normalisation keeps the radius at or below 1, and it equals 1 when criteria influence each other in a closed group with equal totals. That case returns an error explaining it, and no truncated series is substituted.

Value

A list with normalised (N), total_relation (T), D, R, prominence (D + R), relation (D - R), threshold (mean of T), and role (a character vector, "cause" where relation > 0, else "effect").

Load one bundled demo

Description

One of the 22-item teaching library: 17 analysis examples, three presentation examples, and two provenance examples. For the demo that instead exercises every input type SurveyBuilder and SurveyStudio support in a single instrument, see sframe_input_types_demo_data().

Usage

sframe_demo(name, branded = FALSE)

Arguments

Value

A list with instrument, responses, and the paths behind them: instrument_path, responses_path, codebook_path and results_path. The codebook carries variable and value labels, so the data means something outside R. The results table is what surveyframe reports for this demo, which is the reference to compare against when you run the same data through another package.

See Also

sframe_demos(), sframe_export_labelled(), sframe_input_types_demo_data()

Examples

demo <- sframe_demo("two_group")
demo$instrument
head(demo$responses)

The standard demo branding

Description

The render block sframe_demo() splices in when branded = TRUE. Read it, change a colour, and paste it into your own instrument.

Usage

sframe_demo_branding()

Value

A named list suitable for sf_instrument(render = ): the display mode, the theme colour, the submit_label, and the welcome, thankyou and header blocks.

Examples

branding <- sframe_demo_branding()
branding$welcome$title
branding$theme

Load bundled surveyframe demo data

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.

Examples

demo <- sframe_demo_data()
sf_meta(demo$instrument)$title
nrow(demo$responses)

Copy a demo's Quarto notebook so you can run and change it

Description

The code route through a demo is a notebook that renders to a report, which is what a research workflow looks like. This writes one for the named demo: load and validate the instrument and responses, inspect the complete ordered analysis plan, screen data quality, run the plan with status and plots, inspect each result and its reproducible syntax, compare the bundled expected results, render analysis and full reports, and export the data for checking elsewhere.

Usage

sframe_demo_qmd(name, dir = ".", overwrite = FALSE)

Arguments

Value

The path written, invisibly.

See Also

sframe_demo(), sframe_demos()

Examples

out <- sframe_demo_qmd("two_group", dir = tempdir())
basename(out)

List the bundled demos

Description

Every demo does one job, so a failure points at one method and a reader can hold the whole questionnaire in view. Use sframe_demo() to load one.

Usage

sframe_demos()

Value

A data frame with 1 row per demo: its name, whether its focus is analysis, presentation or provenance, what it teaches, the input fields it uses, the statistical technique it demonstrates, and the demo whose responses it reuses, if any.

See Also

sframe_demo(), sframe_demo_branding(), sframe_demo_qmd()

Examples

head(sframe_demos(), 3)
subset(sframe_demos(), focus == "provenance")

Diverging stacked bar for a single Likert item (base graphics)

Description

Base graphics only (no ggplot2 dependency), so it draws in the report's distributions section regardless of whether ggplot2 is installed, including from the Quarto report template, which runs in its own library(surveyframe) session and cannot see unexported functions. counts is a named numeric vector in scale order (names are the response labels, e.g. "Strongly disagree" .. "Strongly agree"), not sorted alphabetically or by frequency. The middle category of an odd-length scale is treated as neutral and split evenly across the zero line. An even-length scale has no neutral category. This is the standard survey-report convention (Pew Research, SurveyMonkey) for visualising an ordered agree/disagree scale, and reads in one glance which way opinion leans, unlike a plain frequency bar.

Usage

sframe_draw_likert_diverging(
  counts,
  theme_color = "#16B3B1",
  palette = c("web", "print")
)

Arguments

Details

Kept horizontal deliberately: this is the one chart in the package where the horizontal orientation is the domain convention, not an accident, and a vertical diverging stack is materially harder to read for this specific shape (see the file-level note in the roxygen docs of the ggplot2 equivalents above). Position (left of zero vs right of zero) carries the primary signal either way, so it also satisfies "do not rely on colour alone" regardless of palette. In print mode, the two poles are further distinguished by a diagonal hatch on the "disagree" side, not colour tone alone.

Value

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

See Also

sframe_plot_item_chart()

Examples

counts <- c("Strongly disagree" = 5, "Disagree" = 10, "Neutral" = 15,
            "Agree" = 40, "Strongly agree" = 30)
sframe_draw_likert_diverging(counts)

Mosaic plot for a two-way categorical result

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

Examples

instr <- sf_instrument("Crosstab demo", components = list(
  sf_item("arm", "Arm", type = "text"),
  sf_item("outcome", "Outcome", type = "text")
))
sf_plan(instr) <- list(list(
  id = "RQ1", research_question = "Does the outcome differ by arm?",
  family = "categorical", method = "chi_square",
  roles = list(row = "arm", column = "outcome")
))

responses <- data.frame(
  arm     = rep(c("control", "treatment"), each = 20),
  outcome = c(rep(c("yes", "no"), c(6, 14)), rep(c("yes", "no"), c(15, 5)))
)
res <- run_analysis_plan(responses, instr)
sframe_draw_mosaic(res$RQ1)

Write responses to SPSS or Stata with the labels attached

Description

A plain CSV carries codes. dm_1 arrives in SPSS as a column of integers with no variable label and no value labels, and the reader has to reconstruct all of it from the questionnaire. This attaches both from the instrument: the variable label is the item's label, and the value labels come from the item's choice set, which stores its values and labels side by side.

Usage

sframe_export_labelled(data, instrument, path)

Arguments

Value

The path, invisibly.

See Also

sframe_demo(), read_responses()

Examples

demo <- sframe_demo("two_group")
out <- file.path(tempdir(), "two_group.sav")
if (requireNamespace("haven", quietly = TRUE)) {
  sframe_export_labelled(demo$responses, demo$instrument, out)
}

Load the input-types demo backing SurveyBuilder and SurveyStudio

Description

Loads the bundled .sframe instrument and simulated response dataset that cover all main survey input types supported by surveyframe. This is a different demo from the 22-item teaching library behind sframe_demo(): where sframe_demo() demonstrates one analysis method per call, this one exists to exercise every input control SurveyBuilder and SurveyStudio support in a single instrument, and is what backs launch_builder_demo(), launch_studio_demo(), and launch_dashboard_demo().

Usage

sframe_input_types_demo_data()

Value

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

See Also

sframe_demo() for the 22-item teaching library instead.

Examples

demo <- sframe_input_types_demo_data()
sf_meta(demo$instrument)$title
nrow(demo$responses)

Group a scale's Likert items for a combined diverging chart

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

Examples

demo <- sframe_demo("likert_scale")
groups <- sframe_likert_scale_groups(demo$instrument)
names(groups)

Term co-occurrence heatmap

Description

Tile heatmap of pairwise within-response term co-occurrence counts for a co_occurrence result. The result's edge list (term_a, term_b, n) is pivoted into a full symmetric term-by-term grid before plotting, so each pair's tile appears twice, once on either side of the diagonal, the way the other tile heatmaps in this file (sframe_plot_correlation_matrix(), sframe_plot_efa_loadings()) read as a full grid rather than a triangle.

Usage

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

Arguments

Value

A ggplot2 object, or NULL when the result carries no table.

See Also

run_analysis_plan(), term_frequency()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("open_text")
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_cooccurrence(res$RQ4)
}

Term co-occurrence network plot

Description

Plots a co_occurrence_network result's node table (term, frequency, cluster, x, y) as a network diagram: edges (from result$edges) as line segments underneath, nodes as points sized by term frequency and coloured by Louvain cluster, with term labels on the larger points only. Labelling every point on a dense network risks overlap chaos, so only the top 15 nodes by frequency are labelled; the full term list stays available in result$table.

Usage

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

Arguments

Details

Clusters beyond the first 8 (ranked largest first) are folded into a single "Other" bucket rather than cycling or interpolating a new hue, per the dataviz skill's categorical-colour guidance; see .sframe_cluster_palette().

Value

A ggplot2 object, or NULL when the result carries no table.

See Also

run_analysis_plan()

Examples

if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("igraph", quietly = TRUE)) {
  demo <- sframe_demo("open_text")
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_cooccurrence_network(res$RQ6)
}

Correlation matrix heatmap

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  sframe_plot_correlation_matrix(demo$responses,
                                 c("sq_1", "sq_2", "sq_3", "sat_1", "sat_2"))
}

Ranked-score bar chart for a decision-family result

Description

The shared chart for every MCDM ranking method: one horizontal bar per alternative, ordered best first, with the leading alternative picked out. It is generic over the method rather than tied to one, so AHP criterion weights and any ranking method's scores all draw through it. The score column is whatever the method reports as its headline quantity (a closeness coefficient, a net flow, a priority weight), so the axis is labelled from the result rather than hard-coded.

Usage

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

Arguments

Value

A ggplot2 object, or NULL when the result carries no ranking.

See Also

run_analysis_plan()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("mcdm_choice")
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_decision_ranking(res$RQ4)
}

Prominence-relation scatter for a DEMATEL result

Description

The dedicated DEMATEL chart: one point per criterion, prominence (D + R) on x and relation (D - R) on y, with a horizontal quadrant line at relation = 0 separating causes (above) from effects (below). This is deliberately a different shape from sframe_plot_decision_ranking(): DEMATEL classifies criteria on two axes rather than producing a single ranked score, so a ranking bar chart would misrepresent it.

Usage

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

Arguments

Value

A ggplot2 object, or NULL when the result carries no DEMATEL fields to plot.

See Also

sframe_plot_decision_ranking()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("mcdm_choice")
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_dematel_influence(res$RQ3)
}

Distribution shape by variable, standardised

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  dr <- descriptives_report(demo$responses, variables = c("sat_1", "sat_2"))
  sframe_plot_descriptives(dr, demo$responses)
}

Loadings heatmap from a fitted EFA solution

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("psych", quietly = TRUE)) {
  demo <- sframe_demo_data()
  fit <- efa_solution(demo$responses, demo$instrument,
                       scales = "service_quality", nfactors = 1)
  sframe_plot_efa_loadings(fit)
}

Scree plot from an EFA readiness report

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

Examples

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

Group-comparison boxplot

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, and 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()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_group_comparison(res$rq_visit_bi, demo$responses)
}

Plot an item response distribution

Description

Draws how one item was answered, as the dashboard and SurveyStudio panels show it. It returns NULL where it has nothing to draw, so a caller can fall back to its own chart.

Usage

sframe_plot_item_chart(
  item,
  col_data,
  choice_set = NULL,
  palette = c("web", "print")
)

Arguments

Details

Shared by launch_dashboard() (inst/shiny/dashboard/app.R) and the SurveyStudio dashboard tab (inst/shiny/app.R), which otherwise duplicated this base-graphics chart. Callers fall back to their own base graphics when this returns NULL (ggplot2 not installed, unsupported item type, or no data), so the dashboard keeps working without ggplot2.

Value

A ggplot2 object, or NULL if this item type/data is unsupported.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  item <- Filter(function(i) i$id == "sat_1", demo$instrument$items)[[1]]
  cs   <- Filter(function(c) c$id == item$choice_set, demo$instrument$choices)[[1]]
  sframe_plot_item_chart(item, demo$responses$sat_1, cs)
}

Grouped diverging chart for a Likert matrix question

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("matrix_likert")
  item <- Filter(function(i) i$type == "matrix", demo$instrument$items)[[1]]
  cs   <- Filter(function(c) c$id == item$choice_set, demo$instrument$choices)[[1]]
  sframe_plot_likert_matrix(item, demo$responses, cs)
}

Grouped diverging chart for a scale's Likert items

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("likert_scale")
  groups <- sframe_likert_scale_groups(demo$instrument)
  g <- groups[["organisation"]]
  sframe_plot_likert_scale(g$items, demo$responses, g$choice_set, g$title)
}

Missing-data report plot: missingness rate by item

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  mr <- missing_data_report(demo$responses, demo$instrument)
  sframe_plot_missingness(mr)
}

N-gram-frequency plot: horizontal bar

Description

Top 20 n-grams from an ngram_freq result as a horizontal bar chart. Shares its bar-building logic with sframe_plot_term_frequency()'s bar path via the internal .sframe_plot_term_bar() helper; unlike that function, there is no word-cloud mode and no group faceting for this id.

Usage

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

Arguments

Value

A ggplot2 object, or NULL when the result carries no table.

See Also

run_analysis_plan(), ngram_frequency()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("open_text")
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_ngram_frequency(res$RQ2)
}

Paired-comparison slope plot

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_paired_comparison(res$rq_ttest_pair, demo$responses)
}

Quality report plot: straight-lining flag rate by scale

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo("likert_scale")
  qr <- quality_report(demo$responses, demo$instrument)
  sframe_plot_quality(qr)
}

Regression diagnostic plots for a regression_linear result

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  res <- run_analysis_plan(demo$responses, demo$instrument)
  panels <- sframe_plot_regression_diagnostics(res$rq_predict_sat)
  panels$residuals_fitted
}

Reliability plot: alpha and omega by scale

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

Examples

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

Scale score distribution chart, ggplot2 equivalent of the dashboard panel

Description

Same sharing rationale as sframe_plot_item_chart().

Usage

sframe_plot_scale_chart(scores, label, palette = c("web", "print"))

Arguments

Value

A ggplot2 object, or NULL if ggplot2 is unavailable or scores is empty.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  demo <- sframe_demo_data()
  scored <- score_scales(demo$responses, demo$instrument)
  sframe_plot_scale_chart(scored$satisfaction, "Satisfaction")
}

Sentiment plot: diverging bar, or a positive/negative comparison cloud

Description

A ggplot2 diverging bar for a tidy_sentiment result by default: positive counts extend one direction, negative counts the other, so bar position (not colour alone) carries the primary polarity signal, the same convention sframe_draw_likert_diverging() uses for Likert agreement (dark ramp toward the pole) rebuilt here in ggplot2 rather than called directly, since that helper is base-graphics and Likert-scale-specific. Facets by group when result$table carries a group column, mirroring sframe_plot_term_frequency()'s grouped branch.

Usage

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

Arguments

Details

When result$options$wordcloud is TRUE (opt-in, default FALSE, matching sframe_plot_term_frequency()'s own word-cloud toggle), draws a comparison cloud instead: negative-sentiment words above the centre line, positive-sentiment words below it, each word sized by how often it occurred, using the internal tidy_sentiment runner's ⁠$word_sentiment⁠ word-by-sentiment counts. Answers a different question from the diverging bar: not "how many responses leaned positive," but "which words drove that."

Value

A ggplot2 object, or NULL when the result carries no table.

See Also

run_analysis_plan(), sframe_draw_likert_diverging()

Examples

if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("tidytext", quietly = TRUE)) {
  demo <- sframe_demo("open_text")
  res <- run_analysis_plan(demo$responses, demo$instrument)
  sframe_plot_sentiment(res$RQ7)
}

Term-frequency plot: horizontal bar or word cloud

Description

Top terms from a term_freq result as a horizontal bar chart, or a word cloud when result$options$wordcloud is TRUE (opt-in, default FALSE). Facets by group when the result carries a group role (todo_text_analysis.md section 1a).

Usage