brainGraph (version 3.1.0)

Matrix utilities: Matrix/array utility functions

Description

These functions are utility/helper functions when working with matrices or arrays.

diag_sq is a pared-down version of diag for square matrices. It does not return any dimnames, does not check if x is a square matrix, and it cannot be used to create a matrix with a given value along the diagonal. Meant to be used in code that is called repeatedly (thousands of times).

get_thresholds calculates the threshold values that would result in a specific graph density. These depend, necessarily on the values in the matrix themselves.

qr.array will calculate the QR decomposition for each matrix in a 3D array.

qr_Q2 and qr_R2 are simplified versions of qr.Q and qr.R.

symm_mean returns a symmetric matrix in which the off-diagonal elements \(A[i, j]\) and \(A[j, i]\) are set to the mean of the values in the input matrix.

symmetrize will symmetrize a numeric matrix (or each matrix in an array) by assigning to the off-diagonal elements either the max (default), min, or average of \(\{A(i, j), A(j, i)\}\).

Usage

colMax(x, n = dim(x)[1L])
colMaxAbs(x, n = dim(x)[1L])
colMin(x, n = dim(x)[1L])
diag_sq(x, n = dim(x)[1L], inds = 1L + 0L:(n - 1L) * (n + 1L))
get_thresholds(x, densities, emax = dim(x)[1L] * (dim(x)[1L] - 1L)/2,
  ...)
is_binary(x)
# S3 method for array
qr(x, ...)
qr_Q2(QR, y = diag(1, n, p), n = dim(QR$qr)[1L], p = QR$rank)
qr_R2(QR, p = QR$rank)
symm_mean(x)
symmetrize(x, ...)
# S3 method for matrix
symmetrize(x, symm.by = c("max", "min", "avg"), ...)
# S3 method for array
symmetrize(x, symm.by = c("max", "min", "avg"), ...)

Value

diag_sq returns an unnamed numeric vector with the values along the diagonal of the input matrix

get_thresholds returns a numeric vector of the thresholds

is_binary returns a logical of length 1

qr.array returns a list in which each element is the QR decomposition of each matrix along x's 3rd dimension

Arguments

x

Numeric matrix or array (the latter, for qr.array and symmetrize.array)

n, p

Integer; the number of rows or rank (respectively) of the input matrix or QR decomposition

inds

Vector-based indices of the diagonal

densities

Numeric vector of densities

emax

Integer; the maximum number of edges

...

Arguments passed to either sort (for get_thresholds) or qr.default (for qr.array). For the former, this will typically only be decreasing=TRUE, if that is the desired behavior

QR

A qr object

y

A numeric matrix with 1 along the diagonal, of the same size as the input matrix (i.e., QR$qr)

symm.by

Character string; how to create symmetric off-diagonal elements. Default: max

Details

Given a vector of densities, get_thresholds returns the numeric values that will result in graphs of the given densities after thresholding by those values. In the Examples section, the thresholds should result in graphs with densities of \(5, 15, \dots, 55\) percent.

Examples

x <- matrix(runif(25 * 25), 25, 25)
x <- symmetrize(x)
diag(x) <- 0
densities <- seq(0.05, 0.55, by=0.1)
threshes <- get_thresholds(x, densities)
## Verify that the densities are correct
graphs <- lapply(threshes, function(th) {
  graph_from_adjacency_matrix(x * (x > th), mode='undirected',
                              diag=FALSE, weighted=TRUE)
  })
sapply(graphs, graph.density)