Skip to contents

Where the burden calculation is exact, and where it rests on assumptions

Source: R/calculation_certainty.R
calculation_certainty.Rd

burden_report() propagates an established item score through a survey's flow and display logic. Some of that propagation is exact (a fixed block sequence, a loop with an explicit cap); some rests on documented assumptions (the gate-independence approximation for large display-logic components, the independence of separate coupling components). This function reports the split so a reader can see which parts of the output depend on those assumptions.

Usage

calculation_certainty(
  qsf,
  scheme = gfs_scheme(),
  max_paths = 10000L,
  paths = NULL,
  scored = NULL,
  blocks = NULL,
  parsed_dl = NULL,
  max_condition_states = 10000L
)

Arguments

qsf

A path to a .qsf, or a qsf_raw object from read_qsf().

scheme

A gfs_scheme() list.

max_paths

Passed to resolve_paths().

paths, scored, blocks, parsed_dl

Optional precomputed resolve_paths(), score_burden(), resolve_live_blocks() and parsed display-logic results for this qsf (internal reuse by burden_report(); NULL computes them here, leaving the public behaviour unchanged).

max_condition_states

Maximum joint condition-state combinations enumerated in full per connected display-logic component (default 10000). Must be a positive finite whole number. Larger components use the primary-gate approximation. This is separate from max_paths and does not remove other modelling assumptions. When precomputed results are supplied, use the same limit that generated those results.

Value

An object of class calculation_certainty (list):

paths

n_full, n_exact (no unresolved display-logic conditions), n_with_unresolved, and a per_path tibble.

branches

One row per flow Branch, with the trigger variable(s). Both outcomes of every branch are always enumerated, so a branch is not an approximation – but which outcome a given respondent takes is unknown before fieldwork.

display_logic

n_conditional questions gated by an unresolved condition on some full path; n_exact scored by exact joint enumeration of their gate states; n_approx scored with the primary-gate approximation; component counts; and cross_component_independence (TRUE when >1 coupling component is convolved as independent).

loops

n_known loop blocks with an explicit iteration cap, n_unknown with a dynamic/unknown bound, and a bounds tibble.

scores

Counts of score_flag: auto (confident structural mapping), inferred (mapping needs an assumption), manual, unknown.

Details

"Exact" is used in two narrow senses here, and neither means the result matches the live survey:

  • a path counted in n_exact has no unresolved display-logic question on it (every question is always shown or ruled out);

  • a display-logic question counted in n_exact was enumerated in full: every joint state of its gates that the model represents was scored, rather than approximated.

Fidelity to the original survey's full logic is established by neither: branch conditions are not checked against each other, embedded-data conditions are treated as free, and unusual Qualtrics constructs may not be modelled at all. The breakdown describes these modelling diagnostics, not an overall certificate of correctness.

Examples

# \donttest{
qsf_path <- system.file("extdata", "demo_travel_survey.qsf",
                         package = "surveyBurden")
calculation_certainty(qsf_path)
#> 
#> ── Calculation certainty: Neighbourhood Travel Survey (demo) ───────────────────
#> 
#> ── Paths ──
#> 
#> 0 of 2 complete paths have no unresolved display-logic question; 2 carry at
#> least one.
#> 3 flow branches; both outcomes of each are enumerated, but which one a given
#> respondent takes is unknown before fieldwork:
#> FL_b_consent: trigger QID2
#> FL_b_area: trigger QID3
#> FL_b_work: trigger QID6
#> 
#> ── Display logic ──
#> 
#> Joint enumeration limit: 10000 condition states per component.
#> 6 conditional questions on some path: 6 scored by exact joint enumeration, 0
#> with the primary-gate approximation.
#> 4 coupling components (4 exact, 0 approximated).
#> Separate components are convolved as independent (assumption).
#> 
#> ── Loops ──
#> 
#> 2 loop blocks with an explicit iteration cap; 0 with a dynamic/unknown bound.
#> Other adults: 0-5 iterations
#> Vehicle details: 0-3 iterations
#> 
#> ── Item scores ──
#> 
#> 19 scored with full confidence (auto); 7 by structural inference (inferred); 0
#> need manual verification; 0 unmapped.
# }