Package 'PsychoMatic'

Automated CFA with psychometric reporting

Description

Runs a confirmatory factor analysis with heuristic estimator selection, multivariate normality diagnostics, fit indices, reliability estimates, and model respecification suggestions. lavaan performs the model fit. When installed, MVN supplies the raw Mardia diagnostic used by automatic estimator selection and semTools supplies composite reliability and AVE. Their absence is recorded explicitly and does not prevent the CFA from being fitted; when normality cannot be evaluated, automatic selection conservatively uses MLR for continuous data. Fit indices retain their base, scaled, and robust values, and the effective variant is identified separately for every index.

Usage

cfa_auto(
  data,
  model,
  ordered = NULL,
  estimator = NULL,
  std.lv = FALSE,
  mi_threshold = 10,
  n_mi = 10,
  alpha_norm = 0.05,
  language = "eng",
  bifactor_orthogonal = TRUE,
  digits = 3,
  report = FALSE,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE,
  fit_variant = c("scaled", "robust", "base")
)

Arguments

data	Data frame containing the observed variables.
model	Model syntax written for lavaan.
ordered	Optional vector indicating which items should be treated as ordinal.
estimator	Optional estimator. If NULL, the function selects one automatically.
std.lv	Whether latent variables should be standardized.
mi_threshold	Minimum threshold for reporting modification indices.
n_mi	Maximum number of modification indices to display.
alpha_norm	Alpha level used when evaluating multivariate normality.
language	Report language: "esp" or "eng".
bifactor_orthogonal	Logical scalar used only for detected bifactor models. The default preserves the historical orthogonal bifactor fit; set FALSE only when latent-factor correlations are substantively intended.
digits	Decimal places in console and reports; stored values keep full precision.
report	If TRUE, also save a reader-facing report.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.
fit_variant	Preferred fit-index variant: "scaled" (default), "robust", or "base". Unavailable requested indices fall back to scaled then base. Base, scaled and robust estimates remain available in the result.

Value

An object of classes cfa_auto and psychomatic_result. The fitted lavaan object is available in fit; reusable tidy tables are available in tables, fit_indices, loadings_table, and reliability_table. warnings is a structured data frame with condition metadata; warnings_list is the transitional character-vector view retained for code written for PsychoMatic 0.3.x.

Compatibility

Since PsychoMatic 1.0.0, use result$warnings for programmatic inspection of warning sources and messages. Existing code that expects a character vector can migrate to result$warnings_list; this compatibility alias will be retained through a deprecation cycle. For example, warning_messages <- result$warnings_list replaces code that previously treated result$warnings as character data.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
model <- "F1 =~ R1 + R2 + R3 + R4"
cfa_auto(MY_DATA, model = model)

## End(Not run)

---

Compare alternative CFA models

Description

Fits a named set of lavaan CFA models and returns a compact comparison table. The recommendation is descriptive only and favors converged models with stronger comparative fit indices. Information criteria are reported when available, but they are not required and are not used for WLSMV-style categorical estimators.

Usage

compare_models_auto(
  data,
  models,
  ordered = NULL,
  estimator = NULL,
  language = c("eng", "esp"),
  digits = 3,
  report = FALSE,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE,
  fit_variant = c("scaled", "robust", "base")
)

Arguments

data	Data frame containing observed variables.
models	Named list or named character vector of lavaan model strings.
ordered	Optional ordered variables passed to lavaan::cfa(). If NULL and a categorical estimator such as WLSMV is used, observed items referenced in models are treated as ordered.
estimator	Estimator passed to lavaan::cfa(). NULL (default) or "auto" uses the same category-count, sample-size and Mardia criteria as cfa_auto(), applied to the observed indicators across the candidate models.
language	Recommendation language: "eng" or "esp".
digits	Decimal places in console and reports; stored values keep full precision.
report	If TRUE, also save a reader-facing report.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.
fit_variant	Fit-index variant for both reporting and comparison: "scaled" (default), "robust", or "base". SRMR remains base. Uncorrected estimators use base indices with the default scaled setting. Otherwise unavailable requested indices remain missing, without substitution.

Value

A list of class psychomatic_model_comparison.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
models <- list(one_factor = "F =~ R1 + R2 + R3 + R4 + R5 + R6",
               two_factors = "F1 =~ R1 + R2 + R3\nF2 =~ R4 + R5 + R6")
compare_models_auto(MY_DATA, models = models)
compare_models_auto(MY_DATA, models = models, fit_variant = "robust")

## End(Not run)

---

Inter-item correlation matrix

Description

Computes an inter-item correlation matrix using Pearson, polychoric, or tetrachoric correlations. Optionally exports the matrix to an Excel file.

Usage

cormat(
  data,
  type = c("auto", "pearson", "poly", "tetra"),
  report = FALSE,
  file_name = NULL,
  digits = 3,
  ordinal_levels = NULL,
  overwrite = FALSE,
  format = "excel",
  verbose = TRUE,
  language = "eng"
)

Arguments

data	Data frame or matrix containing the items.
type	Defaults to "auto": dichotomous items use tetrachoric; ordinal items with 2-5 categories use polychoric. With 6+ categories, ordinal items use polychoric when absolute moment skewness exceeds 1, absolute excess kurtosis exceeds 2, or endpoint mass is at least 0.50; otherwise Pearson is used. Numeric integer items with at most 10 observed categories are inferred ordinal; ordered factors declare this explicitly. These shape flags are operational rules, not universal literature cutoffs. Mixed low-category/continuous inputs require explicit selection. Manual options are "pearson", "poly", and "tetra".
report	If TRUE, save a report in the requested format.
file_name	Optional Excel file name. If NULL, a timestamped name is generated in the working directory (getwd()).
digits	Number of decimal places used in the Excel report.
ordinal_levels	Optional uniquely named list giving the ordered levels for unordered categorical items used with type = "poly" or "tetra".
overwrite	If TRUE, an existing report file may be replaced.
format	Report format: "excel", "word", or both.
verbose	If TRUE, print results directly, including when assigned.
language	Output language: "esp" or "eng".

Value

A correlation matrix with pairwise sample sizes, requested and effective correlation types, and validation diagnostics as attributes.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
cormat(MY_DATA[, 3:14])

## End(Not run)

---

Automated descriptives for psychometric items

Description

Computes compact descriptive statistics for numeric and ordered item columns. Ordinal response percentages are retained as a separate long table. Results can optionally be exported to Excel.

Usage

desc_auto(
  data,
  digits = 3,
  language = "eng",
  report = FALSE,
  file_name = NULL,
  overwrite = FALSE,
  format = "excel",
  verbose = TRUE
)

Arguments

data	Data frame, matrix, or psychomatic_spec containing item responses.
digits	Number of decimal places used in the report. Returned numeric values are not rounded.
language	Report language: "esp" or "eng".
report	If TRUE, save a report in the requested format.
file_name	Optional Excel output path. If NULL, a timestamped name is generated in the working directory (getwd()) when report = TRUE.
overwrite	If TRUE, an existing report file may be replaced.
format	Report format: "excel", "word", or both.
verbose	If TRUE, print results directly, including when assigned.

Value

A compact data frame with one row per item. A long data frame with columns item, category, n, and percent is available from the response_percentages attribute.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
desc_auto(MY_DATA[, 3:14])

## End(Not run)

---

Screen differential item functioning by group

Description

Performs a lightweight DIF screening using logistic regression. By default, polytomous items are reported as not evaluable because dichotomization can obscure category-specific DIF. Median dichotomization is available only as an explicit compatibility option and should be followed by a dedicated IRT or ordinal DIF analysis.

Usage

dif_auto(
  data,
  group,
  items = NULL,
  alpha = 0.01,
  language = c("eng", "esp"),
  digits = 3,
  polytomous = c("not_evaluable", "median"),
  report = FALSE,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

data	Data frame or matrix containing item responses. If group is a column name in data, that column is used as the grouping variable.
group	Grouping vector or the name of the grouping column in data.
items	Optional item names. Defaults to all numeric item columns except the grouping column.
alpha	Significance level used for DIF flags.
language	Interpretation language: "eng" or "esp".
digits	Number of decimal places used in interpretation tables.
polytomous	Handling of polytomous focal items. The default, "not_evaluable", does not dichotomize them. Use "median" only to opt into a compatibility screen that is labeled and accompanied by a methodological warning.
report	If TRUE, also save a reader-facing report.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.

Value

A list of class psychomatic_dif with screening results, item-level interpretation (dif_type, decision, severity, and recommendation), an overall DIF summary, and supporting APA 7 references.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
dif_auto(MY_DATA[, 3:14], group = MY_DATA$Country)

## End(Not run)

---

Automated exploratory factor analysis

Description

Runs a compact exploratory factor-analysis workflow: item checks, correlation selection, Mardia diagnostics, parallel analysis, factor fitting, item screening, and reliability summaries. Screening can suggest changes or remove one item at a time. Every mutation is followed by a complete refit that reclassifies the current item set and resolves its correlation method. Omega uses the same independent one-factor model per dimension as reliability_auto(), not the loadings of the exploratory solution.

Usage

efa_auto(
  data,
  rotation = c("oblique", "orthogonal"),
  min_loading = 0.3,
  min_communality = 0.3,
  min_cross_loading_diff = 0.15,
  max_iter = 20,
  verbose = TRUE,
  export_format = NULL,
  file_name = NULL,
  language = "eng",
  seed = NULL,
  refine = c("remove", "suggest"),
  parallel_iter = 500L,
  parallel_quantile = 0.95,
  repair = c("none", "nearPD"),
  digits = 3,
  report = FALSE,
  format = "excel",
  overwrite = FALSE,
  ...
)

Arguments

data	Data frame, matrix, or psychomatic_spec containing item responses.
rotation	Rotation family: "oblique" or "orthogonal".
min_loading	Minimum acceptable absolute factor loading.
min_communality	Minimum acceptable communality.
min_cross_loading_diff	Minimum difference between the two largest loadings used by the cross-loading screen.
max_iter	Maximum number of item-removal steps.
verbose	If TRUE, print results directly, including when assigned.
export_format	Optional export format passed to export_efa().
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
language	Output language: "esp" or "eng".
seed	Optional non-negative integer seed for parallel analysis.
refine	"remove" preserves the historical automated-removal workflow; "suggest" retains every item and reports screening flags.
parallel_iter	Number of simulations used by parallel analysis.
parallel_quantile	Reference quantile used by parallel analysis.
repair	Correlation-matrix repair. "none" never changes the matrix; "nearPD" explicitly opts into nearest-positive-definite repair.
digits	Decimal places in console and reports; stored values keep full precision.
report	If TRUE, also save a reader-facing report.
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
...	Deprecated Spanish argument aliases.

Value

An object of classes efa_auto and psychomatic_result. Legacy fields remain available during the 1.x compatibility cycle.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
efa_auto(MY_DATA[, 3:14])

## End(Not run)

---

Exploratory structural equation measurement model with transparent rotation

Description

Fits one exploratory measurement block directly in lavaan, retaining all within-block cross-loadings and rotated parameter uncertainty. With no structural regressions this is EFA in the terminology of lavaan; ESEM is also used for these measurement models in the psychometric literature.

Usage

esem_auto(
  data,
  factors = NULL,
  n_factors = NULL,
  items = NULL,
  rotation = "target",
  ordered = NULL,
  estimator = NULL,
  missing = "listwise",
  rotation_args = list(),
  seed = NULL,
  compare_cfa = FALSE,
  fit_variant = c("scaled", "robust", "base"),
  language = "eng",
  digits = 3,
  report = FALSE,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

data	Data frame, matrix, or psychomatic_spec.
factors	Named list of primary item sets. Every selected item occurs once. Target requires this list. With geomin it only supplies selection, factor count and an optional CFA reference, not a rotation target.
n_factors	Integer >= 2, required for geomin without factors.
items	Explicit column names or positive column indices for raw geomin data without factors, for example items = 2:13 or items = names(MY_DATA)[2:13]. Pass column selectors, not a data subset: MY_DATA[, 2:13] is a data frame and is not a valid items argument. This argument is required for raw geomin data, even if all columns are items; in that case use items = names(MY_DATA). NULL with factors or a specification.
rotation	"target" (default) or "geomin".
ordered	NULL inherits/detects measurement levels heuristically; TRUE treats all selected items as ordinal, FALSE requests numeric continuous treatment, or a character vector identifies ordinal items. Nominal factors require explicit ordinal mapping; ordered factors cannot silently become continuous scores.
estimator	NULL selects WLSMV with ordinal items, otherwise MLR. Explicit choices: WLSMV/ULSMV for ordinal or mixed items, ML/MLR for continuous.
missing	"listwise" (default), "fiml" for continuous ML/MLR, or "pairwise" for ordinal WLSMV/ULSMV. No automatic imputation.
rotation_args	Named options: rstarts (30), geomin_epsilon (0.001, geomin only), gpa_tol (1e-5), max_iter (10000).
seed	NULL (default) leaves RNG management to lavaan without imposing a wrapper seed. An explicit nonnegative integer makes rotation starts reproducible and restores the incoming RNG state after fitting.
compare_cfa	Whether to fit the simple-structure CFA specified by factors on the same data/options. Comparison is descriptive, without automatic model selection, LRT or factor alignment.
fit_variant	"scaled", "robust" or "base". Missing requested indices remain NA with a reason. Corrected chi-square/df/p use scaled variants unless base is selected; SRMR is always base.
language	Output language: "eng" or "esp".
digits	Number of display decimals.
report	Whether to write a report, or an explicit report path.
file_name	Report path/base; NULL uses a unique name in getwd().
format	"excel", "word" or both.
overwrite	Whether existing report files may be replaced.
verbose	Whether to print results and the manuscript draft.

Value

An esem_auto/psychomatic_result object. fit contains the native lavaan fit with safe item aliases; results$item_map maps original names. results contains loadings/IC95, item diagnostics, factor correlations, fit variants, raw covariance residuals, target, maps and syntax. Loading tables distinguish original-scale (raw_ci_lower, raw_ci_upper) from standardized (ci_lower, ci_upper) native 95% intervals. effective_settings$preparation records category order, declared reverse scoring and the effective bounds, including inferred bounds. Report encoding is the input category order before reverse scoring, which is recorded separately. manuscript_text and results$manuscript contain a data-based draft placed last under Interpretation in reader-facing console/Word/Excel output. Preparation, item/factor maps and versions remain in the object and exports but are omitted from the console. The text is not an independent validation or substantive interpretation of unlabeled factors. Failed or inadmissible fits produce limitations rather than favorable conclusions.

Choosing a rotation

Target is useful when theory or previous research identifies the primary dimension for each item, while allowing secondary loadings. factors defines the target pattern. Secondary loadings are oriented towards zero, not fixed to zero. A target entry of 1 leaves the primary loading untargeted; it does not fix that loading to 1. A data-derived target from the same sample remains exploratory and requires independent validation for stronger generalization.

Geomin is useful when the item-factor organization is uncertain. It seeks a relatively simple pattern without prescribing substantive memberships. n_factors remains an investigator decision. Factors retain neutral IDs because order and signs do not establish their substantive interpretation. The initial epsilon is 0.001, not a universal optimum; specify alternatives through rotation_args and report the chosen value. Both options are oblique.

Rotations of the same unrestricted block preserve global model fit; CFI and RMSEA do not select the preferable rotation. Consider theoretical coherence, loading patterns and stability. Thirty random starts do not establish a global optimum or sampling stability. Reported standardized loadings are pattern coefficients, not the oblique structure matrix.

References

Asparouhov, T., & Muthén, B. (2009). Exploratory structural equation modeling. Structural Equation Modeling, 16(3), 397–438. doi:10.1080/10705510903008204.

Marsh, H., & Alamer, A. (2024). When and how to use set-exploratory structural equation modelling to test structural models: A tutorial using the R package lavaan. British Journal of Mathematical and Statistical Psychology, 77(3), 459–476. doi:10.1111/bmsp.12336.

Examples

## Not run: 
# Replace MY_DATA with your data frame.
# Ordinal items in columns 2:13; column 1 is not an item.
result <- esem_auto(data = MY_DATA,
                    n_factors = 3,
                    items = 2:13,
                    rotation = "geomin",
                    ordered = TRUE,
                    language = "esp")
result$manuscript_text

# Continuous indicators: MY_DATA must contain only item columns here.
result <- esem_auto(data = MY_DATA,
                    n_factors = 3,
                    items = names(MY_DATA),
                    rotation = "geomin",
                    ordered = FALSE,
                    language = "esp")

# Target: replace the item names and primary memberships with your theory.
factors <- list(Factor1 = c("R1", "R2", "R3", "R4"),
                Factor2 = c("R5", "R6", "R7", "R8"),
                Factor3 = c("R9", "R10", "R11", "R12"))
result <- esem_auto(data = MY_DATA,
                    factors = factors,
                    rotation = "target",
                    ordered = TRUE,
                    language = "esp")

## End(Not run)

---

Export CFA results to Excel or Word

Description

Export CFA results to Excel or Word

Usage

export_cfa(
  result,
  format = c("excel", "word"),
  file_name = NULL,
  digits = 3,
  overwrite = FALSE
)

Arguments

result	Object of class "cfa_auto" returned by cfa_auto().
format	"excel" or "word" (you can provide both).
file_name	Optional base file name without extension. If NULL, a unique timestamped name is generated in the working directory (getwd()).
digits	Number of decimal places used to format report values. Raw numeric values remain unchanged in Excel files.
overwrite	If TRUE, existing output files may be replaced.

Value

Normalized output path, invisibly. When both formats are requested, returns a named character vector; Excel output includes a sheet_map attribute.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
model <- "F1 =~ R1 + R2 + R3 + R4"
result <- cfa_auto(MY_DATA, model = model)
export_cfa(result, format = "word", file_name = "CFA.docx")

## End(Not run)

---

Export EFA results to Excel or Word

Description

Exports the structured tables from an efa_auto() result. The function uses the package-level report writer so EFA exports stay consistent with the integrated psychomatic_report() workflow.

Usage

export_efa(
  result,
  format = c("excel", "word"),
  file_name = NULL,
  overwrite = FALSE
)

Arguments

result	Object of class "efa_auto" returned by efa_auto().
format	Output format: "excel", "word", or both.
file_name	Optional output path or base path. If NULL, a unique timestamped name is generated in the working directory (getwd()).
overwrite	If TRUE, existing output files may be replaced. The default is fail-closed.

Value

The input result, invisibly.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
result <- efa_auto(MY_DATA[, 3:14])
export_efa(result, format = "excel", file_name = "EFA.xlsx")

## End(Not run)

---

Automated complete measurement invariance

Description

Fits configural, metric, scalar and strict multi-group CFA models using native lavaan CFA calls and their default marker identification. WLSMV/ULSMV default to ordered responses; only the four requested stages are fitted. The function automates estimator selection and syntax construction while keeping identification, fit variants, admissibility, and model-comparison evidence available for inspection. Fit-change cutoffs are descriptive heuristics, not proof of invariance.

Usage

factorial_invariance_auto(
  data,
  group,
  model,
  language = c("eng", "esp"),
  estimator = "auto",
  ordered = NULL,
  report = FALSE,
  criteria = "auto",
  missing = "auto",
  min_group_n = 20L,
  overwrite = FALSE,
  digits = 3,
  file_name = NULL,
  format = "excel",
  verbose = TRUE,
  fit_variant = c("scaled", "robust")
)

Arguments

data	A data frame, matrix, or psychomatic_spec containing indicators and (unless supplied as a vector) the grouping variable.
group	A grouping-column name or symbol, one positive column index, or a vector with one value per original row.
model	One lavaan CFA model string.
language	Output language, Spanish ("esp") or English ("eng").
estimator	"auto", "ML", "MLR", "ULS", "WLSMV", or "ULSMV". Explicit WLSMV/ULSMV default to ordered = TRUE and listwise handling. Automatic selection uses WLSMV for detected ordinal responses, otherwise ML when all groups have favourable Mardia evidence and MLR otherwise. ML/MLR/ULS analyze numeric scores as continuous.
ordered	NULL, TRUE/FALSE, or indicator names/indices. With explicit WLSMV/ULSMV, NULL declares every model indicator ordered. FALSE explicitly requests numeric-score estimation instead. Character and unordered-factor responses require declared levels. For an identified threshold/loading invariance sequence use ordinal_invariance_auto().
report	FALSE, TRUE for a report in getwd(), or an explicit Excel path.
criteria	"auto" or a fully named nonnegative numeric vector with cfi, rmsea, srmr_loading, and srmr_other; the three optional ⁠configural_*⁠ entries customize the configural gate.
missing	"auto", "fiml", or "listwise". Categorical analyses require listwise handling.
min_group_n	Operational minimum analytic group size. The default of 20 does not guarantee power, identification, or stable estimation.
overwrite	Whether an existing explicit report path may be replaced.
digits	Decimal places in console and reports; stored values keep full precision.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
verbose	If TRUE, print results directly, including when assigned.
fit_variant	"scaled" (default) or "robust" for CFI and RMSEA, their changes, decisions and reports. Corrected estimators always use scaled chi-square, df and p; SRMR is uncorrected. Uncorrected ML/ULS use base indices by default. Unavailable requested robust indices remain missing; they are never silently replaced by scaled or base indices.

Value

An object of classes factorial_invariance_auto and psychomatic_result. Raw values are not rounded. Direct legacy aliases are retained; ⁠$warnings⁠ is now a structured data frame and ⁠$warnings_list⁠ (also ⁠$notes⁠) is the character compatibility view.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
model <- "F1 =~ R1 + R2 + R3 + R4"
factorial_invariance_auto(MY_DATA, group = "Country", model = model)

## End(Not run)

---

Automated alignment invariance

Description

Runs alignment optimization from loading and intercept matrices (lambda and nu) or from item-level data with a grouping vector.

Usage

inv_align_auto(
  lambda = NULL,
  nu = NULL,
  data = NULL,
  group = NULL,
  sampling_weights = NULL,
  wgt = NULL,
  language = c("eng", "esp"),
  model = c("2PM", "1PM"),
  align.scale = c(lambda = 0.4, nu = 0.2),
  align.pow = c(lambda = 0.25, nu = 0.25),
  parm_tol = NULL,
  noninvariance_cutoff = 25,
  center = FALSE,
  optimizer = "optim",
  fixed = NULL,
  meth = 1,
  eps = 0.001,
  vcov = NULL,
  digits = 3,
  config_args = list(),
  alignment_args = list(),
  report = FALSE,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

lambda, nu	Parameter matrices for loadings and intercepts.
data	Item-level data used when lambda and nu are not supplied.
group	Grouping vector associated with data.
sampling_weights	Optional sampling weights, one per row.
wgt	Optional weights for the alignment procedure.
language	Report language: "esp" or "eng".
model	Model type for the configural alignment step.
align.scale, align.pow, parm_tol	Alignment tuning parameters.
noninvariance_cutoff	Percentage used to flag non-invariance.
center, optimizer, fixed, meth, eps, vcov	Advanced algorithm parameters.
digits	Number of decimal places used in the report.
config_args	Additional arguments for the configural step.
alignment_args	Additional arguments for the alignment step.
report	If TRUE, also save a reader-facing report.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.

Value

Object of class inv_align_auto_result.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
inv_align_auto(data = MY_DATA[, 28:39], group = MY_DATA$Country,
               language = "eng")

## End(Not run)

---

Fit researcher-directed partial measurement invariance

Description

Fits a complete target invariance stage and a matched partial stage using explicit, researcher-justified parameter releases. The function automates the lengthy lavaan/semTools syntax while deliberately avoiding automated modification-index searches or iterative freeing.

Usage

invariance_partial(
  data,
  group,
  model,
  free,
  rationale,
  stage = "scalar",
  measurement = "auto",
  estimator = "auto",
  ordered = NULL,
  criteria = "auto",
  min_anchor_items = 2L,
  report = FALSE,
  language = "eng",
  digits = 3,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE,
  fit_variant = c("scaled", "robust"),
  workflow = c("factorial", "ordinal"),
  missing = "auto",
  min_group_n = 20L
)

Arguments

data	A data frame, matrix, or psychomatic_spec.
group	Group column name/symbol/index or a vector with one value per row.
model	A first-order lavaan measurement model.
free	Canonical parameter expressions to release, supplied as a character vector or a family-named list.
rationale	Required substantive rationale, either one global value or an exactly expression-named character vector.
stage	Target stage: "metric", "scalar", or "strict" in the default factorial workflow. The explicit ordinal workflow additionally accepts "thresholds" and "loadings"; binary ordinal data require joint "scalar" or "strict" stages.
measurement	Assertion ("auto", "continuous", "ordinal", or "mixed") checked against prepared item types.
estimator	Estimator passed through the complete-invariance engine.
ordered	Ordered-item assertion accepted by the complete-invariance engine.
criteria	Fit-change criteria accepted by factorial_invariance_auto().
min_anchor_items	Minimum number of fully constrained anchor items per first-order factor; must be an integer of at least two.
report	FALSE, TRUE, or an Excel output path. Existing files are protected unless overwrite = TRUE explicitly permits replacement.
language	Presentation language, "eng" by default; "esp" for Spanish. Explicit NULL inherits a specification or the package option.
digits	Decimal places in console and reports; stored values keep full precision.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.
fit_variant	"scaled" (default) or "robust" for CFI and RMSEA, changes and decisions. Unavailable robust values are not substituted. Corrected chi-square, df and p remain scaled; SRMR remains base.
workflow	"factorial" (default) follows the native lavaan settings and four-stage constraint sequence of factorial_invariance_auto(), with researcher-specified group.partial releases. WLSMV/ULSMV default to ordered indicators, marker identification and delta parameterization. "ordinal" retains the identified semTools theta/std.lv/Wu-Estabrook procedure, including threshold releases. An ineffective release or a comparison without additional degrees of freedom cannot support invariance.
missing	Missing-data option accepted by factorial_invariance_auto().
min_group_n	Minimum effective group size; default 20.

Value

Invisibly, an object of classes psychomatic_invariance_partial and psychomatic_result.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
model <- "F1 =~ R1 + R2 + R3 + R4"
# Continuous indicators; justify the freed intercept before testing.
invariance_partial(MY_DATA, group = "Country", model = model,
                   free = "R2 ~ 1", estimator = "ML",
                   rationale = "A preregistered item-wording hypothesis")

## End(Not run)

---

Fit basic IRT models automatically

Description

Fits a one-dimensional Rasch, 2PL, or graded response model using mirt. The dependency is optional and is loaded only when this function is called.

Usage

irt_auto(
  data,
  model = c("auto", "rasch", "2pl", "grm"),
  factors = 1,
  itemtype = NULL,
  technical = list(),
  language = c("eng", "esp"),
  digits = 3,
  report = FALSE,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

data	Data frame or matrix containing item responses.
model	IRT model: "auto", "rasch", "2pl", or "grm".
factors	Number of latent dimensions passed to mirt::mirt().
itemtype	Optional mirt item type. If NULL, it is selected from model.
technical	Optional technical arguments passed to mirt::mirt().
language	Interpretation language: "eng" or "esp".
digits	Number of decimal places used in interpretation tables.
report	If TRUE, also save a reader-facing report.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.

Value

A list of class psychomatic_irt with fitted model, item parameters, item-level interpretation, a model-level summary, and supporting APA 7 references.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
irt_auto(MY_DATA[, 3:14])

## End(Not run)

---

Automated exploratory psychometric network analysis

Description

Optionally runs unique variable analysis before EGA (by default Spearman, EBICglasso and consensus Louvain), revised network loadings, TEFI, wording and hierarchy diagnostics, structural bootstrap and group comparisons. Optional packages are required only for requested stages. See the network workflow vignette for assumptions.

Usage

network_auto(
  data,
  items = NULL,
  group = NULL,
  reverse = NULL,
  ranges = NULL,
  uva = NULL,
  uva_cutoff = 0.25,
  corr = c("spearman", "pearson", "polychoric"),
  gamma = 0.5,
  missing = c("listwise", "pairwise"),
  wording = TRUE,
  hierarchy = TRUE,
  bootstrap = TRUE,
  invariance = TRUE,
  n_boot = 1000L,
  n_perm = 5000L,
  consensus_iter = 1000L,
  n_cores = 1L,
  seed = NULL,
  language = "eng",
  report = FALSE,
  format = "excel",
  file_name = NULL,
  overwrite = FALSE,
  digits = 3L,
  verbose = TRUE,
  model = c("glasso", "TMFG", "BGGM"),
  algorithm = c("louvain", "leiden", "walktrap"),
  bootstrap_type = c("resampling", "parametric")
)

Arguments

data	Numeric/ordered item data or a psychomatic_spec.
items	Item columns; defaults to eligible columns, excluding group.
group	Group column (e.g., sex), or declared in the specification.
reverse	Known reverse-keyed item columns. Never inferred from signs.
ranges	Theoretical response ranges for reverse items.
uva	NULL (default) skips UVA entirely. "diagnostic" reports redundant pairs, wTO and justified removal proposals without removing items. "removed" authorizes native representative selection and removal, with recorded criteria, scores and reasons. No mode requests interactive input.
uva_cutoff	Weighted topological overlap threshold, default .25.
corr	"spearman" (default), "pearson", or "polychoric" for ordinal items (including binary items), up to 11 categories per item in EGAnet. Correlations are re-estimated in resamples.
gamma	EBIC penalty, default .5.
missing	"listwise" (default) or "pairwise" for correlations.
wording	Run riEGA on original, unrecoded responses.
hierarchy	Run hierEGA and evaluate identifiable CFA candidates.
bootstrap	Run bootEGA and bootnet accuracy/case-drop analyses.
invariance	Run NCT and EGA loading permutation tests if a group exists.
n_boot	Replications per bootstrap analysis, default 1000.
n_perm	Permutations per comparison, default 5000.
consensus_iter	Louvain consensus iterations, default 1000.
n_cores	Workers for bootEGA, bootnet and loading permutations, default 1. NCT remains sequential in the supported version.
seed	Optional integer-valued seed. NULL (default) draws an analysis seed from the session RNG and records it in effective_settings$seed. An explicit seed is reproducible and restores the caller's RNG state.
language	"eng" (default) or "esp".
report	Export a report, logical or output path.
format	Report format(s), "excel" and/or "word".
file_name	Report output basename/path.
overwrite	Allow overwriting existing report files, default FALSE.
digits	Display precision; numerical results retain full precision.
verbose	Print stage progress, elapsed time and the analysis summary.
model	Network estimator: "glasso" (default), "TMFG", or "BGGM". BGGM requires an EGAnet version that supports it; EGAnet 2.4.1 disables it. No unavailable estimator is silently replaced. Gamma applies only to GLASSO.
algorithm	Community detection: "louvain" (default), "leiden", or "walktrap". Used in empirical/group EGA and both hierEGA orders.
bootstrap_type	bootEGA bootstrap: "resampling" (default) or "parametric". Applies also to configural, riEGA and hierEGA bootstraps. Parametric generates continuous multivariate-normal data; it does not preserve ordinal response categories. No automatic superiority selection. bootnet edge precision and case-drop procedures remain separate.

Details

The default console and reports emphasize communities, structural consistency and group comparisons. Non-significance does not establish equivalence. Complete diagnostic tables remain in the object and can be displayed with print(fit, detail="audit") or exported with psychomatic_report(fit, detail="audit"). APA reference italics are shared across analyses in Word, Excel and compatible interactive consoles; plain logs retain unformatted text. options(PsychoMatic.ansi=FALSE) disables console styling; TRUE forces it for terminals supporting ANSI italics.

Value

A psychomatic_network and psychomatic_result object. Failed optional stages remain explicit in results$stages and errors; partial results are never described as a completed analysis. Original responses remain available in diagnostics$input but are excluded from reader-facing reports.

Examples

## Not run: 
fit <- network_auto(MY_DATA, items = 1:12, group = "sex")
plot(fit, type = "network")
psychomatic_report(fit, format = c("word", "excel"), file_name = "network")

## End(Not run)

---

Export publication figures from cached network results

Description

Export publication figures from cached network results

Usage

network_plots(
  x,
  directory = NULL,
  types = NULL,
  formats = c("pdf", "png"),
  language = NULL,
  width = 10,
  height = 7,
  dpi = 300,
  overwrite = FALSE,
  label_cex = 1.2
)

Arguments

x	A psychomatic_network object.
directory	Existing output directory (created if absent).
types	Figure types; NULL selects relevant publication figures, omitting unavailable wording diagnostics and descriptive TEFI/centrality figures. Supply types=network_plots(x) explicitly for all diagnostic types. With bootstrap results, "ega_stability" combines the EGA network and item replication plot. Standalone "network" and "item_stability" remain available explicitly. Two-group networks flag complete BH loading tests.
formats	File formats, one or more of "pdf", "svg", "png".
language	"eng" or "esp".
width, height	Figure dimensions in inches.
dpi	PNG resolution, default 300.
overwrite	Allow existing files to be overwritten.
label_cex	Node label size multiplier, default 1.2. Increase for figures that will be reduced to a small publication width.

Value

Invisibly, paths of exported figures; without directory, available types.

---

Automated ordinal measurement invariance

Description

Fits configural, equal-threshold, and equal-threshold-and-loading models using theta parameterization and Wu and Estabrook (2016) identification via semTools::measEq.syntax(), as illustrated by Svetina et al. (2020). All indicators must be ordinal. Binary or three-category indicators can make a separate threshold comparison untestable; such stages are explicitly marked as not independently identified rather than accepted as invariant.

Usage

ordinal_invariance_auto(
  data,
  group,
  model,
  language = c("eng", "esp"),
  estimator = "auto",
  ordered = NULL,
  report = FALSE,
  criteria = "auto",
  missing = "auto",
  min_group_n = 20L,
  overwrite = FALSE,
  digits = 3,
  file_name = NULL,
  format = "excel",
  verbose = TRUE,
  fit_variant = c("scaled", "robust")
)

Arguments

data	A data frame, matrix, or psychomatic_spec containing indicators and (unless supplied as a vector) the grouping variable.
group	A grouping-column name or symbol, one positive column index, or a vector with one value per original row.
model	One lavaan CFA model string.
language	Output language, Spanish ("esp") or English ("eng").
estimator	"auto" (WLSMV), "WLSMV", or "ULSMV". ML, MLR, and other estimators are rejected before fitting.
ordered	NULL detects ordinal indicators; TRUE declares all model indicators ordered; names/indices declare an explicit selection. Every model indicator must be ordered. FALSE is rejected.
report	FALSE, TRUE for a report in getwd(), or an explicit Excel path.
criteria	"auto" or a fully named nonnegative numeric vector with cfi, rmsea, srmr_loading, and srmr_other; the three optional ⁠configural_*⁠ entries customize the configural gate.
missing	"auto", "fiml", or "listwise". Categorical analyses require listwise handling.
min_group_n	Operational minimum analytic group size. The default of 20 does not guarantee power, identification, or stable estimation.
overwrite	Whether an existing explicit report path may be replaced.
digits	Decimal places in console and reports; stored values keep full precision.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
verbose	If TRUE, print results directly, including when assigned.
fit_variant	"scaled" (default) or "robust" for CFI and RMSEA, their changes, decisions and reports. Corrected estimators always use scaled chi-square, df and p; SRMR is uncorrected. Uncorrected ML/ULS use base indices by default. Unavailable requested robust indices remain missing; they are never silently replaced by scaled or base indices.

Details

Changes are signed differences (current minus preceding evaluable model). Chen (2007) guidelines are descriptive extrapolations to ordinal estimation, not ordinal-specific validated cutoffs: a CFI decline exceeding .010 together with an RMSEA increase exceeding .015 or SRMR increase exceeding .030 (adding loadings) / .010 (thresholds) signals lack of support. Configural fit and admissibility are checked first. Custom criteria can be supplied.

Value

A result with classes ordinal_invariance_auto, factorial_invariance_auto, and psychomatic_result, including raw fitted models, identification diagnostics, fit changes, and bilingual reports.

References

Wu, H., & Estabrook, R. (2016). Identification of confirmatory factor analysis models of different levels of invariance for ordered categorical outcomes. Psychometrika, 81(4), 1014-1045. doi:10.1007/s11336-016-9506-0

Svetina, D., Rutkowski, L., & Rutkowski, D. (2020). Multiple-group invariance with categorical outcomes using updated guidelines: An illustration using Mplus and the lavaan/semTools packages. Structural Equation Modeling: A Multidisciplinary Journal, 27(1), 111-130. doi:10.1080/10705511.2019.1602776

Chen, F. F. (2007). Sensitivity of goodness of fit indexes to lack of measurement invariance. Structural Equation Modeling: A Multidisciplinary Journal, 14(3), 464-504. doi:10.1080/10705510701301834

Examples

## Not run: 
ordinal_invariance_auto(MY_DATA, group = "Sexo",
  model = "F =~ R1 + R2 + R3 + R4", ordered = TRUE,
  estimator = "WLSMV", report = TRUE, format = c("word", "excel"))

## End(Not run)

---

Plot cached psychometric network results

Description

Plot cached psychometric network results

Usage

## S3 method for class 'psychomatic_network'
plot(x, type = "network", language = NULL, label_cex = 1.2, ...)

Arguments

x	A psychomatic_network result.
type	Figure type. See network_plots() for available figures.
language	Figure language, defaults to the result language.
label_cex	Node label size multiplier, default 1.2. Labels are not automatically shrunk to fit the nodes; use concise item identifiers.
...	Reserved for future graphical arguments.

Value

Invisibly, a qgraph object for "network" and "loadings", or the underlying results for other figures. No analysis is recomputed.

---

Print a psychometric network result

Description

Print a psychometric network result

Usage

## S3 method for class 'psychomatic_network'
print(x, detail = c("report", "audit"), ...)

Arguments

x	A psychomatic_network object.
detail	"report" (default) displays a manuscript-oriented summary; "audit" displays complete diagnostic tables and conditions.
...	Additional arguments, currently unused.

Value

x, invisibly.

---

Create an integrated PsychoMatic report

Description

Collects tables from PsychoMatic result objects and writes an Excel workbook and/or Word document. Reports use the user-supplied path or the current working directory (getwd()) when file_name = NULL.

Usage

psychomatic_report(
  ...,
  format = "excel",
  file_name = NULL,
  language = c("eng", "esp"),
  digits = 3,
  overwrite = FALSE,
  detail = c("report", "audit")
)

Arguments

...	Named PsychoMatic result objects or data frames. Supported objects include outputs from desc_auto(), screen_items(), score_scale(), reliability_auto(), efa_auto(), cfa_auto(), esem_auto(), factorial_invariance_auto(), ordinal_invariance_auto(), inv_align_auto(), irt_auto(), dif_auto(), and compare_models_auto().
format	Output format: "excel", "word", or both.
file_name	Output path or base path. If NULL, a unique timestamped name is generated in getwd(). Explicit paths remain authoritative.
language	Report language: "eng" or "esp".
digits	Number of decimal places for numeric tables.
overwrite	If TRUE, existing report files may be replaced.
detail	"report" (default) organizes reader-facing results by analysis. "audit" retains the detailed technical tables and execution metadata.

Value

Output path, invisibly. When both formats are requested, returns a named character vector. Excel output carries a sheet_map attribute that records requested and effective worksheet names.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
result <- reliability_auto(MY_DATA[, 3:6])
psychomatic_report(reliability = result, format = "word", file_name = "Report.docx")

## End(Not run)

---

Define a psychometric data specification

Description

Selects item columns without silently treating identifiers or unordered categories as measurements. It records item order, measurement levels, ordinal encodings, reverse keys, ranges, grouping, metadata, missing-data policy, language, and the decisions used to build the specification.

Usage

psychomatic_spec(
  data,
  items = NULL,
  metadata = NULL,
  level = "auto",
  ordinal_levels = NULL,
  reverse = NULL,
  ranges = NULL,
  group = NULL,
  missing = "available",
  language = "eng"
)

Arguments

data	A data frame or matrix containing item responses and optional metadata/group columns.
items	Item column names or positive integer indices. If NULL, all eligible columns except metadata and group are considered, and likely identifiers cause an error rather than being silently selected.
metadata	Optional metadata column names or positive integer indices.
level	Measurement level: "auto", "ordinal", or "continuous". It may be scalar, aligned with items, or a named vector of per-item overrides.
ordinal_levels	Optional uniquely named list giving the ordered levels for selected items. Declared levels take precedence over level and must cover every observed non-missing value.
reverse	Optional item names or positive integer indices identifying reverse-keyed items. This records keys; it does not transform responses.
ranges	Optional uniquely named list of numeric vectors c(min, max), or a two-column matrix/data frame with item row names.
group	Optional single group-column name or positive integer index.
missing	Character scalar recording the missing-data policy. The default is "available".
language	Output language, "eng" by default; "esp" for Spanish. Explicit NULL uses getOption("PsychoMatic.language", "eng").

Details

With level = "auto", ordered factors are ordinal. Ordinary numeric columns with two through seven distinct finite integer values are ordinal; other varying numeric columns are continuous. Unordered factors, character vectors, and logical vectors are ambiguous and are never sorted alphabetically. Explicit ordinal_levels take precedence over an explicit per-item level, which in turn takes precedence over automatic classification.

When items = NULL, a candidate is treated as a possible identifier if its normalized name contains id, case, participant, or respondent, if at least 95 percent of its finite numeric values are unique, or if those values form a strictly monotone integer sequence. The function then stops and asks for an explicit items or metadata declaration.

Value

An object of classes psychomatic_spec and psychomatic_result. In addition to the common result-contract fields, direct fields expose data, the pre-mapping raw_data, items, measurement_level, ordinal_levels, reverse, ranges, group, metadata, missing, and language.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
psychomatic_spec(MY_DATA, items = c("R1", "R2", "R3", "R4"))

## End(Not run)

---

Automated reliability analysis

Description

Computes reliability coefficients while keeping the statistical estimand, response matrix, reverse-keying decision, and evaluability status explicit. Continuous responses receive observed-score alpha; ordinal responses also receive alpha from a named polychoric matrix. A fitted lavaan model adds composite reliability and average variance extracted through current semTools APIs when that suggested package is installed. Without a supplied model, omega fits a single congeneric factor (ML for continuous items; WLSMV for ordinal items). Ordinal omega refers to the observed response score using the Green and Yang correction; ordinal alpha refers to latent responses. This assumption requires substantive assessment. Alpha uses pairwise covariances. Omega uses complete cases, refitted after each item deletion; item-rest correlations use complete cases on all items. Deletion alpha uses the corresponding submatrix of the full-scale matrix.

Usage

reliability_auto(
  data,
  items = NULL,
  level = "auto",
  model = NULL,
  report = FALSE,
  language = "eng",
  digits = 3,
  file_name = NULL,
  format = "excel",
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

data	A data frame, matrix, or psychomatic_spec() object.
items	Optional item names or positive indices. Must be NULL for a psychomatic_spec input.
level	Measurement level passed to psychomatic_spec(): "auto", "continuous", or "ordinal".
model	Optional fitted lavaan CFA model.
report	If TRUE, send the structured result to psychomatic_report(). No file is written when FALSE.
language	Output language, "eng" by default; use "esp" for Spanish. Explicit NULL inherits from a specification or the package option.
digits	Decimal places in console and reports; stored values keep full precision.
file_name	Optional base path for exported files. When NULL, reports use a unique timestamped name in the working directory (getwd()).
format	Report format: "excel", "word", or both.
overwrite	If TRUE, allow replacement of an existing report.
verbose	If TRUE, print results directly, including when assigned.

Value

An object of classes psychomatic_reliability and psychomatic_result.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
reliability_auto(MY_DATA[, 3:14])

## End(Not run)

---

Reverse-score selected items

Description

Reverses item scores using either a user-defined score range or the observed range of the selected items. Items can be selected explicitly or detected from negative item-rest correlations.

Usage

reverse_items(
  data,
  items = NULL,
  min_score = NULL,
  max_score = NULL,
  suffix = "_r",
  overwrite = FALSE,
  detect = FALSE
)

Arguments

data	Data frame or matrix containing item responses.
items	Character vector of item names to reverse. Required unless detect = TRUE.
min_score, max_score	Optional theoretical score range. If omitted, the observed range among selected items is used.
suffix	Suffix used for reversed columns when overwrite = FALSE.
overwrite	If TRUE, replace the original columns. If FALSE, append reversed columns.
detect	If TRUE, reverse items flagged by screen_items() as probable reverse-keyed items.

Details

Repeated selections are applied once. Non-missing responses must be finite and fall within the effective scoring range. When reversed columns are appended, an existing target name is treated as a collision and is never overwritten silently.

Value

A data frame with attributes reversed_items and reverse_range.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
reverse_items(MY_DATA, items = c("R2", "R4"), min_score = 1, max_score = 5)

## End(Not run)

---

Score one or more psychometric scales

Description

Computes scale scores using sum or mean scoring, optional reverse scoring, optional person-mean imputation, and a minimum valid-response rule.

Usage

score_scale(
  data,
  keys = NULL,
  items = NULL,
  method = c("mean", "sum"),
  min_valid = 0.8,
  impute = c("none", "person_mean"),
  reverse = NULL,
  min_score = NULL,
  max_score = NULL
)

Arguments

data	Data frame or matrix containing item responses.
keys	Named list where each element contains the item names for one scale. If NULL, items are scored as a single scale named total.
items	Optional item names used when keys = NULL.
method	Scoring method: "mean" or "sum".
min_valid	Minimum number or proportion of valid item responses required to compute a scale score.
impute	Missing-data handling: "none" or "person_mean".
reverse	Optional character vector of items to reverse before scoring.
min_score, max_score	Optional score range used when reverse is provided.

Details

Eligible incomplete rows are prorated: mean scores use the available item mean and sum scores multiply that mean by the scale length. Missing values may remain NA, but non-finite responses are rejected before any scale is scored. Duplicate display labels receive stable unique keys recorded in scale_map.

Value

A list of class psychomatic_scores with score and reliability tables and a scale_map linking unique keys to display labels.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
score_scale(MY_DATA, items = c("R1", "R2", "R3", "R4"))

## End(Not run)

---

Screen item-level data quality

Description

Computes a compact item-screening table for numeric psychometric items: missingness, variance, distribution shape, floor and ceiling proportions, item-rest correlations, and probable reverse-keyed items.

Usage

screen_items(
  data,
  digits = 3,
  floor_cutoff = 0.8,
  ceiling_cutoff = 0.8,
  min_item_rest = -0.1,
  language = "eng",
  report = FALSE,
  format = "excel",
  file_name = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

data	Data frame or matrix containing item responses.
digits	Number of decimal places used in the returned table.
floor_cutoff	Proportion at the minimum score used to flag floor effects.
ceiling_cutoff	Proportion at the maximum score used to flag ceiling effects.
min_item_rest	Item-rest correlation below which an item is flagged as probably reverse keyed or inconsistent with the remaining items.
language	Output language: "eng" (default) or "esp".
report	Generate a report, or supply an output path.
format	Report format: "excel", "word", or both.
file_name	Output file name, without extension when using both formats.
overwrite	Allow replacing an existing report (default FALSE).
verbose	Show results directly in the console (default TRUE).

Details

Displayed percentages are on a 0–100 scale. The returned data frame retains its original English column names and 0–1 proportions for compatibility.

Value

A data frame of class psychomatic_item_screen.

Examples

# Replace MY_DATA with your data frame and adapt the item names or columns.
## Not run: 
screen_items(MY_DATA[, 3:14])

## End(Not run)

---