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

as.distmat {wordspace} | R 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)

Stefan Evert (http://purl.org/stefan.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)

[Package wordspace version 0.2-6 Index]