DistanceMatrix {DECIPHER} | R Documentation

## Calculate the Distances Between Sequences

### Description

Calculates a distance matrix for an `XStringSet`. Each element of the distance matrix corresponds to the dissimilarity between two sequences in the `XStringSet`.

### Usage

    DistanceMatrix(myXStringSet,
                   type = "matrix",
                   includeTerminalGaps = FALSE,
                   penalizeGapLetterMatches = TRUE,
                   penalizeGapGapMatches = FALSE,
                   correction = "none",
                   processors = 1,
                   verbose = TRUE)

### Arguments

`myXStringSet` | An `XStringSet` object of aligned sequences (`DNAStringSet`, `RNAStringSet`, or `AAStringSet`).
`type` | Character string indicating the type of output desired. This should be either `"matrix"` or `"dist"`. (See value section below.)
`includeTerminalGaps` | Logical specifying whether or not to include terminal gaps ("-" or "." characters on each end of the sequence) into the calculation of distance.
`penalizeGapLetterMatches` | Logical specifying whether or not to consider gap-to-letter matches as mismatches. If `FALSE`, then gap-to-letter matches are not included in the total length used to calculate distance.
`penalizeGapGapMatches` | Logical specifying whether or not to consider gap-to-gap matches as mismatches. If `FALSE` (the default), then gap-to-gap matches are not included in the total length used to calculate distance.
`correction` | The substitution model used for distance correction. This should be (an abbreviation of) either `"none"` or `"Jukes-Cantor"`.
`processors` | The number of processors to use, or `NULL` to automatically detect and use all available processors.
`verbose` | Logical indicating whether to display progress.

### Details

The uncorrected (`correction = "none"`) distance matrix represents the hamming distance between each of the sequences in `myXStringSet`. Ambiguity can be represented using the characters of the `IUPAC_CODE_MAP` for `DNAStringSet` and `RNAStringSet` inputs, or using the `AMINO_ACID_CODE` for an `AAStringSet` input. For example, the distance between an 'N' and any other nucleotide base is zero. The letters B (N or D), J (I or L), Z (Q or E), and X (any letter) are degenerate in the `AMINO_ACID_CODE`.

If `includeTerminalGaps = FALSE` then terminal gaps ("-" or "." characters) are not included in sequence length. This can be faster since only the positions common to each pair of sequences are compared. Sequences with no overlapping region in the alignment are given a value of `NA`, unless `includeTerminalGaps = TRUE`, in which case distance is 100%.

Penalizing gap-to-gap and gap-to-letter mismatches specifies whether to penalize these special mismatch types and include them in the total length when calculating distance. Both "-" and "." characters are interpreted as gaps. The default behavior is to calculate distance as the fraction of positions that differ across the region of the alignment shared by both sequences (not including gap-to-gap matches).

The elements of the distance matrix can be referenced by `dimnames` corresponding to the `names` of the `XStringSet`. Additionally, an attribute named "correction" specifying the method of correction used can be accessed using the function `attr`.

### Value

If `type` is `"matrix"`, a symmetric matrix where each element is the distance between the sequences referenced by the respective row and column. The `dimnames` of the matrix correspond to the `names` of the `XStringSet`.

If `type` is `"dist"`, an object of `class` `"dist"` that contains one triangle of the distance matrix as a vector. Since the distance matrix is symmetric, storing only one triangle is more memory efficient.

### Author(s)

Erik Wright eswright@pitt.edu

### See Also

`IdClusters`

### Examples

    # example of using the defaults:
    dna <- DNAStringSet(c("ACTG", "ACCG"))
    dna
    DistanceMatrix(dna)

    # changing the output type to "dist":
    d <- DistanceMatrix(dna, type="dist")
    d
    length(d) # minimal memory space required
    m <- as.matrix(d)
    length(m) # more memory space required

    # supplying an AAStringSet
    aa <- AAStringSet(c("ASYK", "ATYK", "CTWN"))
    aa
    DistanceMatrix(aa)

    # defaults compare intersection of internal ranges:
    dna <- DNAStringSet(c("ANGCT-", "-ACCT-"))
    dna
    d <- DistanceMatrix(dna)
    # d[1,2] is 1 base in 4 = 0.25

    # compare the entire sequence, including gaps:
    dna <- DNAStringSet(c("ANGCT-", "-ACCT-"))
    dna
    d <- DistanceMatrix(dna, includeTerminalGaps=TRUE,
                        penalizeGapGapMatches=TRUE)
    # d[1,2] is now 3 bases in 6 = 0.50

    # compare union of internal positions, without terminal gaps:
    dna <- DNAStringSet(c("ANGCT-", "-ACCT-"))
    dna
    d <- DistanceMatrix(dna, includeTerminalGaps=TRUE,
                        penalizeGapGapMatches=FALSE)
    # d[1,2] is now 2 bases in 5 = 0.40

    # gap ("-") and unknown (".") characters are interchangeable:
    dna <- DNAStringSet(c("ANGCT.", ".ACCT-"))
    dna
    d <- DistanceMatrix(dna, includeTerminalGaps=TRUE,
                        penalizeGapGapMatches=FALSE)
    # d[1,2] is still 2 bases in 5 = 0.40

[Package DECIPHER version 2.20.0 Index]