Skip to contents

Extract latent positions as a tidy data frame

Source: R/latent_positions.R
latent_positions.Rd

Extracts multiplicative latent factor positions (U and V) from a fitted ame, lame or ame_als model and returns them as a tidy data frame suitable for plotting and analysis. Optionally applies Procrustes alignment for dynamic models and includes posterior standard deviations when posterior samples are available.

Usage

latent_positions(object, ...)

# S3 method for class 'ame'
latent_positions(object, align = FALSE, ...)

# S3 method for class 'lame'
latent_positions(object, align = TRUE, ...)

# S3 method for class 'ame_als'
latent_positions(object, align = FALSE, ...)

Arguments

object

A fitted ame, lame or ame_als model object with R > 0.

...

Additional arguments (currently unused).

align

Logical. For dynamic models (dynamic_uv = TRUE), apply Procrustes alignment across the time periods of this fit to remove rotational indeterminacy. Default is FALSE for ame objects (a single period, so there is nothing to align and the argument has no effect) and TRUE for lame objects.

Value

A data frame with columns:

actor

Character. Actor name (from rownames of U or V).

dimension

Integer. Latent dimension index (1 to R).

time

Character. Time period label. Dynamic fits use the time labels from the input; static (cross-sectional) fits return "1" for every row so downstream filtering by time behaves the same in both cases.

value

Numeric. The posterior mean latent position.

posterior_sd

Numeric. Posterior standard deviation of the latent position, or NA if posterior samples are not available. To enable, fit the model with posterior_opts = posterior_options(save_UV = TRUE).

type

Character. "U" for sender/row positions, "V" for receiver/column positions. Symmetric models have only "U".

Returns a zero-row data frame with correct column names if R = 0.

Details

Alignment only ever happens across the periods of one fit: with align = TRUE the fit is passed to procrustes_align, which rotates each period onto the one before it. Nothing here aligns two different fits (two chains, or the same model with and without a covariate) to a common orientation, so their latent positions are not directly comparable. To compare fits that way, stack their U matrices into an [n, R, 2] array (same actors in the same order, same R) and call procrustes_align(U = that_array) on it.

See also

procrustes_align for standalone Procrustes alignment, uv_plot for visualizing latent positions, posterior_options for enabling posterior sampling of U/V

Author

Cassy Dorff, Shahryar Minhas, Tosin Salau

Examples

# \donttest{
data(YX_nrm)
fit <- ame(YX_nrm$Y, Xdyad = YX_nrm$X, R = 2,
           burn = 5, nscan = 5, odens = 1, verbose = FALSE)
lp <- latent_positions(fit)
#> ℹ `posterior_sd` is "NA" because U/V samples were not saved.
#> ℹ To get posterior SDs, refit with `posterior_opts = posterior_options(save_UV
#>   = TRUE)`.
#> This message is displayed once per session.
head(lp)
#>   actor dimension time      value posterior_sd type
#> 1 node1         1    1 -0.1288226           NA    U
#> 2 node2         1    1  0.4080307           NA    U
#> 3 node3         1    1  0.4575497           NA    U
#> 4 node4         1    1 -0.1090946           NA    U
#> 5 node5         1    1  0.1460432           NA    U
#> 6 node6         1    1  0.1578961           NA    U
# }