Fits a fast point-estimator approximation to the dynamic snap-shift
latent-factor model for longitudinal normal-valued networks.
It targets the same drift-versus-reset transition estimand as
lame with dynamic_uv = TRUE and
dynamic_uv_kind = "snap", but returns ALS snap scores rather than
MCMC draws.
lame_snap_als(
Y,
Xdyad = NULL,
Xrow = NULL,
Xcol = NULL,
R = 2L,
R_row = NULL,
R_col = NULL,
family = "normal",
mode = c("unipartite", "bipartite"),
symmetric = FALSE,
max_iter = 200L,
tol = 1e-06,
snap_kappa = 2,
snap_pi_prior = c(a = 1, b = 9),
snap_update = c("soft", "hard", "annealed"),
snap_damping = 0.7,
estimate_rho_uv = TRUE,
estimate_sigma_uv = TRUE,
rho_uv = NULL,
sigma_uv = NULL,
hyper_update = c("robust", "em"),
drift_quantile = 0.05,
drift_min_transitions = 50,
rho_prior_mean = 0.98,
rho_prior_weight = 25,
align = c("sequential", "global", "none"),
threshold = 0.5,
min_sigma = 1e-04,
sigma_floor_fraction = 0.75,
ridge = 1e-08,
snap_stability_tol = 0.05,
snap_convergence = c("quantile", "max", "classification"),
snap_delta_quantile = 0.95,
snap_class_change_tol = 0.005,
unstable_top_n = 10L,
stability = c("none", "quick", "validation"),
verbose = TRUE,
seed = 6886
)An object of class "lame_snap_als" with dynamic latent
positions, snap scores, fitted values, residuals, and
convergence diagnostics.
a list of relational matrices, or a 3D array. Unipartite fits use
[n, n, T] panels. Bipartite fits use rectangular
[n_row, n_col, T] panels. For named lists, slices may have changing
actor composition; the estimator pads to the union actor set and treats
absent actor-periods as unobserved and snap-ineligible. A longitudinal
netify object is also accepted and converted with
netify::to_lame(lame = TRUE).
optional list of dyadic covariate matrices/arrays, or
NULL.
not supported by this fast snap-shift estimator; pass
NULL. Use lame with method = "mcmc" for
node-covariate dynamic snap models.
positive integer latent rank. For bipartite fits, used as the
default for R_row and R_col.
positive integer latent ranks for bipartite row and
column positions. Defaults to R.
currently only "normal".
"unipartite" or "bipartite".
logical; if TRUE, fit a symmetric latent-factor
approximation and report one snap-probability matrix.
maximum block-coordinate iterations.
convergence tolerance on the relative change of the tracked \(-2\times\) variational free energy (see Details).
diffuse snap-prior standard deviation.
length-two vector c(a, b) for the beta prior
used to regularize the snap rate.
one of "soft", "hard", or
"annealed".
scalar in (0, 1]; damping applied to soft
snap-score updates. Values below 1 mix the new score with the
previous score to reduce oscillation on large panels. Ignored for
snap_update = "hard".
logical flags for updating the AR drift persistence and innovation scale.
optional fixed/initial AR drift parameters.
one of "robust" or "em". The default
"robust" estimates drift hyperparameters from the lower tail of
transition innovations, which prevents broad ruptures from being absorbed
into an overly diffuse drift process. "em" uses the untrimmed
soft-classification moment update.
lower-tail transition quantile used by
hyper_update = "robust" for estimating smooth-drift
hyperparameters.
minimum effective number of transitions retained by the lower-tail update. This keeps the default from overfitting the smooth-drift scale on small panels.
weak regularization for the persistence estimate. The defaults encode the snap-shift model's intended persistent, low-innovation drift baseline.
initialization alignment mode; "global" aligns each
period to the pooled static ALS fit, "sequential" aligns each
period to the previous initialized period, and "none" leaves
per-period factors unaligned.
hard-classification threshold for snap_class.
lower bound for the drift scale.
for robust hyperparameter updates, the iterative
drift scale cannot fall below this fraction of the initial
sigma_uv. This prevents broad snap assignments from collapsing the
smooth-drift variance to min_sigma.
small ridge added to latent-position normal equations.
tolerance for declaring soft snap scores stable.
This is separate from tol, which tracks the penalized objective.
convergence criterion for snap scores.
"quantile" uses snap_delta_quantile of the absolute
score changes plus the class-change share; "max" uses the
worst actor-period score change; "classification" uses only
class-change stability. The worst-case max is always stored
and warned about when high.
quantile of actor-period score changes used by
snap_convergence = "quantile".
maximum share of eligible actor-periods whose
snap_class may change between iterations while still declaring
snap convergence.
number of largest actor-period snap-score changes to store in convergence diagnostics.
optional start-sensitivity preset. "none" runs one
fit. "quick" and "validation" rerun the same estimator from
additional seeds and attach fit$stability with snap-score,
classification, top-period, and fitted-surface comparisons.
logical; print progress.
integer seed for initialization perturbations.
The raw snap-ALS intercept mu is not separately identified
from the uncentered multiplicative term: a constant level can be absorbed
into \(\mathrm{mean}(U_t V_t')\) (bipartite:
\(\mathrm{mean}(U_t G V_t')\)), so fit$mu on its own is
arbitrary. After convergence the estimator therefore computes a post-hoc
identified level: fit$mu_t stores the per-period level
\(\mu + \mathrm{mean}(U_t V_t')\) (named by period) and
fit$mu_identified is the mean of fit$mu_t. Interpret the
network level through mu_identified; the latent trajectories and
the covariate coefficients are unaffected by this shift and remain
reliable outputs of this estimator.
On longer panels, the default align = "sequential" keeps the
period-to-period movement in view. align = "global" can help on very
short panels, but on longer panels it can pull each period back toward the
pooled static fit and make early jumps look too strong. If you have a fixed
drift scale, pass rho_uv and sigma_uv with
estimate_rho_uv = FALSE and estimate_sigma_uv = FALSE.
The convergence output separates the usual score summary from the worst
moving actor-period. By default, convergence uses the 95th percentile of
score changes and the share of class changes. final_max_snap_delta
and unstable_transitions still show the largest local moves. Read
snap_prob as an ALS snap score. It is useful for rankings and
heuristic classifications; it is not a Bayesian posterior probability.
For unipartite fits, the tracked objective (fit$objective_trace,
fit$convergence$final_objective) is the exact \(-2\times\)
variational free energy of the snap/drift mixture model, including the
Gaussian log-normalizers, the responsibility entropy, and the beta prior
on the snap rate. The exact block updates descend it monotonically; small
increases can come from damped snap scores or the robust hyperparameter
updates. Because it carries log-variance normalizers it can be negative
and is not a deviance; fit$param_trace$sse tracks raw data fit
directly.
In bipartite mode, the fitted multiplicative term is
\(U_t G V_t'\) with one static interaction matrix \(G\). The returned
snap_prob matrix contains row-actor snap scores and
snap_prob_v contains column-actor snap scores. Bipartite snap ALS
does not estimate node covariates, dynamic coefficients, or a dynamic
\(G_t\); those combinations need a separate model.
set.seed(1)
Y_bip <- lapply(seq_len(3), function(t) {
m <- matrix(rnorm(6 * 5), 6, 5)
rownames(m) <- paste0("r", seq_len(6))
colnames(m) <- paste0("c", seq_len(5))
m
})
fit_bip <- lame_snap_als(Y_bip, R = 1, mode = "bipartite",
max_iter = 3, verbose = FALSE)
dim(fit_bip$snap_prob_v)
Run the code above in your browser using DataLab