Package 'EpiQuestionR'

Description

Interactive HTML Table

Usage

as_datatable(object, ...)

Arguments

Value

DT widget.

Description

Convert Kaiser Table to flextable

Usage

as_flextable(object, ...)

Arguments

Value

A flextable object.

Description

Convert Kaiser Table to gt

Usage

as_gt(object, ...)

Arguments

Value

A gt_tbl object.

Description

Convert to knitr::kable

Usage

as_kable(object, ...)

Arguments

Value

knitr kable.

Description

Convert to tibble

Usage

## S3 method for class 'epi_kaiser'
as_tibble(x, ..., .rows = NULL, .name_repair = "check_unique", rownames = NULL)

Arguments

Value

A tibble.

Description

Converts an object of class epi_kaiser to a data frame containing the Kaiser criterion results.

Usage

## S3 method for class 'epi_kaiser'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'epi_kaiser'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame containing the Kaiser criterion results.

Description

Converts an '"epi_map"' object to its component-level MAP results table.

Usage

## S3 method for class 'epi_map'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame containing the MAP criterion results.

Description

Extract Eigenvalue Table

Usage

## S3 method for class 'epi_kaiser'
as.matrix(x, ...)

Arguments

Value

A matrix containing the eigenvalue table stored in the table component of the epi_kaiser object. The matrix provides a tabular representation of the eigenvalue results used to summarize and interpret factor retention.

Description

Adds the retained-factor recommendation as attributes.

Usage

## S3 method for class 'epi_kaiser'
augment(x, data = NULL, ...)

Arguments

Value

A tibble.

Description

Returns component- or factor-level parallel-analysis results with additional derived quantities useful for downstream analysis, visualization, and reporting.

Usage

## S3 method for class 'epi_parallel'
augment(x, data = NULL, newdata = NULL, ...)

Arguments

Details

Unlike augmentation methods for regression models, rows in this output represent components or factors rather than individual observations.

Value

A data frame containing augmented component- or factor-level results.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)
generics::augment(result)

Description

Draw a scree plot for an object of class epi_kaiser.

Usage

## S3 method for class 'epi_kaiser'
autoplot(object, show_cutoff = TRUE, show_labels = TRUE, ...)

Arguments

Value

A ggplot object.

Description

Creates a 'ggplot2' visualization of a Velicer MAP test.

Usage

## S3 method for class 'epi_map'
autoplot(
  object,
  type = c("map", "eigenvalues"),
  highlight = TRUE,
  show_line = TRUE,
  show_label = TRUE,
  title = NULL,
  subtitle = NULL,
  ...
)

Arguments

Details

The default '"map"' plot displays the MAP criterion against the number of partialled components and highlights the recommended dimensionality.

The '"eigenvalues"' plot creates a scree plot with a horizontal Kaiser reference line at an eigenvalue of 1.

Value

A 'ggplot' object.

Examples

set.seed(123)

dat <- matrix(
  rnorm(1000),
  ncol = 10
)

fit <- map_test(dat)

ggplot2::autoplot(fit)

ggplot2::autoplot(
  fit,
  type = "eigenvalues"
)

Description

Creates a publication-ready ggplot2 visualization of Horn's Parallel Analysis results.

Usage

## S3 method for class 'epi_parallel'
autoplot(
  object,
  type = c("parallel", "scree", "variance", "retention"),
  reference = c("criterion", "percentile", "mean", "both"),
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  legend_position = "bottom",
  base_size = 12,
  ...
)

Arguments

Details

Available plot types include:

"parallel"

Observed versus simulated eigenvalue curves.

"variance"

Percentage variance explained by each component.

"retention"

Observed-minus-reference eigenvalue differences.

Value

A ggplot object.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

ggplot2::autoplot(result)

ggplot2::autoplot(
  result,
  type = "parallel",
  reference = "both"
)

ggplot2::autoplot(
  result,
  type = "variance"
)

ggplot2::autoplot(
  result,
  type = "retention"
)

Description

Bayesian Information Criterion

Usage

bic(object)

Arguments

Value

Numeric.

Description

Extract Eigenvalues

Usage

## S3 method for class 'epi_kaiser'
coef(object, ...)

Arguments

Value

A named numeric vector containing the eigenvalues from the epi_kaiser object. The elements are named PC1, PC2, and so on, corresponding to successive principal components or factors. Each value represents the variance associated with the corresponding component.

Description

Extracts the number of components recommended by Velicer's MAP test.

Usage

## S3 method for class 'epi_map'
coef(object, ...)

Arguments

Value

A named integer containing the recommended number of components.

Examples

set.seed(123)

dat <- matrix(
  rnorm(500),
  ncol = 5
)

fit <- map_test(dat)

coef(fit)

Description

Extracts eigenvalue-based results from an "epi_parallel" object.

Usage

## S3 method for class 'epi_parallel'
coef(
  object,
  type = c("observed", "simulated_mean", "simulated_percentile", "difference",
    "retained", "all"),
  ...
)

Arguments

Details

By default, the method returns observed eigenvalues. Other available outputs include mean simulated eigenvalues, percentile reference eigenvalues, differences between observed and reference eigenvalues, and retained component or factor indices.

Value

Depending on type, returns a numeric vector, integer vector, or data frame.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

coef(result)
coef(result, type = "simulated_mean")
coef(result, type = "simulated_percentile")
coef(result, type = "difference")
coef(result, type = "retained")
coef(result, type = "all")

Description

Communalities

Usage

communalities(object)

Arguments

Value

Numeric vector.

Description

Draw a publication-quality bar chart of item communalities.

Usage

communality_plot(
  object,
  sort = TRUE,
  horizontal = TRUE,
  fill = "#2C7FB8",
  title = "Communalities"
)

Arguments

Value

A ggplot object.

Examples

set.seed(123)

latent <- rnorm(200)

example_data <- data.frame(
  Q1 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q2 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q3 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q4 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q5 = 0.6 * latent + rnorm(200, sd = 0.5)
)

fit <- efa(
  example_data,
  items = paste0("Q", 1:5),
  nfactors = 1
)

communality_plot(fit)

Description

Item Complexity

Usage

complexity(object)

Arguments

Value

Numeric vector.

Description

Performs Exploratory Factor Analysis (EFA) for questionnaire data.

Usage

efa(
  data,
  items,
  nfactors = NULL,
  extraction = "minres",
  rotation = "oblimin",
  scores = TRUE
)

Arguments

Details

Features: - KMO Measure - Bartlett Test - Parallel Analysis - Automatic Factor Selection - Multiple Extraction Methods - Multiple Rotations

Value

Object of class epi_efa

Examples

data(questionnaire_data)

efa(
  questionnaire_data,
  items = paste0("Q", 1:5),
  nfactors = 1
)

Description

EFA Fit Statistics

Usage

efa_fit(object)

Arguments

Value

Data frame.

Description

Publication-quality eigenvalue plot.

Usage

eigenvalue_plot(object, criterion = 1)

Arguments

Value

ggplot object.

Description

Eigenvalues

Usage

eigenvalues(x, ...)

Arguments

Value

A numeric vector containing the eigenvalues from the epi_kaiser object. Each element represents the amount of variance associated with the corresponding component or factor and is used in the Kaiser criterion for factor retention.

Description

Exports the Kaiser criterion results to a CSV file.

Usage

export_kaiser_csv(
  object,
  file = tempfile(pattern = "kaiser_results_", fileext = ".csv"),
  digits = object$digits
)

Arguments

Value

Invisibly returns the normalized output filename.

Description

Exports the Kaiser criterion results to an Excel workbook.

Usage

export_kaiser_excel(
  object,
  file = tempfile(pattern = "kaiser_results_", fileext = ".xlsx"),
  digits = 3
)

Arguments

Value

Invisibly returns the normalized output filename.

Description

Export Kaiser Results to JSON

Usage

export_kaiser_json(
  object,
  file = tempfile(pattern = "kaiser_results_", fileext = ".json")
)

Arguments

Value

Invisibly returns the filename.

Description

Export Markdown Report

Usage

export_kaiser_markdown(
  object,
  file = tempfile(pattern = "kaiser_report_", fileext = ".md"),
  digits = object$digits
)

Arguments

Value

Invisibly returns the filename.

Description

Export Kaiser Results to YAML

Usage

export_kaiser_yaml(
  object,
  file = tempfile(pattern = "kaiser_results_", fileext = ".yml")
)

Arguments

Value

Invisibly returns the filename.

Description

Exports results from a Velicer Minimum Average Partial (MAP) test to a file.

Usage

export_map(x, file, format = NULL, digits = 4L, overwrite = FALSE, ...)

Arguments

Details

Supported formats include CSV, Excel, and plain-text reports.

Value

The normalized path to the exported file, invisibly.

Examples

fit <- map_test(USArrests)

csv_file <- tempfile(fileext = ".csv")
xlsx_file <- tempfile(fileext = ".xlsx")
txt_file <- tempfile(fileext = ".txt")

export_map(
  fit,
  file = csv_file
)

export_map(
  fit,
  file = xlsx_file
)

export_map(
  fit,
  file = txt_file
)

file.exists(csv_file)
file.exists(xlsx_file)
file.exists(txt_file)

Description

Exports the component-level MAP criterion table to a CSV file.

Usage

export_map_csv(x, file, digits = 4L, overwrite = FALSE, row.names = FALSE, ...)

Arguments

Value

The normalized output path, invisibly.

Examples

fit <- map_test(USArrests)

file <- tempfile(fileext = ".csv")

export_map_csv(
  fit,
  file
)

Description

Exports MAP analysis results to an Excel workbook containing separate worksheets for the analysis summary, MAP criterion results, eigenvalues, settings, and metadata.

Usage

export_map_excel(x, file, digits = 4L, overwrite = FALSE, ...)

Arguments

Value

The normalized output path, invisibly.

Examples

fit <- map_test(USArrests)

file <- tempfile(fileext = ".xlsx")

export_map_excel(
  fit,
  file
)

Description

Writes a publication-ready textual report of a Velicer MAP analysis to a plain-text file.

Usage

export_map_report(
  x,
  file,
  style = c("standard", "apa", "brief"),
  digits = 4L,
  overwrite = FALSE,
  ...
)

Arguments

Value

The normalized output path, invisibly.

Examples

fit <- map_test(USArrests)

file <- tempfile(fileext = ".txt")

export_map_report(
  fit,
  file
)

Description

Saves a complete "epi_parallel" object to an RDS file. This preserves the full object structure, including results, settings, metadata, matrices, diagnostics, and other stored elements.

Usage

export_parallel(x, file, compress = TRUE)

Arguments

Value

Invisibly returns the normalized output file path.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

export_parallel(
  result,
  file = tempfile(fileext = ".rds")
)

Description

Generates and exports a text report from an "epi_parallel" object.

Usage

export_parallel_report(x, file, digits = 3, overwrite = FALSE)

Arguments

Details

The exported report contains methods, results, interpretation, and recommendation sections.

Value

Invisibly returns the normalized output file path.

Examples

set.seed(123)
dat <- data.frame(
    item1 = rnorm(30),
    item2 = rnorm(30),
    item3 = rnorm(30),
    item4 = rnorm(30),
    item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

tmp <- tempfile(fileext = ".txt")
export_parallel_report(
    result,
    file = tmp
)
file.exists(tmp)

Description

Exports tables generated from an "epi_parallel" object as CSV files.

Usage

export_parallel_tables(
  x,
  path = ".",
  prefix = "parallel_analysis",
  digits = 3,
  include_variance = TRUE,
  include_retention = TRUE,
  create_dir = TRUE,
  overwrite = FALSE
)

Arguments

Details

The function can export the analysis summary, component-level parallel analysis results, variance-explained results, and retention decisions.

Value

Invisibly returns a named character vector containing exported file paths.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

export_parallel_report(
  result,
  file = tempfile(fileext = ".txt")
)

Description

Draw a heatmap of the factor correlation matrix (Phi).

Usage

factor_correlation_plot(
  object,
  digits = 2,
  low = "#2166AC",
  mid = "white",
  high = "#B2182B"
)

Arguments

Details

This plot is only available for oblique rotations such as "oblimin", "promax", "quartimin", etc.

Value

ggplot object.

Description

Extract Factor Loadings

Usage

factor_loadings(object)

Arguments

Value

Matrix of factor loadings.

Description

Factor Scores

Usage

factor_scores(object)

Arguments

Value

Data frame.

Description

Returns a one-row summary suitable for model comparison.

Usage

## S3 method for class 'epi_kaiser'
glance(x, ...)

Arguments

Value

A tibble.

Description

Returns a one-row summary of a Velicer Minimum Average Partial (MAP) test.

Usage

## S3 method for class 'epi_map'
glance(x, ...)

Arguments

Value

A one-row data frame containing the recommended number of components, minimum MAP value, criterion, number of observations, number of variables, input type, correlation method, and maximum number of components evaluated.

Examples

set.seed(123)
dat <- matrix(rnorm(1000), ncol = 10)
fit <- map_test(dat)
generics::glance(fit)

Description

Returns a one-row summary of Horn's Parallel Analysis, including dataset dimensions, simulation settings, retention criterion, and the recommended number of retained components or factors.

Usage

## S3 method for class 'epi_parallel'
glance(x, ...)

Arguments

Value

A one-row data frame containing model-level summary information.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)
generics::glance(result)

Description

APA Caption

Usage

kaiser_caption(object)

Arguments

Value

Character string.

Description

Determines the recommended number of factors using the Kaiser criterion (retain factors with eigenvalues greater than 1).

Usage

kaiser_criterion(
  data,
  items = NULL,
  correlation = "auto",
  use = "pairwise.complete.obs",
  digits = 3,
  verbose = TRUE
)

Arguments

Value

An object of class epi_kaiser.

Examples

data(bfi, package = "psych")

dat <- bfi[
  complete.cases(bfi[, 1:6]),
  1:6
]

res <- kaiser_criterion(
  dat[1:200, ],
  verbose = FALSE
)

print(res)
summary(res)

Description

Kaiser Table Footnote

Usage

kaiser_footnote(object)

Arguments

Value

Character string.

Description

Table Notes

Usage

kaiser_notes(object)

Arguments

Value

Character vector.

Description

Kaiser Summary Table

Usage

kaiser_summary_table(object)

Arguments

Value

data.frame

Description

Create a publication-ready table summarizing the Kaiser criterion results.

Usage

kaiser_table(object, digits = object$digits, retain_label = "Yes")

Arguments

Value

A data.frame.

Description

Load Kaiser Object

Usage

load_kaiser(file)

Arguments

Value

Object of class epi_kaiser.

Description

Draws a publication-quality heatmap of factor loadings.

Usage

loading_heatmap(object, cutoff = 0.3, absolute = FALSE, digits = 2)

Arguments

Value

ggplot object.

Examples

set.seed(123)

latent <- rnorm(200)

example_data <- data.frame(
  Q1 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q2 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q3 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q4 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q5 = 0.6 * latent + rnorm(200, sd = 0.5)
)

fit <- efa(
  example_data,
  items = paste0("Q", 1:5),
  nfactors = 1
)

loading_heatmap(fit)

Description

Demonstrates a complete workflow for dimensionality assessment using Velicer's Minimum Average Partial (MAP) test.

Usage

map_analysis_example()

Details

The example generates simulated questionnaire data containing an underlying latent component structure and applies both the original and revised MAP criteria.

Value

A named list containing:

data

Simulated questionnaire data.

original

Results from the original MAP criterion.

revised

Results from the revised MAP criterion.

summary

A comparison table of recommendations.

Examples

example <- map_analysis_example()

example$original

summary(example$original)

map_table(example$original)

map_eigenvalue_table(example$original)

plot(example$original)

report_map(example$original)

Description

Returns eigenvalues and explained-variance information from an '"epi_map"' object.

Usage

map_eigenvalue_table(x, digits = 4L, percentage = FALSE)

Arguments

Value

A data frame containing component numbers, eigenvalues, variance proportions, and cumulative variance.

Examples

fit <- map_test(USArrests)
map_eigenvalue_table(fit)

Description

Generates a concise textual interpretation of the dimensionality recommendation from Velicer's MAP test.

Usage

map_interpretation(x, include_value = TRUE, digits = 4L)

Arguments

Value

A character string containing the interpretation.

Examples

fit <- map_test(USArrests)

map_interpretation(fit)

Description

Creates a compact one-row summary suitable for manuscripts, supplementary tables, or export.

Usage

map_report_table(x, digits = 4L)

Arguments

Value

A one-row data frame summarizing the MAP analysis.

Examples

fit <- map_test(USArrests)

map_report_table(fit)

Description

Extracts a publication-friendly table of MAP criterion values from an '"epi_map"' object.

Usage

map_table(x, digits = 4L, labels = TRUE)

Arguments

Value

A data frame containing the MAP results.

Examples

fit <- map_test(USArrests)
map_table(fit)

Description

Performs Velicer's Minimum Average Partial (MAP) test to estimate the optimal number of components to retain in dimensionality assessment.

Usage

map_test(
  data,
  method = c("original", "revised"),
  correlation = c("pearson", "spearman", "kendall"),
  use = "pairwise.complete.obs",
  is_corr = FALSE,
  max_components = NULL,
  tolerance = sqrt(.Machine$double.eps),
  ...
)

Arguments

Details

The MAP procedure sequentially partials principal components from a correlation matrix. After each component is removed, the average squared partial correlation among variables is calculated. The number of components associated with the minimum average partial correlation is selected as the recommended dimensionality.

A revised MAP criterion based on the average fourth power of the partial correlations is also available.

Velicer's MAP procedure begins with the original correlation matrix and computes an average measure of the off-diagonal correlations. Principal components are then sequentially removed. At each step, a residual covariance matrix is reconstructed and standardized to obtain a partial correlation matrix.

For the original MAP criterion, the statistic at step $k$ is the mean squared off-diagonal partial correlation.

For the revised MAP criterion, the statistic is the mean fourth power of the off-diagonal partial correlations.

The recommended number of components corresponds to the step with the smallest MAP statistic. Step zero represents the unpartialled correlation matrix and therefore allows the procedure to recommend zero components.

The MAP test is commonly used alongside parallel analysis when determining the dimensionality of questionnaire and psychometric data.

Value

An object of class '"epi_map"' containing:

n_components

Recommended number of components.

map_value

Minimum MAP statistic.

criterion

MAP criterion used.

results

A data frame containing the number of partialled components and corresponding MAP statistics.

eigenvalues

Eigenvalues of the input correlation matrix.

correlation_matrix

Correlation matrix used in the analysis.

settings

Analysis settings.

metadata

Information about the input data.

call

Matched function call.

References

Velicer, W. F. (1976). Determining the number of components from the matrix of partial correlations. Psychometrika, 41, 321-327.

Velicer, W. F., Eaton, C. A., & Fava, J. L. (2000). Construct explication through factor or component analysis: A review and evaluation of alternative procedures for determining the number of factors or components. In R. D. Goffin & E. Helmes (Eds.), Problems and Solutions in Human Assessment.

See Also

[parallel_analysis()]

Examples

set.seed(123)

dat <- data.frame(
  item1 = rnorm(300),
  item2 = rnorm(300),
  item3 = rnorm(300),
  item4 = rnorm(300),
  item5 = rnorm(300)
)

# Original MAP
fit <- map_test(dat)

fit

# Revised MAP
fit_revised <- map_test(
  dat,
  method = "revised"
)

fit_revised

# Correlation matrix input
R <- cor(dat)

fit_cor <- map_test(
  R,
  is_corr = TRUE
)

Description

Number of Retained Factors

Usage

nfactors(x, ...)

Arguments

Value

A single non-negative integer giving the number of factors retained by the Kaiser criterion. For an object of class epi_kaiser, this value is obtained from the nfactors component of the object.

Description

Performs Horn's parallel analysis to estimate the number of principal components or common factors to retain. Observed eigenvalues are compared with eigenvalues obtained from simulated random datasets.

Usage

parallel_analysis(
  data,
  analysis = c("pca", "fa"),
  correlation = c("auto", "pearson", "spearman", "polychoric", "tetrachoric", "mixed"),
  n_iter = 1000L,
  criterion = c("percentile", "mean"),
  percentile = 95,
  extraction = "minres",
  use = "pairwise.complete.obs",
  n_cores = 1L,
  seed = NULL,
  simulate = c("normal", "permutation"),
  adjust_pd = TRUE,
  diagnostics = TRUE,
  progress = interactive(),
  verbose = TRUE,
  ...
)

Arguments

Details

The function supports PCA and factor-analysis retention criteria, Pearson, Spearman, polychoric, tetrachoric, and mixed correlation matrices, serial and multicore simulation, reproducible random-number generation, and optional diagnostic information.

Value

An object of class "epi_parallel".

Description

Generates a human-readable interpretation of an "epi_parallel" object.

Usage

parallel_interpret(
  x,
  style = c("brief", "publication", "detailed"),
  digits = 3
)

Arguments

Details

Three reporting styles are available:

"brief"

Returns a concise statement of the recommended number of dimensions.

"publication"

Returns manuscript-ready results text.

"detailed"

Returns a more detailed interpretation including analysis settings, retention criterion, retained indices, and recommendation.

Value

A character scalar containing the interpretation.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

parallel_interpret(result)

Description

Creates a plot comparing the observed eigenvalues from an exploratory factor analysis with simulated reference eigenvalues from Horn's parallel analysis. The plot can be used to assess the number of factors that should be retained.

Usage

parallel_plot(object)

Arguments

Value

A ggplot object. The plot displays observed eigenvalues and simulated reference eigenvalues across components or factors. Components for which the observed eigenvalue exceeds the relevant simulated reference value are candidates for retention.

Description

Generates a structured report from an "epi_parallel" object suitable for manuscript preparation, thesis reporting, technical reports, or reproducible analysis pipelines.

Usage

parallel_report(
  x,
  digits = 3,
  include_variance = TRUE,
  include_retention = TRUE
)

Arguments

Details

The returned object contains methods text, results text, interpretation, recommendation, analysis settings, and publication-ready tables.

Value

An object of class "epi_parallel_report" containing:

methods

Methods-section text.

results

Results-section text.

interpretation

Detailed interpretation.

recommendation

Recommended dimensional solution.

summary_table

One-row analysis summary table.

results_table

Component- or factor-level results table.

variance_table

Optional variance-explained table.

retention_table

Optional retention-decision table.

settings

Analysis settings.

metadata

Analysis metadata.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

report <- parallel_report(result)

Description

Extracts selected narrative sections from an "epi_parallel_report" object.

Usage

parallel_report_text(
  x,
  section = c("all", "methods", "results", "interpretation", "recommendation")
)

Arguments

Value

A character scalar.

Description

Creates a table focused on the component or factor retention decision.

Usage

parallel_retention_table(x, digits = 3)

Arguments

Value

A data frame.

Description

Creates a compact one-row summary of the parallel analysis.

Usage

parallel_summary_table(x)

Arguments

Value

A one-row data frame.

Description

Extracts a clean component-level results table from an "epi_parallel" object.

Usage

parallel_table(x, digits = 3, include_decision = TRUE)

Arguments

Value

A data frame containing parallel analysis results.

Description

Creates a table containing observed eigenvalues, percentage variance explained, cumulative variance, and retention decisions.

Usage

parallel_variance_table(x, digits = 2)

Arguments

Value

A data frame.

Description

Eigenvalue Bar Plot

Usage

plot_eigenvalues(object)

Arguments

Value

A ggplot object containing a bar plot of the eigenvalues from the epi_kaiser object. Each bar represents the eigenvalue associated with a component or factor, allowing the relative magnitude of the eigenvalues to be visually assessed.

Description

Plot Dispatcher

Usage

plot_kaiser(object, which = c("scree", "eigenvalues", "variance"))

Arguments

Value

The plot generated for the selected value of which. If which = "scree", which = "eigenvalues", or which = "variance", the corresponding plot is displayed. The function returns the result invisibly, where applicable, primarily for its plotting side effect.

Description

Creates a plot showing the proportion of variance explained by each retained or available component or factor.

Usage

plot_variance(object)

Arguments

Value

A plot showing the proportion of variance explained by each component or factor. The plot is generated for visual interpretation of the contribution of each component or factor and is returned invisibly, where applicable.

Description

Produces publication-ready EFA graphics.

Usage

## S3 method for class 'epi_efa'
plot(x, type = c("scree", "parallel"), ...)

Arguments

Value

A plot.

Description

Creates a scree plot with the Kaiser cut-off (Eigenvalue = 1).

Usage

## S3 method for class 'epi_kaiser'
plot(
  x,
  type = c("base", "ggplot"),
  show_cutoff = TRUE,
  show_labels = TRUE,
  point_size = 19,
  line_size = 2,
  ...
)

Arguments

Value

For type = "base", no return value. The function is called for its side effect of producing a scree plot showing the eigenvalues and the Kaiser cut-off at Eigenvalue = 1. For type = "ggplot", returns a ggplot object representing the same scree plot, which can be further modified or displayed.

Description

Creates a base R plot for an object returned by [map_test()].

Usage

## S3 method for class 'epi_map'
plot(
  x,
  type = c("map", "eigenvalues"),
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  highlight = TRUE,
  show_line = TRUE,
  show_label = TRUE,
  ...
)

Arguments

Details

The default plot displays the MAP criterion across the number of partialled components. The recommended number of components is highlighted at the minimum MAP value.

An eigenvalue scree plot can also be requested.

Value

The input object 'x', invisibly.

Examples

set.seed(123)

dat <- matrix(
  rnorm(1000),
  ncol = 10
)

fit <- map_test(dat)

plot(fit)

plot(
  fit,
  type = "eigenvalues"
)

Description

Creates a base R visualization of Horn's Parallel Analysis results.

Usage

## S3 method for class 'epi_parallel'
plot(
  x,
  type = c("parallel", "scree", "variance", "retention"),
  reference = c("criterion", "percentile", "mean", "both"),
  main = NULL,
  xlab = "Component / Factor",
  ylab = NULL,
  legend = TRUE,
  ...
)

Arguments

Details

The default plot compares observed eigenvalues with simulated reference eigenvalues. Components or factors are retained when their observed eigenvalues exceed the selected simulated reference criterion.

Value

Invisibly returns x.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

plot(result)
plot(result, type = "parallel")
plot(result, type = "variance")
plot(result, type = "retention")
plot(result, reference = "both")

Description

Print EFA Results

Usage

## S3 method for class 'epi_efa'
print(x, digits = 3, ...)

Arguments

Value

Prints EFA summary.

Description

Print Kaiser Criterion Results

Usage

## S3 method for class 'epi_kaiser'
print(x, digits = x$digits, ...)

Arguments

Value

No visible return value. The epi_kaiser object is returned invisibly after a formatted summary of the Kaiser criterion results is printed to the console. The printed output summarizes the eigenvalue-based factor-retention results.

Description

Prints a concise summary of the results from Velicer's Minimum Average Partial (MAP) test.

Usage

## S3 method for class 'epi_map'
print(x, digits = 4L, ...)

Arguments

Value

The input object 'x', invisibly.

Examples

set.seed(123)

dat <- data.frame(
  item1 = rnorm(300),
  item2 = rnorm(300),
  item3 = rnorm(300),
  item4 = rnorm(300),
  item5 = rnorm(300)
)

fit <- map_test(dat)
print(fit)

Description

Prints a concise summary of a Horn's Parallel Analysis result produced by EpiQuestionR.

Usage

## S3 method for class 'epi_parallel'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Details

The print method reports the analysis method, number of variables, simulation settings, retention criterion, and the recommended number of components or factors.

Value

Invisibly returns x.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)
print(result)

Description

Prints a structured report generated by parallel_report().

Usage

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

Arguments

Value

Invisibly returns x.

Description

Prints a formatted summary of an object returned by summary.epi_parallel().

Usage

## S3 method for class 'summary_epi_parallel'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

Invisibly returns x.

Description

Prints a detailed summary of an object returned by 'summary.epi_map()'.

Usage

## S3 method for class 'summary.epi_map'
print(x, digits = 4L, ...)

Arguments

Value

The input object 'x', invisibly.

Description

Simulated questionnaire data included with EpiQuestionR.

Format

A data frame with 100 rows and 5 variables:

Q1

Likert score (1-5)

Q2

Likert score (1-5)

Q3

Likert score (1-5)

Q4

Likert score (1-5)

Q5

Likert score (1-5)

Source

Simulated data

Examples

data(questionnaire_data)
head(questionnaire_data)

Description

Reporting Sentence

Usage

report_kaiser(object)

Arguments

Value

Character string.

Description

Generates a publication-ready narrative report of a Velicer Minimum Average Partial (MAP) analysis.

Usage

report_map(
  x,
  style = c("standard", "apa", "brief"),
  digits = 4L,
  include_sample = TRUE,
  include_method = TRUE
)

Arguments

Value

A character string containing a report-ready interpretation.

Examples

set.seed(123)

dat <- matrix(
  rnorm(1000),
  ncol = 10
)

fit <- map_test(dat)

report_map(fit)

report_map(
  fit,
  style = "apa"
)

Description

Residual Correlation Matrix

Usage

residual_matrix(object)

Arguments

Value

Matrix.

Description

Extract the indices of components retained by the Kaiser criterion.

Usage

retained_components(object)

Arguments

Value

An integer vector containing the indices of retained components.

Description

RMSEA

Usage

rmsea(object)

Arguments

Value

Numeric.

Description

RMSR

Usage

rmsr(object)

Arguments

Value

Numeric.

Description

Export a publication-quality communality plot.

Usage

save_communality_plot(
  object,
  filename = tempfile(pattern = "communality_plot_", fileext = ".tiff"),
  width = 6,
  height = 5,
  dpi = 600
)

Arguments

Value

Invisibly returns the filename.

Description

Save EFA Plot

Usage

save_efa_plot(
  object,
  filename = tempfile(pattern = "efa_plot_", fileext = ".tiff"),
  type = "scree",
  width = 6,
  height = 5,
  dpi = 600
)

Arguments

Value

Invisibly returns a character string containing the path to the saved plot file. The function is primarily called for its side effect of writing the selected EFA plot to the specified output file.

Description

Saves the eigenvalue plot to an image file.

Usage

save_eigenvalue_plot(
  object,
  filename = tempfile(pattern = "eigenvalues_", fileext = ".tiff"),
  width = 6,
  height = 5,
  dpi = 600
)

Arguments

Value

Invisibly returns the saved plot.

Description

Saves the factor correlation plot to an image file.

Usage

save_factor_correlation_plot(
  object,
  filename = tempfile(pattern = "factor_correlation_", fileext = ".tiff"),
  width = 6,
  height = 6,
  dpi = 600
)

Arguments

Value

Invisibly returns the saved plot.

Description

Saves the complete epi_kaiser object to an RDS file.

Usage

save_kaiser(
  object,
  file = tempfile(pattern = "kaiser_results_", fileext = ".rds")
)

Arguments

Value

Invisibly returns the normalized output filename.

Description

Save Loading Heatmap

Usage

save_loading_heatmap(
  object,
  filename = tempfile(pattern = "loading_heatmap_", fileext = ".tiff"),
  width = 7,
  height = 6,
  dpi = 600
)

Arguments

Value

Invisibly returns the normalized path to the saved heatmap file as a character string. The function is primarily called for its side effect of writing the loading heatmap to the specified output file.

Description

Export a publication-quality uniqueness plot.

Usage

save_uniqueness_plot(
  object,
  filename = tempfile(pattern = "uniqueness_plot_", fileext = ".tiff"),
  width = 7,
  height = 6,
  dpi = 600
)

Arguments

Value

Invisibly returns the filename.

Description

Save the variance explained plot as a publication-quality figure.

Usage

save_variance_explained_plot(
  object,
  filename = tempfile(pattern = "variance_explained_", fileext = ".tiff"),
  width = 7,
  height = 5,
  dpi = 600
)

Arguments

Value

Invisibly returns the filename.

Description

Draw a scree plot for exploratory factor analysis or Kaiser criterion results.

Usage

scree_plot(object)

scree_plot(object)

Arguments

Value

For an epi_kaiser object, a ggplot object. For an epi_efa object, the plot is drawn using base graphics.

Description

Repeats Horn's parallel analysis across alternative simulation counts, percentile thresholds, or analysis specifications.

Usage

sensitivity_analysis(
  data,
  percentiles = c(0.9, 0.95, 0.99),
  n_iters = c(100, 500, 1000),
  analyses = c("pca", "fa"),
  correlation = "auto",
  seed = 123,
  n_cores = 1L,
  verbose = FALSE,
  ...
)

Arguments

Value

A data frame of sensitivity-analysis results with class "epi_parallel_sensitivity".

Description

Generates a reproducible synthetic questionnaire dataset with a latent multidimensional correlation structure. The resulting data can be used to demonstrate parallel analysis and related dimensionality functions in EpiQuestionR.

Usage

simulate_parallel_data(
  n = 300,
  n_items = 12,
  n_factors = 3,
  loading = 0.7,
  seed = NULL,
  ordinal = FALSE,
  categories = 5
)

Arguments

Details

This function is intended for examples, demonstrations, tutorials, and package testing. It should not be used as a substitute for real data in substantive analyses.

Value

A data frame with n rows and n_items columns.

Examples

questionnaire_data <- simulate_parallel_data(
    n = 300,
    n_items = 12,
    n_factors = 3,
    seed = 123
)

head(questionnaire_data)

Description

Summary of EFA

Usage

## S3 method for class 'epi_efa'
summary(object, digits = 3, cutoff = 0.3, ...)

Arguments

Value

Prints detailed summary.

Description

Summarize a Kaiser Criterion Analysis

Usage

## S3 method for class 'epi_kaiser'
summary(object, digits = object$digits, ...)

Arguments

Value

An object of class summary.epi_kaiser.

Description

Creates a detailed summary of an '"epi_map"' object produced by [map_test()].

Usage

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

Arguments

Value

An object of class '"summary.epi_map"' containing the MAP recommendation, MAP criterion values, eigenvalue information, settings, metadata, and original function call.

Examples

set.seed(123)

dat <- data.frame(
  item1 = rnorm(300),
  item2 = rnorm(300),
  item3 = rnorm(300),
  item4 = rnorm(300),
  item5 = rnorm(300)
)

fit <- map_test(dat)
summary(fit)

Description

Produces a structured summary of a Horn's Parallel Analysis result.

Usage

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

Arguments

Details

The returned summary includes analysis settings, observed eigenvalues, simulated reference eigenvalues, retention decisions, and optional variance information.

Value

An object of class "summary_epi_parallel" containing:

call

The original function call.

settings

Parallel analysis settings.

n_variables

Number of variables analyzed.

n_observations

Number of observations, when available.

n_retained

Recommended number of retained components or factors.

retained_indices

Indices of retained components or factors.

results

Component-level parallel analysis results.

variance

Optional variance-explained table.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)
summary(result)

Description

Convert a epi_kaiser object into a tidy tibble.

Usage

## S3 method for class 'epi_kaiser'
tidy(x, conf.int = FALSE, conf.level = 0.95, ...)

Arguments

Value

A tibble with one row per component.

Description

Converts the component-level results of a Velicer Minimum Average Partial (MAP) test into a tidy data frame.

Usage

## S3 method for class 'epi_map'
tidy(x, ...)

Arguments

Value

A data frame with one row for each number of partialled components. The output contains the component number, MAP criterion value, minimum indicator, recommendation indicator, and criterion used.

Examples

set.seed(123)
dat <- matrix(rnorm(1000), ncol = 10)
fit <- map_test(dat)
generics::tidy(fit)

Description

Converts component- or factor-level results from Horn's Parallel Analysis into a tidy data frame.

Usage

## S3 method for class 'epi_parallel'
tidy(x, conf.int = FALSE, conf.level = 0.95, ...)

Arguments

Details

Each row represents one component or factor. The output includes observed eigenvalues, simulated mean eigenvalues, simulated percentile eigenvalues, the reference eigenvalue used for retention, the difference between the observed and reference eigenvalues, and the retention decision.

Value

A data frame with one row per component or factor and columns:

component

Component or factor index.

observed

Observed eigenvalue.

simulated_mean

Mean simulated eigenvalue.

simulated_percentile

Percentile-based simulated eigenvalue.

reference

Reference eigenvalue used for the retention decision.

difference

Observed eigenvalue minus the reference eigenvalue.

retained

Logical retention indicator.

decision

Human-readable retention decision.

Examples

set.seed(123)
dat <- data.frame(
  item1 = rnorm(30),
  item2 = rnorm(30),
  item3 = rnorm(30),
  item4 = rnorm(30),
  item5 = rnorm(30)
)
result <- parallel_analysis(dat, n_iter = 100)

generics::tidy(result)

Description

Converts an object returned by 'summary.epi_map()' into a tidy component-level data frame.

Usage

## S3 method for class 'summary.epi_map'
tidy(x, ...)

Arguments

Value

A tidy data frame.

Description

Tucker Lewis Index

Usage

tli(object)

Arguments

Value

Numeric.

Description

Uniqueness

Usage

uniqueness(object)

Arguments

Value

Numeric vector.

Description

Draw a publication-quality bar chart of item uniqueness values.

Usage

uniqueness_plot(
  object,
  sort = TRUE,
  horizontal = TRUE,
  fill = "#D95F02",
  title = "Uniqueness",
  digits = 2
)

Arguments

Details

Uniqueness represents the proportion of variance not explained by the extracted common factors (Uniqueness = 1 - Communality).

Value

A ggplot object.

Examples

set.seed(123)

latent <- rnorm(200)

example_data <- data.frame(
  Q1 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q2 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q3 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q4 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q5 = 0.6 * latent + rnorm(200, sd = 0.5)
)

fit <- efa(
  example_data,
  items = paste0("Q", 1:5),
  nfactors = 1
)

uniqueness_plot(fit)

Description

Variance Explained

Usage

variance_explained(x, ...)

Arguments

Value

A numeric vector containing the proportion of total variance explained by each component or factor in the epi_kaiser object. Each value represents the relative contribution of the corresponding component or factor to the total variance and can be used to assess its importance.

Description

Draw a publication-quality plot showing the percentage of variance explained by each extracted factor and the cumulative percentage of variance explained.

Usage

variance_explained_plot(
  object,
  cumulative = TRUE,
  bar_fill = "#4C78A8",
  line_colour = "#D62728",
  point_colour = "#D62728",
  title = "Variance Explained"
)

Arguments

Value

A ggplot object.

Examples

set.seed(123)

latent <- rnorm(200)

example_data <- data.frame(
  Q1 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q2 = 0.8 * latent + rnorm(200, sd = 0.5),
  Q3 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q4 = 0.7 * latent + rnorm(200, sd = 0.5),
  Q5 = 0.6 * latent + rnorm(200, sd = 0.5)
)

fit <- efa(
  example_data,
  items = paste0("Q", 1:5),
  nfactors = 1
)

variance_explained_plot(fit)

Description

Extracts the variance explained from an exploratory factor analysis object.

Usage

## S3 method for class 'epi_efa'
variance_explained(x, ...)

Arguments

Value

A data frame containing variance explained statistics.

Description

Variance Explained Table

Usage

variance_table(object)

Arguments

Value

data.frame