Package {glt}

gltfactor: Bayesian Factor Models with GLT Process Priors

Description

Fits a Bayesian Gaussian factor model under a Generalized Lower Triangular (GLT) process prior using an MCMC sampler implemented in C++ via Rcpp. The package provides tools for model fitting, posterior summarisation, identification post-processing, and visualisation of loading matrices and variance decompositions.

Details

The main entry point is gltfa(), which accepts a data matrix y (T x m) and returns a "gltfit" object containing posterior draws and metadata.

Main functions

gltfa()

Fit a GLT factor model via MCMC.

get_variance()

Compute posterior draws of the factor and total covariance matrices.

get_pivots()

Extract pivot row indices from a binary allocation matrix Delta.

plot_real_matrix()

Visualise a numeric matrix as a colour image using a diverging palette.

Author(s)

Maintainer: Antonio Canale antonio.canale@unipd.it

Authors:

• Antonio Canale antonio.canale@unipd.it

References

Canale, A. and Frühwirth-Schnatter, S. (2026). "The generalized lower triangular process prior." Technical Report,

Construct a "facmatrix" object

Description

A thin wrapper that tags a numeric matrix with class "facmatrix" so that it is plotted via plot.facmatrix() (a colour-image raster) rather than via the default matrix print/plot methods.

Usage

facmatrix(mat)

Arguments

Value

mat with class "facmatrix" prepended.

Extract pivot row indices from a Delta matrix

Description

For each column of Delta, returns the row index of the first 1, which defines the pivot row for that factor.

Usage

get_pivots(Delta)

Arguments

Value

An integer vector of length H.

Posterior draws of variance decomposition

Description

For each saved MCMC draw, computes the m \times m matrices \Lambda\Lambda^\top (factor covariance) and \Lambda\Lambda^\top + \Sigma (total marginal covariance), where \Sigma = \mathrm{diag}(\sigma^2_1, \ldots, \sigma^2_m).

Usage

get_variance(fit)

Arguments

Value

A named list with two elements:

LLt

An m \times m \times S array of \Lambda_s \Lambda_s^\top draws.

total

An m \times m \times S array of \Lambda_s \Lambda_s^\top + \Sigma_s draws.

Fit a Bayesian factor model with GLT process prior

Description

Fits a Bayesian Gaussian factor model under a Generalized Lower Triangular (GLT) process prior using an MCMC sampler implemented in C++ via Rcpp. This is the main user-facing entry point of the package.

Usage

gltfa(
  y,
  mcmc = list(),
  Hmax = ncol(y),
  prior = list(),
  init = list(),
  control = list(),
  fixed = list(),
  verbose = interactive()
)

Arguments

Details

The model is:

y_t = \Lambda \eta_t + \epsilon_t, \quad \epsilon_t \sim N_m(0, \Sigma)

where \Lambda is a sparse lower-triangular loading matrix controlled by a binary allocation matrix \Delta, and \Sigma = \mathrm{diag}(\sigma^2_1, \ldots, \sigma^2_m).

Notation and dimensions:

• y is a numeric matrix of dimension T \times m.

• Lambda is a loading matrix of dimension m \times H.

• Delta is a binary allocation matrix of dimension m \times H.

• Eta is a factor score matrix of dimension H \times T.

Value

An object of class "gltfit", a named list with components:

draws

A named list of posterior draws (if control$store_draws = TRUE): Lambda (m \times H_{\max} \times n_{\text{save}}), Delta (m \times H_{\max} \times n_{\text{save}}), sigma2 (m \times n_{\text{save}}), H (n_{\text{save}}), and optionally Eta (H_{\max} \times T \times n_{\text{save}}).

meta

A named list with nsave, Hmax, T, m.

input

A named list echoing the processed mcmc, prior, control, and fixed arguments.

call

The matched call.

References

Canale, A. and Frühwirth-Schnatter, S. (2026). "The generalized lower triangular process prior." arXiv preprint arXiv:2610.09762.

See Also

get_variance(), get_pivots(), plot_real_matrix()

Examples

set.seed(42)
Y <- matrix(rnorm(200 * 10), nrow = 200, ncol = 10)

fit <- gltfa(
  y       = Y,
  mcmc    = list(niter = 2000, nburn = 1000, thin = 1),
  Hmax    = 5,
  prior   = list(a_sigma = 2, b_sigma = 1),
  init    = list(H = 2),
  control = list(store_draws = TRUE, seed = 1L, random_scan = TRUE),
  verbose = FALSE
)

Fit a STAR-extended GLT factor model for discrete/mixed-scale data

Description

Fits the Kowal & Canale (2020) simultaneous transformation and rounding (STAR) extension of gltfa() to discrete-valued (e.g. counts, ordinal) observed data. A continuous latent matrix z is linked to the observed matrix y via a column-specific monotone transform G_j and a column-specific threshold sequence, and modelled with a regression mean plus the same sparse GLT factor model used by gltfa():

Usage

gltfa_star(
  y,
  X = NULL,
  thresholds = NULL,
  g_type = "exp",
  mcmc = list(),
  Hmax = ncol(y),
  prior = list(),
  init = list(),
  control = list(),
  fixed = list(),
  verbose = interactive()
)

Arguments

Details

y_{ij} = \ell \iff G_j(z_{ij}) \in [a_{j,\ell}, a_{j,\ell+1})

z_{ij} = x_i'\beta_j + \epsilon_{ij}, \quad \epsilon_t \sim N_m(0, \Lambda\Lambda' \text{-structured } \Sigma)

Two extra Gibbs steps run before the original 8-step sampler on each iteration: imputing z from its truncated-normal full conditional (Step 0a), and updating the regression coefficients Beta (Step 0b, conjugate normal). The residual ⁠epsilon = z - X Beta⁠ is then fed into the unchanged Delta/pivots/H/Lambda/sigma2/Eta updates.

Value

An object of class c("gltfit_star", "gltfit"). In addition to the components documented in gltfa(), draws$Beta holds ⁠p x m⁠ draws of the regression coefficients (always stored), and last$z / last$epsilon hold the final latent-z / residual draws (not stored across iterations).

References

Canale, A. and Frühwirth-Schnatter, S. (2026). "The generalized lower triangular process prior." arXiv preprint arXiv:2610.09762,

Kowal, D. and Canale, A. (2020). "Simultaneous transformation and rounding (STAR) models for integer-valued data." Electronic Journal of Statistics, 14(1), 1744-1772.

See Also

gltfa()

Examples

set.seed(42)
Ycounts <- matrix(rpois(100 * 6, lambda = 3), nrow = 100, ncol = 6)

fit <- gltfa_star(
  y       = Ycounts,
  Hmax    = 3,
  mcmc    = list(niter = 500, nburn = 250, thin = 1),
  init    = list(H = 1),
  control = list(store_draws = TRUE, seed = 1L),
  verbose = FALSE
)

Plot a "facmatrix" object

Description

S3 plot method for objects of class "facmatrix". Renders the matrix as a colour-image raster using signed_palette() by default; see plot_real_matrix() for the full set of supported arguments.

Usage

## S3 method for class 'facmatrix'
plot(x, ...)

Arguments

Value

Invisibly x; called for its side effect of producing a plot.

See Also

plot_real_matrix(), facmatrix()

Plot a real-valued matrix as a colour image

Description

Renders a numeric matrix as a raster image using a diverging colour palette (via signed_palette() by default), with optional grid lines and axis labels. Rows increase downward (matrix convention).

Usage

plot_real_matrix(
  mat,
  palette_fun = signed_palette,
  draw_grid = TRUE,
  grid_col = "grey80",
  axes = TRUE,
  xlab = "column",
  ylab = "row",
  asp = 1,
  main = "",
  legend = FALSE,
  legend_n = 100,
  legend_width = 1.4,
  legend_digits = 2,
  v_lines = NULL,
  h_lines = NULL,
  ...
)

Arguments

Details

This is the internal workhorse used by plot.facmatrix(); it remains available for plotting plain numeric matrices directly.

Value

Invisibly NULL; called for its side effect of producing a plot.

See Also

signed_palette()

Print a "summary.gltfit" object

Description

Print a "summary.gltfit" object

Usage

## S3 method for class 'summary.gltfit'
print(x, ...)

Arguments

Value

Invisibly x.

Summarize a "gltfit" object

Description

Computes posterior averages (across admissible saved MCMC draws) of Lambda, Delta, sigma2, and H, along with the posterior average of \Omega = \Lambda \Lambda^\top + \Sigma, where \Sigma = \mathrm{diag}(\sigma^2). The posterior-mean Lambda, Delta, and Omega matrices are returned with class "facmatrix" so they inherit plot.facmatrix().

Usage

## S3 method for class 'gltfit'
summary(object, ...)

Arguments

Details

Before averaging, draws are filtered using admissible_draws(): a draw is dropped when, after removing spurious columns (loadings on a single variable) and any resulting all-zero rows, the allocation matrix fails sparvaride::counting_rule_holds(). This mirrors the usual post-processing step for GLT-type factor models, where unidentified draws (e.g. those with too few active variables per factor) should not contribute to posterior summaries of Lambda/Delta.

object$draws$Lambda and object$draws$Delta are stored as ragged lists of length n_{\text{save}}, each element an m \times H_s matrix (H_s is the active number of factors for that draw, see object$draws$H). Kept draws are zero-padded to m \times H_{\max} before elementwise averaging. sigma2 draws are stored as an n_{\text{save}} \times m matrix, averaged over kept rows. \Omega is computed per kept draw as \Lambda_s \Lambda_s^\top + \mathrm{diag}(\sigma^2_s) (using the draw's own, unpadded \Lambda_s) and then averaged.

Value

A named list with class "summary.gltfit" containing:

Lambda

Posterior mean loading matrix (m \times H_{\max}), class "facmatrix".

Delta

Posterior mean allocation matrix (m \times H_{\max}), class "facmatrix".

sigma2

Posterior mean idiosyncratic variances (length m).

H

Posterior mean number of active factors (scalar).

Omega

Posterior mean of \Lambda \Lambda^\top + \Sigma (m \times m), class "facmatrix".

n_admissible

Number of draws retained after filtering.

n_total

Total number of saved draws before filtering.

See Also

gltfa(), plot.facmatrix(), sparvaride::counting_rule_holds()