rowDists: Compute Distances between Rows or Columns of a Matrix

In kuwisdelu/matter: Out-of-core statistical computing and signal processing

Compute Distances between Rows or Columns of a Matrix

Description

Compute and return the distances between specific rows or columns of matrices according to a specific distance metric.

Usage

## S4 method for signature 'matrix,matrix'
rowDists(x, y, ..., BPPARAM = bpparam())

## S4 method for signature 'matrix,matrix'
colDists(x, y, ..., BPPARAM = bpparam())

## S4 method for signature 'matter_mat,matrix'
rowDists(x, y, ..., BPPARAM = bpparam())

## S4 method for signature 'matrix,matter_mat'
colDists(x, y, ..., BPPARAM = bpparam())

## S4 method for signature 'sparse_mat,matrix'
rowDists(x, y, ..., BPPARAM = bpparam())

## S4 method for signature 'matrix,sparse_mat'
colDists(x, y, ..., BPPARAM = bpparam())

## S4 method for signature 'ANY,missing'
rowDists(x, at, ..., simplify = TRUE, BPPARAM = bpparam())

## S4 method for signature 'ANY,missing'
colDists(x, at, ..., simplify = TRUE, BPPARAM = bpparam())

.rowDists(x, y, metric = "euclidean", p = 2,
	weights = NULL, iter.dim = 1L, BPPARAM = bpparam(), ...)

.colDists(x, y, metric = "euclidean", p = 2,
	weights = NULL, iter.dim = 1L, BPPARAM = bpparam(), ...)

# Low-level row/col distance functions
rowdist(x, y = x, metric = "euclidean", p = 2, weights = NULL, ...)
coldist(x, y = x, metric = "euclidean", p = 2, weights = NULL, ...)

rowdist_at(x, ix, y = x, iy = list(1L:nrow(y)),
	metric = "euclidean", p = 2, weights = NULL, ...)

coldist_at(x, ix, y = x, iy = list(1L:ncol(y)),
	metric = "euclidean", p = 2, weights = NULL, ...)

Arguments

x, y	Numeric matrices for which distances should be calculated according to rows or columns. If a parallel backend is provided, then the calculation is parallelized over x, and y is passed to each worker.
at	A list, matrix, or vector of specific row or column indices for which to calculate the distances. Each row or column of x will be compared to the rows or columns indicated by the corresponding element of at.
simplify	Should the result be simplified into a matrix if possible?
metric	Distance metric to compute. Supported metrics include "euclidean", "maximum", "manhattan", and "minkowski".
p	The power for the Minkowski distance.
weights	A numeric vector of weights for the distance components if calculating weighted distances. For example, the weighted Euclidean distance is sqrt(sum(w * (x - y)^2)).
iter.dim	The dimension to iterate over. Must be 1 or 2, where 1 indicates rows and 2 indicates columns.
ix, iy	A list of specific row or column indices for which to calculate the pairwise distances. Numeric vectors will be coerced to lists. Each list element should give a vector of indices to use for a distance computation. Elements of length 1 will be recycled to an appropriate length.
BPPARAM	An optional instance of BiocParallelParam. See documentation for bplapply.
...	Additional arguments passed to rowdist() or coldist().

Details

rowdist() and coldist() calculate straightforward distances between each row or column, respectively in x and y. If y = x (the default), then the output of rowdist() will match the output of dist (except it will be an ordinary matrix).

rowdist_at() and coldist_at() allow passing a list of specific row or column indices for which to calculate the distances.

rowDists() and colDists() are S4 generics. The current methods provide (optionally parallelized) versions of rowdist() and coldist() for matter_mat and sparse_mat matrices.

Value

For rowdist() and coldist(), a matrix with rows equal to the number of observations in x and columns equal to the number of observations in y.

For rowdist_at() and coldist_at(), a list where each element gives the pairwise distances corresponding to the indices given by ix and iy.

rowDists() and colDists() have corresponding return values depending on whether at has been specified (and the value of simplify).

Author(s)

Kylie A. Bemis

See Also

dist

Examples

register(SerialParam())

set.seed(1)

x <- matrix(runif(25), nrow=5, ncol=5)
y <- matrix(runif(25), nrow=3, ncol=5)

rowDists(x) # same as as.matrix(dist(x))
rowDists(x, y)

# distances between:
# x[1,] vs x[,]
# x[5,] vs x[,]
rowdist_at(x, c(1,5))

# distances between:
# x[1,] vs x[1:3,]
# x[5,] vs x[3:5,]
rowdist_at(x, ix=c(1,5), iy=list(1:3, 3:5))

# distances between:
# x[i,] vs x[(i-1):(i+1),]
rowDists(x, at=roll(1:5, width=3))

# distances between:
# x[,] vs x[1,]
rowDists(x, at=1)

kuwisdelu/matter documentation built on Oct. 19, 2024, 10:31 a.m.