Package 'netregR' reference manual

Title:	Regression of Network Responses
Description:	Regress network responses (both directed and undirected) onto covariates of interest that may be actor-, relation-, or network-valued. In addition, compute principled variance estimates of the coefficients assuming that the errors are jointly exchangeable. Missing data is accommodated. Additionally implements building and inversion of covariance matrices under joint exchangeability, and generates random covariance matrices from this class. For more detail on methods, see Marrs, Fosdick, and McCormick (2017) <arXiv:1701.05530>.
Authors:	Frank W. Marrs [aut, cre], Bailey K. Fosdick [aut], Tyler H. McCormick [aut]
Maintainer:	Frank W. Marrs <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.1
Built:	2024-11-26 05:38:03 UTC
Source:	https://github.com/cran/netregR

Build an exchangeable matrix of sparseMatrix class

Description

Build an exchangeable matrix of sparseMatrix class

Usage

build_exchangeable_matrix(n, phi, directed = TRUE, dyads = NULL)
build_exchangeable_matrix(n, phi, directed = TRUE, dyads = NULL)

Arguments

`n`	Number of actors in the network, scalar numeric.
`phi`	Appropriate-length vector of parameters, must be length 5 or 6 for directed=`TRUE` or length 2 or 3 for directed=`FALSE`.
`directed`	Optional logical indicator of whether input data is for a directed network, default is `TRUE`. Undirected data format is lower triangle of adjacencey matrix.
`dyads`	Optional numeric vector of dyads to subset the matrix to.

Details

This function builds a covariance matrix in the exchangeable class from the vector of parameters input. See Marrs et.al. (2017).

Value

out

Exchangeable matrix.

References

Marrs, F. W., Fosdick, B. K., & McCormick, T. H., (2017). Standard errors for regression on relational data with exchangeable errors. arXiv preprint arXiv:1701.05530.

Examples

n <- 5
build_exchangeable_matrix(n, rphi(n, seed=1))

n <- 5
build_exchangeable_matrix(n, rphi(n, seed=1))

Coef S3 generic for class lmnet

Description

Coef S3 generic for class lmnet

Usage

## S3 method for class 'lmnet'
coef(object, ...)
## S3 method for class 'lmnet'
coef(object, ...)

Arguments

`object`	lmnet object
`...`	ignored

Input preprocessing

Description

Prepare covariates and optional response in adjacency matrix form. If undirected, the values are drawn from the lower triangle of the adjacency matrices.

Usage

inputs_lmnet(Xlist, Y = NULL, directed = TRUE, add_intercept = TRUE,
  time_intercept = FALSE)
inputs_lmnet(Xlist, Y = NULL, directed = TRUE, add_intercept = TRUE,
  time_intercept = FALSE)

Arguments

`Xlist`	List of $n \times n \times tmax$ matrices, possibly containing response matrix labeled ‘Y’. Diagonals (self-loops) are ignored.
`Y`	Optional $n \times n \times tmax$ response matrix. NAs in this matrix will be automatically removed. Diagonals (self-loops) are ignored.
`directed`	Optional logical indicator of whether input data is for a directed network, default is `TRUE`. Undirected data format is lower triangle of adjacencey matrix.
`add_intercept`	Optional logical indicator of whether intercept should be added to X, default is `TRUE`.
`time_intercept`	Optional logical indicator of whether separate intercept should be added to X for each observation of the relational matrix, default is `FALSE`.

Details

This function takes a list of network covariates (in adjacency matrix form) and prepares them for the regression code lmnet. Accomodates 3-dimensional relational arrays with tmax repeated observations of the network (over time or context). Typical network data with a single observation may be input as matrices, i.e. tmax = 1.

Value

A list of:

`Y`	Vector of responses (column-wise vectorization order) of appropriate length.
`X`	Matrix of covariates (column-wise vectorization order) of appropriate size.
`nodes`	2-column matrix (or 3-column for repeated observations) indicating directed relation pairs to which each entry in $Y$ and each row in $X$ corresponds.

Examples

# tmax = 1
set.seed(1)
n <- 10
Xlist <- list(matrix(rnorm(n^2),n,n), matrix(sample(c(0,1), n^2, replace=TRUE),n,n))
Xlist$Y <- matrix(rnorm(n^2), n, n)
Xlist$Y[1:5] <- NA
r <- inputs_lmnet(Xlist)
r
lmnet(r$Y,r$X,nodes=r$nodes)

# tmax = 4
set.seed(1)
n <- 10
tmax <- 4
X1 <- array(rnorm(n^2*tmax),c(n,n,tmax))
X2 <- array(sample(c(0,1), n^2*tmax, replace=TRUE), c(n,n,tmax))
Xlist <- list(X1, X2)
Xlist$Y <- array(rnorm(n^2)*tmax, c(n, n, tmax))
Xlist$Y[1:5] <- NA
r <- inputs_lmnet(Xlist)
head(r$nodes)

# tmax = 1
set.seed(1)
n <- 10
Xlist <- list(matrix(rnorm(n^2),n,n), matrix(sample(c(0,1), n^2, replace=TRUE),n,n))
Xlist$Y <- matrix(rnorm(n^2), n, n)
Xlist$Y[1:5] <- NA
r <- inputs_lmnet(Xlist)
r
lmnet(r$Y,r$X,nodes=r$nodes)

# tmax = 4
set.seed(1)
n <- 10
tmax <- 4
X1 <- array(rnorm(n^2*tmax),c(n,n,tmax))
X2 <- array(sample(c(0,1), n^2*tmax, replace=TRUE), c(n,n,tmax))
Xlist <- list(X1, X2)
Xlist$Y <- array(rnorm(n^2)*tmax, c(n, n, tmax))
Xlist$Y[1:5] <- NA
r <- inputs_lmnet(Xlist)
head(r$nodes)

Social interaction data set

Description

A synthetic data set of standardized, directed interactions between 25 students in a seventh grade class.

Format

A data set with four variables. Includes the true parameters.

interactions: 25 x 25 x 5 numeric array of directed relations
xbinary: 25 x 25 x 5 numeric array of binary indictors
xabs: 25 x 25 x 5 numeric array of standardized absolute difference in indicated interest in each subject area
betatrue: Numeric vector of length 7 that contains true coefficients. The first two (value 1) pertain to shared_project and grade_difference_abs. The last three are separate intercepts for each observation of the network.
Omegatrue: 3000 x 3000 numeric matrix: the true covariance matrix of the errors.
phitrue: 2x6 numeric matrix: true parameters of covariance matrix.

Details

We generated a symthetic data set form a true linear model with jointly exchangeable errors. The interactions (the outcomes) between 25 students represent normalized, directed relations between them in 5 different contexts (texts). The observation could be, for instance, the standardized number of characters texted from one student to another over a month pertaining to five subjects: school, friends, family, significant others, and popular culture. The first covariate, xbinary, indicates whether both students indicated in a survey that they were interested in each topic. The second covariate, xabs, measures the absolute, standardized difference in number of characters in total texts of each student of each subject area.

Examples

data("interactions")

data("interactions")

Invert an exchangeable matrix

Description

Invert an exchangeable matrix

Usage

invert_exchangeable_matrix(n, phi, directed = TRUE)
invert_exchangeable_matrix(n, phi, directed = TRUE)

Arguments

`n`	Number of actors in the network, scalar numeric.
`phi`	Appropriate-length vector of parameters, must be length 5 or 6 for directed=`TRUE` or length 2 or 3 for directed=`FALSE`.
`directed`	Optional logical indicator of whether input data is for a directed network, default is `TRUE`. Undirected data format is lower triangle of adjacencey matrix.

Details

This function inverts a covariance matrix of the exchangeable class in a manner much faster than the direct inverse, and the computational cost does not scale with n. See Marrs et. al. (2017). This approach will only work for complete networks.

Value

out

Parameters of inverted matrix of exchangeable class.

References

Marrs, F. W., Fosdick, B. K., & McCormick, T. H., (2017). Standard errors for regression on relational data with exchangeable errors. arXiv preprint arXiv:1701.05530.

Examples

n <- 10
phi <- rphi(n, seed=1)
p <- invert_exchangeable_matrix(n, phi)
I1 <- build_exchangeable_matrix(n, phi) %*% build_exchangeable_matrix(n, p)
range(I1 -  diag(n*(n-1)))   # it works

n <- 10
phi <- rphi(n, seed=1)
p <- invert_exchangeable_matrix(n, phi)
I1 <- build_exchangeable_matrix(n, phi) %*% build_exchangeable_matrix(n, p)
range(I1 -  diag(n*(n-1)))   # it works

Linear regression for network response

Description

This function takes $X$ and $Y$ values and fits the multiple linear regression $Y = X \beta + \epsilon$ and returns standard errors.

Usage

lmnet(Y, X, directed = TRUE, tmax = 1, nodes = NULL, reweight = FALSE,
  type = "exchangeable", tol = 1e-06, maxit = 10000, ndstop = TRUE,
  verbose = FALSE)
lmnet(Y, X, directed = TRUE, tmax = 1, nodes = NULL, reweight = FALSE,
  type = "exchangeable", tol = 1e-06, maxit = 10000, ndstop = TRUE,
  verbose = FALSE)

Arguments

`Y`	Vector of relations to be regress, of length $d$ . Column-wise vectorization of adjacency matrix without diagonal entries (self-loops).
`X`	Matrix of covariates to be regressed upon, including intercept if intercept is desired, must have $d$ rows. Ordering of rows should match `Y` and optional input `nodes`.
`directed`	Optional logical indicator of whether input data is for a directed network, default is `TRUE`. Undirected data format is lower triangle of adjacencey matrix.
`tmax`	Optional numeric of third dimension of relational data array, default is `1`, i.e. a relational matrix.
`nodes`	Optional $d \times 2$ matrix indicating the (directed) relation pairs to which each entry in $Y$ and each row in $X$ corresponds. If not input, complete network observation with column-wise vectorization of adjacency matrix without diagonal entries (self-loops) is assumed. The size $d$ and `directed` must correspond to an appropriate network of size $n$ .
`reweight`	Optional logical indicator of whether iteratively reweighted least squares should be used to compute estimate of $\beta$ . Default is `FALSE`.
`type`	Optional character specifying degree of exchangeability of third dimension of array (when present, i.e. in temporal relational arrays). Default is `exchangeable`, and the remaining option is `independent`. Truncated inputs are accepted. See details below.
`tol`	Optional numeric, tolerance of stopping criteria of iteratively reweighted least squares estimate of $\beta$ . Default is `tol=1e-6`.
`maxit`	Optional numeric, maximum number of iterations for iteratively reweighted least squares estimate of $\beta$ . Default is `maxit=1e4`.
`ndstop`	Optional logical indicator of whether negative definite weighting matrix in iteratively reweighted least squares should stop the descent. Default is `TRUE`.
`verbose`	Optional logical indicator of whether information from iteratively reweighted least squares estimate of $\beta$ should be printed. Default is `FALSE`.

Details

This function takes $X$ and $Y$ values and fits the multiple linear regression $Y = X \beta + \epsilon$ by ordinary least squares or iteratively reweighted least squares as indicated by the input. The covariance structure is exchangeable from that of Marrs et. al. (2017). The standard errors and test statistics are based on the same paper.

The three dimensional relational array case, i.e. temporal relational data, requires a specification of the type of exchangeability in this third dimension. We may assume that different time periods are independent. On the other hand, we might assume each repeated observation is exchangeable (for example decomposing trade networks into sectors of trade: goods vs. services). See Figure 6a of Marrs et. al. (2017) for the exchangeable case and the surrounding discussion for the independent case.

Value

fit

An lmnet object containing summary information.

References

Marrs, F. W., Fosdick, B. K., & McCormick, T. H., (2017). Standard errors for regression on relational data with exchangeable errors. arXiv preprint arXiv:1701.05530.

Examples

set.seed(1)
n <- 10
d <- n*(n-1)
X <- cbind(1, rnorm(d), sample(c(0,1), d, replace=TRUE))
betatrue <- rep(1,3)
Y <- X %*% betatrue + rnorm(d)
fit <- lmnet(Y,X)
fit
fit2 <- lmnet(Y,X,reweight=TRUE)
fit2

set.seed(1)
n <- 10
d <- n*(n-1)
X <- cbind(1, rnorm(d), sample(c(0,1), d, replace=TRUE))
betatrue <- rep(1,3)
Y <- X %*% betatrue + rnorm(d)
fit <- lmnet(Y,X)
fit
fit2 <- lmnet(Y,X,reweight=TRUE)
fit2

model.matrix S3 generic for class lmnet

Description

model.matrix S3 generic for class lmnet

Usage

## S3 method for class 'lmnet'
model.matrix(object, ...)
## S3 method for class 'lmnet'
model.matrix(object, ...)

Arguments

`object`	lmnet object
`...`	ignored

Plot S3 generic for class lmnet

Description

Plot S3 generic for class lmnet

Usage

## S3 method for class 'lmnet'
plot(x, ...)
## S3 method for class 'lmnet'
plot(x, ...)

Arguments

`x`	lmnet object
`...`	ignored

Print S3 generic for class lmnet

Description

Print S3 generic for class lmnet

Usage

## S3 method for class 'lmnet'
print(x, ...)
## S3 method for class 'lmnet'
print(x, ...)

Arguments

`x`	lmnet object
`...`	ignored

Print S3 generic for class summary.lmnet

Description

Print S3 generic for class summary.lmnet

Usage

## S3 method for class 'summary.lmnet'
print(x, ...)
## S3 method for class 'summary.lmnet'
print(x, ...)

Arguments

`x`	summary.lmnet object
`...`	ignored

Print S3 generic for summary.vnet object

Description

Print S3 generic for summary.vnet object

Usage

## S3 method for class 'summary.vnet'
print(x, ...)
## S3 method for class 'summary.vnet'
print(x, ...)

Arguments

`x`	summary.vnet object
`...`	ignored

Print S3 generic for vnet object

Description

Print S3 generic for vnet object

Usage

## S3 method for class 'vnet'
print(x, ...)
## S3 method for class 'vnet'
print(x, ...)

Arguments

`x`	vnet object
`...`	ignored

Generate positive definite phi set

Description

Generate positive definite phi set

Usage

rphi(n, seed = NULL, phi6 = FALSE, directed = TRUE)
rphi(n, seed = NULL, phi6 = FALSE, directed = TRUE)

Arguments

`n`	Number of actors in the network, scalar numeric.
`seed`	Optional numeric seed to set, default is `NULL`.
`phi6`	Optional logical indicator of whether sixth parameter $\phi_6$ should be considered nonzero. Default is `FALSE`.
`directed`	Optional logical indicator of whether input data is for a directed network, default is `TRUE`. Undirected data format is lower triangle of adjacencey matrix.

Details

This function generates a set of 5 (or 6, as appropriate) parameters that corresponds to positive definite exchangeable covariance matrix for a network of size n. See Marrs et. al. (2017).

Value

phi

Vector of parameters.

References

Marrs, F. W., Fosdick, B. K., & McCormick, T. H., (2017). Standard errors for regression on relational data with exchangeable errors. arXiv preprint arXiv:1701.05530.

Examples

rphi(10, seed=1)

rphi(10, seed=1)

Summary S3 generic for class lmnet

Description

Summary S3 generic for class lmnet

Usage

## S3 method for class 'lmnet'
summary(object, ...)
## S3 method for class 'lmnet'
summary(object, ...)

Arguments

`object`	lmnet object
`...`	ignored

Summary S3 generic for vnet object

Description

Summary S3 generic for vnet object

Usage

## S3 method for class 'vnet'
summary(object, ...)
## S3 method for class 'vnet'
summary(object, ...)

Arguments

`object`	vnet object
`...`	ignored

vcov S3 generic for class lmnet

Description

vcov S3 generic for class lmnet

Usage

## S3 method for class 'lmnet'
vcov(object, ...)
## S3 method for class 'lmnet'
vcov(object, ...)

Arguments

`object`	lmnet object
`...`	ignored

Variance computation for linear regression of network response

Description

Stand-alone estimation of exchangeable variance matrix based on residuals and design matrix.

Usage

vnet(e = NULL, X = NULL, directed = TRUE, nodes = NULL,
  type = "exchangeable", tmax = 1, fit = NULL)
vnet(e = NULL, X = NULL, directed = TRUE, nodes = NULL,
  type = "exchangeable", tmax = 1, fit = NULL)

Arguments

`e`	Optional vector of residuals, of length $d$ . Column-wise unfolding of adjacency matrix without diagonal entries (self-loops).
`X`	Optional matrix of covariates from regression, must have $d$ rows.
`directed`	Optional logical indicator of whether input data is for a directed network, default is `TRUE`. Undirected data format is lower triangle of adjacencey matrix.
`nodes`	Optional $d \times 2$ matrix indicating the (directed) relation pairs to which each entry in $e$ and each row in $X$ corresponds. If not input, complete network observation is assumed and the size $d$ and `directed` must correspond to an appropriate network of size $n$ .
`type`	Optional string indicating whether the ‘meat’ in the sandwich variance estimator is estimated using exchangeable theory (see Marrs et. al. (2017)) or using dyadic clustering (Fafchamps and Gubert (2007)).
`tmax`	Optional numeric of third dimension of relational data array, default is `1`, i.e. a relational matrix. Currently only accepts `tmax = 1`.
`fit`	Optional fitted model object. One of either `fit` or the pair `(e, X)` must be specified. Defaults to `fit` if both entered. Designed around ‘lmnet’ class but may work for others, such as ‘lm’

Details

This function takes $X$ and $e$ values computes the variance-covariance matrix of $\hat{\beta}$ that resulted in the residuals $e = Y - X \hat{\beta}$ assuming that the errors are exchangeable, as based on Marrs et. al. (2017) when type = "exchangeable". When type = "dyadic clustering", the theory from Fafchamps and Gubert (2007) is implemented.

Value

A an object of class vhat containing summary information:

`vhat`	Estimated variance-covariance matrix of cofficient estimates $\hat{\beta}$ .
`phi`	Vector of variance-covariance parameter estimates.
`corrected`	Logical of whether variance-covariance matrix was corrected from negative definite to positive semi-definite.
`type`	See inputs.
`tmax`	See inputs.

References

Marrs, F. W., Fosdick, B. K., & McCormick, T. H., (2017). Standard errors for regression on relational data with exchangeable errors. arXiv preprint arXiv:1701.05530.

Fafchamps, M., & Gubert, F. (2007). Risk sharing and network formation. American Economic Review, 97(2), 75-79.

Examples

set.seed(1)
n <- 10
d <- n*(n-1)
X <- cbind(1, rnorm(d), sample(c(0,1), d, replace=TRUE))
e <- rnorm(d)
vnet(e=e,X=X)

set.seed(1)
n <- 10
d <- n*(n-1)
X <- cbind(1, rnorm(d), sample(c(0,1), d, replace=TRUE))
e <- rnorm(d)
vnet(e=e,X=X)

Wolf network data set

Description

A data set measuring dominance and its behavioral measures in a captive wolf pack.

Format

A data set with three variables

wolf: 16 x 16 numeric matrix of dominance measures
wolf_age_diff: 16 x 16 numeric matrix of difference in ages (column less row)
wolf_same_sex: 16 x 16 numeric matrix of indicators of same sex

Details

This is data on a captive family of wolves in Arnheim, Germany. The 16 wolves studied here were housed in a large wooded enclosure and observed in 1978. This matrix displays deference acts. The number in a cell represents the number of occasions on which the row wolf was seen to exhibit a "low posture" display directed toward the column wolf. The behavior could involve approach or retreat, but the fact that it was performed in "low posture" suggests that it was deferent. Data obtained March 20, 2018 from http://moreno.ss.uci.edu/data.html#wolf.

Source

http://moreno.ss.uci.edu/data.html#wolf

References

Jan A. R. A. M. van Hooff and Joep A. B. Wensing, "Dominance and its behavioral measures in a captive wolf pack," Chapter 11 in Harry Frank, ed., Man and Wolf. Dordrecht: Junk, 1987, pp. 219-252.

Examples

data("wolf")

data("wolf")

Package 'netregR'

Help Index

Build an exchangeable matrix of sparseMatrix class

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Coef S3 generic for class lmnet

Description

Usage

Arguments

Input preprocessing

Description

Usage

Arguments

Details

Value

See Also

Examples

Social interaction data set

Description

Format

Details

Examples

Invert an exchangeable matrix

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Linear regression for network response

Description

Usage

Arguments

Details

Value

References

See Also

Examples

model.matrix S3 generic for class lmnet

Description

Usage

Arguments

Plot S3 generic for class lmnet

Description

Usage

Arguments

Print S3 generic for class lmnet

Description

Usage

Arguments

Print S3 generic for class summary.lmnet

Description

Usage

Arguments

Print S3 generic for summary.vnet object

Description

Usage

Arguments

Print S3 generic for vnet object

Description

Usage

Arguments

Generate positive definite phi set

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Summary S3 generic for class lmnet