as_distmat: Mark an arbitrary matrix as a pre-computed 'dist.matrix'...

as.distmatR Documentation

Mark an arbitrary matrix as a pre-computed dist.matrix object (wordspace)

Description

Mark an arbitrary dense or sparse matrix as a pre-computed dist.matrix object, so it can be used with nearest.neighbours and pair.distances. Default methods are provided for a regular dense matrix, any type of sparseMatrix from the Matrix package, as well as a dsm object (from which the raw or scored co-occurrence matrix is extracted).

Usage


as.distmat(x, ...)

## S3 method for class 'matrix'
as.distmat(x, similarity=FALSE, symmetric=FALSE, ...)
## S3 method for class 'sparseMatrix'
as.distmat(x, similarity=FALSE, symmetric=FALSE, force.dense=FALSE, ...)
## S3 method for class 'dsm'
as.distmat(x, similarity=FALSE, symmetric=FALSE, force.dense=FALSE, ...)

Arguments

x

a matrix-like object of a suitable class (for which a method implementation is available) or a DSM object of class dsm

similarity

whether the matrix contains similarity or distance values. Note that sparse distance matrices (similarity=FALSE) are not supported.

symmetric

whether the distance or similarity is symmetric (i.e. it has the same rows and columns in the same order and d(x, y) = d(y, x)). Methods trust the specified value and do not check whether this is actually true.

force.dense

whether to convert a sparse distance matrix into a dense matrix object. Keep in mind that the resulting matrix may be extremely large.

...

additional arguments passed on to the method implementations (see respective manpages for details)

Details

This method is called as.distmat because the regular name as.dist.matrix would collide with the as.dist method for matrix objects.

The method has two main purposes:

  1. enable the use of pre-computed distance information from external sources in wordspace;

  2. disguise a (scored) co-occurrence matrix as a similarity matrix so that nearest.neighbours and pair.distances can be used for lookup of first-order co-occurrence data.

Value

If x is a dense matrix or force.dense=TRUE, it is assigned to class dist.matrix so it can be used with nearest.neighbours and pair.distances as well as the plot and head methods.

If x is a sparse matrix, it is marked with an attribute dist.matrix recognized by nearest.neighbours and pair.distances; however, method implementations for dist.matrix objects will not apply. Important note: In this case, x must be a non-negative similarity matrix and empty cells are treated as zeroes.

In either case, attributes similarity and symmetric are set as specified.

Author(s)

Stephanie Evert (https://purl.org/stephanie.evert)

See Also

plot and head methods for distances matrices; nearest.neighbours and pair.distances

Examples


  # interpret co-occurrence frequency as similarity measure
  M <- as.distmat(DSM_HieroglyphsMatrix, similarity=TRUE)
  nearest.neighbours(M, "cat")
  nearest.neighbours(M, "hear", byrow=FALSE)


wordspace documentation built on Aug. 23, 2022, 1:06 a.m.