DistanceMatrix {DECIPHER} | R Documentation |
Calculates a distance matrix for an XStringSet
. Each element of the distance matrix corresponds to the dissimilarity between two sequences in the XStringSet
.
DistanceMatrix(myXStringSet, type = "matrix", includeTerminalGaps = FALSE, penalizeGapLetterMatches = TRUE, penalizeGapGapMatches = FALSE, correction = "none", processors = 1, verbose = TRUE)
myXStringSet |
An |
type |
Character string indicating the type of output desired. This should be either |
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 |
penalizeGapGapMatches |
Logical specifying whether or not to consider gap-to-gap matches as mismatches. If |
correction |
The substitution model used for distance correction. This should be (an abbreviation of) either |
processors |
The number of processors to use, or |
verbose |
Logical indicating whether to display progress. |
The uncorrected 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
.
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.
Erik Wright eswright@pitt.edu
# 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