Package 'sigPCA'

Compute Eigenvalues of the Covariance Matrix

Description

Compute Eigenvalues of the Covariance Matrix

Usage

compute_eigenvalues(data)

Arguments

data	A numeric matrix or data frame. Observations in rows, features in columns.

Value

A numeric vector of eigenvalues, sorted decreasingly.

Examples

set.seed(123)
mat <- matrix(rnorm(50), nrow = 10, ncol = 5)
compute_eigenvalues(mat)

---

Marchenko–Pastur Theoretical Bounds

Description

Computes the lower and upper bounds of the Marchenko–Pastur distribution, based on the aspect ratio of the data matrix.

Usage

marchenko_pastur_bounds(p, n)

Arguments

p	Number of features (columns)
n	Number of observations (rows)

Value

A named list with lambda_min and lambda_max.

Examples

bounds <- marchenko_pastur_bounds(p = 10, n = 100)
print(bounds)

---

Plot PCA Eigenvalue Spectrum with Marchenko–Pastur Bounds

Description

Visualizes the eigenvalue spectrum of a PCA, highlighting significant components based on Marchenko–Pastur bounds.

Usage

plot_sigPCA(eigenvalues, mp_bounds, highlight = NULL, add_null = NULL)

Arguments

eigenvalues	Numeric vector of eigenvalues from the real data.
mp_bounds	A list with lambda_min and lambda_max (from marchenko_pastur_bounds()).
highlight	Logical vector (same length as eigenvalues). Defaults to eigenvalues > lambda_max.
add_null	Optional numeric vector of null eigenvalues (e.g. from permutation). Default: NULL.

Value

A ggplot2 object.

Examples

set.seed(123)
x <- matrix(rnorm(100 * 10), nrow = 100, ncol = 10)
result <- sigPCA_mp(x)
plot_sigPCA(result$eigenvalues, result$mp_bounds)

---

Plot PCA Eigenvalue Histogram with Marchenko-Pastur Bounds

Description

PCA eigenvalue histogram, showing the empirical eigenvalue distribution together with the Marchenko-Pastur theoretical bounds. Original design by Enrique Hernandez Lemus

Usage

plot_sigPCA_histogram(x, mp_bounds = NULL, bins = 30)

Arguments

x	A result from sigPCA_mp(), sigPCA(method = "mp"), or a numeric vector of eigenvalues.
mp_bounds	Optional list with lambda_min and lambda_max. Required if x is a numeric vector.
bins	Number of histogram bins. Default: 30.

Value

A ggplot2 object.

Examples

set.seed(123)
x <- matrix(rnorm(100 * 10), nrow = 100, ncol = 10)
result <- sigPCA_mp(x)
plot_sigPCA_histogram(result)

---

Unified PCA Significance Wrapper

Description

Runs significance testing on PCA eigenvalues using either Marchenko–Pastur bounds, permutation tests, or both. Results are returned as a structured list.

Usage

sigPCA(
  data,
  method = c("mp", "perm", "both"),
  num_permutations = 1000,
  center = TRUE,
  scale. = TRUE
)

Arguments

data	A numeric matrix or data frame.
method	One of "mp", "perm", or "both". Default: "mp".
num_permutations	Integer. Used only if method is "perm" or "both".
center, scale.	Logical. Passed to scale(). Default: TRUE.

Value

A structured list containing method results.

Examples

set.seed(123)
x <- matrix(rnorm(100 * 10), nrow = 100, ncol = 10)
sigPCA(x, method = "mp")
sigPCA(x, method = "perm", num_permutations = 100)
sigPCA(x, method = "both", num_permutations = 100)

---

PCA Significance Based on Marchenko–Pastur Distribution

Description

Tests which principal components have eigenvalues beyond the theoretical bounds of the Marchenko–Pastur distribution.

Usage

sigPCA_mp(data, center = TRUE, scale. = TRUE)

Arguments

data	A numeric matrix or data frame. Observations in rows, variables in columns.
center	Logical. Whether to center the variables. Default: TRUE.
scale.	Logical. Whether to scale variables to unit variance. Default: TRUE.

Value

A list with:

eigenvalues

All eigenvalues of the covariance matrix

mp_bounds

A list with lambda_min and lambda_max

significant_components

Indices of eigenvalues > lambda_max

Examples

set.seed(123)
x <- matrix(rnorm(100 * 10), nrow = 100, ncol = 10)
result <- sigPCA_mp(x)
result$significant_components

---

PCA Significance via Permutation Test

Description

Assesses the statistical significance of PCA components using column-wise permutation of the input data to create a null distribution of eigenvalues.

Usage

sigPCA_perm(data, num_permutations = 1000, center = TRUE, scale. = TRUE)

Arguments

data	A numeric matrix or data frame.
num_permutations	Number of permutations to generate. Default: 1000.
center	Logical. Whether to center variables before analysis. Default: TRUE.
scale.	Logical. Whether to scale variables before analysis. Default: TRUE.

Value

A list with:

eigenvalues

Observed eigenvalues

null_eigenvalues

Matrix of eigenvalues from permutations

pvalues

Empirical p-values per component

significant_components

Indices where p < 0.05

Examples

set.seed(123)
x <- matrix(rnorm(100 * 10), nrow = 100, ncol = 10)
result <- sigPCA_perm(x, num_permutations = 100)
result$significant_components

---