Skip to contents

Calculate pairwise distances between sequences using various methods

Source: R/calculate-distances.R
calculate_distance.Rd

This function provides a unified interface for computing pairwise distances between sequences using a variety of distance metrics. It dispatches to appropriate internal functions based on the specified method.

Usage

calculate_distance(
  x,
  method,
  subtype = NULL,
  tree = NULL,
  map = NULL,
  substitution_matrix = NULL,
  ...
)

Arguments

x

A character vector of sequences (typically amino acid or nucleotide sequences). Currently, you can pass NULL if you want to use the `"cartographic"` or `"cophenetic"` methods without specifying a sequence vector.

method

A character string specifying the distance method to use. Available options include:

  • `"hamming"`: Computes Hamming distance.

  • `"dl"`: Computes Damerau-Levenshtein distance.

  • `"p-epitope"`: Computes p-epitope distances for a specified subtype, by default the dominant p-peitope distance is returned but you can access all arguments of dist_pepi.

  • `"p-all-epitope"`: Computes p-all-epitope distances for a subtype.

  • `"cophenetic"` or `"tree"`: Computes distances based on a phylogenetic tree.

  • `"cartographic"` or `"cartography"`: Computes cartographic distances from a Racmacs map.

  • `"temporal"`: Computes temporal distances based on sequence names.

  • `"grantham"`: Computes Grantham's distance based on a substitution matrix.

  • `"substitution"`: Computes general weighted Hamming distances based on different substitution metrics which you can specify with the `substitution_matrix` argument.

subtype

(Optional) A character string indicating the subtype (e.g., `"H1"`, `"B"`) to use when computing p-epitope distances. Required for methods `"p-epitope"` and `"p-all-epitope"`.

tree

(Optional) A `phylo` object used when `method = "cophenetic"` or `"tree"`.

map

(Optional) A Racmacs map object used when `method = "cartographic"` or `"cartography"`.

...

Additional arguments passed to the corresponding distance functions.

Value

A numeric matrix of pairwise distances between the input sequences.

Details

This function acts as a dispatcher, validating the `method` input and routing the data to the correct underlying distance function. Required arguments for specific methods (e.g., `subtype`, `tree`, `map`) must be supplied when applicable or an error will be thrown.

See also

dist_string for `"hamming"` and `"dl"` distances, dist_pepi for `"p-epitope"` and `"p-all-epitope"` distances, tree_to_distances for `"cophenetic"` or `"tree"` distances, racmaps_map_to_distances for `"cartographic"` or `"cartography"` distances, dist_temporal for `"temporal"` distances. dist_substitution for `"substitution"` and `"grantham"` distances.

Examples

if (FALSE) calculate_distance(my_seq, "hamming") # \dontrun{}
if (FALSE) calculate_distance(my_seq, "p-epitope", subtype = "A(H1N1)") # \dontrun{}
if (FALSE) calculate_distance(my_seq, "cartographic", map = my_ac_map) # \dontrun{}