Convert and rescale relatedness matrices

Coerces every matrix in a relatedness collection to one declared type, optionally rescales it and writes a fixed diagonal, and records each operation in a history list-column. Rows without a defined conversion are reported in an error before any conversion occurs.

Usage

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

Arguments

data: A tibble from precise_dist(), precise_read(), or an earlier precise_transform() call, or a named list of matrices. List names are resolved against the registry to supply metric and type. A name that is not a canonical measure gets type = NA and therefore has no conversion.
to: NULL (the default, meaning no conversion), "distance", or "similarity".
conversion: Conversion mode. Only "auto" is supported.
normalize: NULL (the default) or "range01", which rescales each matrix to [0, 1] preserving symmetry. A constant matrix becomes all zeros.
diagonal: NULL (the default) or a value written on every matrix diagonal.
remove_dups: TRUE or FALSE. Drop rows whose matrix duplicates an earlier row.

Value

A tibble with the columns distance, metric, matrix, type, and time_taken_seconds carried over from the input, plus history. history is always present. Existing history is preserved; a row with no prior or newly applied operation contains an empty list. Any other input column is dropped.

Conversion to distance

to = "distance" selects a formula from the row's declared type and, where it matters, the registry family behind the canonical metric:

distance is unchanged, after asserting a zero diagonal.
correlation becomes sqrt(2 * (1 - r)), with r clamped to [-1, 1] so floating-point overshoot cannot produce NaN.
A kernel affinity becomes sqrt(2 * (1 - k)).
A random-forest similarity becomes 1 - proximity.
cosine becomes sqrt(2 * max(0, 1 - s)).
jaccard becomes 1 - jaccard.
Any other similarity with values in [0, 1] becomes 1 - s.

Generic similarity conversion writes a zero diagonal. Similarities outside [0, 1], non-kernel affinities, and functions with no declared type have no automatic conversion. pd_convertible_to_distance() reports the same table for one measure.

Conversion to similarity

to = "similarity" maps a distance to 1 / (1 + d) with a diagonal of one, after clamping numerical negatives to zero. An existing similarity is unchanged. A correlation or an affinity is numerically unchanged and retyped as a similarity.

Validation and order of operations

Every input matrix is validated before any operation runs, and every converted matrix is validated again. A matrix that is not numeric, square, symmetric within 1e-8, and finite is an error, as is a distance row with negative values or a nonzero diagonal.

Coercion is all or nothing. If any row lacks a conversion to the requested type, nothing is converted and the error names every offender.

Operations run in the fixed order to, normalize, diagonal. Each appends an entry to history recording the operation, the metric, the type before and after, and the formula applied. Row removal by remove_dups happens last, so history is complete first.

Author

Brian Muchmore

Examples

data(data_cell_cycle, package = "PreciseDist")

cells <- c(1:4, 60:63, 118:121)
cell_cycle <- as.matrix(data_cell_cycle[cells, 2:41])
rownames(cell_cycle) <- paste0(data_cell_cycle$Cell_cycle[cells], "_", cells)

measures <- precise_dist(
  cell_cycle,
  dists = c("euclidean", "cosine"),
  verbose = FALSE
)
measures[, c("distance", "type")]
#> # A tibble: 2 × 2
#>   distance  type      
#>   <chr>     <chr>     
#> 1 euclidean distance  
#> 2 cosine    similarity

distances <- precise_transform(measures, to = "distance")
distances[, c("distance", "type")]
#> # A tibble: 2 × 2
#>   distance  type    
#>   <chr>     <chr>   
#> 1 euclidean distance
#> 2 cosine    distance

# history records the formula applied to the converted row.
distances$history[[2]][[1]]$formula
#> [1] "sqrt(2 * max(0, 1 - s))"