Package {PsychoMatic}

Type: Package
Title: Automated Psychometric Workflows and Reporting Tools
Version: 1.0.0
Description: Automates common psychometric workflows for applied researchers, including item descriptives, inter-item correlations, exploratory and confirmatory factor analysis, exploratory structural equation measurement models, reliability, psychometric network analysis, multi-group measurement invariance, and alignment optimization. Decision heuristics are informed by procedures such as parallel analysis (Horn, 1965, <doi:10.1007/BF02289447>), multivariate normality diagnostics (Mardia, 1970, <doi:10.1093/biomet/57.3.519>), measurement-invariance fit-change rules (Chen, 2007, <doi:10.1080/10705510701301834>), and alignment optimization (Asparouhov and Muthen, 2014, <doi:10.1080/10705511.2014.919210>), among others. Results can be returned as structured R objects and exported as bilingual reports for transparent analytical documentation.
License: GPL (≥ 3)
Copyright: 2026 José Gamarra-Moncayo
URL: https://github.com/gmoncayoj/PsychoMatic
BugReports: https://github.com/gmoncayoj/PsychoMatic/issues
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: GPArotation, lavaan (≥ 0.7-3), Matrix, psych, stats, utils
Suggests: bootnet (≥ 1.6), callr, EGAnet (≥ 2.0.7), flextable, igraph, knitr, mirt, MVN (≥ 6.3), NetworkComparisonTest, officer, openxlsx, pkgload, qgraph, rmarkdown, semTools (≥ 0.5-9), sirt (≥ 4.2-133), testthat (≥ 3.0.0), writexl, xml2
Config/testthat/edition: 3
VignetteBuilder: knitr
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-10-23 14:11:23 UTC; JoseGM
Author: Jose Gamarra-Moncayo ORCID iD [aut, cre]
Maintainer: Jose Gamarra-Moncayo <gamarramoncayoj@gmail.com>
Repository: CRAN
Date/Publication: 2026-10-23 16:50:06 UTC

PsychoMatic: automated psychometric workflows

Description

PsychoMatic provides low-syntax, reproducible workflows for declaring and checking psychometric data, scoring, reliability, exploratory and confirmatory factor analysis, exploratory structural equation measurement models, psychometric networks, complete and researcher-directed partial measurement invariance, alignment, IRT/DIF screening, auditing, and reports. Automation reduces procedural syntax but does not replace measurement theory, design decisions, or substantive review.

Details

Use psychomatic_spec() when item roles or encodings should be explicit. Main analysis functions include desc_auto(), score_scale(), reliability_auto(), cormat(), efa_auto(), cfa_auto(), esem_auto(), network_auto(), network_plots(), factorial_invariance_auto(), ordinal_invariance_auto(), invariance_partial(), inv_align_auto(), irt_auto(), dif_auto(), and compare_models_auto(). Use psychomatic_report() for explicit export.

Most 1.0.0 analysis objects inherit from psychomatic_result and separate requested/effective settings, raw results, structured conditions, diagnostics, decisions, and conclusions. Numerical analysis fields retain full precision; display and report formatting may honor digits.

Ordinal encodings, missing-data policies, estimator/identification settings, and not_evaluable states should always be inspected. Fit cutoffs, parallel analysis, Chen fit-change thresholds, DIF flags, and alignment summaries are decision aids rather than formal proof of validity or invariance.

Author(s)

Maintainer: Jose Gamarra-Moncayo gamarramoncayoj@gmail.com (ORCID)

Authors:

See Also

Useful links:

Internal reliability calculations

Description

Internal reliability calculations

Usage

.pm_auto_omega(x, level, keying = "none")

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 complete measurement-invariance fit changes

Description

Plot complete measurement-invariance fit changes

Usage

## S3 method for class 'factorial_invariance_auto'
plot(x, ...)

Arguments

x

Object returned by factorial_invariance_auto().

...

Additional graphical arguments (currently unused).

Value

Plotting data, invisibly.

Plot psychometric item issues by severity

Description

Plot psychometric item issues by severity

Usage

## S3 method for class 'psychomatic_check'
plot(x, ...)

Arguments

x

A psychomatic_check object.

...

Additional graphical arguments passed to graphics::barplot().

Value

The plotted severity-count data frame, invisibly.

Plot a dimensionality-sensitivity analysis

Description

Plot a dimensionality-sensitivity analysis

Usage

## S3 method for class 'psychomatic_dimensionality'
plot(x, ...)

Arguments

x

Object returned by dimensionality_sensitivity().

...

Additional graphical parameters passed to plot().

Value

The plotted configuration rows, invisibly.

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.

Plot an automated reliability result

Description

Plot an automated reliability result

Usage

## S3 method for class 'psychomatic_reliability'
plot(x, ...)

Arguments

x

A psychomatic_reliability object.

...

Additional arguments passed to graphics::barplot().

Value

The plotted coefficient rows, invisibly.

Print a cfa_auto object

Description

Print a cfa_auto object

Usage

## S3 method for class 'cfa_auto'
print(x, digits = NULL, ...)

Arguments

x

Object returned by cfa_auto().

digits

Number of decimal places shown in the printed report.

...

Additional unused arguments.

Print an automated EFA result

Description

Print an automated EFA result

Usage

## S3 method for class 'efa_auto'
print(x, digits = NULL, ...)

Arguments

x

Object returned by efa_auto().

digits

Decimal places for display. NULL uses the analysis setting.

...

Additional unused arguments.

Value

x, invisibly.

Print a complete measurement-invariance result

Description

Print a complete measurement-invariance result

Usage

## S3 method for class 'factorial_invariance_auto'
print(x, digits = NULL, ...)

Arguments

x

Object returned by factorial_invariance_auto().

digits

Display precision.

...

Additional unused arguments.

Value

x, invisibly.

Print an inv_align_auto_result object

Description

Print an inv_align_auto_result object

Usage

## S3 method for class 'inv_align_auto_result'
print(x, ...)

Arguments

x

Object returned by inv_align_auto().

...

Additional unused arguments.

Print psychometric item checks

Description

Print psychometric item checks

Usage

## S3 method for class 'psychomatic_check'
print(x, ...)

Arguments

x

A psychomatic_check object.

...

Additional arguments, currently unused.

Value

x, invisibly.

Print a dimensionality-sensitivity analysis

Description

Print a dimensionality-sensitivity analysis

Usage

## S3 method for class 'psychomatic_dimensionality'
print(x, ...)

Arguments

x

Object returned by dimensionality_sensitivity().

...

Additional unused arguments.

Value

x, invisibly.

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.

Print an automated reliability result

Description

Print an automated reliability result

Usage

## S3 method for class 'psychomatic_reliability'
print(x, digits = NULL, ...)

Arguments

x

A psychomatic_reliability object.

digits

Number of digits used only for display.

...

Additional arguments, currently unused.

Value

x, invisibly.

Print a psychometric data specification

Description

Print a psychometric data specification

Usage

## S3 method for class 'psychomatic_spec'
print(x, ...)

Arguments

x

A psychomatic_spec object.

...

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)

Summarize an automated CFA result

Description

Summarize an automated CFA result

Usage

## S3 method for class 'cfa_auto'
summary(object, ...)

Arguments

object

Object returned by cfa_auto().

...

Additional unused arguments.

Value

A list of tidy tables.

Summarize an automated EFA result

Description

Summarize an automated EFA result

Usage

## S3 method for class 'efa_auto'
summary(object, ...)

Arguments

object

Object returned by efa_auto().

...

Additional unused arguments.

Value

A list of tidy tables.

Summarize a factorial invariance result

Description

Summarize a factorial invariance result

Usage

## S3 method for class 'factorial_invariance_auto'
summary(object, ...)

Arguments

object

Object returned by factorial_invariance_auto().

...

Additional unused arguments.

Value

A list preserving raw fit evidence, decisions, diagnostics, criteria, structured conditions, conclusion, and references.

Summarize an inv_align_auto_result object

Description

Summarize an inv_align_auto_result object

Usage

## S3 method for class 'inv_align_auto_result'
summary(object, ...)

Arguments

object

Object returned by inv_align_auto().

...

Additional unused arguments.

Summarize psychometric item checks

Description

Summarize psychometric item checks

Usage

## S3 method for class 'psychomatic_check'
summary(object, ...)

Arguments

object

A psychomatic_check object.

...

Additional arguments, currently unused.

Value

A list containing severity counts and the complete issue table.

Summarize a dimensionality-sensitivity analysis

Description

Summarize a dimensionality-sensitivity analysis

Usage

## S3 method for class 'psychomatic_dimensionality'
summary(object, ...)

Arguments

object

Object returned by dimensionality_sensitivity().

...

Additional unused arguments.

Value

A list containing the configuration table, range, agreement, and conclusion.

Summarize a researcher-directed partial invariance result

Description

Summarize a researcher-directed partial invariance result

Usage

## S3 method for class 'psychomatic_invariance_partial'
summary(object, ...)

Arguments

object

Object returned by invariance_partial().

...

Additional unused arguments.

Value

A structured list preserving raw fit evidence, releases, anchors, comparisons, conditions, and the cautious conclusion.

Summarize an automated reliability result

Description

Summarize an automated reliability result

Usage

## S3 method for class 'psychomatic_reliability'
summary(object, ...)

Arguments

object

A psychomatic_reliability object.

...

Additional arguments, currently unused.

Value

A list of coefficient, setting, and diagnostic tables/lists.

Summarize a psychometric data specification

Description

Summarize a psychometric data specification

Usage

## S3 method for class 'psychomatic_spec'
summary(object, ...)

Arguments

object

A psychomatic_spec object.

...

Additional arguments, currently unused.

Value

A list containing the data summary, item specification table, and decision log.