Generate Copula Factor Models Data and Perform Tests

Description

This function simulates data based on a Copula Factor Model structure. It generates factor scores, factor loadings, and error terms (using specified Copula distributions), combines them to create the observed data, and then performs KMO and Bartlett's tests on the generated data.

Usage

CoFM(n = 1000, p = 10, m = 5, type = "Clayton", param = 2)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# Clayton copula errors (toy size)
res1 <- CoFM::CoFM(n = 200, p = 6, m = 2, type = "Clayton", param = 2)
res1$KMO
res1$Bartlett

# Gumbel copula errors (toy size)
res2 <- CoFM::CoFM(n = 150, p = 6, m = 2, type = "Gumbel", param = 2)
head(res2$data)

Generate Copula-Distributed Error Terms

Description

Generate random samples (error terms) from various copula distributions, including Archimedean (Clayton, Gumbel, Frank), Elliptical (t, Normal), Mixed, and Extreme-Value (Galambos) copulas. Useful for simulation studies involving non-normal error structures.

Usage

Copula_errors(
  n,
  type = "Clayton",
  dim = 2,
  param = NULL,
  extra_params = list()
)

Arguments

Value

A numeric matrix of dimension (n x dim) containing the generated random samples.

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# Example 1: Clayton Copula (toy example)
U_clayton <- Copula_errors(n = 200, type = "Clayton", dim = 2, param = 2)
head(U_clayton)

# Example 2: t-Copula with degrees of freedom (toy example)
U_t <- Copula_errors(
  n = 200, type = "t", dim = 2, param = 0.7,
  extra_params = list(df = 4)
)
head(U_t)

# Example 3: Multivariate Normal Copula (dim = 3)
# normalCopula() expects the upper-triangular correlations as a vector:
# (rho_12, rho_13, rho_23) for dim=3
rho_vec <- c(0.5, 0.3, 0.4)
U_normal <- Copula_errors(n = 200, type = "Normal", dim = 3, param = rho_vec)
head(U_normal)

Perform Factor Analysis via Principal Component (FanPC) for CoFM

Description

This function estimates factor loadings and uniquenesses using a principal-component (FanPC) approach. It then compares these estimates with the true parameters (A and D) to calculate Mean Squared Errors (MSE) and relative loss metrics. This is designed to work with data generated by the CoFM function.

Usage

FanPC_CoFM(data, m, A, D)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# 1. Generate toy data using CoFM
sim_result <- CoFM(n = 200, p = 6, m = 2, type = "Clayton", param = 2.0)

# 2. Extract true parameters and observed data
true_A <- sim_result$True_Params$A
true_D <- sim_result$True_Params$D
obs_data <- sim_result$data

# 3. Apply FanPC and compute error metrics
fanpc_result <- FanPC_CoFM(data = obs_data, m = 2, A = true_A, D = true_D)

# 4. Inspect results
fanpc_result$MSESigmaA
fanpc_result$MSESigmaD
head(fanpc_result$AF)

Perform Basic FanPC Factor Analysis

Description

This function performs factor analysis using a principal-component (FanPC) approach. It estimates the factor loading matrix and uniquenesses from the correlation matrix of the input data. Unlike FanPC_CoFM, this function does not calculate error metrics against true parameters, making it suitable for simple estimation tasks.

Usage

FanPC_basic(data, m)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# 1. Generate synthetic data using CoFM (toy example)
sim <- CoFM(n = 200, p = 6, m = 2, type = "Clayton", param = 2.0)
obs_data <- sim$data

# 2. Apply FanPC method (extract 2 factors)
fit <- FanPC_basic(data = obs_data, m = 2)

# 3. Inspect estimates
head(fit$AF)  # Estimated loadings
fit$DF        # Estimated uniquenesses

Perform PCA-based Factor Estimation for CoFM

Description

This function performs Principal Component Analysis (PCA) on the correlation matrix of the data to estimate factor loadings and uniquenesses. It is designed to work with data generated by the CoFM function and calculates error metrics (MSE and relative loss) by comparing estimates against the true parameters.

Usage

PC_CoFM(data, m, A, D)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# 1. Generate toy data using CoFM
sim_result <- CoFM(n = 200, p = 6, m = 2, type = "Clayton", param = 2.0)

# 2. Extract true parameters and observed data
true_A <- sim_result$True_Params$A
true_D <- sim_result$True_Params$D
obs_data <- sim_result$data

# 3. Apply PC method to estimate parameters and compute errors
pc_result <- PC_CoFM(data = obs_data, m = 2, A = true_A, D = true_D)

# 4. Inspect results
pc_result$MSESigmaA
pc_result$MSESigmaD
head(pc_result$A2)

Perform Projected PCA (PPC) Estimation for CoFM

Description

This function performs Projected Principal Component Analysis (PPC) on the input data to estimate factor loadings and uniquenesses. It is designed to work with data generated by the CoFM function and calculates error metrics (MSE and relative loss) by comparing estimates against true parameters. The method projects data onto a subspace (using a projection operator) before performing PCA.

Usage

PPC_CoFM(data, m, A, D)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# 1. Generate toy data using CoFM
sim_result <- CoFM(n = 200, p = 6, m = 2, type = "Clayton", param = 2.0)

# 2. Extract true parameters and observed data
true_A <- sim_result$True_Params$A
true_D <- sim_result$True_Params$D
obs_data <- sim_result$data

# 3. Apply PPC method and compute errors
ppc_result <- PPC_CoFM(data = obs_data, m = 2, A = true_A, D = true_D)

# 4. Inspect results
ppc_result$MSESigmaA
ppc_result$MSESigmaD
head(ppc_result$Ap2)

Perform Basic Projected PCA (PPC) Estimation

Description

This function performs Projected Principal Component Analysis (PPC) to estimate factor loadings and specific variances. It projects the data onto a specific subspace before performing eigen decomposition. Unlike PPC_CoFM, this function does not calculate error metrics against true parameters.

Usage

PPC_basic(data, m)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)

# 1. Generate toy data using CoFM
sim <- CoFM(n = 200, p = 6, m = 2, type = "Clayton", param = 2.0)
obs_data <- sim$data

# 2. Apply PPC method (extract 2 factors)
fit <- PPC_basic(data = obs_data, m = 2)

# 3. Inspect estimates
head(fit$Apro)
fit$Dpro

Center-then-PCA: Projection on the Orthogonal Complement of the Mean Vector

Description

This function performs a specific type of Projected PCA where the data is projected onto the orthogonal complement of the mean vector. It effectively applies the centering projection P = I - (1/n)J (where J is the all-ones matrix), optionally rescales the columns, and then performs PCA on the covariance matrix. This allows estimation of factor loadings and residual variances after removing the mean structure.

Usage

PPC_new(data, m)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(1)
dat <- matrix(stats::rnorm(200), ncol = 4)
ans <- PPC_new(data = dat, m = 2)
str(ans)
head(ans$Apro)

Projection-on-Complement PCA (Generalized)

Description

Projects the data onto the orthogonal complement of a given vector u, eliminating the effect of u, and then performs PCA on the projected data. This is useful for removing specific trends (e.g., time trends, common market factors) before analysis.

Usage

PPC_u(data, m, u)

Arguments

Value

A list containing:

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(123)
dat <- matrix(stats::rnorm(200), ncol = 4)
u0 <- seq_len(nrow(dat))     # e.g., a linear trend to remove
res <- PPC_u(data = dat, m = 2, u = u0)
res$u
head(res$Apro)

Air Quality Data Set

Description

Air quality measurements collected from a gas multisensor device deployed in an Italian city.

This dataset contains the responses of a gas multisensor device deployed on the field in an Italian city.

Usage

air_quality

air_quality

Format

A data frame with 9358 rows and 14 variables:

DateTime

Date and time of the measurement (POSIXct).

CO_GT

True hourly averaged CO concentration in mg/m^3 (reference analyzer).

PT08_S1_CO

PT08.S1 (tin oxide) hourly averaged sensor response (CO targeted).

NMHC_GT

True hourly averaged non-methanic hydrocarbons concentration in \mu g/m^3.

C6H6_GT

True hourly averaged benzene concentration in \mu g/m^3.

PT08_S2_NMHC

PT08.S2 (titania) hourly averaged sensor response (NMHC targeted).

NOx_GT

True hourly averaged NOx concentration in ppb.

PT08_S3_NOx

PT08.S3 (tungsten oxide) hourly averaged sensor response (NOx targeted).

NO2_GT

True hourly averaged NO2 concentration in \mu g/m^3.

PT08_S4_NO2

PT08.S4 (tungsten oxide) hourly averaged sensor response (NO2 targeted).

PT08_S5_O3

PT08.S5 (indium oxide) hourly averaged sensor response (O3 targeted).

T

Temperature in degrees Celsius.

RH

Relative humidity (percent).

AH

Absolute humidity.

A data frame with 9357 rows and 16 variables.

Details

The dataset was collected from March 2004 to February 2005. Missing values are tagged with -200 value in the raw data, but have been converted to NA.

Source

UCI Machine Learning Repository: http://archive.ics.uci.edu/ml/datasets/Air+Quality

https://archive.ics.uci.edu/ml/datasets/Air+Quality

POET: Principal Orthogonal complEment Thresholding

Description

Implements the POET method for large covariance matrix estimation (Fan, Liao & Mincheva, 2013). The method assumes a factor model structure, estimates the low-rank component via PCA, and applies thresholding to the sparse residual covariance matrix.

Usage

poet(
  X,
  r = NULL,
  r.max = 10,
  thresh = "hard",
  lambda = NULL,
  gamma = 3.7,
  delta = 1e-04,
  method.r = "IC1"
)

Arguments

Value

A list containing:

References

Fan, J., Liao, Y., & Mincheva, M. (2013). Large covariance estimation by thresholding principal orthogonal complements. Journal of the Royal Statistical Society: Series B, 75(4), 603-680.

Examples

# Examples should be fast and reproducible for CRAN checks
set.seed(2025)
T_obs <- 40; N_var <- 15; r_true <- 2

# Generate a simple factor model: X = F * Lambda' + U
Lambda <- matrix(stats::rnorm(N_var * r_true), N_var, r_true)
F_scores <- matrix(stats::rnorm(T_obs * r_true), T_obs, r_true)
U <- matrix(stats::rnorm(T_obs * N_var), T_obs, N_var)
X_sim <- F_scores %*% t(Lambda) + U  # T x N

# Apply POET (choose r via IC1; use soft thresholding)
res <- poet(X_sim, r = NULL, method.r = "IC1", thresh = "soft")
res$r.hat
res$Sigma.poet[1:5, 1:5]