dtwSP: Calculate DTW alignment of two snow profiles

Description

This is the core function of the package and allows to match layers between pairs of snow profiles to align them. It provides a variety of options, where the default values represent a good starting point to the alignment of most generic profiles.

Usage

dtwSP(
  query,
  ref,
  open.end = TRUE,
  checkGlobalAlignment = TRUE,
  keep.internals = TRUE,
  step.pattern = symmetricP1,
  resamplingRate = 0.5,
  rescale2refHS = TRUE,
  bottom.up = TRUE,
  top.down = TRUE,
  ...
)

Arguments

query

The query snow profile to be warped

ref

The reference snow profile to be warped against

open.end

Is an open end alignment desired?

checkGlobalAlignment

If open.end = TRUE, do you want to check whether a global alignment performs better (i.e., open.end = FALSE), and use the optimal one of the computed alignments?

keep.internals

Append resampled and aligned snow profiles as well as internal parameters to the output object?

step.pattern

The local slope constraint of the warping path, defaults to Sakoe-Chiba's symmetric pattern described by a slope factor of P = 1, see dtw::stepPattern

resamplingRate

Resampling rate for a regular depth grid; can also be a vector that provides the depth grid. Set to NA to keep the (original, likely irregular) depth grid (see Details, bullet point 2.2).

rescale2refHS

Rescale the query snow height to match the ref snow height?

bottom.up

Compute an open.end alignment from the ground upwards?

top.down

Compute an open.end alignment from the snow surface downwards?

...

Arguments passed to distMatSP and dtw, e.g.

dims, weights (defaults specified in distMatSP)
ddateNorm, numeric, normalize deposition date (default specified in distMatSP)
windowFunction, default warpWindowSP
window.size, ddate.window.size (defaults specified in warpWindowSP)
gtype_distMat, (default specified in distMatSP), cf. e.g. grainSimilarity_align
prefLayerWeights, weighting matrix for preferential layer matching, e.g. layerWeightingMat

Value

An alignment object of class 'dtwSP' is returned. This is essentially a list with various information about the alignment. If keep.internals = TRUE, the resampled snow profiles 'query', 'reference' and 'queryWarped', as well as the 'costMatrix' and 'directionMatrix' are elements of the returned object.

Details

The individual steps of aligning snow profiles:

(optional) Rescale the profiles to the same height (cf., scaleSnowHeight)
Resample the profiles onto the same depth grid. 2 different approaches:
- regular grid with a sampling rate that is provided by the user (recommended, cf., resampleSP). This approach requires to rescale the profiles.
- irregular grid that includes all layer interfaces within the two profiles (i.e., set resamplingRate = NA) (cf., resampleSPpairs)
Compute a weighted local cost matrix from multiple layer characteristics (cf., distMatSP)
Match the layers of the profiles with a call to dtw (eponymous R package)
Align the profiles by warping the query profile onto the reference profile (cf., warpSP)
(optional) If the function has been called with multiple different boundary conditions (global, top-down, or bottom-up alignments), the optimal alignment as determined by simSP will be returned.

Examples

Run this code

# NOT RUN {
dtwAlignment <- dtwSP(SPpairs$A_modeled, SPpairs$A_manual, open.end = FALSE)

## dtwSP object:
summary(dtwAlignment)
plot(dtwAlignment$queryWarped)
plotSPalignment(dtwAlignment = dtwAlignment)

# }