nomo_run() coordinates the package's staged evidence workflow while
stopping at consequential researcher decisions. Evidence can be computed
automatically when doing so does not change the researcher's data or model,
but nomo_run() does not silently select factor counts, remove items,
construct a CFA model, free parameters, or respecify a model.
Usage
nomo_run(
data = NULL,
scales = NULL,
mode = c("teaching", "research"),
guidance = nomo_defaults(),
decisions = list(),
settings = list(),
resume = NULL
)Arguments
- data
A non-empty data frame or a
nomo_split()object. A split uses calibration rows for exploratory stages and validation rows for CFA, reliability, validity, and invariance. A network branch receives the split object so the same prespecified network can be evaluated across calibration and validation samples.- scales
A non-empty named list. Each element is a character vector of candidate item-column names for one scale/construct, at least three per scale, since factor-retention evidence needs three. May also be a handoff from
contentvalidR'scontent_handoff(), whose carried items and construct mapping then define the scales, as described fornomo_screen(). A handoff from a review with no construct mapping is refused, because a guided run needs scales and nomologR does not invent them.- mode
Presentation mode:
"teaching"or"research". Mode changes presentation, not statistical behavior.- guidance
Guidance settings from
nomo_defaults().auto_deleteandauto_respecifycannot beTRUE, since nomologR never deletes an item or respecifies a model.- decisions
Named list of explicit researcher decisions. Decisions may be supplied one pause at a time or all at once for a fully prespecified one-call run. A structured decision can be written as
list(value = ..., rationale = "...").- settings
Named list of stage-specific argument lists. Examples include
list(factors = list(n_iter = 200, seed = 2026)),list(invariance = list(group = "group")), orlist(network = list(hypotheses = h)). Pipeline-controlled arguments such as component data/model inputs cannot be overridden throughsettings.settings$invariance$groupmust name a column of the data the confirmatory stages use. When resuming, settings for future stages may be supplied without recomputing completed stages.list(screen = list(effort = TRUE))adds careless-responding indices (seenomo_screen()). They describe a respondent across the whole instrument, and even-odd consistency cannot be computed within one scale. So they are computed once, over every item in the run with the run's scales, and never inside the per-scale item audits.reverse,scale_range,pair_magnitude, andscalesmay be given alongsideeffort.reverseandscale_rangealso reach the per-scale item audits, with or withouteffort, andreversemust name items in the run's scales. When the scales came from acontentvalidRhandoff, each ofreverseandscale_rangeis taken from its declared keying unless given here, as innomo_screen(); giving one replaces only that one. The decision log records a declared value replaced, or a response scale the handoff did not record supplied here.The invariance and network stages refit the measurement model with the CFA stage's
ordered,estimator, andmissingfromsettings$cfa, unlesssettings$invarianceorsettings$networknames its own (NULLfor the default). The decision log records what was inherited and any value that differs from the CFA's.Two further requests attach evidence to the measurement model:
list(scores = list(method = "sum"))scores it withnomo_scores(), using a method the researcher names; nomologR does not choose one.list(missing = list())compares missing-data strategies withnomo_missing().strategies, lavaanmissingoptions such as"listwise"or"ml", andreliabilitymay be given. The comparison covers the network too when one is requested.
Both run after convergent and discriminant evidence, so they are in view when the researcher decides whether to carry the model forward. Neither is a stage of its own. Requested evidence that cannot be computed is recorded in the design log, and the workflow continues, since no later stage depends on it.
- resume
Optional prior
nomo_runobject. When supplied, the existing source data, scales, guidance, completed component results, decisions, and provenance are reused.
Value
A nomo_run object. The fields to read are:
statusandnext_stage: where the run is.results: each component's result, by stage and then by scale; for exampleresults$screen$Agencyis anomo_screenobject.stage_status: one row per stage.decision_requests: the decisions the run is waiting for.decision_log: the workflow's own log, one row per design choice, decision, or recorded event, with the columnsid,stage,scope,observation,reason,options,consequence,decision,rationale, andsource.sourceis"researcher_input"(given in the call, such as the scales or a setting),"researcher_decision"(a decision at a pause, or a revision),"content_review"(from acontentvalidRhandoff), or"pipeline"(recorded by the workflow). These columns differ from those of the components' decision logs, whichnomo_table(x, "component_log")returns with their own columns.scales,mode,sample_design,sample_n,decisions, andsettings.
print() shows where the run is, one line of key evidence per component,
and the decision the run waits for or why it is blocked. summary() adds
every stage, the scales, the recorded decisions, the component recipe,
the methods used, and each flag the components raised.
nomo_table() returns the run's tables, including the component recipe,
the settings with their values, the component decision logs, and the
revision lineage. Other fields hold
the source data and state needed to resume or revise the run. They may
change between releases and are not part of the stable interface (see
?nomologR).
Details
The guided workflow is resumable. Completed component objects are retained
rather than recomputed. Future-stage settings may be added or revised until
that stage runs. Settings given when resuming are merged argument by
argument: a named argument is added or replaces the earlier value, the
others keep theirs, and the decision log records the change. Settings are
locked for a stage that has completed or blocked, for an invariance or
network branch a completed run marked not requested, and for scores and
missing once the CFA has been fitted, since they would never run; a new
nomo_run() is then the way to request them. At the pause after a
"revise" decision, settings for invariance, the network, scores, or
missing may still be given when this run has not computed that evidence:
nomo_revise() carries the settings into the revision, which runs it.
Consequential decisions are currently:
factor_count: the EFA factor count for each named scale;cfa_model: the prespecified confirmatory measurement model;measurement_model:"proceed"or"revise"after reviewing CFA, reliability, and convergent/discriminant evidence.
Optional invariance and nomological-network branches are requested explicitly
through settings$invariance and settings$network. A network branch must
include a nomo_hypotheses object. Invariance diagnostics never free
parameters automatically, and network results never collapse to a one-number
validity score.
References
Boateng, G. O., Neilands, T. B., Frongillo, E. A., Melgar-Quiñonez, H. R., & Young, S. L. (2018). Best practices for developing and validating scales for health, social, and behavioral research: A primer. Frontiers in Public Health, 6, 149. doi:10.3389/fpubh.2018.00149
Clark, L. A., & Watson, D. (1995). Constructing validity: Basic issues in objective scale development. Psychological Assessment, 7(3), 309-319. doi:10.1037/1040-3590.7.3.309
Flake, J. K., & Fried, E. I. (2020). Measurement schmeasurement: Questionable measurement practices and how to avoid them. Advances in Methods and Practices in Psychological Science, 3(4), 456-465. doi:10.1177/2515245920952393
Flake, J. K., Pek, J., & Hehman, E. (2017). Construct validation in social and personality research: Current practice and recommendations. Social Psychological and Personality Science, 8(4), 370-378. doi:10.1177/1948550617693063
Hinkin, T. R. (1998). A brief tutorial on the development of measures for use in survey questionnaires. Organizational Research Methods, 1(1), 104-121. doi:10.1177/109442819800100106
Simmons, J. P., Nelson, L. D., & Simonsohn, U. (2011). False-positive psychology: Undisclosed flexibility in data collection and analysis allows presenting anything as significant. Psychological Science, 22(11), 1359-1366. doi:10.1177/0956797611417632
Examples
scales <- list(
Agency = c("ag1", "ag2", "ag3", "ag4"),
Persistence = c("pe1", "pe2", "pe3", "pe4")
)
# Evidence is computed, then the run pauses for the factor-count decision.
run <- nomo_run(
data = nomo_demo_network,
scales = scales,
settings = list(factors = list(n_iter = 20, seed = 2026))
)
run
#> <nomo_run> Guided workflow
#> Status: Paused | Mode: teaching | Sample design: same sample
#> Exploratory cases: 800 | Confirmatory cases: 800 | Scales: 2
#> Completed: screen -> factors | Next: EFA
#>
#> Key evidence
#> - Item audit: 8 items; flags: none
#> - Parallel analysis suggests: Agency 1, Persistence 1
#>
#> Researcher decision required on the factor counts
#> Reason: The EFA factor count changes the fitted model. Retention evidence
#> can inform that choice, but it does not authorize the pipeline to choose for
#> the researcher.
#> Options: Inspect the full `nomo_factors` result, compare plausible
#> neighboring solutions when appropriate, and supply a positive integer for
#> each scale.
#> Consequence: No EFA is fitted until an explicit researcher factor-count
#> decision is supplied.
#> - Agency: Parallel analysis currently suggests 1 factor; the retained
#> plausible set is 1. The pipeline has not adopted a factor count.
#> - Persistence: Parallel analysis currently suggests 1 factor; the retained
#> plausible set is 1. The pipeline has not adopted a factor count.
#> Example: decisions = list(factor_count = c(Agency = <integer>,
#> Persistence = <integer>))
#>
#> No later stage has been run automatically while this consequential decision is
#> unresolved.
#>
#> EFA = exploratory factor analysis.
#>
#> See summary(x) for the stages and recorded decisions and
#> nomo_table(x, "requests") for the decision requests.
nomo_table(run, "requests")
#> # A tibble: 2 × 8
#> id stage scope observation reason options consequence example
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 factor_count:Agency efa Agen… Parallel a… The E… Inspec… No EFA is … decisi…
#> 2 factor_count:Persi… efa Pers… Parallel a… The E… Inspec… No EFA is … decisi…
# \donttest{
# Each decision resumes the run, which computes the next evidence and pauses
# again.
run <- nomo_run(
resume = run,
decisions = list(
factor_count = list(
value = c(Agency = 1, Persistence = 1),
rationale = "Each scale was written to measure one construct."
)
)
)
run <- nomo_run(
resume = run,
decisions = list(
cfa_model = list(
value = "Agency =~ ag1 + ag2 + ag3 + ag4; Persistence =~ pe1 + pe2 + pe3 + pe4",
rationale = "Prespecified two-construct measurement model."
)
)
)
run <- nomo_run(
resume = run,
decisions = list(
measurement_model = list(
value = "proceed",
rationale = "Measurement evidence reviewed before downstream analyses."
)
)
)
nomo_table(run, "stages")
#> # A tibble: 8 × 3
#> stage status detail
#> <chr> <chr> <chr>
#> 1 screen completed Candidate items audited exactly as supplied; no dat…
#> 2 factors completed Factor-retention evidence computed; no factor count…
#> 3 efa completed EFA fitted using explicit researcher factor-count d…
#> 4 cfa completed Researcher-specified CFA estimated; the model was n…
#> 5 reliability completed Reliability evidence computed from the retained CFA…
#> 6 validity completed Convergent/discriminant evidence computed; no valid…
#> 7 invariance not_requested Measurement invariance was not requested in this wo…
#> 8 network not_requested A theory-specified nomological network was not requ…
# }