Package 'factorana'

Description

Generates R bootstrap samples, fits every replicate in a local loop (each fit is restartable via ⁠stage_dir/sample_<id>.rds⁠), and collects the results. For a single estimation stage on one machine. For multi-stage, distributed, or restart-heavy workflows, use the primitives (generate_bootstrap_samples(), bootstrap_fit_sample(), collect_bootstrap()) directly so each stage and sample is an independent, resumable job.

Usage

bootstrap_factorana(
  model_system,
  data,
  R,
  cluster = NULL,
  stage_dir,
  control = NULL,
  seed = NULL,
  conf_level = 0.95,
  ...
)

Arguments

Value

A factorana_bootstrap object (see collect_bootstrap()).

See Also

generate_bootstrap_samples(), bootstrap_fit_sample(), collect_bootstrap()

Description

Runs a multi-stage bootstrap on one machine: for each replicate, fits each stage in turn, chaining every stage on that replicate's own earlier-stage fits. Each (stage, sample) fit is written to ⁠dir/stage_<k>/sample_<id>.rds⁠ and skipped if it already exists, so an interrupted run resumes where it stopped. If a stage fails to converge for a replicate, its later stages are skipped (so a bad earlier fit is not chained forward).

Usage

bootstrap_factorana_multistage(
  stage_builders,
  data,
  R,
  cluster = NULL,
  dir,
  control = NULL,
  seed = NULL,
  conf_level = 0.95,
  ...
)

Arguments

Details

For distributed (multi-node) runs, drive the same per-stage, per-sample work with bootstrap_fit_sample() directly (one array-job task per sample), which is what this driver does internally.

Value

A factorana_bootstrap_multistage list with a per-stage collect_bootstrap() summary in stages and final pointing at the last stage.

See Also

bootstrap_factorana(), bootstrap_fit_sample(), collect_bootstrap()

Description

Fits model_system to the data reweighted by bootstrap sample sample_id and writes the result to ⁠stage_dir/sample_<id>.rds⁠. If that file already exists it returns immediately, so an interrupted run (or a rebooted node) simply re-runs the missing samples. This is the unit of work to scatter across a compute cluster (one array-job task per sample_id).

Usage

bootstrap_fit_sample(
  model_system,
  data,
  samples,
  sample_id,
  stage_dir,
  control = NULL,
  ...,
  weight_col = ".bootw",
  overwrite = FALSE
)

Arguments

Details

Rows whose bootstrap weight is zero are dropped, and the remaining rows are given their integer frequency weight via model_system$weights. For a multi-stage workflow, set model_system$previous_stage (built from this sample's previous-stage fit) before calling, so each replicate chains on its own earlier stage.

Value

Invisibly, the path to the written result file.

See Also

generate_bootstrap_samples(), collect_bootstrap()

Description

Constructs a dummy previous_stage result that plugs the anchor-period measurement intercepts into every factor slot, pairs them with the (tied) shared loadings and residual sigmas / thresholds, and is ready to pass as previous_stage to a Stage 2 SE_linear or SE_quadratic model via define_model_system.

Usage

build_dynamic_previous_stage(dyn, stage1_result, data, anchor_period = 1L)

Arguments

Value

A list suitable as previous_stage in define_model_system: has fields model_system, estimates, std_errors, convergence, loglik. Every per-component measurement parameter is the corresponding Stage 1 estimate, with the intercepts overwritten to the anchor-period values for all periods.

See Also

define_dynamic_measurement.

Description

When using parallel estimation with Ctrl-C interrupts, worker processes may continue running after the main process exits. This function finds and terminates any orphaned R worker processes started by the parallel package.

Usage

cleanup_parallel_workers(signal = "TERM", verbose = TRUE, list_only = FALSE)

Arguments

Value

Invisible NULL (or vector of PIDs if list_only = TRUE)

Examples

# Safe to run: list potential orphaned parallel workers without killing them.
cleanup_parallel_workers(list_only = TRUE, verbose = FALSE)


# After interrupting a parallel job with Ctrl-C, terminate orphaned workers:
cleanup_parallel_workers()

# Force kill if graceful shutdown doesn't work:
cleanup_parallel_workers(signal = "KILL")

Description

Reads every ⁠sample_<id>.rds⁠ in stage_dir, stacks the estimates, and returns the bootstrap covariance, bootstrap standard errors, and percentile confidence intervals. Non-converged replicates are dropped by default.

Usage

collect_bootstrap(stage_dir, conf_level = 0.95, require_convergence = TRUE)

Arguments

Value

A factorana_bootstrap list with boot_se, boot_cov, ci (a data frame of percentile intervals and bootstrap SEs), the stacked estimates, and counts (n_total, n_converged, n_used).

See Also

generate_bootstrap_samples(), bootstrap_fit_sample()

Description

Creates a table with model components as columns and parameter types as rows. This is similar to how SEM/CFA software displays results.

Usage

components_table(result, digits = 3, show_se = TRUE, stars = TRUE)

Arguments

Value

A data frame with the formatted table

Examples

# Estimate a small model and display the components table
set.seed(1); n <- 200
f <- rnorm(n)
dat <- data.frame(intercept = 1,
                  y1 = 1.0 * f + rnorm(n, 0, 0.5),
                  y2 = 0.8 * f + rnorm(n, 0, 0.5))
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
fit <- estimate_model_rcpp(ms, dat, control = ctrl,
  optimizer = "nlminb", parallel = FALSE, verbose = FALSE)

components_table(fit)

Description

Creates a LaTeX table from a factorana_result with components as columns.

Usage

components_to_latex(
  result,
  digits = 3,
  file = NULL,
  caption = NULL,
  label = NULL,
  stars = TRUE,
  note = NULL,
  booktabs = TRUE
)

Arguments

Value

A character string containing the LaTeX table code

Description

Builds a Stage 1 measurement model for a single latent construct observed at two or more time points. Measurement invariance is imposed on loadings and residual sigmas (tied across periods via equality_constraints), while measurement intercepts are left period-specific. This is the recommended Stage 1 setup for an SE_linear or SE_quadratic structural model in the second stage.

Usage

define_dynamic_measurement(
  data,
  items,
  period_prefixes,
  model_type = "linear",
  n_categories = NULL,
  covariates = "intercept",
  evaluation_indicator = NULL
)

Arguments

Details

Why period-specific intercepts? Under the usual factor-model identification convention E[f_k] = 0 for every factor k, pooling measurement intercepts across periods biases them by $\lambda_m \cdot E[f_2]/2$ when the period-mean drifts between waves, an artefact that propagates into an under-estimate of se_intercept in Stage 2. Leaving the intercepts period-specific and carrying the wave-1 intercepts into Stage 2 (via build_dynamic_previous_stage) sidesteps the bias.

Value

An object of class "dynamic_measurement": a list with

• model_system: a model_system object ready to pass to estimate_model_rcpp.

• factor_model: the underlying factor_model.

• items, period_prefixes, model_type, n_categories, covariates, evaluation_indicator: the inputs, kept for use by build_dynamic_previous_stage.

See Also

build_dynamic_previous_stage constructs the Stage 2 previous_stage object from the Stage 1 estimation result.

Examples

# Simulate a simple dynamic single-factor model
set.seed(1); n <- 500
f1 <- rnorm(n); eps <- rnorm(n, 0, sqrt(0.5))
f2 <- 0.4 + 0.6 * f1 + eps
dat <- data.frame(
  intercept = 1, eval = 1L,
  Y_t1_m1 = 1.5 + f1 + rnorm(n, 0, 0.7),
  Y_t1_m2 = 1.0 + 0.9 * f1 + rnorm(n, 0, 0.75),
  Y_t1_m3 = 0.8 + 1.1 * f1 + rnorm(n, 0, 0.65),
  Y_t2_m1 = 1.5 + f2 + rnorm(n, 0, 0.7),
  Y_t2_m2 = 1.0 + 0.9 * f2 + rnorm(n, 0, 0.75),
  Y_t2_m3 = 0.8 + 1.1 * f2 + rnorm(n, 0, 0.65)
)
dyn <- define_dynamic_measurement(
  data = dat, items = c("m1", "m2", "m3"),
  period_prefixes = c("Y_t1_", "Y_t2_"),
  model_type = "linear", evaluation_indicator = "eval"
)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
s1 <- estimate_model_rcpp(dyn$model_system, dat, control = ctrl,
                          optimizer = "nlminb", parallel = FALSE,
                          verbose = FALSE)
prev <- build_dynamic_previous_stage(dyn, s1, dat)   # Stage 2 input

Description

Define estimation control settings

Usage

define_estimation_control(
  n_quad_points = 16,
  num_cores = 1,
  cluster_type = "auto",
  adaptive_integration = FALSE,
  adapt_int_thresh = 0.5
)

Arguments

Details

Adaptive integration is useful in two-stage estimation where factor scores have been estimated in a first stage. The key insight is that observations with well-identified factor scores (small SE) need fewer integration points, while observations with poorly-identified factors (large SE) need full quadrature.

To use adaptive integration:

1. Estimate Stage 1 model to get factor scores via estimate_factorscores_rcpp()

2. Initialize FactorModel for Stage 2 via initialize_factor_model_cpp()

3. Call set_adaptive_quadrature_cpp() with factor scores, SEs, and variances

4. Run estimation - the adaptive settings are applied automatically

The diagnostic output from set_adaptive_quadrature_cpp(verbose=TRUE) shows:

• Distribution of integration points across observations

• Average integration points vs standard (shows computational savings)

• Computational reduction percentage

Value

An object of class estimation_control containing control settings

Description

Creates an object of class "factor_model" that specifies the structure of the unobserved latent factors. This includes the number of factors and mixture components. Loading constraints are specified at the component level via define_model_component(). Numerical integration settings (quadrature points) are specified in define_estimation_control().

Usage

define_factor_model(
  n_factors,
  n_types = 1,
  factor_structure = "independent",
  n_mixtures = 1,
  factor_covariates = NULL,
  se_covariates = NULL
)

Arguments

Value

An object of class "factor_model"

Examples

# Single factor model
fm <- define_factor_model(n_factors = 1)

# Two-factor structural equation model
fm_se <- define_factor_model(n_factors = 2, factor_structure = "SE_linear")

Description

Define a model component

Usage

define_model_component(
  name,
  data,
  outcome,
  factor,
  evaluation_indicator = NULL,
  covariates = NULL,
  model_type = c("linear", "logit", "probit", "oprobit"),
  intercept = TRUE,
  num_choices = 2,
  nrank = NULL,
  exclude_chosen = TRUE,
  rankshare_var = NULL,
  loading_normalization = NULL,
  factor_index = NULL,
  factor_spec = c("linear", "quadratic", "interactions", "full"),
  use_types = FALSE,
  skip_collinearity_check = FALSE
)

Arguments

Value

An object of class "model_component". A list representing the model component

Examples

dat <- data.frame(y = rnorm(50), intercept = 1)
fm <- define_factor_model(n_factors = 1)
mc <- define_model_component("Y", dat, "y", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)

# Multi-factor: assign an item to a factor with the length-n_factors vector.
dat2 <- data.frame(y1 = rnorm(50), y2 = rnorm(50))
fm2 <- define_factor_model(n_factors = 2)
# item loads on factor 1 only, as its anchor (loading fixed at 1):
a1 <- define_model_component("a1", dat2, "y1", fm2,
  loading_normalization = c(1, 0))
# item loads freely on factor 2 only -- same thing via factor_index:
a2 <- define_model_component("a2", dat2, "y2", fm2,
  factor_index = 2, loading_normalization = NA_real_)

Description

Define a model system

Usage

define_model_system(
  components,
  factor,
  previous_stage = NULL,
  weights = NULL,
  equality_constraints = NULL,
  free_params = NULL
)

Arguments

Value

An object of class "model_system". A list of model_component objects and one factor_model object.

Examples

dat <- data.frame(y1 = rnorm(50), y2 = rnorm(50), intercept = 1)
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)

Description

Reverts to standard (non-adaptive) quadrature integration.

Usage

disable_adaptive_quadrature_cpp(fm_ptr)

Arguments

Value

No return value. Called for its side effect of disabling adaptive quadrature and clearing any observation weights on the FactorModel pointed to by fm_ptr.

Description

Calls estimate_model(), then writes the four expected output files:

• model_config.csv

• meas_par.csv

• system_inits_long.csv

• simulated_data.csv

Usage

estimate_and_write(
  model_system,
  factor_model,
  control,
  data = NULL,
  results_dir
)

Arguments

Value

Invisibly returns a list with two components: results (a data frame of initial parameter values per component, as produced by estimate_model()) and packed (a list with values and ses giving the packed parameter vector and standard errors written to meas_par.csv). Called primarily for the side effect of writing model_config.csv, meas_par.csv, system_inits_long.csv, and optionally simulated_data.csv into results_dir.

Description

Estimates factor scores for each observation after model estimation. The model parameters are held fixed at their estimated values, and factor scores are computed as the posterior mode for each observation.

Usage

estimate_factorscores_rcpp(
  result,
  data,
  control = NULL,
  parallel = FALSE,
  verbose = TRUE,
  include_prior = FALSE,
  id_var = NULL
)

Arguments

Details

Factor scores are estimated by maximizing the posterior density:

$L(f|y_i, \theta) = p(y_i|f, \theta) \cdot \phi(f|0, \sigma^2)$

where:

• $f$ is the vector of factor values for observation i

• $y_i$ is the observed data for observation i

• $\theta$ are the fixed model parameters (from previous estimation)

• $\phi(f|0, \sigma^2)$ is the normal prior on factors

Standard errors are computed from the diagonal of the inverse Hessian of the log-posterior at the mode. By default (include_prior=FALSE), the SE is based only on the observation likelihood Hessian, matching the legacy C++ implementation. Set include_prior=TRUE to include the prior's Hessian contribution (-1/sigma^2) which produces smaller SEs.

When parallel=TRUE, observations are distributed across cores using doParallel/foreach, with each worker processing a subset of observations.

Value

A data frame with columns:

• obs_id - Observation index (1-based)

• <id_var> - ID variable values (if id_var was specified)

• factor_1, factor_2, ... - Estimated factor scores

• se_factor_1, se_factor_2, ... - Standard errors

• converged - Whether optimization converged for this observation

• log_posterior - Log-posterior value at the mode

Examples

# Estimate a small one-factor model, then recover factor scores
set.seed(1); n <- 200
f <- rnorm(n)
dat <- data.frame(intercept = 1,
                  y1 = 1.0 * f + rnorm(n, 0, 0.5),
                  y2 = 0.8 * f + rnorm(n, 0, 0.5))
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
fit <- estimate_model_rcpp(ms, dat, control = ctrl,
  optimizer = "nlminb", parallel = FALSE, verbose = FALSE)

fscores <- estimate_factorscores_rcpp(fit, dat, control = ctrl,
                                       parallel = FALSE, verbose = FALSE)
head(fscores)

Description

Estimate model

Usage

estimate_model(ms, control)

Arguments

Value

description

Description

This function estimates a factor model by optimizing the likelihood using C++ for fast evaluation and R for optimization and parallelization.

Usage

estimate_model_rcpp(
  model_system,
  data,
  init_params = NULL,
  control = NULL,
  optimizer = "nlminb",
  parallel = TRUE,
  verbose = TRUE,
  max_restarts = 5,
  factor_scores = NULL,
  factor_ses = NULL,
  factor_vars = NULL,
  init_factor_scores = NULL,
  checkpoint_file = NULL
)

Arguments

Details

For maximum efficiency, use optimizer = "nlminb" or optimizer = "trust" which exploit the analytical Hessian computed in C++. The default L-BFGS methods only use the gradient and approximate the Hessian from gradient history.

When optimization fails to converge (possibly at a saddle point), the function will attempt to escape by moving in the direction of negative Hessian eigenvalues. This is controlled by the max_restarts parameter.

Value

List with parameter estimates, standard errors, log-likelihood, etc.

See Also

vcov_factorana() and robust_se() for robust and cluster-robust standard errors from a fitted model.

Examples

# Simulate a simple one-factor model with two linear indicators
set.seed(1); n <- 100
f <- rnorm(n)
dat <- data.frame(intercept = 1,
  y1 = 1.0 * f + rnorm(n, 0, 0.5),
  y2 = 0.8 * f + rnorm(n, 0, 0.5))
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
result <- estimate_model_rcpp(ms, dat, control = ctrl,
  optimizer = "nlminb", parallel = FALSE, verbose = FALSE)
result$estimates
# Robust (Huber-White) standard errors from the same fit:
robust_se(result, dat, type = "robust")

Description

Used for factor score estimation. The model parameters are held fixed, and the factor values are treated as the parameters to optimize.

Usage

evaluate_factorscore_likelihood_cpp(
  fm_ptr,
  iobs,
  factor_values,
  model_params,
  compute_gradient = FALSE,
  compute_hessian = FALSE,
  include_prior = TRUE
)

Arguments

Value

List with log-likelihood, gradient (if requested), and Hessian (if requested)

Description

Evaluate log-likelihood for given parameters

Usage

evaluate_likelihood_cpp(
  fm_ptr,
  params,
  compute_gradient = FALSE,
  compute_hessian = FALSE
)

Arguments

Value

List with:

• logLikelihood: scalar log-likelihood value

• gradient: vector of length n_param_free (if requested)

• hessian: vector of length n_param_free*(n_param_free+1)/2 stored as upper-triangular in row-major order (if requested). To expand to full symmetric matrix in R: idx <- 1; for(i in 1:n) for(j in i:n) { H[i,j] <- H[j,i] <- hess[idx]; idx <- idx + 1 }

Description

Evaluate log-likelihood only (for optimization)

Usage

evaluate_loglik_only_cpp(fm_ptr, params)

Arguments

Value

Log-likelihood value

Description

Evaluates the model at the supplied FREE parameters and returns the per-observation score matrix d(log L_i)/d(theta_free), i.e. the gradient of each observation's marginal (factor-integrated) log-likelihood with respect to the free parameters. Rows are observations (in the FactorModel's data order), columns are free parameters. Summing the rows reproduces the total gradient returned by evaluate_likelihood_cpp. This is the "meat" ingredient of a sandwich covariance estimator.

Usage

evaluate_obs_scores_cpp(fm_ptr, params)

Arguments

Value

Numeric matrix (nobs x nparam_free) of per-observation scores

Description

Given a full parameter vector (including fixed parameters), extract only the free parameters based on the model's fixed parameter mask.

Usage

extract_free_params_cpp(fm_ptr, full_params)

Arguments

Value

Vector of free parameters only (size n_param_free)

Description

Constrains a regression coefficient (beta) to a fixed value during estimation. The coefficient will not be optimized - it remains at the specified value.

Usage

fix_coefficient(component, covariate, value, choice = NULL)

Arguments

Details

Fixed coefficients are stored in the component and used during:

• Parameter initialization: fixed values are used directly (no estimation)

• Optimization: fixed parameters are excluded from the optimization

• Likelihood evaluation: fixed values are inserted into the parameter vector

Note: This function only fixes regression coefficients (betas), not:

• Factor loadings (use loading_normalization in define_model_component)

• Sigma (for linear models)

• Thresholds (for ordered probit)

Value

The modified model_component object with the fixed coefficient constraint added.

Examples

# Build a minimal model component and fix a coefficient
dat <- data.frame(intercept = 1, x1 = rnorm(20), y = rnorm(20))
fm <- define_factor_model(n_factors = 1)
mc <- define_model_component(
  name = "y", data = dat, outcome = "y", factor = fm,
  covariates = c("intercept", "x1"), model_type = "linear",
  loading_normalization = 1
)

# Fix intercept to 0 and x1 coefficient to 0.1
mc <- fix_coefficient(mc, covariate = "intercept", value = 0.0)
mc <- fix_coefficient(mc, covariate = "x1", value = 0.1)
length(mc$fixed_coefficients)  # 2 constraints stored on the component

Description

Constrains a parameter in the latent-factor distribution (factor variance, SE-equation slope / intercept / residual variance, type-probability intercept, type-probability loading, factor-mean covariate coefficient, or SE covariate coefficient) to a fixed value. The parameter will be held at that value during estimation, excluded from the optimizer's free vector, and reported in result$estimates with result$std_errors == 0 and result$param_table$fixed == TRUE.

Usage

fix_factor_param(factor_model, name, value = NULL)

Arguments

Details

Use this for substantive restrictions known at model-definition time, e.g., setting a ⁠type_<t>_loading_<k>⁠ to 0 when factor k is known not to enter the type-probability model. Estimating such a loading free can leak identification, push the optimizer along a flat ridge, and inflate the standard errors of the remaining type-model parameters.

Value

The modified factor_model object. The fix is stored in factor_model$fixed_params as a named numeric vector.

Conflicts with previous_stage / free_params

When define_model_system(previous_stage = ..., free_params = ...) is used, fix_factor_param() always wins. The user-fixed value is the binding constraint; any value for the same name in previous_stage$ estimates is ignored, and inclusion of the same name in free_params is silently honoured (the parameter stays fixed regardless). A warning is emitted once per conflict so accidental misuse surfaces during debugging without spamming routine workflows.

Auto-fixed slots

For SE structures, ⁠type_<t>_loading_<n_factors>⁠ (the type loading on the outcome factor) is auto-fixed at 0 because the type probability model must depend only on input factors. Calling fix_factor_param(fm, "type_<t>_loading_<n_factors>", 0) is a no-op. Calling it with any non-zero value is an error.

When a factor variance is non-identified (no measurement component fixes a non-zero loading on that factor), it is normally auto-fixed at its initial value of 1. An explicit fix_factor_param(fm, "factor_var_<k>", v) overrides the auto-fix and uses the user-supplied value.

Examples

fm <- define_factor_model(n_factors = 3, n_types = 2,
                          factor_structure = "SE_linear")

# Single fix
fm <- fix_factor_param(fm, "type_2_loading_2", 0.0)

# Batch via named numeric
fm <- fix_factor_param(fm, c(type_2_loading_2 = 0.0,
                             type_2_loading_3 = 0.0))

# Unfix
fm <- fix_factor_param(fm, "type_2_loading_2", NA_real_)

Description

For models with n_types > 1, each component has type-specific intercepts that shift the linear predictor for each non-reference type. This function constrains those intercepts to zero, effectively removing the type-specific shift for this component.

Usage

fix_type_intercepts(component, types = NULL, choice = NULL)

Arguments

Details

When n_types > 1, the model includes a latent type structure where different types can have different intercepts in each measurement equation. By default, these intercepts are freely estimated. Fixing them to zero constrains the outcome equation to have no type-specific shifts (though the type model loadings at the factor level may still differ).

This is useful when you want the type model to affect outcomes only through factor loadings, not through direct type-specific intercepts.

Fixed type intercepts are stored in the component and used during:

• Parameter initialization: fixed values are used directly (no estimation)

• Optimization: fixed parameters are excluded from the optimization

• Likelihood evaluation: fixed values are inserted into the parameter vector

Value

The modified model_component object with the fixed type intercept constraints added.

Examples

# Build a component with n_types = 2 and fix the type-2 intercept
dat <- data.frame(intercept = 1, y = rnorm(20))
fm <- define_factor_model(n_factors = 1, n_types = 2)
mc <- define_model_component(
  name = "y", data = dat, outcome = "y", factor = fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1, use_types = TRUE
)
mc <- fix_type_intercepts(mc)
length(mc$fixed_type_intercepts)

Description

Compute Gauss-Hermite quadrature nodes and weights

Usage

gauss_hermite_quadrature(n)

Arguments

Value

List with nodes and weights

Description

Draws R bootstrap replicates by resampling clusters (or rows) with replacement and records, for each replicate, the integer frequency weight of every row (the number of times its cluster was drawn). The weights are saved once so that the same replicate is reproducible across nodes and across restarts.

Usage

generate_bootstrap_samples(data, R, cluster = NULL, dir = NULL, seed = NULL)

Arguments

Value

A factorana_boot_samples list with weights (an integer nrow(data) x R matrix), and metadata (R, nobs, n_clusters). Invisibly returns the same object when dir is supplied.

See Also

bootstrap_fit_sample(), collect_bootstrap(), bootstrap_factorana()

Description

Get parameter counts from FactorModel

Usage

get_parameter_info_cpp(fm_ptr)

Arguments

Value

List with parameter count information

Description

Initialize a FactorModel C++ object from R model system

Usage

initialize_factor_model_cpp(
  model_system,
  data,
  n_quad = 8L,
  init_params = NULL
)

Arguments

Value

External pointer to FactorModel object

Description

Estimates each model component separately in R (ignoring factors) to obtain good starting values. Also checks factor identification.

Usage

initialize_parameters(model_system, data, factor_scores = NULL, verbose = TRUE)

Arguments

Details

Factor identification: For each factor, if NO component has a non-zero fixed loading, then the factor variance is not identified and must be fixed to 1.0.

When factor_scores is provided, the initialization will estimate loadings by treating factor scores as additional regressors. For example, for a linear model: Y ~ X + factor_scores and the coefficients on factor_scores become the loading estimates. This typically provides better starting values than the default (0.5).

Value

List with:

• init_params - Initial parameter values

• factor_variance_fixed - Logical vector indicating which factor variances must be fixed

Description

Print method for components_table

Usage

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

Arguments

Value

Invisibly returns x. Called for its side effect of printing a components-as-columns view of model estimates (one column per model component, factor parameters in a separate section) to the console.

Description

Print method for factorana_factorscores

Usage

## S3 method for class 'factorana_factorscores'
print(x, n = 10, ...)

Arguments

Value

Invisibly returns x. Called for its side effect of printing a summary of the factor score estimates (convergence rate, per-factor summary statistics, and the first n rows) to the console.

Description

Functions for displaying and exporting factor model estimation results in formatted tables, including LaTeX output. Print method for factorana_result objects

Usage

## S3 method for class 'factorana_result'
print(x, digits = 4, ...)

Arguments

Value

Invisibly returns x. Called for its side effect of printing a formatted summary (convergence status, log-likelihood, and a parameter table with estimates and standard errors) to the console.

Description

Print method for factorana_table

Usage

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

Arguments

Value

Invisibly returns x. Called for its side effect of printing a side-by-side model-comparison table (parameters grouped by component, with estimates and standard errors) to the console.

Description

Print method for model_component objects

Usage

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

Arguments

Value

Invisibly returns x. Called for its side effect of printing a human-readable summary of the component to the console.

Description

Print method for summary.factorana_result

Usage

## S3 method for class 'summary.factorana_result'
print(x, digits = 4, ...)

Arguments

Value

Invisibly returns x. Called for its side effect of printing a detailed estimation summary (convergence, log-likelihood, and a coefficient table with z-values and significance stars) to the console.

Description

Creates a table comparing estimates across multiple models, with standard errors in parentheses below each estimate.

Usage

results_table(
  ...,
  model_names = NULL,
  digits = 3,
  se_format = c("parentheses", "brackets", "below"),
  include_loglik = TRUE,
  include_n = TRUE,
  stars = TRUE
)

Arguments

Value

A data frame with the formatted table

Examples

# Estimate a small one-factor model and format the result as a table
set.seed(1); n <- 200
f <- rnorm(n)
dat <- data.frame(intercept = 1,
                  y1 = 1.0 * f + rnorm(n, 0, 0.5),
                  y2 = 0.8 * f + rnorm(n, 0, 0.5))
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
fit <- estimate_model_rcpp(ms, dat, control = ctrl,
  optimizer = "nlminb", parallel = FALSE, verbose = FALSE)

results_table(fit, model_names = "Baseline")

Description

Creates a LaTeX table from factorana results, suitable for academic papers.

Usage

results_to_latex(
  ...,
  model_names = NULL,
  digits = 3,
  file = NULL,
  caption = NULL,
  label = NULL,
  stars = TRUE,
  note = NULL,
  booktabs = TRUE,
  include_loglik = TRUE,
  param_labels = NULL
)

Arguments

Value

A character string containing the LaTeX table code

Examples

# Estimate a small model and export the result as a LaTeX table
set.seed(1); n <- 200
f <- rnorm(n)
dat <- data.frame(intercept = 1,
                  y1 = 1.0 * f + rnorm(n, 0, 0.5),
                  y2 = 0.8 * f + rnorm(n, 0, 0.5))
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
fit <- estimate_model_rcpp(ms, dat, control = ctrl,
  optimizer = "nlminb", parallel = FALSE, verbose = FALSE)

# Return LaTeX as a character string
tex <- results_to_latex(fit, model_names = "Baseline")

# Or write to a file inside tempdir()
results_to_latex(fit,
                 model_names = "Baseline",
                 file = file.path(tempdir(), "results_table.tex"))

Description

Convenience wrapper returning sqrt(diag(vcov_factorana(...))) as a named vector over the full parameter vector. See vcov_factorana() for details and caveats.

Usage

robust_se(
  object,
  data,
  type = c("robust", "cluster"),
  cluster = NULL,
  n_quad = NULL,
  finite_sample = TRUE
)

Arguments

Value

Named numeric vector of standard errors (fixed/tied parameters are 0).

See Also

vcov_factorana()

Description

Enables adaptive integration where the number of quadrature points varies by observation based on the precision of factor score estimates. When factor scores are well-determined (small SE), fewer integration points are used. Importance sampling weights are computed automatically.

Usage

set_adaptive_quadrature_cpp(
  fm_ptr,
  factor_scores,
  factor_ses,
  factor_vars,
  threshold = 0.5,
  max_quad = 16L,
  verbose = TRUE
)

Arguments

Value

No return value. Called for its side effect of enabling adaptive quadrature on the FactorModel pointed to by fm_ptr and (when verbose = TRUE) printing a summary of the per-observation integration-point distribution.

Description

Sets per-observation weights for the likelihood calculation. When weights are set, each observation's contribution to the log-likelihood is multiplied by its weight. This is used for importance sampling in adaptive integration.

Usage

set_observation_weights_cpp(fm_ptr, weights)

Arguments

Value

No return value. Called for its side effect of setting the per-observation likelihood weights on the FactorModel pointed to by fm_ptr.

Description

Generates a simulated data set from a fitted or fully specified factorana model, following the legacy simulation algorithm: for each simulated unit a base row is drawn from data (with weights) to supply the covariates, the latent factor(s) are drawn from the model's unconditional distribution, and each component's outcome is drawn from its model (linear, probit, logit, or ordered probit) given the covariates and factors.

Usage

simulate_factor_model(
  object,
  data,
  n = NULL,
  params = NULL,
  weights = NULL,
  seed = NULL,
  detail = TRUE
)

Arguments

Details

Supports all four model types (linear, probit, logit including multinomial, ordered probit), latent types, mixtures of normals, and the independent, correlated, and structural-equation (⁠SE_*⁠) factor structures. The simulated outcome column is named after each component's outcome variable, so the returned data frame can be re-estimated with the same model system.

Value

A data frame with one row per simulated unit: an xid, the resampled covariates, the drawn latent factor(s) (⁠factor_<k>⁠), and per component the simulated outcome (named after the component) plus, when detail = TRUE, the diagnostic columns.

See Also

estimate_model_rcpp()

Description

Summary method for factorana_result objects

Usage

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

Arguments

Value

A summary object with formatted tables

Description

Computes a sandwich (Huber-White) or cluster-robust covariance matrix for a model fitted with estimate_model_rcpp(), as a post-hoc alternative to the default inverse-Hessian (model-based) standard errors. The estimator is

$V = H^{-1} B H^{-1},$

where the "bread" $H^{-1}$ is the inverse observed information already computed at fit time and the "meat" $B$ is built from the per-observation scores of the marginal (factor-integrated) log-likelihood: $B = \sum_i g_i g_i'$ (robust) or $B = \sum_c s_c s_c'$ with $s_c = \sum_{i \in c} g_i$ (cluster).

Usage

vcov_factorana(
  object,
  data,
  type = c("hessian", "robust", "cluster"),
  cluster = NULL,
  n_quad = NULL,
  finite_sample = TRUE
)

Arguments

Details

One factorana observation is one row of data, with its measurements integrated jointly over the latent factors. The latent factor therefore already models the within-row dependence. Clustering is meaningful only when a cluster groups several rows (for example several individuals in the same household or school, or several stacked person-wave rows for one person in a long-format second stage). With one row per cluster, the cluster estimator reduces to the ordinary robust estimator.

For two-stage estimates these standard errors treat the first-stage (measurement) parameters and any plug-in factor scores as known, so they understate uncertainty (the generated-regressor problem). Use a bootstrap that re-runs both stages for honest two-stage inference.

Value

A ⁠nparam x nparam⁠ covariance matrix over the full parameter vector, with row/column names equal to the parameter names. Fixed and equality-tied parameters have zero rows and columns. Standard errors are sqrt(diag(.)).

See Also

estimate_model_rcpp()

Description

Write a single CSV with all configuration rows

Usage

write_model_config_csv(model_system, factor_model, estimation_control, file)

Arguments

Value

Invisibly returns the data frame of configuration rows that was written to file (columns section, component, key, value, dtype). Called primarily for its side effect of writing a CSV.