Skip to contents

Typed, auditable transformation of a PreciseDist relatedness object

Source: R/precise_transform.R
precise_transform.Rd

Coerce and/or normalize the matrices in a precise_dist object while preserving type, names, symmetry, and an auditable transformation history. Automatic coercion uses a small, documented set of formulas and otherwise raises a clear, actionable error.

Usage

precise_transform(
  data,
  to = NULL,
  conversion = "auto",
  normalize = NULL,
  diagonal = NULL,
  remove_errors = FALSE,
  remove_dups = FALSE
)

Arguments

data

A PreciseDist object (the tibble from precise_dist) or a named list of matrices.

to

NULL (default; no coercion), "distance", or "similarity".

conversion

Automatic conversion mode. Only "auto" is currently supported; its formulas are documented above.

normalize

NULL (default) or "range01" (rescale each matrix to [0, 1], symmetry-preserving).

diagonal

NULL (default) or a value written on every matrix diagonal.

remove_errors

TRUE/FALSE. Drop rows whose matrix is non-finite.

remove_dups

TRUE/FALSE. Drop rows with a duplicated matrix.

Value

A PreciseDist object (tibble: distance, metric, matrix, type, time_taken_seconds, history).

Details

Coercion (conversion = "auto") is driven by each row's type and, for distance targets, registry family (recovered from the canonical metric). For to = "distance":

  • distance -> identity (asserts a ~0 diagonal first)

  • correlation -> sqrt(2 * (1 - r)) (r clamped to [-1, 1])

  • affinity+kernel -> sqrt(2 * (1 - k))

  • similarity+rf -> 1 - proximity

  • cosine -> sqrt(2 * max(0, 1 - s))

  • jaccard -> 1 - jaccard

  • any other similarity in [0, 1] -> 1 - s

Generic similarity conversion sets the diagonal to zero. Similarities outside [0, 1], non-kernel affinities, and custom metrics without a declared type remain unsupported. For to = "similarity", distance input uses 1 / (1 + d); existing similarity input is unchanged, and correlation or affinity input is numerically unchanged and retyped as similarity. Coercion requires an all-convertible set and rejects an unsupported mixed set up front (query pd_convertible_to_distance for distance planning).

Operations run in a fixed order: to (coercion) before normalize and diagonal; each mutating operation appends an entry to the history list-column.

References

Muchmore, B., Muchmore P. and Alarcón-Riquelme ME. (2018). Optimal Distance Matrix Construction with PreciseDist and PreciseGraph.

Author

Brian Muchmore

Examples

x <- matrix(
  c(1, 0, 2, 0, 1, 2, 1, 1, 0, 2, 1, 1, 1, 2, 3, 3, 1, 2),
  nrow = 6,
  byrow = TRUE
)
d <- precise_dist(
  x,
  dists = c("euclidean", "cosine"),
  verbose = FALSE
)

precise_transform(d, to = "distance")$type
#> [1] "distance" "distance"
precise_transform(d, to = "similarity")$type
#> [1] "similarity" "similarity"