One Gibbs sampling sweep for LDA (collapsed) using document–term list.

Description

This function performs a single collapsed Gibbs sampling pass over all non-zero document–term entries. Each (d, v, count) triple is treated as 'count' replicated word tokens sharing the same topic assignment.

Usage

eLDA_pass_b_fast(mod, count, ndsum, NZ, V, K, alpha, beta)

Arguments

Details

The state is stored in a list 'mod' containing:

z

Integer vector of length NZ; topic assignment for each (d, v, count) triple.

nd

D×K integer matrix; document–topic counts.

nw

K×V integer matrix; topic–word counts.

nwsum

Integer vector of length K; total word count per topic.

Value

A list with updated state:

z

Updated topic assignment vector (length NZ).

nd

Updated D×K document–topic counts.

nw

Updated K×V topic–word counts.

nwsum

Updated total word counts per topic.

Initialize LDA/STM state from a (d, v, c) sparse count matrix.

Description

Given a document-term matrix in triplet form (d, v, c) using 0-based indices, this function initializes the LDA state: - samples initial topic assignments z, - constructs document-topic counts nd, - constructs topic-word counts nw, - computes ndsum, nwsum, and normalized topic proportions X.

Usage

init_mod_from_count(count, K = NULL, phi = NULL, seed = NULL)

Arguments

Details

If a topic-word probability matrix 'phi' is provided (V x K), initial topics are sampled according to phi[v+1, ]. Otherwise, topics are sampled uniformly from K topics.

Value

A list with components:

z

Integer vector (length NZ) of sampled topics, 0-based.

nd

DxK document-topic count matrix.

nw

KxV topic-word count matrix.

ndsum

Integer vector (length D) with row sums of nd.

nwsum

Integer vector (length K) with row sums of nw.

X

DxK matrix of normalized topic proportions nd / ndsum.

D

Number of documents.

V

Vocabulary size.

K

Number of topics.

NZ

Number of non-zero entries (rows in count).

Collapsed LDA Gibbs sampling for sparse (d, v, c) triplet data.

Description

This function performs collapsed Gibbs sampling for the standard LDA model using a sparse document-term representation:

1. initializes the LDA state via init_mod_from_count(),

2. runs n_iter iterations of the C++ Gibbs kernel eLDA_pass_b_fast(),

3. returns the final model state, including posterior topic-word and document-topic distributions.

Usage

run_lda_gibbs(
  count,
  K,
  alpha,
  beta,
  n_iter = 100L,
  phi = NULL,
  seed = NULL,
  verbose = TRUE,
  progress_every = 10L
)

Arguments

Value

A list mod containing:

z

Integer vector of length NZ; final topic assignments (0-based).

nd

D x K document-topic count matrix.

nw

K x V topic-word count matrix.

ndsum

Integer vector of length D; document token counts.

nwsum

Integer vector of length K; topic token counts.

phi

V x K topic-word posterior mean p(w \mid z=k) computed from nw.

theta

D x K document-topic posterior mean p(z=k \mid d) computed from nd.

loglik_trace

Vector of log-likelihoods.

D

Number of documents.

V

Vocabulary size.

K

Number of topics.

NZ

Number of non-zero (d, v, c) entries.

Multi-level supervised topic model (MLSTM) via variational inference.

Description

This function fits a multi-output supervised LDA model with a hierarchical prior on regression coefficients:

\eta_j \sim N(\mu, \Lambda^{-1}), \quad \Lambda \sim \text{IW}(\upsilon, \Omega).

Usage

run_mlstm_vi(
  count,
  Y,
  K,
  alpha,
  beta,
  mu,
  upsilon,
  Omega,
  phi = NULL,
  seed = NULL,
  max_iter = 200L,
  min_iter = 50L,
  tol_elbo = 1e-04,
  update_sigma = TRUE,
  tau = 20L,
  exact_second_moment = FALSE,
  show_progress = TRUE,
  chunk = 5000L,
  verbose = TRUE,
  sigma2_init = NULL
)

Arguments

Details

The latent topic layer is standard LDA, and each response dimension j follows a Gaussian regression on document-level topic proportions. Variational inference is performed by repeated calls to the C++ routine stm_multi_hier_vi_parallel() until convergence or a maximum number of sweeps is reached.

Convergence is assessed based on the relative changes in the evidence lower bound (ELBO) and the supervised label log-likelihood:

\frac{\mathrm{ELBO}_t - \mathrm{ELBO}_{t-1}}{|\mathrm{ELBO}_{t-1}|}, \qquad \frac{\ell_t - \ell_{t-1}}{|\ell_{t-1}|}.

After a minimum number of iterations, the algorithm is declared to have converged when both quantities are non-negative and smaller than the prescribed tolerance.

Value

A list mod containing (at least):

nd

D x K document-topic counts.

nw

K x V topic-word counts.

ndsum

Integer vector of length D; document token counts.

nwsum

Integer vector of length K; topic token counts.

eta

K x J matrix of regression coefficients.

sigma2

Length-J vector of noise variances.

Lambda_E

K x K posterior mean of \Lambda (if returned by C++).

IW_upsilon_hat

Posterior degrees of freedom (if returned by C++).

IW_Omega_hat

Posterior scale matrix (if returned by C++).

phi

V x K topic-word posterior mean p(w \mid z=k) computed from nw.

theta

D x K document-topic posterior mean p(z=k \mid d) computed from nd.

elbo

Final ELBO value.

label_loglik

Final label log-likelihood term.

elbo_trace

Numeric vector of ELBO values over iterations.

label_loglik_trace

Numeric vector of label log-likelihoods.

n_iter

Number of sweeps actually performed.

D

Number of documents.

V

Vocabulary size.

K

Number of topics.

J

Number of response dimensions.

NZ

Number of non-zero (d, v, c) entries.

Supervised topic model (STM) variational inference with ELBO-based convergence.

Description

This function performs supervised topic model (STM) using variational inference. It initializes topic assignments from count (optionally using a topic-word prior phi), estimates regression parameters, and repeatedly calls the C++ routine stm_vi_parallel() until convergence.

Usage

run_stm_vi(
  count,
  y,
  K,
  alpha,
  beta,
  phi = NULL,
  seed = NULL,
  max_iter = 200L,
  min_iter = 50L,
  tol_elbo = 1e-04,
  update_sigma = TRUE,
  tau = 20L,
  show_progress = TRUE,
  chunk = 5000L,
  verbose = TRUE,
  sigma2_init = NULL
)

Arguments

Details

Convergence is assessed based on the relative changes in the evidence lower bound (ELBO) and the supervised label log-likelihood:

\frac{\mathrm{ELBO}_t - \mathrm{ELBO}_{t-1}}{|\mathrm{ELBO}_{t-1}|}, \qquad \frac{\ell_t - \ell_{t-1}}{|\ell_{t-1}|}.

After a minimum number of iterations, the algorithm is declared to have converged when both quantities are non-negative and smaller than the prescribed tolerance.

**Important:** This function assumes that the response vector y contains **no NA** values. The underlying C++ implementation does not skip missing responses and requires y[d] to be finite for all documents.

Value

A list containing:

nd

D x K document-topic count matrix.

nw

K x V topic-word count matrix.

ndsum

Length-D vector of document token counts.

nwsum

Length-K vector of topic token counts.

eta

K-dimensional regression coefficient vector.

sigma2

Final noise variance.

phi

V x K topic-word posterior mean.

theta

D x K document-topic posterior mean.

elbo

Final ELBO.

label_loglik

Final supervised term.

elbo_trace

ELBO values per sweep.

label_loglik_trace

Label log-likelihood per sweep.

n_iter

Number of iterations actually performed.

D, V, K, NZ

Model dimensions.

Set threading options for STM/MLSTM computations

Description

This helper configures OpenMP/BLAS threads to ensure reproducible and stable performance across the low-level C++ routines used by the package.

Usage

set_threads(num_threads = NULL)

Arguments

Value

Invisibly returns an integer giving the number of threads used.

Variational inference for multi-output supervised topic models with hierarchical prior.

Description

The model includes: - LDA structure: theta_d ~ Dir(alpha), phi_k ~ Dir(beta) - Gaussian response: y[d,j] ~ N(zbar_d^T eta_j, sigma_j^2) - Hierarchical prior: eta_j ~ N(mu, Lambda^-1) Lambda ~ inverse-Wishart(upsilon, Omega)

Usage

stm_multi_hier_vi_parallel(
  mod,
  docs,
  y,
  ndsum,
  NZ,
  V,
  K,
  J,
  alpha,
  beta,
  mu,
  upsilon,
  Omega,
  update_sigma = TRUE,
  tau = 20L,
  exact_second_moment = FALSE,
  show_progress = TRUE,
  chunk = 5000L
)

Arguments

Value

A list with updated variational parameters and diagnostics:

nd

D x K integer matrix of document-topic counts.

nw

K x V integer matrix of topic-word counts.

eta

K x J numeric matrix of regression coefficients.

sigma2

Length-J numeric vector of noise variances.

Lambda_E

K x K numeric matrix, posterior mean of precision matrix Lambda.

IW_upsilon_hat

Numeric scalar, posterior degrees of freedom.

IW_Omega_hat

K x K numeric matrix, posterior scale matrix.

elbo

Numeric scalar, evidence lower bound.

label_loglik

Numeric scalar, supervised log-likelihood term.

Variational inference for supervised LDA (single continuous response).

Description

The model combines unsupervised topic modeling (LDA) with a Gaussian response on document-level topic proportions.

Usage

stm_vi_parallel(
  mod,
  docs,
  y,
  ndsum,
  NZ,
  V,
  K,
  alpha,
  beta,
  update_sigma = TRUE,
  tau = 20L,
  show_progress = TRUE,
  chunk = 5000L
)

Arguments

Details

y_d \sim N(zbar_d^T eta, sigma^2).

This function performs one variational inference sweep with a parallel document-level E-step and simple updates for the regression parameters.

Value

A list with updated variational parameters and diagnostics:

nd

Updated D x K document-topic counts.

nw

Updated K x V topic-word counts.

eta

Updated K-dimensional regression coefficient vector.

sigma2

Updated scalar noise variance.

elbo

Scalar evidence lower bound (approximate).

label_loglik

Gaussian response log-likelihood component.