Package {CoFM}


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 CoFM).

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)