| Type: | Package |
| Title: | Copula Factor Models |
| Version: | 1.2.6 |
| Author: | Guangbao Guo [aut, cre], Xin Gao [aut] |
| Maintainer: | Guangbao Guo <ggb11111111@163.com> |
| Description: | Provides tools for factor analysis in high-dimensional settings under copula-based factor models. It includes functions to simulate factor-model data with copula-distributed idiosyncratic errors (e.g., Clayton, Gumbel, Frank, Student t and Gaussian copulas) and to perform diagnostic tests such as the Kaiser-Meyer-Olkin measure and Bartlett's test of sphericity. Estimation routines include principal component based factor analysis, projected principal component analysis, and principal orthogonal complement thresholding for large covariance matrix estimation. The philosophy of the package is described in Guo G. (2023) <doi:10.1007/s00180-022-01270-z>. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| LazyData: | true |
| Depends: | R (≥ 4.1.0) |
| Suggests: | testthat (≥ 3.0.0), spelling |
| NeedsCompilation: | no |
| Imports: | MASS, copula, matrixcalc, stats |
| Language: | en-US |
| Config/roxygen2/version: | 8.1.1 |
| Packaged: | 2026-11-16 11:02:37 UTC; admin |
| Repository: | CRAN |
| Date/Publication: | 2026-11-18 12:20:02 UTC |
The CoFM function is to generate Copula Factor Models data.
Description
The function supports various elliptical distributions for generating the data, including: Elliptical-Normal Distribution, Elliptical-t Distribution, Elliptical Distribution.
Usage
CoFM(n, p, m, theta, distribution_type)
Arguments
n |
Sample size. |
p |
Sample dimensionality. |
m |
Number of factors. |
theta |
A numerical parameter used in the copula distribution. |
distribution_type |
The type of distribution. |
Value
A list containing:
data |
A matrix of generated data. |
A |
A matrix representing the factor loadings. |
D |
A diagonal matrix representing the unique variances. |
Examples
library(copula)
library(MASS)
n <- 1000
p <- 10
m <- 5
theta <- 2.0
distribution_type <- "Clayton"
X <- CoFM(n, p, m, theta, distribution_type)
Copula Errors Function
Description
This function calculates the Mean Squared Error (MSE) and relative error for Copula distributions.
Usage
Copula_errors(data, copula_type, param)
Arguments
data |
Matrix of data. |
copula_type |
Character string specifying the type of Copula (e.g., "clayton", "gumbel", "frank", "t", "nested", "mixed", "galambos", "normal"). |
param |
Parameters for the specified Copula type. |
Value
A named vector containing:
MSE |
Mean Squared Error for the Copula distribution. |
RelativeError |
Relative error for the Copula distribution. |
Examples
# Example for Clayton Copula
if (!requireNamespace("copula", quietly = TRUE)) {
utils::install.packages("copula")
}
library(copula)
set.seed(123)
n <- 1000
clayton.cop <- copula::claytonCopula(2, dim = 2)
data <- copula::rCopula(n, clayton.cop)
errors <- Copula_errors(data, "clayton", 2)
print(errors)
Distributed POET covariance matrix estimation
Description
Estimates a high-dimensional covariance matrix using a distributed Principal Orthogonal complEment Thresholding (POET) procedure. Local subsets are randomly sampled from the full dataset, and their covariance estimates are averaged.
Usage
DPOET(data, r.max = 10, n1, K, delta = 0.01, eps = 1e-08)
Arguments
data |
A numeric matrix or data frame. Rows represent observations and columns represent variables. All values must be finite. |
r.max |
A positive integer specifying the maximum number of latent factors considered by the information criterion. The effective maximum is limited to min(r.max, n1 - 1, p - 1), where p is the number of variables. Default is 10. |
n1 |
An integer between 2 and the total sample size. The number of observations randomly sampled without replacement for each local subset. |
K |
A positive integer specifying the number of local subsets. Each subset is sampled independently from the full dataset. |
delta |
A non-negative finite numeric value added to the diagonal entries of the thresholded residual covariance matrix. Default is 0.01. |
eps |
A positive finite numeric value used as a numerical lower bound for factor eigenvalues and residual covariance diagonal entries. Default is 1e-8. |
Details
For each local subset, the number of latent factors is selected using an information criterion. The residual covariance matrix is estimated using hard thresholding with threshold sqrt(log(p) / n1). Local subsets may overlap because they are independently sampled. For reproducibility, call set.seed() before running DPOET().
Value
A list containing:
- Abar
A p by r_common matrix obtained by averaging the zero-padded local factor loading matrices, where r_common is the maximum local factor number.
- Dbar
A p by p matrix representing the average thresholded residual covariance estimate.
- Sigmahatbar
A p by p symmetric matrix representing the average local POET covariance estimate.
- rbar
The mean of the estimated local factor numbers.
Examples
set.seed(123)
n <- 100; p <- 10; r <- 3
F <- matrix(rnorm(n * r), nrow = n, ncol = r)
A <- matrix(runif(p * r, -1, 1), nrow = p, ncol = r)
U <- matrix(rnorm(n * p, sd = 0.5), nrow = n, ncol = p)
X <- F %*% t(A) + U
result1 <- DPOET(data = X, r.max = 3, n1 = 50, K = 2, delta = 0.01, eps = 1e-8)
dim(result1$Sigmahatbar)
result1$rbar
result2 <- DPOET(data = X, r.max = 5, n1 = 50, K = 2)
dim(result2$Abar)
result2$rbar
Distributed Projection Principal Component Method
Description
Estimates a covariance matrix using a distributed projection principal component method. Local loading matrices are aligned using singular value decomposition before aggregation.
Usage
DPPC(data, m, n1, K)
Arguments
data |
A numeric matrix or data frame with observations in rows and variables in columns. |
m |
A positive integer specifying the number of principal components. |
n1 |
An integer specifying the sample size of each local subset. |
K |
A positive integer specifying the number of local subsets. |
Value
Abarpro, Dbarpro, Sigmahatbarpro.
Examples
set.seed(123)
n <- 100; p <- 10; m <- 3
F <- matrix(rnorm(n * m), nrow = n, ncol = m)
A <- matrix(runif(p * m, -1, 1), nrow = p, ncol = m)
E <- matrix(rnorm(n * p, sd = 0.5), nrow = n, ncol = p)
X <- F %*% t(A) + E
fit <- DPPC(data = X, m = 3, n1 = 50, K = 2)
dim(fit$Abarpro)
dim(fit$Dbarpro)
dim(fit$Sigmahatbarpro)
Distributed U-projection Principal Component Method
Description
Estimates a covariance matrix using a distributed U-projection principal component method. The data are projected onto the orthogonal complement of a direction vector, and local factor loading matrices are aligned using singular value decomposition before aggregation.
Usage
DUPPC(data, m, n1, K, seed = NULL, u = NULL)
Arguments
data |
A numeric n by p matrix or data frame, with observations in rows and variables in columns. All values must be finite. |
m |
A positive integer specifying the number of principal components. |
n1 |
An integer specifying the number of observations sampled for each local subset, between 2 and the total sample size. |
K |
A positive integer specifying the number of local subsets. |
seed |
An optional integer random seed for reproducibility. Default is NULL, which leaves the random number generator unchanged. |
u |
An optional nonzero projection direction vector of length n. If NULL, the first principal component score vector is used. |
Value
A list containing: Abarpro, Dbarpro, Sigmahatbarpro.
Examples
set.seed(123)
n <- 100; p <- 10; m <- 3
F <- matrix(rnorm(n * m), nrow = n, ncol = m)
A <- matrix(runif(p * m, -1, 1), nrow = p, ncol = m)
E <- matrix(rnorm(n * p, sd = 0.5), nrow = n, ncol = p)
X <- F %*% t(A) + E
result1 <- DUPPC(data = X, m = 3, n1 = 50, K = 2, seed = 123)
dim(result1$Abarpro)
dim(result1$Dbarpro)
dim(result1$Sigmahatbarpro)
u <- F[, 1]
result2 <- DUPPC(data = X, m = 3, n1 = 50, K = 2, seed = 123, u = u)
dim(result2$Sigmahatbarpro)
FanPC estimation for the Copula Factor Model
Description
Perform FanPC (eigen-structure thresholding) on CoFM data to estimate loadings (AF), uniquenesses (DF) and their errors.
Usage
FanPC.CoFM(data, m, A, D, p)
Arguments
data |
n×p data matrix (generated by |
m |
Number of latent factors. |
A |
True p×m loading matrix (for error evaluation). |
D |
True p×p uniqueness matrix (for error evaluation). |
p |
Number of variables. |
Value
List with components
AF |
Estimated loadings. |
DF |
Estimated uniquenesses. |
MSESigmaA, MSESigmaD, LSigmaA, LSigmaD |
Error metrics (same definition as FanPC.SFM). |
Examples
library(copula); library(MASS)
X <- CoFM(n=1000, p=10, m=5, theta=2, distribution_type="Clayton")
res <- FanPC.CoFM(X$data, m=5, X$A, diag(diag(X$D)), p=10)
print(res)
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
data |
A matrix or data frame of input data (n x p). |
m |
Integer. The number of principal components (factors) to extract. |
Value
A list containing:
AF |
Estimated factor loadings matrix (p x m). |
DF |
Estimated uniquenesses vector (p). |
SigmahatF |
The correlation matrix of the input data. |
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, theta = 2.0, distribution_type = "Clayton")
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
PC estimation for the Copula Factor Model
Description
Classical PCA solution for CoFM data.
Usage
PC.CoFM(data, m, A, D)
Arguments
data |
n×p data matrix. |
m |
Number of factors. |
A |
True p×m loading matrix. |
D |
True p×p uniqueness matrix. |
Value
List with components
A2 |
Estimated loadings. |
D2 |
Estimated uniquenesses. |
MSESigmaA, MSESigmaD, LSigmaA, LSigmaD |
Error metrics. |
Examples
X <- CoFM(n=1000, p=10, m=5, theta=2, distribution_type="Gumbel")
res <- PC.CoFM(X$data, m=5, X$A, diag(diag(X$D)))
print(res)
Projection-on-Orthogonal-Complement Estimation and Transformation
Description
Projection-on-Orthogonal-Complement Estimation and Transformation
Usage
POET(X, r.max = 10, delta = 0.01, eps = 1e-08)
Arguments
X |
A numeric n by p data matrix, with observations in rows and variables in columns. |
r.max |
A positive integer specifying the maximum number of factors considered for selection. The effective upper bound is limited by the sample size and number of variables. |
delta |
A non-negative numeric value added to the diagonal of the residual covariance estimate. Default is 0.01. |
eps |
A positive numeric tolerance used to stabilize eigenvalue-based calculations and residual variances. Default is 1e-8. |
Value
Ahat, Dhat, Sigmahat, Fhat.
References
Fan, J., Liao, Y. and Mincheva, M. (2013). Large covariance estimation by thresholding principal orthogonal complements. Journal of the Royal Statistical Society: Series B, 75(4), 603–680.
Examples
set.seed(123)
n <- 100; p <- 10; r <- 3
F <- matrix(rnorm(n * r), nrow = n, ncol = r)
A <- matrix(runif(p * r, -1, 1), nrow = p, ncol = r)
E <- matrix(rnorm(n * p, sd = 0.5), nrow = n, ncol = p)
X <- F %*% t(A) + E
res <- POET(X = X, r.max = 5, delta = 0.01, eps = 1e-8)
dim(res$Sigmahat)
res$rhat
Sigma.true <- A %*% t(A) + diag(0.25, p)
MSESigma <- mean((res$Sigmahat - Sigma.true)^2)
MSESigma
Projection-based Perturbation Principal Component Analysis
Description
Projection-based Perturbation Principal Component Analysis
Usage
PPC(data, m)
Arguments
data |
is a total data set. |
m |
is the number of principal component |
Value
Apro, Dpro, Sigmahatpro
Examples
library(copula)
library(MASS)
n=1000
p=10
m=5
mu=t(matrix(rep(runif(p,0,n),n),p,n))
mu0=as.matrix(runif(m,0))
sigma0=diag(runif(m,1))
F=matrix(mvrnorm(n,mu0,sigma0),nrow=n)
A=matrix(runif(p*m,-1,1),nrow=p)
D=as.matrix(diag(rep(runif(p,0,1))))
theta = 2.0
clayton.cop <- claytonCopula(param = theta, dim = p)
U_clayton <- rCopula(n, clayton.cop)
epsilon_clayton <- qnorm(U_clayton)
data=mu+F%*%t(A)+epsilon_clayton
PPC(data=data,m=5)
PPC estimation for the Copula Factor Model
Description
Projected-PCA (noise-reduction projection) for CoFM data.
Usage
PPC.CoFM(data, m, A, D)
Arguments
data |
n×p data matrix. |
m |
Number of factors. |
A |
True p×m loading matrix. |
D |
True p×p uniqueness matrix. |
Value
List with components
Ap2 |
Estimated loadings. |
Dp2 |
Estimated uniquenesses. |
MSESigmaA, MSESigmaD, LSigmaA, LSigmaD |
Error metrics. |
Examples
X <- CoFM(n=1000, p=10, m=5, theta=2, distribution_type="Frank")
res <- PPC.CoFM(X$data, m=5, X$A, diag(diag(X$D)))
print(res)
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
data |
A matrix or data frame of input data (n x p). |
m |
Integer. The number of principal components (factors) to extract. |
Value
A list containing:
Apro |
Estimated projected factor loadings matrix (p x m). |
Dpro |
Estimated projected uniquenesses vector (p). |
Sigmahatpro |
The covariance matrix of the projected data. |
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, theta = 2.0, distribution_type = "Clayton")
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
Projection-on-Complement Principal Component Analysis
Description
Performs principal component analysis after projecting the standardized data onto the orthogonal complement of the leading principal component score direction.
Usage
UPPC(data, m)
Arguments
data |
A numeric n by p data matrix, with observations in rows and variables in columns. |
m |
A positive integer specifying the number of principal components to retain. Must be smaller than p. |
Value
Apro, Dpro, Sigmahatpro.
Examples
set.seed(123)
n <- 100; p <- 10; m <- 3
F <- matrix(rnorm(n * m), nrow = n)
A <- matrix(runif(p * m, -1, 1), nrow = p)
E <- matrix(rnorm(n * p, sd = 0.5), nrow = n)
X <- F %*% t(A) + E
result <- UPPC(data = X, m = 3)
dim(result$Apro)
length(result$Dpro)
dim(result$Sigmahatpro)
Traditional Chinese Medicinal Herbal Tea Consumption Survey Data
Description
A dataset containing questionnaire responses on awareness, purchasing behavior, consumer preferences, purchase intentions, and satisfaction with traditional Chinese medicinal herbal tea.
Usage
herbal_tea_survey
Format
A data frame containing questionnaire responses with the following 68 variables:
- RespondentID
Unique respondent identifier.
- Duration
Questionnaire completion duration.
- Q1
Response to question 1.
- Q2
Response to question 2.
- Q3
Response to question 3.
- Q4
Response to question 4.
- Q5
Response to question 5.
- Q6
Response to question 6.
- Q7_1
Response to question 7, item 1.
- Q7_2
Response to question 7, item 2.
- Q7_3
Response to question 7, item 3.
- Q7_4
Response to question 7, item 4.
- Q7_5
Response to question 7, item 5.
- Q7_6
Response to question 7, item 6.
- Q7_7
Response to question 7, item 7.
- Q7_8
Response to question 7, item 8.
- Q8_1
Response to question 8, item 1.
- Q8_2
Response to question 8, item 2.
- Q8_3
Response to question 8, item 3.
- Q8_4
Response to question 8, item 4.
- Q8_5
Response to question 8, item 5.
- Q8_6
Response to question 8, item 6.
- Q8_7
Response to question 8, item 7.
- Q9
Response to question 9.
- Q10
Response to question 10.
- Q11_1
Response to question 11, item 1.
- Q11_2
Response to question 11, item 2.
- Q11_3
Response to question 11, item 3.
- Q11_4
Response to question 11, item 4.
- Q11_5
Response to question 11, item 5.
- Q11_6
Response to question 11, item 6.
- Q11_7
Response to question 11, item 7.
- Q11_8
Response to question 11, item 8.
- Q12_1
Response to question 12, item 1.
- Q12_2
Response to question 12, item 2.
- Q12_3
Response to question 12, item 3.
- Q12_4
Response to question 12, item 4.
- Q12_5
Response to question 12, item 5.
- Q13_1
Response to question 13, item 1.
- Q13_2
Response to question 13, item 2.
- Q13_3
Response to question 13, item 3.
- Q13_4
Response to question 13, item 4.
- Q13_5
Response to question 13, item 5.
- Q13_6
Response to question 13, item 6.
- Q13_7
Response to question 13, item 7.
- Q13_8
Response to question 13, item 8.
- Q14_1
Response to question 14, item 1.
- Q14_2
Response to question 14, item 2.
- Q14_3
Response to question 14, item 3.
- Q14_4
Response to question 14, item 4.
- Q14_5
Response to question 14, item 5.
- Q14_6
Response to question 14, item 6.
- Q14_7
Response to question 14, item 7.
- Q15
Response to question 15.
- Q16
Response to question 16.
- Q17
Response to question 17.
- Q18
Response to question 18.
- Q19
Response to question 19.
- Q20
Response to question 20.
- Q21
Response to question 21.
- Q22
Response to question 22.
- Q23
Response to question 23.
- Q24
Response to question 24.
- Q25
Response to question 25.
- Q26
Response to question 26.
- Q27
Response to question 27.
- Q28
Response to question 28.
- Q29
Response to question 29.
Author(s)
Guangbao Guo, Ningxin Hu
Source
Guangbao Guo and Ningxin Hu (2024, January). Traditional Chinese Medicinal Herbal Tea Questionnaire Survey.
Examples
data(herbal_tea_survey)
head(herbal_tea_survey)