DistanceMatrix: 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, includeTerminalGaps = FALSE, penalizeGapLetterMatches = TRUE, penalizeGapGapMatches = FALSE, correction = "none", processors = 1, verbose = TRUE)

Arguments

myXStringSet

An XStringSet object of aligned sequences (DNAStringSet, RNAStringSet, or AAStringSet).

includeTerminalGaps

Logical specifying whether or not to include terminal gaps ("-" 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.

Value

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.

Details

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.

Examples

Run this code

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

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

# compare union of internal ranges:
dna <- DNAStringSet(c("ANGCT-","-ACCT-"))
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-"))
d <- DistanceMatrix(dna, includeTerminalGaps=TRUE,
                    penalizeGapGapMatches=FALSE)
# d[1,2] is still 2 bases in 5 = 0.40