nomologR: Guided scale development and construct validation
Source:R/utils-aaa.R
nomologR-package.RdnomologR coordinates established psychometric and structural-equation
modeling tools while adding evidence-guided diagnostics, transparent
decision logging, and teaching-oriented interpretation.
Details
The package follows a measurement-first philosophy: understand the item set and measurement model before interpreting a theory-specified structural network. Numerical reference values are prompts for investigation rather than universal deletion or validity rules.
print() shows a result's main evidence and any flags and ends with a
pointer to where to look next; summary() shows the full evidence, with the
reason for every flag.
Stability and deprecation
From version 0.3.0, the first release submitted to CRAN, the public interface changes only after a deprecation period. Code written against one release keeps working in the next.
What is covered. The interface is:
the exported functions;
their documented arguments and defaults;
the documented fields of the objects they return;
the
typevaluesnomo_table()accepts;the columns of decision logs. Each analysis's decision log has the columns
stage,object,metric,value,reference,severity,observation,recommendation,decision, andrationale; the guided workflow keeps its own log, described innomo_run().
Functions reached only with :::, undocumented fields, the wording of
decision-log rows, and the layout of rendered reports are not covered.
Names and values that differ from one table to another are covered as they
stand; Conventions in returned tables below sets them out.
Deprecation before removal. A breaking change is deprecated for at least one minor release before it takes effect. Breaking changes include removing or renaming any part of the interface, or changing a default in a way that changes results. While deprecated, the function or argument keeps working, warns once per session naming its replacement, and is listed in NEWS.
What is not breaking. Any release may add new functions, new arguments whose defaults leave results unchanged, new fields in returned objects, or new decision-log rows. Address fields by name, not position.
APA formatting. The type values of nomo_apa_table() and the structure
of the object it returns are covered. The formatting of a table, meaning its
headings, number formats, and notes, may still be corrected where it departs
from APA style, with the correction described in NEWS.
Experimental. Two functions remain experimental after 1.0.0. They may change during 1.x without a deprecation period, with each change described in NEWS:
nomo_method_variance(). Its output may be reorganized as the marker technique is extended beyond continuous indicators.nomo_power_simulate(). The metric of its estimates and its summaries may be refined as it is extended beyond complete continuous data.
The contentvalidR handoff. The exchange object is versioned by its
producer. Within a schema version, fields are only added, and nomologR
ignores fields it does not know. Anything else is a new schema version,
agreed with contentvalidR. nomologR refuses a schema version it does not
read, naming both package versions.
Conventions in returned tables
A few names and values differ from one table to another. They are part of the interface described above and are kept as they are, so they are set out here.
Proportions and percentages. A column named pct_* holds a proportion
between 0 and 1, not a percentage, although printed output shows it as a
percentage: pct_missing in the item_summary and case_summary of
nomo_screen() and in the variables table of nomo_missing(),
pct_incomplete in the pattern table of nomo_missing(), and
pct_dropped in the sample_summary of nomo_cfa(). Columns named
*_prop or proportion_* are proportions too. The one percentage is
percent_unique in the item_summary of nomo_screen(), the number of
distinct responses as a percentage (0 to 100) of the observed responses,
which is the scale of the near-zero-variance rule. Its reference in
nomo_defaults(), nzv_percent_unique_reference, is a percentage as well.
Flags. A stored flag uses one of three vocabularies:
Loading tables.
attentionin theitem_summaryofnomo_efa()and in thestandardized_loadingsofnomo_cfa()andnomo_validity()is"KEEP","REVIEW", or"STRONG REVIEW".The item review of
summary.nomo_screen().attentionis"none","review", or"concern".Decision logs and other evidence.
severityin each analysis's decision log and in theheywoodtable ofnomo_cfa(), and theattention,measurement_attention, andsignalcolumns of the other evidence tables, are"info","review", or"concern". An evidence table may also mark a value that could not be computed as"unavailable", as thefit_evidenceofnomo_cfa()does.
The three describe the same levels. Printed output, plots, and reports show
them in one wording: no flag for "KEEP", "none", and "info"; "review"
for "REVIEW" and "review"; "concern" for "STRONG REVIEW" and
"concern"; and "not computed" for "unavailable". The stored values do
not change, so code that filters a table uses that table's own values.
Status words shared with contentvalidR below relates these words to
that package's.
p values and fit indices. A p value is named p_value, or
<model>_p_value where a table holds one for each model. Three kinds of
table differ:
lavaan's parameter tables,parameter_estimatesandstandardized_solution, keeplavaan's name,pvalue.The
modelstables ofnomo_esem(),nomo_method_variance(), andnomo_compare(), and thefit_evidenceofnomo_invariance()andnomo_network(), name the fit indices they hold aslavaan::fitMeasures()does:chisq,df,pvalue,cfi,tli,rmsea,srmr,aic, andbic. Innomo_invariance(), the likelihood-ratio test against the level before islrt_chisq,lrt_df, andlrt_p.The
fit_evidenceofnomo_cfa()is long, one row per index named inmetric. It and thefittable ofnomo_missing()spell the indiceschi_square,df,p_value,CFI,TLI,RMSEA, andSRMR.
The Fit tables section of nomo_table() names the index columns of
each fit table.
Status words shared with contentvalidR
nomologR and contentvalidR, which reviews item content before the
analyses here, show status in words that correspond, so an item can be
followed from one package to the other:
contentvalidR | nomologR |
| Supported | no flag |
| Review | review |
| (no counterpart) | concern |
| Insufficient data | not computed |
| Descriptive only | note |
In both, "review" means look at the item again, never delete it.
The field recommendation means different things in the two packages. In
a nomologR decision log it is prose advice about what to examine next; in
contentvalidR's results and handoff it is a decision word.