Package {APD}

Average Proportional Distance (APD)

Description

Average Proportional Distance (APD) is a measure of a test's internal consistency that focuses on the average difference between item scores. To calculate it, the absolute difference is obtained for every pair of item scores, these differences are averaged, and the result is divided by the number of response options minus one to obtain a proportional score ranging from 0 to 1.

Usage

APD(
  data,
  ncat,
  ci = FALSE,
  conf.level = 0.95,
  B = 1000,
  cimethod = "perc",
  nd = 3
)

Arguments

Details

The APD is computed in three main steps:

1. Compute the absolute difference between every possible pair of item scores for each respondent.

2. Average all absolute differences across respondents and item pairs to obtain the average difference AD.

3. Divide AD by ncat - 1 to rescale it to the proportional metric:

   APD = AD / (n_{\mathrm{cat}} - 1).

The APD ranges from 0 (perfect internal consistency) to 1 (maximum possible inconsistency given the response scale). Lower values reflect greater similarity among item scores, indicating stronger internal consistency.

When ci = TRUE, APD confidence intervals are obtained by nonparametric bootstrap resampling. Three interval types are available:

• "bca" - bias-corrected and accelerated interval.

• "perc" - percentile interval.

• "norm" - normal-approximation interval.

Value

A one-row data.frame with the following columns:

• Estimate: character string identifying the reported coefficient.

• AD: average absolute difference between all pairs of item scores.

• APD: average proportional distance.

• lwr.ci: lower confidence bound for APD when ci = TRUE; otherwise NA.

• upr.ci: upper confidence bound for APD when ci = TRUE; otherwise NA.

Interpretation

APD quantifies the average disagreement between item scores on a 0 to 1 scale. The following informal guidelines may help interpretation:

• APD < 0.20: typically indicates very good internal consistency.

• 0.20 <= APD <= 0.25: often acceptable depending on the construct.

• APD > 0.25: may signal weaker internal consistency or heterogeneous item content.

These values were suggested by Sturman et al. (2009), but they are not strict cutoffs and should be interpreted alongside other reliability evidence (e.g., alpha, omega) and substantive test characteristics.

References

Sturman, E. D., Cribbie, R. A., & Flett, G. L. (2009). The average distance between item values: A novel approach for estimating internal consistency. Journal of Psychoeducational Assessment, 27(5), 409-420. doi:10.1177/0734282908330937

Examples

set.seed(123)
x <- data.frame(matrix(sample(1:5, 200 * 5, replace = TRUE), ncol = 5))

# APD without confidence interval
APD(x, ncat = 5, ci = FALSE, conf.level = 0.95, B = 500,
    cimethod = "perc", nd = 3)

# APD with 95% percentile confidence interval
APD(x, ncat = 5, ci = TRUE, conf.level = 0.95, B = 300,
    cimethod = "perc", nd = 3)

# APD with BCa confidence interval
APD(x, ncat = 5, ci = TRUE, conf.level = 0.95, B = 300,
    cimethod = "bca", nd = 3)

Item-Level Average Proportional Distance (APDitem)

Description

Computes the item-level Average Proportional Distance (APD) for a single data frame or matrix of item responses. For each item, the function calculates its average absolute discrepancy against all remaining items across respondents, and rescales it to the proportional metric. For a scale with p items and K response categories, the total APD is defined as the average absolute discrepancy across all within-person item pairs, divided by K-1. Extending this logic, the item-level APD for item j is the average absolute discrepancy between that item and all remaining items across respondents, also divided by K-1. Under this definition, the total APD equals the mean of the item-level APD values.

Usage

APDitem(
  data,
  ncat,
  ci = FALSE,
  conf.level = 0.95,
  B = 500,
  cimethod = c("perc", "bca", "norm")
)

Arguments

Details

For each item j, the average distance is computed as:

AvDiff_j = \frac{1}{n(p-1)} \sum_{i=1}^{n} \sum_{k \neq j} |x_{ij} - x_{ik}|

The proportional index is:

APD_j = \frac{AvDiff_j}{n_{cat} - 1}

Under this definition, the mean of the item-level APD values equals the total APD computed from the same data matrix.

When ci = TRUE, bootstrap confidence intervals are computed for the item-level APD values.

Value

A data.frame with one row per item and the following columns:

• item: item name.

• AvDiff: average absolute discrepancy of the item against all remaining items.

• APD: proportional item-level APD.

• %cont: percentage contribution of the item to the sum of item-level APD values.

• lwr.ci: lower confidence bound (if ci = TRUE).

• upr.ci: upper confidence bound (if ci = TRUE).

References

Sturman, D., Cribbie, R. A., & Flett, G. L. (2009). The average distance between item values: A novel approach for estimating internal consistency. Journal of Psychoeducational Assessment, 27(5), 409-420. doi:10.1177/0734282908330937

Item-Level Average Proportional Distance for Multiple Groups (APDitemmg)

Description

Computes item-level Average Proportional Distance (APD) separately for each group defined by a grouping variable.

Computes the item-level Average Proportional Distance (APD) separately within multiple groups defined by a grouping variable.

Usage

APDitemmg(
  data,
  group,
  ncat,
  ci = FALSE,
  conf.level = 0.95,
  B = 500,
  cimethod = c("perc", "bca", "norm")
)

APDitemmg(
  data,
  group,
  ncat,
  ci = FALSE,
  conf.level = 0.95,
  B = 500,
  cimethod = c("perc", "bca", "norm")
)

Arguments

Details

The function splits the data according to group, applies APDitem() to each subgroup, and returns a named list of results.

APDitemmg() extends the logic of APDitem() to multigroup settings by estimating item-level APD indices independently within each group.

For each item, the procedure computes its absolute discrepancy with all remaining items across respondents within the same group, averages those discrepancies, and rescales the result to the proportional metric:

APD_j = \frac{AD_j}{K - 1}

where AD_j is the average absolute discrepancy involving item j, and K is the number of response categories.

Conceptually, this means that for each item, its absolute discrepancy with all other items is computed across respondents and averaged. This extension is congruent with the spirit of the original APD method, because Sturman et al. (2009) emphasized that APD provides direct information about differences among item scores and penalizes large average discrepancies between items.

The resulting item-level APD values provide a fine-grained diagnostic of the contribution of each item to the overall response inconsistency within each group.

When ci = TRUE, bootstrap confidence intervals are computed independently for each item within each group.

Value

A named list. Each element corresponds to one group and contains a data.frame with columns: item, AvDiff, APD, %cont, lwr.ci, and upr.ci (the last two only if ci = TRUE).

A named list in which each element corresponds to a group. Each group contains a data.frame with the following columns:

• item: item name.

• AvDiff: average absolute discrepancy involving the item.

• APD: proportional item-level APD value.

• %cont: percentage contribution of the item to the sum of item-level APD values within the group.

• lwr.ci: lower confidence interval bound (if ci = TRUE).

• upr.ci: upper confidence interval bound (if ci = TRUE).

References

Sturman, D., Cribbie, R. A., & Flett, G. L. (2009). The average distance between item values: A novel approach for estimating internal consistency. Journal of Psychoeducational Assessment, 27(5), 409-420. doi:10.1177/0734282908330937

Examples

set.seed(123)

dat <- data.frame(
  group = rep(c("A", "B"), each = 100),
  Item1 = sample(1:5, 200, replace = TRUE),
  Item2 = sample(1:5, 200, replace = TRUE),
  Item3 = sample(1:5, 200, replace = TRUE),
  Item4 = sample(1:5, 200, replace = TRUE)
)

APDitemmg(
  data = dat,
  group = "group",
  ncat = 5,
  ci = FALSE
)

Average Proportional Distance for multiple groups

Description

Computes the Average Proportional Distance (APD) for two or more groups. APD is an index of internal consistency based on the average absolute difference between item scores, scaled to the range [0, 1] by dividing by ncat - 1.

For each group, the function can optionally estimate bootstrap confidence intervals. Pairwise differences in APD between groups are then quantified using a MOVER-type (Method Of Variance Estimates Recovery) confidence interval, which combines the uncertainty of the two APD estimates. This MOVER approach is considered experimental but reasonable for exploratory comparison of APD values across groups. Note: Missing values are handled by pairwise deletion at the level of item differences. That is, a given paired difference is omitted only when one or both item responses involved in that difference are missing.

Usage

APDmg(
  data,
  ncat,
  group,
  ci = TRUE,
  conf.level = 0.95,
  B = 1000,
  cimethod = "bca",
  nd = 3
)

Arguments

Value

A list with two elements:

• group_results: A data.frame containing, for each group:

  • group: Group label.

  • APD: Estimated Average Proportional Distance.

  • LCI: Lower confidence limit (or NA if ci = FALSE).

  • UCI: Upper confidence limit (or NA if ci = FALSE).

• comparisons: A data.frame containing all pairwise comparisons between groups:

  • group1, group2: The groups compared.

  • Difference: APD difference (APD_group1 - APD_group2).

  • Lower_CI, Upper_CI: MOVER-based confidence interval for the difference. Empty if only one group is present.

References

Newcombe, R. G. (1998). Interval estimation for the difference between independent proportions: comparison of eleven methods. Statistics in Medicine, 17, 873-890. doi:10.1002/(SICI)1097-0258(19980430)17:8<873::AID-SIM779>3.0.CO;2-I

Sturman, D., Cribbie, R. A., & Flett, G. L. (2009). The average distance between item values: A novel approach for estimating internal consistency. Journal of Psychoeducational Assessment, 27(5), 409-420. doi:10.1177/0734282908330937

Zou, G. Y., & Donner, A. (2008). Construction of confidence limits about effect measures: A general approach. Statistics in Medicine, 27, 1693-1702. doi:10.1002/sim.3095

Examples

set.seed(123)

# Simulated data: 30 respondents, 5 items, 2 groups
dat <- data.frame(
  item1 = sample(1:5, 30, replace = TRUE),
  item2 = sample(1:5, 30, replace = TRUE),
  item3 = sample(1:5, 30, replace = TRUE),
  item4 = sample(1:5, 30, replace = TRUE),
  item5 = sample(1:5, 30, replace = TRUE)
)

grp <- rep(c("Group_A", "Group_B"), each = 15)

res <- APDmg(data = dat, ncat = 5, group = grp,
             ci = TRUE, conf.level = 0.95, B = 200,
             cimethod = "bca")

res$APD.group
res$comparisons

Average Inter-Item Correlation with Optional Bootstrap Confidence Intervals

Description

Computes the average inter-item correlation (aii) for a set of items, with optional bootstrap confidence intervals. It supports Pearson, Spearman, and polychoric correlations and allows grouped analysis. Fisher's z-transformation is used to average correlations appropriately. When confidence intervals are requested and groups are provided, the function also computes MOVER-type confidence intervals and Wald-type tests for the difference in aii between all pairs of groups, as well as a global test of homogeneity across groups.

Usage

aiicor(
  data,
  rmethod = "pearson",
  ci = FALSE,
  conf.level = 0.95,
  nboot = 1000,
  ci.method = "perc",
  nd = 3,
  group = NULL
)

Arguments

Details

For each group, the function estimates an inter-item correlation matrix using the method specified in rmethod. The unique pairwise inter-item correlations are then extracted from the lower-triangular part of the matrix, excluding the diagonal:

r_{ij}, \quad i > j.

In practice, this corresponds to extracting cor_matrix[lower.tri(cor_matrix)], which yields the set of non-redundant inter-item correlations.

These correlations are averaged after applying Fisher's transformation z = \mathrm{arctanh}(r), and the final estimate is back-transformed to the correlation metric. This yields an average inter-item correlation that is less biased than the direct arithmetic mean of raw correlations, especially when the correlations are moderately large.

When rmethod = "poly", the function uses psych::polychoric with correct = TRUE to estimate the polychoric correlation matrix. The resulting average inter-item correlation is still summarized through Fisher's z-transformation as a practical approximation.

When ci = TRUE, confidence intervals are estimated by nonparametric bootstrap. Bootstrap resampling is performed by resampling rows (respondents) from the original data matrix within each group, rather than resampling already-computed correlations. Thus, in each bootstrap sample, the correlation matrix is recomputed from the resampled item data, and the average inter-item correlation is recalculated from that matrix. This row-wise bootstrap strategy is especially important for rmethod = "poly", because the polychoric matrix must be re-estimated in each resample.

When more than one group is present and ci = TRUE, two types of inferential summaries are provided:

(1) Global test of homogeneity (Q statistic, fixed-effects framework).

Let \hat{\theta}_g denote the average inter-item correlation (aii) for group g, and let [L_g, U_g] be its confidence interval at level conf.level. An approximate standard error for each group is obtained by assuming a normal-based interval:

\mathrm{SE}_g \approx \frac{U_g - L_g}{2 z_{1-\alpha/2}},

where \alpha = 1 - \text{conf.level} and z_{1-\alpha/2} is the corresponding standard normal quantile. The within-group variances are then V_g = \mathrm{SE}_g^2, and fixed-effect weights are defined as w_g = 1 / V_g.

A pooled (fixed-effect) average inter-item correlation is computed as

\hat{\theta}_{\mathrm{pooled}} = \frac{\sum_g w_g \hat{\theta}_g}{\sum_g w_g}.

The Cochran-type Q statistic for testing homogeneity of the group-specific aii values is

Q = \sum_g w_g (\hat{\theta}_g - \hat{\theta}_{\mathrm{pooled}})^2,

which is compared to a chi-square distribution with G - 1 degrees of freedom, where G is the number of groups. The null hypothesis is that all groups share the same underlying average inter-item correlation (fixed-effects perspective).

In addition, a descriptive index of heterogeneity is reported:

I^2 = \max\left(0, \frac{Q - (G-1)}{Q}\right) \times 100,

representing the percentage of between-group variability in the aii estimates that exceeds what would be expected from sampling error alone (within the fixed-effects approximation).

(2) Pairwise differences between groups (MOVER CI and Wald-type test).

For each pair of groups g_1 and g_2, the function reports the difference in average inter-item correlations:

D = \hat{\theta}_{g_1} - \hat{\theta}_{g_2}.

A MOVER-type (Method Of Variance Estimates Recovery) confidence interval for D is constructed using only the endpoints of the group-specific confidence intervals [L_{g}, U_{g}]. For example, one form of the MOVER interval is

\mathrm{CI}_{\Delta} = \left[ D \pm \sqrt{(\hat{\theta}_{g_1} - L_{g_1})^2 + (U_{g_2} - \hat{\theta}_{g_2})^2} \right],

with the complementary limits obtained by swapping the roles of the lower and upper bounds. This approach combines the uncertainty from both groups without requiring explicit variance formulas for the difference.

In parallel, a Wald-type test is provided for each pairwise difference. Using the same approximate standard errors derived from the confidence intervals,

\mathrm{SE}_{g} \approx \frac{U_{g} - L_{g}}{2 z_{1-\alpha/2}},

the standard error of the difference is

\mathrm{SE}_{D} = \sqrt{\mathrm{SE}_{g_1}^2 + \mathrm{SE}_{g_2}^2},

assuming independence between groups. The Wald statistic is then

z = \frac{D}{\mathrm{SE}_{D}},

with a two-sided p-value computed from the standard normal distribution. These Wald p-values and the MOVER confidence intervals are both based on approximations derived from the group-level intervals and should be interpreted as exploratory inferential summaries rather than exact tests.

Value

The returned object depends on ci and the number of groups:

• If ci = FALSE, the function returns a data.frame with one row per group and the columns group, avg_r, min, max, and sd.

• If ci = TRUE and only one group is present (including group = NULL), the function returns a data.frame with the columns group, avg_r, lwr.ci, upr.ci, min, max, and sd.

• If ci = TRUE and more than one group is present, the function returns a list with three components:

  • group_results: A data.frame containing, for each group:

    • group: Group label.

    • avg_r: Average inter-item correlation (back-transformed from Fisher's z).

    • lwr.ci, upr.ci: Lower and upper bounds of the bootstrap confidence interval.

    • min, max: Minimum and maximum inter-item correlations in the matrix.

    • sd: Standard deviation of inter-item correlations.

  • comparisons: A data.frame containing all pairwise comparisons between groups:

    • group1, group2: The groups being compared.

    • diff: Difference in average inter-item correlations (avg_r_group1 - avg_r_group2).

    • lwr.ci, upr.ci: MOVER-type confidence interval limits for the difference.

    • z: Wald-type test statistic for the difference.

    • p.value: Two-sided p-value associated with the Wald statistic.

  • global_test: A data.frame with a single row (labelled "test") summarizing the fixed-effects homogeneity test across all groups:

    • Q: Cochran-type Q statistic for homogeneity of the group-specific aii values.

    • df: Degrees of freedom (G - 1, where G is the number of groups).

    • p.value: p-value for the Q statistic under the chi-square approximation.

    • I2: Percentage of heterogeneity (I^2), expressing the proportion of between-group variability beyond sampling error (in %).

    • k: Number of groups included in the test.

    • pooled: Fixed-effect pooled estimate of the average inter-item correlation.

References

Briggs, S.R. and Cheek, J.M. (1986). The role of factor analysis in the development and evaluation of personality scales. Journal of Personality, 54, 106-148. doi:10.1111/j.1467-6494.1986.tb00391.x

Clark, L. A., & Watson, D. (1995). Constructing validity: Basic issues in objective scale development. Psychological Assessment, 7(3), 309-319. doi:10.1037/1040-3590.7.3.309

Piedmont, R.L. (2014). Inter-item correlations. In A.C. Michalos (Ed.), Encyclopedia of Quality of Life and Well-Being Research. Springer, Dordrecht. doi:10.1007/978-94-007-0753-5_1493

Park, J., van den Broek, K. L., Bhullar, N., Ogunbode, C. A., Schermer, J. A., Doran, R., Ardi, R., Hanss, D., Maran, D. A., Albzour, M., Aquino, S. D., Ayanian, A. H., Chegeni, R., Chukwuorji, J. B. C., Enea, V., Ghanbarian, E., Ghorayeb, J., Jiang, F., Kehinde, O. A., ... Yadav, R. (2022). Comparison of the inter-item correlations of the Big Five Inventory-10 (BFI-10) between Western and non-Western contexts. Personality and Individual Differences 196, 111751. doi:10.1016/j.paid.2022.111751

Examples

set.seed(123)

data <- data.frame(
  item1 = rnorm(100),
  item2 = rnorm(100),
  item3 = rnorm(100)
)

# Single-group point estimate only
aiicor(data, ci = FALSE)

# Single-group estimate with bootstrap CI
aiicor(data, ci = TRUE)

# Two groups with MOVER and Wald comparisons plus global test
grp <- rep(c("A", "B"), each = 50)
res <- aiicor(data, rmethod = "spearman", ci = TRUE, group = grp)
res$group_results
res$comparisons
res$global_test

First eigenvalue from average inter-item association (Kaiser's formula)

Description

Computes the average inter-item association, the first eigenvalue using Kaiser's formula, and the percentage of variance explained by the first component.

Usage

aiicorEigen(data, rmethod = c("pearson", "spearman", "poly"), nd = 3)

Arguments

Value

A data.frame with:

• n.items: Number of items (k).

• rmean: Average inter-item association (mean of the lower triangular elements of the association matrix, excluding the diagonal).

• lambda1.Kaiser: First eigenvalue according to Kaiser's formula, 1 + (k - 1)\,\bar{r}.

• pct.var: Percentage of total variance explained by the first component.

References

Cureton, E. E. (1971). A Measure of the Average Intercorrelation. Educational and Psychological Measurement, 31(3), 627-628. doi:10.1177/001316447103100303

Kaiser, H. F. (1968). A Measure of the Average Intercorrelation. Educational and Psychological Measurement, 28(2), 245-247. doi:10.1177/001316446802800203

Examples

# Example with continuous items (Pearson correlation)
set.seed(123)
x1 <- rnorm(200)
x2 <- 0.6 * x1 + rnorm(200, sd = 0.8)
x3 <- 0.6 * x1 + rnorm(200, sd = 0.8)
dat <- data.frame(x1, x2, x3)

aiicorEigen(dat, rmethod = "pearson")
aiicorEigen(dat, rmethod = "spearman")



# Example with ordinal items (polychoric correlation)
# Uncomment if the 'psych' package is installed
dat_ord <- data.frame(
  item1 = cut(x1, breaks = 4, labels = FALSE),
  item2 = cut(x2, breaks = 4, labels = FALSE),
  item3 = cut(x3, breaks = 4, labels = FALSE))

aiicorEigen(dat_ord, rmethod = "poly")

Root-Mean-Square Inter-Item Correlation (Meyer, 1975)

Description

Computes the root-mean-square inter-item correlation (RMSIIC), introduced by Meyer (1975) as a measure of the average inter-item association based on the squared correlation matrix. The function can also compute group-specific estimates and pairwise group comparisons using the MOVER method.

Usage

rmsiic(
  data,
  method = c("pearson", "spearman"),
  nd = 3,
  ci = FALSE,
  B = 1000,
  conf.level = 0.95,
  method.ci = c("perc", "bca", "norm"),
  group = NULL
)

Arguments

Details

Let R be the p \times p correlation matrix of a set of items. Meyer (1975) defined the root-mean-square inter-item correlation as:

\mathrm{RMSIIC} = \sqrt{ \frac{ \mathrm{tr}(R^{2}) - p }{ p(p - 1) } } ,

where \mathrm{tr}(R^{2}) denotes the trace of the squared correlation matrix. This equals the square root of the average squared inter-item correlation, excluding the diagonal.

Meyer argued that RMSIIC is preferable to the simple mean correlation because:

• it treats negative correlations as positive contributions (via squaring), avoiding sign cancellation,

• it gives proportionally more weight to strong correlations,

• it reflects overall item homogeneity more sensitively.

When group is supplied, the statistic is computed independently within each group. Differences between groups are evaluated using the MOVER method, combining group-specific confidence intervals into an interval for the difference without assuming asymptotic normality.

Bootstrap confidence intervals may be computed using percentile, BCa, or normal-based methods.

Value

A list with:

• group_results: A data frame with one row per group (or a single row for the total sample), containing:

  • group: Group label.

  • n.items: Number of items.

  • rms.iic: RMSIIC estimate.

  • lwr.ci, upr.ci: Bootstrap confidence limits (if ci=TRUE).

• comparisons: A data frame with MOVER-based pairwise group comparisons:

  • group1, group2: Groups being compared.

  • diff: Difference in RMSIIC (group1 - group2).

  • lwr.ci, upr.ci: MOVER confidence limits.

References

Meyer, E. P. (1975). A measure of the average intercorrelation. Educational and Psychological Measurement, 35(1), 67-72. doi:10.1177/001316447503500107

Examples

set.seed(123)
X <- matrix(rnorm(200), ncol = 5)

# Single-sample RMSIIC
rmsiic(X)

# Bootstrap CI
rmsiic(X, ci = TRUE, B = 500)

# Group comparison using MOVER
g <- rep(c("A","B"), each = 20)
rmsiic(X[1:40, ], group = g, ci = TRUE, B = 300)