| Title: | MULTIplex NEtworks with Shared Structure |
| Version: | 1.0.2 |
| Description: | Model fitting and simulation for Gaussian and logistic inner product MultiNeSS models for multiplex networks. The package implements a convex fitting algorithm with fully adaptive parameter tuning, including options for edge cross-validation. For more details see MacDonald et al. (2020). |
| License: | GPL (≥ 3) |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.1.2 |
| Imports: | glmnet (≥ 4.0.2), Matrix (≥ 1.1.0), RSpectra (≥ 0.16.0), |
| Depends: | R (≥ 3.6.0) |
| URL: | https://github.com/peterwmacd/multiness/ |
| BugReports: | https://github.com/peterwmacd/multiness/issues/ |
| NeedsCompilation: | no |
| Packaged: | 2022-11-21 22:20:55 UTC; pwmacdon |
| Author: | Peter W. MacDonald
 [aut, cre] |
| Maintainer: | Peter W. MacDonald <pwmacdon@umich.edu> |
| Repository: | CRAN |
| Date/Publication: | 2022-11-25 01:20:05 UTC |
Agricultural trade multiplex network
Description
An undirected multiplex network containing trade volumes for 13 highly traded agricultural products for the year 2010, collected by the Food and Agriculture Organization of the United Nations (FAO). The original data set can be downloaded from Manlio DeDomenico's website. Array entries are in units of tonnes (metric tons) of bilateral trade of a given agricultural product. For further documentation and product definitions see https://www.fao.org/faostat/en/#definitions/.
Usage
data(agri_trade)
Format
An array of dimension 145 \times 145 \times 13.
Source
https://manliodedomenico.com/; https://www.fao.org/faostat/en/#data/
References
DeDomenico et al. (2015) Nature Communications
Adjacency Spectral Embedding (ASE)
Description
ase calculates the d-dimensional adjacency spectral embedding of a symmetric
n \times n matrix M.
Usage
ase(M,d)
Arguments
M |
A symmetric matrix. |
d |
A non-negative integer embedding dimension. |
Value
An n \times d matrix X, defined as U |S|^{1/2}
where S is a diagonal matrix of the d leading (in absolute value)
eigenvalues of M, and U is a matrix of the corresponding
eigenvectors.
X has an additional attribute "signs" which gives the sign of
the eigenvalue corresponding to each column.
If d=0, ase returns an n \times 1
matrix of zeros.
Inverse logistic link function
Description
expit applies the inverse logistic link function f(x) = e^x / (1+e^x).
Usage
expit(x)
Arguments
x |
A numeric vector. |
Logistic link function
Description
logit applies the logistic link function f(x) = log(x / (1-x)).
Usage
logit(x,tol=1e-6)
Arguments
x |
A numeric vector with values in the interval [0,1]. |
tol |
A positive scalar which bounds the entries of x away from 0 and 1
for numerical stability.
Defaults to |
Fit the MultiNeSS model
Description
multiness_fit fits the Gaussian or logistic MultiNeSS model
with various options for parameter tuning.
Usage
multiness_fit(A,model,self_loops,refit,tuning,tuning_opts,optim_opts)
Arguments
A |
An |
model |
A string which provides choice of model,
either |
self_loops |
A Boolean, if |
refit |
A Boolean, if |
tuning |
A string which provides the tuning method, valid options are
|
tuning_opts |
A list, containing additional optional arguments controlling
parameter tuning. The arguments used depends on the choice of tuning method.
If
If
If
|
optim_opts |
A list, containing additional optional arguments controlling the proximal gradient descent algorithm.
|
Details
A MultiNeSS model is fit to an n \times n \times m array A of
symmetric adjacency matrices on a common set of nodes. Fitting
proceeds by convex proximal gradient descent on the entries of
F = VV^{T} and G_k = U_kU_k^{T}, see
MacDonald et al., (2020),
Section 3.2. Additional optional arguments for
the gradient descent routine can be provided in optim_opts.
refit provides an option
to perform an additional refitting step to debias the eigenvalues
of the estimates, see
MacDonald et al., (2020), Section 3.3.
By default, multiness_fit will return estimates of the matrices
F and G_k. optim_opts$return_posns provides an option
to instead return estimates of latent positions V and U_k
based on the adjacency spectral embedding (if such a factorization exists).
Tuning parameters \lambda and \alpha_k in the nuclear norm penalty
\lambda ||F||_* + \sum_k \lambda \alpha_k ||G_k||_*
are either set by the
user (tuning='fixed'), selected adaptively using a
robust estimator of the
entry-wise variance (tuning='adaptive'), or
selected using edge cross-validation (tuning='cv'). For more details
see MacDonald et al., (2020),
Section 3.4. Additional optional arguments for parameter tuning
can be provided in tuning_opts.
Value
A list is returned with the MultiNeSS model estimates, dimensions of the common and individual latent spaces, and some additional optimization output:
F_hat |
An |
G_hat |
A list of length |
V_hat |
A matrix estimating the common latent positions.
Returned if |
U_hat |
A list of length |
d1 |
A non-negative integer, the estimated common dimension of the latent space. |
d2 |
An integer vector of length |
K |
A positive integer, the number of iterations run in proximal gradient descent. |
convergence |
An integer convergence code, |
lambda |
A positive scalar, the tuned |
alpha |
A numeric vector of length |
Examples
# gaussian model data
data1 <- multiness_sim(n=100,m=4,d1=2,d2=2,
model="gaussian")
# multiness_fit with fixed tuning
fit1 <- multiness_fit(A=data1$A,
model="gaussian",
self_loops=TRUE,
refit=FALSE,
tuning="fixed",
tuning_opts=list(lambda=40,alpha=1/2),
optim_opts=list(max_rank=20,verbose=TRUE))
# multiness_fit with adaptive tuning
fit2 <- multiness_fit(A=data1$A,
refit=TRUE,
tuning="adaptive",
tuning_opts=list(layer_wise=FALSE),
optim_opts=list(return_posns=TRUE))
# logistic model data
data2 <- multiness_sim(n=100,m=4,d1=2,d2=2,
model="logistic",
self_loops=FALSE)
# multiness_fit with cv tuning
fit3 <- multiness_fit(A=data2$A,
model="logistic",
self_loops=FALSE,
tuning="cv",
tuning_opts=list(N_cv=2,
penalty_const_vec=c(1,2,2.309,3),
verbose_cv=TRUE))
Simulate from the MultiNeSS model
Description
multiness_sim simulates a realization of the Gaussian
or logistic MultiNeSS model with Gaussian latent positions.
Usage
multiness_sim(n,m,d1,d2,model,sigma,self_loops,opts)
Arguments
n |
A positive integer, the number of nodes. |
m |
A positive integer, the number of layers. |
d1 |
A non-negative integer, the number of common latent dimensions. |
d2 |
A non-negative integer, the number of individual latent dimensions. |
model |
A string which provides choice of model,
either |
sigma |
A positive scalar or numeric vector of length |
self_loops |
A Boolean, if |
opts |
A list, containing additional optional arguments:
|
Details
The common and individual latent positions, V and U_k
respectively, are generated as
Gaussian random variables with standard deviation opts$gamma, and
dependence controlled by the optional
arguments opts$dependence_type and opts$rho.
Under the Gaussian model, the n \times n adjacency matrix for layer k=1,...,m
has independent Gaussian entries with standard deviation sigma and
mean given by
E(A_k) = VV^{T} + U_kU_k^{T}.
Under the logistic model, the n \times n adjacency matrix for layer k=1,...,m
has independent Bernoulli entries with mean given by
E(A_k) = g(VV^{T} + U_kU_k^{T}),
where g denotes the element-wise application of the inverse logistic
link (expit) function. Under both models, self_loops provides
an option to set the diagonal entries of the adjacency matrices to zero.
Value
A list is returned with the realizations of the latent dimensions and the multiplex network:
A |
An array of dimension |
V |
A matrix of dimension |
U |
An array of dimension |
P |
If specified, an array of dimension |
density |
If specified and |
Examples
# gaussian model, uncorrelated latent positions
data1 <- multiness_sim(n=100,m=4,d1=2,d2=2,
model="gaussian")
# logistic model, correlated latent positions
data2 <- multiness_sim(n=100,m=4,d1=2,d2=2,
model="logistic",
self_loops=FALSE,
opts=list(dependence_type="all",rho=.3,return_density=TRUE))