The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Package {GulFM}

Type: Package
Title: General Unilateral Load Estimator for Two-Layer Latent Factor Models
Version: 0.5.1
Description: Implements general unilateral loading estimator for two-layer latent factor models with smooth, element-wise factor transformations. We provide data simulation, loading estimation,finite-sample error bounds, and diagnostic tools for zero-mean and sub-Gaussian assumptions. A unified interface is given for evaluating estimation accuracy and cosine similarity. The philosophy of the package is described in Guo G. (2026) <doi:10.1016/j.apm.2025.116280>.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 3.5.0)
Imports: MASS, matrixStats
Suggests: testthat (≥ 3.0.0), ggplot2
NeedsCompilation: no
Language: en-US
Author: Guangbao Guo [aut, cre]
Maintainer: Guangbao Guo <ggb11111111@163.com>
Packaged: 2026-10-09 12:00:02 UTC; Kong Pengbo
Repository: CRAN
Date/Publication: 2026-10-10 02:50:02 UTC

General unilateral load Estimator

Description

General unilateral load Estimator

Usage

estimate_gul_loadings(X, m)

Arguments

X

n *p data matrix (already centred and scaled if desired).

m

number of latent factors (both layers).

Details

Step 1: PCA on X to get hat_A1 Step 2: Regress X on hat_A1 to get hat_gF1 Step 3: PCA on hat_gF1 to get hat_A2 Step 4: hat_Ag = hat_A1

Value

A list with hat_A1 : p * m 1st-layer loadings hat_A2 : m * m 2nd-layer loadings hat_Ag : p * m overall loadings Sigma1 : p * p sample cov(X) (for diagnostics) Sigma2 : m * m sample cov(hat_gF1) hat_gF1 : n * m estimated transformed latent factors eig1 : eigen-values of Sigma1 eig2 : eigen-values of Sigma2

Examples

dat  <- generate_gfm_data(500, 50, 5, tanh, seed = 1)
est  <- estimate_gul_loadings(dat$X, m = 5)
err  <- sqrt(mean((est$hat_Ag - dat$Ag)^2))  # overall RMSE

Smooth link functions compliant with Theorems 9&10

Description

Returns a vectorised map g(\cdot) and its exact Lipschitz constant L_g for three increasingly nonlinear choices.

Usage

g_fun(type = c("linear", "weak_nonlinear", "strong_nonlinear"))

Arguments

type

Character string selecting the map: "linear", "weak_nonlinear", or "strong_nonlinear".

Value

Named list with components

g_fun

vectorised function g(\cdot)

L_g

scalar Lipschitz constant of g

Examples

## pick a link with L_g = 1
tmp  <- g_fun("linear")
dat  <- generate_gfm_data(n = 500, p = 200, m = 5, g_fun = tmp$g_fun)
est  <- estimate_gul_loadings(dat$X, m = 5)
err  <- norm(est$hat_Ag - dat$Ag, "F")
sprintf("F-error (L_g = %d) = %.3f", tmp$L_g, err)

Simulation wrapper for Theorems 9 & 10

Description

One Monte-Carlo replicate; returns empirical error, exceedance indicator, theoretical bounds, and assumption-check flags.

Usage

g_theorem(n, p, m, g_type, epsilon, zero_tol = 0.02)

Arguments

n

sample size

p

number of observed variables

m

number of latent factors

g_type

character: "linear", "weak_nonlinear", "strong_nonlinear"

epsilon

error threshold

zero_tol

zero-mean tolerance (default 0.02)

Value

one-row data-frame

Examples

  df <- g_theorem(500, 200, 5, "linear", 0.6)

Generate general factor model with smooth latent transformation

Description

Generate general factor model with smooth latent transformation

Usage

generate_gfm_data(n, p, m, g_fun, seed = 1, sigma_V = 0.1)

Arguments

n

Integer: sample size.

p

Integer: number of observed variables.

m

Integer: number of latent factors (both layers).

g_fun

Function: smooth, element-wise transformation applied to latent factors. Must be vectorised, e.g. 'sin', 'tanh', 'scale'.

seed

1.

sigma_V

Numeric: standard deviation of the idiosyncratic noise (default 0.1 => Var = 0.01).

Value

List with components X : n * p matrix of standardised observations. A1 : p * m first-layer loading matrix. A2 : m * m second-layer loading matrix. Ag : p * m overall loading matrix (Ag = A1 F1 : n * m latent factors (before transformation). gF1: n * m latent factors (after transformation). V1 : n * p noise matrix (for diagnostics).

Examples

dat <- generate_gfm_data(200, 50, 5, g_fun = tanh)

Two-Stage Eigenvalue-Ratio Estimator for the Number of Factors

Description

Estimates the number of factors in the General Factor Model (GFM) using a two-stage eigenvalue-ratio (ER) procedure tailored to the GUL's two-layer structure.

Usage

gul_factor_number(
  X,
  k_max = NULL,
  g_fun = identity,
  p_norm = TRUE
)

Arguments

X

An n by p numeric matrix of observed data, column-wise standardized (mean zero, unit variance).

k_max

Integer upper bound for the first-stage search. Defaults to min(n-1, p-1).

g_fun

A known smooth function applied element-wise to the first-layer factor scores before forming the second-layer covariance. Defaults to identity (no transformation).

p_norm

Logical. If TRUE, divide first-layer scores by sqrt(p) before computing the second-layer covariance, as in Equation (3.5) of the paper.

Details

The procedure proceeds in two stages.

Stage 1. Compute the singular values of \mathbf X, form the eigenvalues \hat\lambda_k = \hat\sigma_k^2/(n-1) of the sample covariance, and select

\hat m_1 = \arg\max_{1\le k\le k_{\max}} \hat\lambda_k / \hat\lambda_{k+1}.

Stage 2. Using the first \hat m_1 leading eigenvectors \widehat{\mathbf Q}_1, compute first-layer scores \widehat g(\mathbf F_1) = \mathbf X \widehat{\mathbf Q}_1, apply the known transformation g(\cdot), normalize by \sqrt p (if p_norm = TRUE), and form the second-layer sample covariance \hat\Sigma^*_{g(F_1)}. Let its eigenvalues be \hat\mu_1 \ge \cdots \ge \hat\mu_{\hat m_1}. Select

\hat m = \arg\max_{1\le k\le \hat m_1} \hat\mu_k / \hat\mu_{k+1},

with the convention \hat\mu_{\hat m_1+1}=0.

When m > n-1, Stage 1 can detect at most n-1 factors; in that regime \hat m_1 \le n-1 < m and the estimate serves as a lower bound.

Value

A list with the following components:

m_hat_1

Integer. First-stage eigenvalue-ratio estimate, bounded above by min(n-1, p-1).

m_hat

Integer. Second-stage refined eigenvalue-ratio estimate.

lambda_hat

Numeric vector. Top eigenvalues of the first-layer sample covariance \hat\Sigma_X.

mu_hat

Numeric vector. Eigenvalues of the second-layer sample covariance \hat\Sigma^*_{g(F_1)}.

ratio_1

Numeric vector. First-stage eigenvalue ratios \hat\lambda_k / \hat\lambda_{k+1}.

ratio_2

Numeric vector. Second-stage eigenvalue ratios \hat\mu_k / \hat\mu_{k+1}, with the convention \hat\mu_{\hat m_1+1}=0.

Examples


set.seed(1)
n <- 500; p <- 200; m_true <- 5
F  <- matrix(rnorm(n * m_true), n, m_true)
gF <- sin(F)
A1 <- matrix(rnorm(p * m_true, 0, 1/sqrt(p)), p, m_true)
V1 <- matrix(rnorm(n * p, sd = 2), n, p)
X  <- gF %*% t(A1) + V1

res <- gul_factor_number(X, g_fun = sin)
cat("True m =", m_true,
    "\nStage 1 =", res$m_hat_1,
    "\nStage 2 =", res$m_hat, "\n")

Single-replication GUL simulation

Description

Generates one synthetic data set, estimates loadings with the GUL, and evaluates estimation accuracy.

Usage

gul_simulation(n, p, m, g_fun)

Arguments

n

Integer: sample size.

p

Integer: number of observed variables.

m

Integer: number of latent factors (both layers).

g_fun

Function: element-wise, smooth transformation applied to the latent factors (e.g. 'tanh', 'sin').

Value

Named numeric vector with components error_F : Frobenius norm ||hat(Ag) - Ag||_F

Examples

gul_simulation(200, 50, 5, g_fun = tanh)

Multi-metric evaluation of factor loading matrix estimation error

Description

Multi-metric evaluation of factor loading matrix estimation error

Usage

loading_metrics(A_true, A_hat)

Arguments

A_true

True loading matrix (p x m)

A_hat

Estimated loading matrix (p x m)

Value

data.frame with MSE, RMSE, MAE, MaxDev, and Cosine similarity

Examples

## simulated example
p <- 100; m <- 5
Ag_true  <- matrix(rnorm(p*m), p, m)
Ag_hat   <- Ag_true + matrix(rnorm(p*m, 0, 0.1), p, m)
metrics  <- loading_metrics(Ag_true, Ag_hat)
print(metrics)

Verify zero-mean preservation (Theorem 10 assumption 2a)

Description

Draws n i.i.d. N(0, I_m) latent factors, applies g component-wise, and checks whether |E[g(x)]| < tol on every coordinate.

Usage

verify_mean(g_fun, m = 5, n = 10000, tol = 0.001)

Arguments

g_fun

vectorised map g: R -> R

m

latent dimension

n

Monte-Carlo sample size

tol

numerical tolerance (default 1e-3)

Value

logical TRUE if |mean| < tol on all coords

Examples

  tmp <- g_fun("weak_nonlinear")
  verify_mean(tmp$g_fun, m = 5)

Verify sub-Gaussian preservation

Description

Draws n i.i.d. N(0, I_m) latent factors, applies g component-wise, and checks whether E[exp(g(x))] remains below an empirical cut-off. This is a quick proxy for finite sub-Gaussian norm.

Usage

verify_subgaussian(g_fun, m = 5, n = 1000, cut = exp(2))

Arguments

g_fun

vectorised map g: R -> R

m

latent dimension

n

Monte-Carlo sample size

cut

empirical threshold (default exp(2) & 7.389)

Value

logical TRUE if E[exp(g)] < cut on all coords

Examples

  tmp <- g_fun("strong_nonlinear")
  verify_subgaussian(tmp$g_fun, m = 5)

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.