---
title: "Automating Item Removal Strategies with ItemRest"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Automating Item Removal Strategies with ItemRest}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

The `ItemRest` package is designed to automate the process of evaluating item removal strategies in Exploratory Factor Analysis (EFA). It helps identify low-quality items (those with low factor loadings or significant cross-loadings) and assesses the impact of their removal on the model's overall fit and structure. This guide provides a step-by-step walkthrough of the package's core functionalities.

## 1. Loading the Package

To begin the analysis, we first load the `ItemRest` library.

```{r setup}
library(ItemRest)
```

## 2. Preparing Example Data

For this demonstration, we will use the `bfi` (Big Five Inventory) dataset, which is available in the `psych` package. This dataset includes responses to 25 personality items. For a clean analysis, we will remove cases with missing data.

```{r data_prep}
# Ensure the 'psych' package is available
if (requireNamespace("psych", quietly = TRUE)) {
  data(bfi, package = "psych")
  
  # Select the personality items (first 25 columns)
  analysis_data <- bfi[, 1:25]
  
  # Omit rows with missing values for this example
  analysis_data <- na.omit(analysis_data)
  
  # View the first few rows of the prepared data
  head(analysis_data)
}
```

## 3. Running the Analysis

With the data prepared, we can now run the main `itemrest()` function. Based on the Big Five model, we set the `n_factors` argument to 5.

```{r run_analysis}
# Run the analysis
if (exists("analysis_data")) {
  results <- itemrest(
    data = analysis_data,
    n_factors = 5,
    cor_method = "pearson"
  )
}
```

As `itemrest()` runs, it prints messages to the console, informing you about the initial EFA results, the problematic items it has identified, and the progress of testing different removal combinations.

## 4. Reviewing the Results

After the analysis is complete, the `results` object contains all the output. We can use the `print()` method to display the summary tables.

### Optimal Strategy Report

By default, the `print()` function displays the "optimal" report. This table shows the strategies that resulted in a clean factor structure (no cross-loadings), sorted by the highest total explained variance.

```{r print_optimal}
if (exists("results")) {
  # Print the default optimal report
  print(results, report = "optimal")
}
```

In the table above, a user should typically look for the row where "Cross_Loading" is "No" and the "Total_Explained_Var" is highest. This often represents the most statistically sound item removal strategy.

### All Strategies Report

If you wish to see the results for every combination that was tested, you can set the `report` argument to `"all"`.

```{r print_all}
if (exists("results")) {
  # Print the report for all tested strategies
  print(results, report = "all")
}
```

This guide has demonstrated how to use the `ItemRest` package to automate and evaluate the item removal process in an EFA.