---
title: "Introduction to reliacoef"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to reliacoef}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

The `reliacoef` package is designed to compute and compare a wide range of unidimensional and multidimensional reliability coefficients commonly used in psychometrics and social science research.

## 1. Unidimensional Reliability

Unidimensional reliability is appropriate when a scale is assumed to measure a single underlying factor. The `unirel()` function provides a comprehensive suite of estimates, allowing researchers to compare multiple coefficients beyond the traditional Cronbach's alpha.

### Example: Comparing Estimates
You can pass a data frame or a covariance matrix to `unirel()`.

```r
# Using the included Graham1 dataset
result_uni <- unirel(Graham1)
result_uni
```

`unirel()` computes the following:
- **Coefficient Alpha**: The most common but often criticized for strict assumptions.
- **Jöreskog's Congeneric Reliability**: Also known as Composite Reliability or Omega.
- **Feldt-Gilmer Coefficient**: A practical alternative that maintains congeneric assumptions.
- **Ten Berge & Zegers' mu series**: A series of lower bounds that improve upon alpha.

---

## 2. Multidimensional Reliability

When a scale consists of several sub-dimensions, multidimensional reliability coefficients provide a more accurate picture of measurement quality. The `multirel()` function summarizes these estimates.

### Defining the Structure (The `until` argument)
Multidimensional functions require the `until` vector to define the boundaries of sub-constructs. For example, if a 12-item scale has 4 sub-dimensions (3 items each), use `until = c(3, 6, 9)`.

### Summary Analysis with `multirel()`
We can use the provided `Cho_multi` dataset (a 12x12 covariance matrix) to see a global comparison.

```r
# Comparing various multidimensional coefficients
result_multi <- multirel(Cho_multi, until = c(3, 6, 9))
result_multi
```

### Individual Model Functions
You can also call specific models directly if your theory supports a particular structure:

- **`bifactor()`**: Computes reliability based on a general factor and specific group factors.
- **`second_order()`**: For hierarchical models where sub-factors load onto a higher-order factor.
- **`stratified_alpha()`**: A weighted sum of alpha coefficients for sub-tests.
- **`nunnally()`**: Uses the bottom-up approach to combine sub-test reliabilities.

```r
# Analyzing general factor saturation via Bifactor model
bif_res <- bifactor(Cho_multi, until = c(3, 6, 9))
b_omega_h <- bif_res$omega_hierarchical
```

---

## 3. Testing Statistical Assumptions

Before selecting a reliability coefficient, it is critical to test whether the data fits the underlying model. The `test.tauequivalence()` function performs a chi-square difference test between the essential tau-equivalence model (required for alpha) and the congeneric model.

```r
# Testing the assumption for Coefficient Alpha
test_res <- test.tauequivalence(Graham1)
test_res
```
If the p-value is significant, Jöreskog's congeneric reliability is generally preferred over coefficient alpha.

## 4. The `reliacoef` Class

All primary functions in this package return an object of class `reliacoef`. These objects are designed for clarity:
- **Clean Output**: A customized print method displays results in a formatted table.
- **CFA Details**: For model-based coefficients, you can access detailed fit indices and parameter estimates using `$fit_indices` and `$estimates`.

```r
# Accessing detailed CFA fit indices
bif_res$fit_indices
```