fase {fase} | R Documentation |
Functional adjacency spectral embedding
Description
fase
fits a functional adjacency spectral embedding to snapshots
of (undirected) functional network data. The latent processes are fit
in a spline basis specified by the user, with additional options for
ridge penalization.
Usage
fase(A,d,self_loops,spline_design,lambda,optim_options,output_options)
Arguments
A |
An |
d |
A positive integer, the number of latent space dimensions of the functional embedding. |
self_loops |
A Boolean, if |
spline_design |
A list, containing the spline design information.
For fitting with a
For fitting with a smoothing spline design:
|
lambda |
A positive scalar, the scale factor for the generalized ridge
penalty (see Details). Defaults to |
optim_options |
A list, containing additional optional arguments controlling the gradient descent algorithm.
|
output_options |
A list, containing additional optional arguments controlling
the output of
|
Details
fase
finds a functional adjacency spectral embedding of an
n \times n \times m
array A
of
symmetric adjacency matrices on a common set of nodes, where
each n \times n
slice is associated to a scalar index x_k
for k=1,...,m
.
Embedding requires the specification of a latent space dimension
d
and spline design information (with the argument
spline_design
).
fase
can fit latent processes using either a cubic B
-spline
basis with
equally spaced knots, or a natural cubic spline basis with a second
derivative (generalized ridge) smoothing penalty: a smoothing spline.
To fit with a B
-spline design (spline_design$type = 'bs'
),
one must minimally provide a basis
dimension q
of at least 4
and at most m
.
When fitting with a smoothing spline design, the generalized ridge
penalty is scaled by
\lambda/n
, where \lambda
is specified by the argument lambda
.
see MacDonald et al., (2022+),
Appendix E for more details.
lambda
can also be used to introduce a ridge penalty on the
basis coordinates when fitting with B
-splines.
Fitting minimizes a least squares loss,
using gradient descent (Algorithm 2) on the basis coordinates w_{i,r}
of each component process
z_{i,r}(x) = w_{i,r}^{T}B(x).
Additional options for the fitting algorithm, including initialization,
can be specified by the argument optim_options
.
For more details on the fitting and initialization algorithms, see
MacDonald et al., (2022+),
Section 3.
By default, fase
will return estimates of the latent processes
evaluated at the snapshot indices as an n \times d \times m
array, after
performing a Procrustes alignment of the consecutive snapshots.
This extra alignment step can be skipped.
fase
will also return the spline design information used to fit the
embedding, convergence information for gradient descent, and (if specified)
the basis coordinates.
When fitting with B
-splines, fase
can return a
network generalized cross validation criterion, described in
MacDonald et al., (2022+),
Section 3.3. This criterion can be minimized to choose appropriate values
for q
and d
.
Value
A list is returned with the functional adjacency spectral embedding, the spline design information, and some additional optimization output:
Z |
An |
W |
For |
spline_design |
A list, describing the spline design:
|
ngcv |
A scalar, the network generalized cross validation criterion
(see Details). Only returned for |
K |
A positive integer, the number of iterations run in gradient descent. |
converged |
An integer convergence code, |
Examples
# Gaussian edge data with sinusoidal latent processes
set.seed(1)
data <- gaussian_snapshot_ss(n=50,d=2,
x_vec=seq(0,1,length.out=50),
self_loops=FALSE,sigma_edge=4)
# fase fit with B-spline design
fit_bs <- fase(data$A,d=2,self_loops=FALSE,
spline_design=list(type='bs',q=9,x_vec=data$spline_design$x_vec),
optim_options=list(eps=1e-4,K_max=40),
output_options=list(return_coords=TRUE))
# fase fit with smoothing spline design
fit_ss <- fase(data$A,d=2,self_loops=FALSE,
spline_design=list(type='ss',x_vec=data$spline_design$x_vec),
lambda=.5,
optim_options=list(eta=1e-4,K_max=40,verbose=FALSE),
output_options=list(align_output=FALSE))
#NOTE: both examples fit with small optim_options$K_max=40 for demonstration