Run a pre-planned analysis from an instrument's analysis plan
Source:R/analysis_plan.R
run_analysis_plan.RdExecutes 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
- data
A
tibbleordata.frameof responses, typically produced byread_responses()orread_sheet_responses().- instrument
An
sframeobject containing ananalysis_plan.- scored
Logical. Whether to automatically score scales before running the analysis. Defaults to
TRUE.- plots
Logical. When
TRUEand ggplot2 is installed, supported blocks gain a$plotelement holding a brand-styled ggplot object: bar charts for frequency and chi-square blocks, scatter plots with a regression overlay for correlation and linear-regression blocks. Defaults toFALSE.- plot_palette
One of
"web"(brand colours, for on-screen use) or"print"(black, grey, and white, for journal-ready print figures). Applied to every plot attached whenplots = TRUE. Seesframe_brand().- seed
Integer or
NULL. The random seed the analysis runs under. Defaults to a fixed value so the same instrument and the same data give the same answer every time, which is what makes a rendered report usable as an audit artefact. Every bootstrap confidence interval in the plan, and the parallel analysis behind the EFA family, depend on it. PassNULLfor the unseeded behaviour of releases before 0.4.1. Each block's stream starts from this seed and the block's id, so a block gives the same interval whatever blocks come before it. The caller's own random stream is restored afterwards, so seeding here does not affect anything that runs later.- strict
Logical. When
TRUE, an error is raised if any block fails or scale scoring fails, listing each failure. WhenFALSE, the default, failures are kept in the results and counted in theirstatus.
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 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.
Cross-tabulations
A crosstab or chi_square block's result carries $totals, the
counts with a Total row and column. Set options = list(percent = "row"),
"column" or "total" for $percent_table, the percentages over that
denominator. The Total row of row percentages is the column distribution,
and the Total column of column percentages is the row distribution. The
report then shows each count with its percentage beside it, and the chart
draws the percentages.
Weights
A frequency, descriptives, cross-tabulation or chi-square block may name a
case-weight column in its weights role. A design weight is set by the
researcher, not asked of respondents, so it may be a column that is not an
item: validate_sframe() notes it, and it must then be in the responses,
read with read_responses(meta_cols = ). A block whose weight column is
missing, or holds a negative, non-finite or non-numeric value, fails with
a message saying so.
How answers are coded
Categories follow 1 order in every locale: the codes of the item's choice set as the instrument declares them, then factor levels, then any other value, numbers by value and other text in code point order. A category nobody chose is dropped before a model is fitted.
McNemar's test lays both items out on that order, so each category is paired with itself. 2 items with different choice sets are refused.
An ordinal logistic outcome is ordered as its choice set declares. The result's
$outcome_levelsand its sentence give the order.In every model (linear, binary, ordinal, multinomial and Firth logistic regression, and the ANCOVA covariates) a
single_choiceormultiple_choiceitem enters as a category, with 1 indicator term per category after the first, whatever its codes look like. The first category with answers is the reference. The result's$predictor_codinglists each categorical predictor's levels, and the sentence names each reference category.A binary or Firth logistic model gives the odds of its event, the last category of its outcome in that order (1 of 0 and 1, the last declared code of a choice set).
options = list(event = "yes")names another. The result's$eventand$reference_level, and its sentence, name both. A multinomial model's reference is the first category.
See also
render_results(), read_sheet_responses()
Other Analyse functions:
score_scales(),
sframe_assumption_results(),
sframe_descriptives_results(),
sframe_efa_readiness_results(),
sframe_efa_solution(),
sframe_item_results(),
sframe_posthoc_results(),
sframe_reliability_results(),
sframe_validity_results()
Examples
instr <- read_sframe(
system.file("extdata", "demos", "two_group.sframe",
package = "surveyframe")
)
responses <- read_responses(
system.file("extdata", "demos", "two_group_responses.csv",
package = "surveyframe"),
instr,
respondent_id = "respondent_id",
submitted_at = "submitted_at",
meta_cols = "started_at"
)
# \donttest{
results <- run_analysis_plan(responses, instr)
print(results)
# }