FAPA: Factor Analytic Profile Analysis of Ipsatized Data

Description

Implements Factor Analytic Profile Analysis of Ipsatized Data (FAPA), a metric inferential framework for pattern detection and person-level reconstruction in multivariate profile data.

After row-centering (ipsatization) to remove profile elevation, FAPA applies singular value decomposition (SVD) to recover shared core profiles and individual pattern weights, supporting the following workflow:

1. Ipsatization — load_and_ipsatize removes person-level elevation, isolating within-person pattern structure.

2. Core estimation — fapa_core performs SVD and returns the core-profile matrix, person weights, and variance decomposition.

3. Stage 1: Dimensionality — fapa_pa applies variance-matched Horn's parallel analysis to determine how many components to retain.

4. Stage 2: Subspace stability — fapa_procrustes assesses dimensional stability via bootstrap principal angles.

5. Stage 3: Profile replicability — fapa_tucker computes Tucker's congruence coefficients across bootstrap resamples.

6. Inference — fapa_bca provides BCa bootstrap confidence intervals for core-profile coordinates using the canonical boot implementation.

7. Reconstruction — fapa_person projects each person onto the retained core profiles and reports reconstruction R^2 and optional bootstrap CIs for selected participants.

Key references

• Horn, J. L. (1965). A rationale and test for the number of factors in factor analysis. Psychometrika, 30(2), 179–185.

• Davison, A. C., & Hinkley, D. V. (1997). Bootstrap Methods and Their Application. Cambridge University Press.

• Lorenzo-Seva, U., & ten Berge, J. M. F. (2006). Tucker's congruence coefficient as a meaningful index of factor similarity. Methodology, 2(2), 57–64.

• Kim, S.-K. (2024). Factorization of person response profiles to identify summative profiles carrying central response patterns. Psychological Methods, 29(4), 723–730. doi:10.1037/met0000568

Author(s)

Se-Kang Kim se-kang.kim@bcm.edu

See Also

Useful links:

• https://github.com/sekangakim/FAPA

• Report bugs at https://github.com/sekangakim/FAPA/issues

Align bootstrap core-profile columns to a reference via inner-product signs

Description

For each column k, flips the sign of Xb[, k] if its inner product with X0[, k] is negative. This prevents the bootstrap distribution of core-profile coordinates from becoming bimodal due to SVD sign ambiguity across resamples.

Usage

.align_signs(X0, Xb)

Arguments

Value

Xb with columns sign-aligned to X0.

BCa bootstrap confidence intervals for FAPA core profiles

Description

Computes BCa (bias-corrected and accelerated) bootstrap confidence intervals for every coordinate of every retained core profile, using the canonical implementation in boot and boot.ci.

Usage

fapa_bca(Xtilde, K, B = 2000, alpha = 0.05, seed = NULL)

Arguments

Details

Sign ambiguity across bootstrap resamples is handled inside the statistic function via an inner-product alignment rule (see .align_signs), ensuring that each bootstrap distribution is unimodal before BCa adjustment.

Value

A named list:

ci

List of K data frames (one per core profile), each with columns Ori, Mean, SE, Lower, Upper, BCaLower, BCaUpper.

X0

Original core-profile matrix (I \times K).

boot_out

The full boot object for downstream diagnostics.

boot_X

3-D array (B \times I \times K) of bootstrap profiles.

K, B, alpha, varnames

Inputs echoed for plotting and output.

References

Davison, A. C., & Hinkley, D. V. (1997). Bootstrap Methods and Their Application. Cambridge University Press. doi:10.1017/CBO9780511802843

See Also

plot_fapa_core, write_fapa_results

Core FAPA estimation via SVD

Description

Computes the thin singular value decomposition (SVD) of an ipsatized person-by-variable matrix, returning the K core profiles, person weights, singular values, and variance-accounting summaries.

Usage

fapa_core(Xtilde, K, direction = NULL)

Arguments

Details

The core-profile (scale) matrix is defined as \mathbf{X} = \mathbf{V}\boldsymbol{\Sigma}, so that each individual's ipsatized profile satisfies \tilde{\mathbf{m}}_p = \mathbf{X} \mathbf{u}_p exactly (rank-K reconstruction).

Signs of the singular vectors are normalised so that the element with the largest absolute value in each core-profile column is positive.

Value

A named list:

U

Person-weight matrix (P \times K).

S

Singular values (length K).

V

Right singular vectors (I \times K).

X

Core-profile matrix \mathbf{V}\boldsymbol{\Sigma} (I \times K).

total_var

Total ipsatized variance (Frobenius norm^2).

var_k

Variance per component (\sigma_k^2).

prop_var

Proportion of variance per component.

cum_var

Cumulative proportion of variance.

person_cor

Normalised person-core correlations (P \times K).

direction

Sign vector applied (for reproducibility).

K

Number of components extracted.

References

Kim, S.-K. (2024). Factorization of person response profiles to identify summative profiles carrying central response patterns. Psychological Methods, 29(4), 723–730. doi:10.1037/met0000568

Stage 1: Horn's Parallel Analysis (variance-matched bootstrap)

Description

Determines the number of components to retain from the SVD of an ipsatized data matrix using a variance-matched bootstrap version of Horn's (1965) parallel analysis.

Usage

fapa_pa(Xtilde, B = 2000, alpha = 0.05, seed = NULL)

Arguments

Details

For each of B bootstrap replicates, a random matrix of identical dimensions is row-centred (ipsatized) and then rescaled to the same Frobenius norm as Xtilde. This variance-matching step is essential: without it, raw-score data trivially dominates N(0,1) random matrices and PA retains all components. Components whose observed \sigma^2_k exceeds the (1-\alpha) quantile of the matched null distribution are retained.

Value

A named list:

n_retain

Number of components retained.

obs_sv2

Observed squared singular values (length = K_{\max}).

thresh

Bootstrap (1-\alpha) quantile per component.

prop_obs

Proportion of variance per observed component.

prop_rand

Mean proportion of variance per random component.

rand_sv2

Full B \times K_{\max} matrix of random \sigma^2.

total_var

Total ipsatized variance.

alpha, B

Inputs echoed for reporting.

References

Horn, J. L. (1965). A rationale and test for the number of factors in factor analysis. Psychometrika, 30(2), 179–185.

See Also

print_pa, plot_pa_scree

Person-level reconstruction and pattern weights

Description

Projects each person onto the retained core profiles, returning reconstruction R^2, pattern weights \mathbf{u}_p, and normalised person-core correlations. Optionally computes percentile bootstrap confidence intervals for pattern weights of selected participants.

Usage

fapa_person(
  Xtilde,
  fit,
  participants = NULL,
  B_boot = 2000,
  alpha = 0.05,
  seed = NULL
)

Arguments

Value

A named list:

weights

Data frame (P rows) with columns Person, Level, R2, w1 ... wK, rDim1 ... rDimK.

weights_B

Matrix of bootstrap summary statistics for participants (or NULL).

R2_k

Partial R^2 per dimension.

R2_mean

Mean person reconstruction R^2 across all persons.

Stage 2: Procrustes stability via principal angles

Description

For each of B bootstrap resamples of the ipsatized data matrix, computes the K right singular vectors and measures the principal angles (in degrees) between the bootstrap subspace and the original K-dimensional right singular vector subspace.

Usage

fapa_procrustes(Xtilde, K, B = 2000, angle_thresh = 30, seed = NULL)

Arguments

Details

A bootstrap replicate is declared stable when all K principal angles are strictly less than angle_thresh. This criterion confirms that the bootstrap subspace is nearly parallel to the original, providing geometric evidence of dimensional stability.

Value

A named list:

angles_mat

B \times K matrix of principal angles (degrees).

angle_mean, angle_sd

Per-dimension mean and SD of angles.

angle_q025, angle_q975

Per-dimension 2.5th and 97.5th percentiles.

n_stable

Number of replicates satisfying the stability criterion.

prop_stable

Proportion of stable replicates.

angle_thresh, K, B

Inputs echoed for reporting.

References

Bjorck, A., & Golub, G. H. (1973). Numerical methods for computing angles between linear subspaces. Mathematics of Computation, 27(123), 579–594.

See Also

print_procrustes, plot_principal_angles

Synthetic EDI-2 profile data for FAPA examples

Description

A simulated dataset approximating the structure of the calibration sample used in Kim (in preparation). It contains no real clinical records. The data comprise 500 synthetic cases on 22 variables: 11 pre-treatment and 11 post-treatment administrations of the Eating Disorder Inventory-2 (EDI-2) subscales.

Usage

fapa_simdata

Format

A data frame with 500 rows and 22 columns. The first 11 columns contain pre-treatment EDI-2 subscale scores (Drive for Thinness through Social Insecurity) and the remaining 11 columns contain the corresponding post-treatment scores. Column names follow the convention Before_<n>_<abbr> and After_<n>_<abbr>, where n is the subscale index and abbr is a two-letter abbreviation. Scores are integers in the range 0–40.

Details

The 11 EDI-2 subscales are:

• Dt Drive for Thinness

• Bu Bulimia

• Bd Body Dissatisfaction

• In Ineffectiveness

• Pf Perfectionism

• Id Interpersonal Distrust

• Ia Interoceptive Awareness

• Mf Maturity Fears

• As Asceticism

• Ir Impulse Regulation

• Si Social Insecurity

The latent structure was constructed to approximate two components: a normative symptom gradient (CP1) and a pre-/post-treatment change contrast (CP2).

Source

Simulated. See data-raw/simulate_fapa_data.R.

References

Garner, D. M. (1991). Eating Disorder Inventory-2 Manual. Psychological Assessment Resources.

Examples

data(fapa_simdata)
dim(fapa_simdata)

## Quick ipsatization check
Xtilde <- as.matrix(fapa_simdata) - rowMeans(as.matrix(fapa_simdata))
range(rowSums(Xtilde))   # should be ~0

Stage 3: Profile replicability via Tucker's congruence coefficients

Description

For each of B bootstrap resamples, computes Tucker's congruence coefficient (CC) between each original core profile and its bootstrap counterpart. Sign ambiguity is resolved by choosing the sign that maximises the absolute CC before storing.

Usage

fapa_tucker(Xtilde, K, B = 2000, cc_thresh = 0.85, seed = NULL)

Arguments

Details

Conventional thresholds (Lorenzo-Seva & ten Berge, 2006):

• CC \ge 0.95: high similarity ("factor replication").

• CC \ge 0.85: fair similarity.

• CC < 0.85: poor similarity.

Value

A named list:

cc_mat

B \times K matrix of Tucker CCs.

cc_mean, cc_sd

Per-profile mean and SD of CCs.

cc_q025, cc_q975

Per-profile 2.5th and 97.5th percentiles.

cc_thresh, K, B

Inputs echoed for reporting.

References

Lorenzo-Seva, U., & ten Berge, J. M. F. (2006). Tucker's congruence coefficient as a meaningful index of factor similarity. Methodology, 2(2), 57–64. doi:10.1027/1614-2241.2.2.57

Tucker, L. R. (1951). A method for synthesis of factor analysis studies (Personnel Research Section Report No. 984). Department of the Army.

See Also

print_tucker, plot_tucker_cc

Load a CSV and ipsatize (row-centre) it

Description

Reads a person-by-variable CSV file, assigns column labels, and removes each person's mean across variables (ipsatization), isolating within-person pattern structure from overall profile elevation.

Usage

load_and_ipsatize(path, col_labels)

Arguments

Value

A named list with elements:

raw

Original data as a data.frame.

ipsatized

Row-centred matrix (\tilde{M}).

row_means

Numeric vector of per-person means (profile levels).

varnames

The supplied col_labels.

Examples

## Create a small temporary CSV and ipsatize it
tmp <- tempfile(fileext = ".csv")
write.csv(matrix(sample(1:5, 30, replace = TRUE), nrow = 6),
          tmp, row.names = FALSE)
dat <- load_and_ipsatize(tmp, col_labels = paste0("V", 1:5))
round(rowSums(dat$ipsatized), 10)  # should all be 0
unlink(tmp)

Plot a core profile with BCa confidence intervals

Description

Displays the ith core profile from a fapa_bca result, split at a variable boundary (e.g., pre vs post) with BCa CI bands. Variables before split_at are drawn in red (dashed), variables from split_at + 1 onward in blue (solid).

Usage

plot_fapa_core(
  bca,
  i = 1,
  split_at = 11,
  main = NULL,
  ylab = "Core-Profile Coordinate"
)

Arguments

Value

Invisibly returns NULL. Called for its side-effect.

Scree plot for Horn's parallel analysis

Description

Plots observed \sigma^2_k versus the random 95th-percentile reference line, with a vertical cut at the retention boundary.

Usage

plot_pa_scree(pa, main = "Horn's Parallel Analysis — Scree")

Arguments

Value

Invisibly returns NULL.

Overlay a person's ipsatized profile against FAPA core profiles

Description

Plots the standardized ipsatized profile of person p alongside each of the first K core profiles (also standardized), one panel per dimension.

Usage

plot_person_match(bca, Xtilde, p = 1, K = 2)

Arguments

Value

Invisibly returns NULL.

Distribution plots for Stage 2 principal angles

Description

Draws one histogram per dimension showing the bootstrap distribution of principal angles, with the stability threshold marked as a vertical line.

Usage

plot_principal_angles(pr)

Arguments

Value

Invisibly returns NULL.

Distribution plots for Stage 3 Tucker congruence coefficients

Description

Draws one histogram per core profile showing the bootstrap distribution of Tucker CCs, with reference lines at the fair (default 0.85) and high (0.95) thresholds.

Usage

plot_tucker_cc(tc, cc_thresh = 0.85)

Arguments

Value

Invisibly returns NULL.

Compute principal angles between two column spaces (degrees)

Description

Compute principal angles between two column spaces (degrees)

Usage

principal_angles_deg(A, B)

Arguments

Value

Numeric vector of principal angles in degrees (length = ncol(A)).

Print a summary of Stage 1 parallel analysis results

Description

Print a summary of Stage 1 parallel analysis results

Usage

print_pa(pa)

Arguments

Value

Invisibly returns NULL. Called for its side-effect of printing a formatted table to the console.

Print a summary of Stage 2 principal-angle results

Description

Print a summary of Stage 2 principal-angle results

Usage

print_procrustes(pr, K_pa = NULL)

Arguments

Value

Invisibly returns NULL.

Print a summary of Stage 3 Tucker CC results

Description

Print a summary of Stage 3 Tucker CC results

Usage

print_tucker(tc, cc_thresh, K_pa = NULL)

Arguments

Value

Invisibly returns NULL.

Tucker's congruence coefficient between two vectors

Description

Computes the cosine of the angle between x and y, equivalent to Tucker's (1951) congruence coefficient.

Usage

tucker_cc(x, y)

Arguments

Value

Scalar; NA if either vector has zero norm.

Write core-profile BCa CI tables to CSV

Description

Writes one CSV file per retained core profile, containing the original coordinates together with bootstrap mean, SE, percentile, and BCa confidence bounds.

Usage

write_fapa_results(bca, prefix)

Arguments

Value

Invisibly returns a character vector of file paths written.

Write three-stage verification results to CSV

Description

Writes one CSV file for each of the three verification stages.

Usage

write_verification(pa, pr, tc, prefix, K_pa = NULL)

Arguments

Value

Invisibly returns a named character vector of the three file paths.