sarp.snowprofile.alignment (version 1.0.2)

distMatSP: Calculate a multidimensional distance matrix between two profiles

Description

This routine calculates a distance matrix for two given profiles (query and ref). Analogously to other DTW routines, the query is arranged along the matrix rows, the ref along the columns. Every cell of the matrix represents the distance between the corresponding profile layers. The distance is calculated based on the specified layer properties (e.g., hardness, gtype, ddate). The routine calls subroutines to calculate the distance for each property and combines the normalized distances by weighted averaging.

Usage

distMatSP(
  query,
  ref,
  dims = c("hardness", "gtype"),
  weights = c(0.2, 0.8),
  gtype_distMat = sim2dist(grainSimilarity_align(FALSE)),
  prefLayerWeights = layerWeightingMat(FALSE),
  ddateNorm = 5,
  windowFunction = warpWindowSP,
  ...
)

Arguments

query

The query snowprofile object

ref

The ref snowprofile object

dims

Character vector containing the layer properties to calculate the distance over. Currently implemented are the properties hardness, gtype, ddate.

weights

Numeric vector of the same length as dims specifying the averaging weights to each element of dims.

gtype_distMat

A symmetric distance scoring matrix provided as data.frame that stores information about the distances between the encountered grain types of the provided profiles. Default is the corresponding distance matrix of grainSimilarity_align, cf. sim2dist.

prefLayerWeights

A matrix similar to gtype_distMat, but storing weights for preferential layer matching, e.g. defaults to layerWeightingMat; the higher the values for a given grain type pair, the more the algorithm will try to match those layers above others. To turn weighting scheme off, set prefLayerWeights = NA

ddateNorm

Normalize the deposition date distance by ddateNorm number of days. Numeric, default 5.

windowFunction

a window function analogous to warpWindowSP (Note! designed for a quadratic distance matrix, i.e. two profiles with identical numbers of layers. To resample the profiles see resampleSPpairs and examples below. Other compatible window functions can be found in dtw::dtwWindowingFunctions.)

...

arguments to the window function, e.g. window.size, ddate.window.size, ...

Value

A distance matrix of dimension (n x m), where n, m are the number of layers in the query and ref, respectively.

See Also

resampleSPpairs

Examples

# NOT RUN {
## call function with two snow profiles of unequal lengths, without using a window function:
dMat_noWindow <- distMatSP(SPpairs$A_modeled, SPpairs$A_manual, windowFunction = NA)
graphics::image(dMat_noWindow, main = "Default distance matrix without a warping window")


## compute distance based on grain type alone,
## and additionally disable preferential layer matching:
dMat <- distMatSP(SPpairs$A_modeled, SPpairs$A_manual, windowFunction = NA,
                  dims = "gtype", weights = 1, prefLayerWeights = NA)
graphics::image(dMat,
                main = "... only based grain type, and without preferential layer matching")


## to use a warping window, the profiles need to have equal numbers of layers:
## i.e., resample them first, then compute dMat with a warping window
plist <- resampleSPpairs(SPpairs$A_modeled, SPpairs$A_manual)
dMat <- distMatSP(plist$query, plist$ref)
graphics::image(dMat, main = "Default with warping window")

# }