BLSM (version 0.1.0)

estimate_latent_positions: BLSM simulation

Description

Core function of the BLSM package: run a simulation to obtain the positions of the network nodes in the latent space for each sampled iteration.

The positions are simulated accordingly to the model assumptions, please refer to BLSM for further information. The output of the function can be used to retrieve and compare specific iterations, observe their evolution or simply compute the average positions (more details in the descriptions and examples below).

Usage

estimate_latent_positions(Y, W, procrustean = TRUE, k = 2, alpha = 2,
  nscan = 8 * 10^5, burn_in = 5 * 10^5, odens = 10^3, zdelta = 1,
  z_norm_prior_mu = 0, z_norm_prior_sd = 10, adelta = 0.3,
  a_exp_prior_a = 1, a_exp_prior_b = 1, dynamic_plot = FALSE,
  dynamic_circles = FALSE, ...)

Arguments

Y

Adjacency matrix of the network

W

(Optional) BLSM Weight matrix of the network

procrustean

Boolean to include/exclude (TRUE/FALSE) the Procrustean Transform step in the algorithm. Set TRUE by default.

k

Space dimensionality

alpha

Starting value of the \(\alpha\) variable

nscan

Number of iterations

burn_in

Burn-in value (starting iterations to be discarded)

odens

Thinning: only 1 iteration every odens will be sampled and stored in the output

zdelta

Standard deviation of the Gaussian proposal for latent positions

z_norm_prior_mu

Mean of the Gaussian prior distribution for latent positions

z_norm_prior_sd

Standard deviation of the Gaussian prior distribution for latent positions

adelta

The uniform proposal for \(\alpha\) is defined on the \([-adelta,+adelta]\) interval

a_exp_prior_a

Shape parameter of the Gamma prior distribution for \(\alpha\). As the value is usually set to 1 the prior is an exponential distribution.

a_exp_prior_b

Rate parameter of the Gamma prior distribution for \(\alpha\).

dynamic_plot

Boolean to plot dynamically the simulated positions (one update every odens iterations)

dynamic_circles

Boolean to add circles of radius \(\alpha\) to the dynamic plots

…

Additional parameters that can be passed to plot_latent_positions

Value

Returns a "BLSM object" (blsm_obj), i.e. a list containing:

• Alpha \(\alpha\) values from the sampled iterations

• Likelihood Log-likelihood values from the sampled iterations

• Iterations Latent space coordinates from the sampled iterations. Latent positions are stored in a 3D array whose dimensions are given by (1: number of nodes, 2: space dimensionality, 3: number of iterations). In the non-Procrustean framework the latent distances are given instead of the positions: another 3D array is returned, whose dimensions are given by (1: number of nodes, 2: number of nodes, 3: number of iterations). The command needed in order to get the average values over the iterations for either the positions or the distances is rowMeans(blsm_obj$Iterations, dims=2) (see example below).

• StartingPositions Latent space coordinates right after the initialization step. In the non-Procrustean framework starting distances are given instead.

• Matrix Original matrices of the network (adjacency and BLSM weights)

• Parameters List of parameters specified during the call to estimate_latent_positions

Examples

# NOT RUN {
 # Procrustean version followed by clustering
 blsm_obj = estimate_latent_positions(example_adjacency_matrix,  
                          burn_in = 3*10^4, nscan = 10^5, dynamic_plot = TRUE)
                          
 avg_latent_positions = rowMeans(blsm_obj$Iterations, dims=2)                   
 h_cl = hclust(dist(avg_latent_positions), method="complete")
 n = 3
 latent_space_clusters = cutree(h_cl, k=n)
 print(latent_space_clusters)
 plot(avg_latent_positions, col=rainbow(n)[latent_space_clusters], pch=20)
 
 # Non-Procrustean version followed by clustering                    
 blsm_obj_2 = estimate_latent_positions(example_adjacency_matrix, procrustean=FALSE,
                          burn_in = 3*10^4, nscan = 10^5)
 avg_latent_distances = rowMeans(blsm_obj_2$Iterations, dims=2)
 h_cl = hclust(as.dist(avg_latent_distances), method="complete")
 n = 3
 latent_space_clusters_2 = cutree(h_cl, k=n)
 print(latent_space_clusters_2)
                           
 # Weighted network 
 blsm_obj_3 = estimate_latent_positions(example_adjacency_matrix, example_weights_matrix, 
                          burn_in = 10^5, nscan = 2*10^5, dynamic_plot = TRUE)
# }