Package 'surveyframe'

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 [email protected] (ORCID)

Authors:

• Mohammed Ali Sharafuddin [email protected] (ORCID)

See Also

Useful links:

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

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

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

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)

Description

Attaches sf_reference() records to an instrument. A reference whose id is already present replaces the old one when replace = TRUE, and is refused otherwise, which keeps a second source from silently taking over a citation key. cited_by targets of a replaced reference are merged.

Usage

add_references(instrument, ..., replace = FALSE)

Arguments

Details

Adding references changes the file hash, as any edit does, and leaves the content hash that amend_sframe() records unchanged: citing a source is disclosure, outside the design.

Value

The instrument, with the references added.

Examples

instr <- sf_instrument("Demo", components = list(
  sf_item("q1", "How satisfied are you?", "likert", choice_set = "agree5"),
  sf_choices("agree5", 1:5, c("SD", "D", "N", "A", "SA"))
))
instr <- add_references(instr, sf_reference(
  "likert_1932", "A technique for the measurement of attitudes",
  author = "Likert, R.", year = 1932, container = "Archives of Psychology",
  volume = "22", issue = "140", pages = "1-55", cited_by = "item:q1"
))
length(sframe_references(instr))

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, amendments and references 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.

Wording on the participant's screens

The welcome, consent and thank-you wording lives in render, and both hashes cover render, so editing that wording changes the instrument as much as editing an item does. On a published instrument, record it as a pipeline-tier amendment with reason_code = "other" and a reason_text saying what was reworded, then write the file with write_sframe(). This is the intended path for a host that lets researchers edit these screens. A file whose JSON is edited directly fails read_sframe()'s hash check.

revised <- instrument
revised$render$welcome$consent_text <- "I agree to take part."
revised <- amend_sframe(instrument, revised, "other",
                        "Consent wording shortened", tier = "pipeline")
write_sframe(revised, "study.sframe", overwrite = TRUE)

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

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)

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

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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)

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)

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)

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]

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, scales_table, plan_table, models_table and format, and with format = "md", markdown: one character string holding the whole codebook as Markdown, with a pipe table per component. Save it with writeLines(cb$markdown, "codebook.md"). With "html", print() shows a compact summary, and render_report() includes 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)
md <- codebook_report(instr, format = "md")
cat(substr(md$markdown, 1, 200))
nrow(sf_items(cb))
nrow(sf_scales(cb))

Description

Percentile bootstrap for the standardised mean difference between two independent groups. The difference is signed, the mean of x minus the mean of y, so the interval can include zero. 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)

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)

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

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

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
}

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)

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)

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)

Description

Generates a single HTML file that presents the survey instrument in a browser by itself, offline, with the Shiny server left out. 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 reads back none of the reply to 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.

For a host page: confirmed delivery, restarts and drafts

While a response is being sent, the survey shows a sending screen. A host that can confirm delivery, such as a platform embedding the survey, defines window.sframeSendResponse(row) in the page before the survey script runs. The survey then hands each response to that function in place of its own POST. It returns a Promise: resolving to true, or to {confirmed: true}, shows the response as recorded. Resolving to anything else shows it as sent and unconfirmed, and a rejection shows the failure screen with a retry.

The thank-you screen states delivery itself, one line for each outcome: recorded, sent but unconfirmed, not sent, or failed. Write render$thankyou$message as thanks, a debrief or contact details, and do not state delivery in it. It appears below the status line in every case except a failed send, and defaults to "Thank you for participating."

Two settings in the instrument's render block suit a host too. render$thankyou$show_restart = FALSE hides "Submit another response". render$save_draft = TRUE keeps the answers in the browser's local storage as the respondent goes, under a key drawn from the instrument's content, so a respondent who closes the tab is offered to resume on return. The draft is cleared once the response is submitted, and kept when delivery fails.

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

See Also

launch_studio(), launch_builder(), render_survey()

Examples

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

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


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

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

Description

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
}

Description

Format an sf_branch object as a string

Usage

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

Arguments

Value

A single character string.

Description

Format an sf_check object as a string

Usage

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

Arguments

Value

A single character string.

Description

Format an sf_choices object as a string

Usage

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

Arguments

Value

A single character string.

Description

Format an sf_item object as a string

Usage

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

Arguments

Value

A single character string.

Description

Format an sf_model object as a string

Usage

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

Arguments

Value

A single character string.

Description

Format an sf_scale object as a string

Usage

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

Arguments

Value

A single character string.

Description

Format an sframe instrument object as a string

Usage

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

Arguments

Value

A single character string.

Description

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

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)

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)

Description

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

Usage

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

Arguments

Details

Overview

Response count, date range, and instrument metadata.

Items

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

Scales

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

Quality

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

Raw data

Scrollable response table with a CSV download button.

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

Value

Called for its side effect. Returns nothing.

See Also

run_analysis_plan(), quality_report(), score_scales()

Examples

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

# Open the dashboard with your own instrument and responses
instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)
launch_dashboard(instr, responses)

## End(Not run)

Description

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

Usage

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

Arguments

Value

Called for its side effect.

Examples

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

## End(Not run)

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)

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)

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

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

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

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

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

Description

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

Usage

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

Arguments

Value

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

Examples

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

Description

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

Usage

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

Arguments

Value

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

Description

Post-hoc and pairwise comparison report

Usage

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

Arguments

Value

An object of class sframe_posthoc_report.

Examples

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

Description

Loads a bundled demo with the standard branding and opens it as a respondent would see it, either as a standalone page in the browser or on SurveyStudio's preview screen. The preview has its collector removed, so trying it is safe.

Usage

preview_demo(
  name = "two_group",
  where = c("browser", "studio"),
  open = interactive()
)

Arguments

Value

For "browser", the path of the HTML page, invisibly. For "studio", what launch_studio() returns.

See Also

sframe_demo(), export_static_survey(), launch_studio()

Examples

path <- preview_demo("two_group", open = FALSE)
file.exists(path)

Description

Print an sf_branch object

Usage

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

Arguments

Value

x, invisibly.

Examples

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

Description

Print an sf_check object

Usage

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

Arguments

Value

x, invisibly.

Examples

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

Description

Print an sf_choices object

Usage

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

Arguments

Value

x, invisibly.

Examples

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

Description

Print an sf_item object

Usage

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

Arguments

Value

x, invisibly.

Examples

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

Description

Print an sf_model object

Usage

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

Arguments

Value

x, invisibly.

Description

Print an sf_scale object

Usage

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

Arguments

Value

x, invisibly.

Examples

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

Description

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

Usage

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

Arguments

Value

x, invisibly.

Examples

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

Description

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

Usage

quality_report(
  data,
  instrument,
  respondent_id = NULL,
  submitted_at = NULL,
  started_at = NULL,
  time_min = NULL,
  straightline_scales = TRUE,
  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)

Description

Parses BibTeX, the format Google Scholar, Zotero, Mendeley and most journal pages export, into sf_reference() records. Covers the common entry types (⁠@article⁠, ⁠@book⁠, ⁠@incollection⁠, ⁠@inbook⁠, ⁠@inproceedings⁠, ⁠@techreport⁠, ⁠@phdthesis⁠, ⁠@mastersthesis⁠, ⁠@misc⁠, ⁠@online⁠, ⁠@software⁠, ⁠@dataset⁠, ⁠@unpublished⁠) and the common fields. Accented letters written as LaTeX commands are converted. Base R alone.

Usage

read_bibtex(file = NULL, text = NULL, cited_by = NULL)

Arguments

Value

A list of sf_reference objects, named by citation key. An entry that fails to parse is skipped with a warning naming it. A key used by more than one entry is an error that names every repeated key. Entries may be written ⁠@article{key, ...}⁠ or ⁠@article(key, ...)⁠.

Examples

refs <- read_bibtex(text = "@article{cronbach_1951,
  author  = {Cronbach, Lee J.},
  title   = {Coefficient alpha and the internal structure of tests},
  journal = {Psychometrika},
  year    = {1951},
  volume  = {16},
  number  = {3},
  pages   = {297--334}
}")
names(refs)

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,
  delim = NULL
)

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

Description

Reads a .sframe JSON file, or the same JSON held as text, and reconstructs an sframe instrument object. The SHA-256 integrity hash is verified by default, and content that 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 = NULL, validate = TRUE, text = NULL, verify = 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.

Unverified reads

verify = FALSE is for a host holding a payload it cannot vouch for, which it would otherwise rebuild by hand and lose fields doing so. The result carries the attribute sframe_verified, FALSE (it is TRUE on every verified read), and print() says so. write_sframe() refuses to write an unverified instrument unless new_instrument = TRUE declares it new, since nothing ties its content to a state anyone wrote. The exception is one written back unchanged with the amendment log it was read with. No amendment can start from it: amend_sframe() refuses it, and the write refuses any entry appended to its log.

See Also

write_sframe(), validate_sframe()

Examples

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

Description

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

Usage

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

Arguments

Value

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

See Also

export_google_sheet(), read_responses(), quality_report()

Examples

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

## End(Not run)

Description

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

Usage

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

Arguments

Value

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

See Also

sf_scale(), item_report()

Examples

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

Description

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

Usage

render_report(
  instrument,
  data = NULL,
  output_file = NULL,
  output_path = NULL,
  format = c("html", "pdf"),
  include_quality = TRUE,
  include_reliability = TRUE,
  include_codebook = TRUE,
  include_missing = TRUE,
  include_descriptives = TRUE,
  include_analysis = TRUE,
  include_models = TRUE,
  plot_palette = c("web", "print"),
  interpretations = NULL,
  show_code = TRUE,
  references = NULL,
  csl = NULL,
  title = NULL,
  authors = NULL,
  figures = getOption("surveyframe.figures"),
  figure_dir = NULL,
  open = interactive()
)

Arguments

Value

The output file path, invisibly.

References

The Quarto report cites in text, author and year, and lists every work it cites once, in a References section at the end, formatted by pandoc's citation processor in the chosen style. That covers the methods' own references, the sources the instrument cites for its items, scales, plan blocks and models, and references. The built-in HTML engine, used when Quarto is unavailable, lists the methods' references the same way.

See Also

codebook_report(), quality_report(), reliability_report()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)

old <- options(surveyframe.use_quarto = FALSE)
out <- tryCatch(
  render_report(
    instr,
    data = responses,
    output_file = tempfile(fileext = ".html"),
    include_reliability = FALSE,
    include_analysis = FALSE
  ),
  finally = options(old)
)
file.exists(out)

Description

Takes one result from run_analysis_plan() and returns what the report shows for it: the formatted table with its caption and note, any second table sframe_result_supplement() gives, the APA line, and the chart the report picks for that method, with the instrument's labels. The table, the chart and their choice per method come from the code render_report() uses, so a host rendering results one at a time and the report agree.

Usage

render_result(
  result,
  data,
  instrument = NULL,
  palette = c("web", "print"),
  format = c("html", "png", "svg"),
  width = 7,
  height = 4.5,
  dpi = 150
)

Arguments

Value

A list with block_id, test, caption, apa, table (a data frame), note, supplement (a list with table and caption, or NULL), chart (a ggplot, or NULL where the method has none or ggplot2 is absent), html (the fragment, for format = "html"), chart_file (for "png" and "svg") and syntax where the result has one. A result that failed carries its error, and html shows it.

See Also

run_analysis_plan(), render_report(), sframe_save_figures()

Examples

d <- sframe_demo("two_group")
res <- run_analysis_plan(d$responses, d$instrument)
out <- render_result(res[[1]], d$responses, d$instrument)
out$caption
out$table

Description

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

Usage

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

Arguments

Value

The output file path, invisibly.

See Also

run_analysis_plan(), render_report()

Examples

instr <- read_sframe(
  system.file("extdata", "tourism_services_demo.sframe",
              package = "surveyframe")
)
responses <- read_responses(
  system.file("extdata", "tourism_services_responses.csv",
              package = "surveyframe"),
  instr,
  respondent_id = "respondent_id",
  submitted_at = "submitted_at",
  meta_cols = "started_at"
)

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

Description

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

Usage

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

Arguments

Value

A shiny.appobj.

See Also

launch_studio(), read_responses()

Examples

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

Description

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

Usage

run_analysis_plan(
  data,
  instrument,
  scored = TRUE,
  plots = FALSE,
  plot_palette = c("web", "print"),
  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)

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

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