Package 'FAPA'

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 [email protected]

See Also

Useful links:

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

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

---

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

Xtilde	Numeric matrix (persons $\times$ variables), already ipsatized.
K	Integer. Number of core profiles (must equal the retained dimensionality from fapa_pa).
B	Integer. Number of bootstrap replicates. Default 2000.
alpha	Numeric. Two-tailed significance level. Default 0.05.
seed	Integer or NULL. Random seed.

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

Xtilde	Numeric matrix (persons $\times$ variables), already ipsatized.
K	Integer. Number of components to extract.
direction	Integer vector of length $K$ with values $\pm 1$, overriding the automatic sign convention. NULL (default) triggers automatic normalisation.

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

Xtilde	Numeric matrix (persons $\times$ variables), already ipsatized.
B	Integer. Number of bootstrap replicates. Default 2000.
alpha	Numeric. Significance level. Default 0.05.
seed	Integer or NULL. Random seed for reproducibility.

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

Xtilde	Numeric matrix (persons $\times$ variables), already ipsatized.
fit	A list returned by fapa_core.
participants	Integer vector of row indices for which bootstrap CIs are desired, or NULL to skip individual inference.
B_boot	Integer. Bootstrap replicates for participant CIs. Default 2000.
alpha	Numeric. Two-tailed significance level. Default 0.05.
seed	Integer or NULL. Random seed.

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

Xtilde	Numeric matrix (persons $\times$ variables), already ipsatized.
K	Integer. Number of dimensions to assess.
B	Integer. Number of bootstrap replicates. Default 2000.
angle_thresh	Numeric. Upper stability bound in degrees. Default 30.
seed	Integer or NULL. Random seed.

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

Xtilde	Numeric matrix (persons $\times$ variables), already ipsatized.
K	Integer. Number of core profiles to assess.
B	Integer. Number of bootstrap replicates. Default 2000.
cc_thresh	Numeric. Acceptability lower bound. Default 0.85.
seed	Integer or NULL. Random seed.

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

path	Character. Path to a CSV file with a header row.
col_labels	Character vector of length equal to the number of columns. Column names are replaced with these labels after loading.

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 $i$th 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

bca	A list returned by fapa_bca.
i	Integer. Which core profile to plot. Default 1.
split_at	Integer. Index at which to switch colour/line-type. Default 11 (11 pre + 11 post EDI-2 subscales).
main	Character. Plot title. Default auto-generated.
ylab	Character. Y-axis label.

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

pa	A list returned by fapa_pa.
main	Character. Plot title.

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

bca	A list returned by fapa_bca.
Xtilde	Numeric matrix (persons $\times$ variables), ipsatized.
p	Integer. Row index of the focal person. Default 1.
K	Integer. Number of core profiles to overlay. Default 2.

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

pr	A list returned by fapa_procrustes.

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

tc	A list returned by fapa_tucker.
cc_thresh	Numeric. Fair-similarity reference line. Default 0.85.

Value

Invisibly returns NULL.

---

Print a summary of Stage 1 parallel analysis results

Description

Print a summary of Stage 1 parallel analysis results

Usage

print_pa(pa)

Arguments

pa	A list returned by fapa_pa.

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

pr	A list returned by fapa_procrustes.
K_pa	Integer or NULL. If supplied, a PA_Retained column is appended showing which dimensions were retained by PA.

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

tc	A list returned by fapa_tucker.
cc_thresh	Numeric. Acceptability cutoff to display (should match the value used in fapa_tucker).
K_pa	Integer or NULL. If supplied, a PA_Retained column is appended.

Value

Invisibly returns NULL.

---

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

bca	A list returned by fapa_bca.
prefix	Character. Base name for output files (e.g., "fapa"). Files are named <prefix>_CoreProfile1.csv, etc.

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

pa	A list returned by fapa_pa.
pr	A list returned by fapa_procrustes.
tc	A list returned by fapa_tucker.
prefix	Character. Base name for output files.
K_pa	Integer or NULL. If supplied, a PA_Retained column is appended to the Stage 2 and Stage 3 CSVs.

Value

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

---