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 = "auto",
  keep.internals = TRUE,
  step.pattern = symmetricP1,
  resamplingRate = 0.5,
  rescale2refHS = FALSE,
  bottom.up = TRUE,
  top.down = TRUE,
  nonMatchedSim = 0,
  nonMatchedThickness = 10,
  simType = "HerlaEtAl2021",
  apply_scalingFactor = FALSE,
  ...
)

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.

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? Recommended if profiles will not be rescaled.

checkGlobalAlignment

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? 'auto' sets to TRUE if simType == "HerlaEtAl2021" and to FALSE otherwise.

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

Scalar, numeric resampling rate for a regular depth grid. If the profiles have been rescaled prior to calling this routine, set to NA. To resample onto the smallest possible mutual (original, likely irregular) depth grid (see Details, bullet point 2.2), set to 'irregularInterfaces'.

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?

nonMatchedSim

Similarity value [0, 1] for non-matched layers, see simSP. indifference = 0.5, penalty < 0.5

nonMatchedThickness

How strongly should the thicknesses of non-matched layers influence the resulting similarity of the profiles? The smaller this (positive!) value, the more influence; and vice versa. See simSP for more details.

simType

the similarity between two profiles can be computed with different approaches, see simSP

apply_scalingFactor

Setting for simSP in case simType == "layerwise.

...

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, window.size.abs, 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

Author

fherla

Details

The individual steps of aligning snow profiles (which can all be managed from this function):

(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).
- irregular grid that includes all layer interfaces within the two profiles (i.e., set resamplingRate = 'irregularInterfaces') (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 or by the DTW distance will be returned.
(optional) Compute a similarity score for the two profiles with simSP

References

Herla, F., Horton, S., Mair, P., & Haegeli, P. (2021). Snow profile alignment and similarity assessment for aggregating, clustering, and evaluating of snowpack model output for avalanche forecasting. Geoscientific Model Development, 14(1), 239–258. https://doi.org/10.5194/gmd-14-239-2021

Examples

Run this code


## Align a modeled and a manual snow profile, primarily based on default settings:
dtwAlignment <- dtwSP(SPpairs$A_modeled, SPpairs$A_manual, open.end = FALSE)

## check out the resulting dtwSP alignment object:
summary(dtwAlignment)
plotSPalignment(dtwAlignment = dtwAlignment)
plotCostDensitySP(dtwAlignment)


## Align profiles from subsequent days without re-scaling them:
dtwAlignment <- dtwSP(SPpairs$C_day3, SPpairs$C_day1, resamplingRate = 0.5, rescale2refHS = FALSE,
                      window.size.abs = 30)
## Note, per default both bottom.up and top.down alignments have been considered,
#  let's check out which one was suited better:
dtwAlignment$direction  # i.e., bottom up
## Check it out visually:
plotSPalignment(dtwAlignment = dtwAlignment,
                mainQu = "3 Days after...", mainRef = "...the reference profile.")
plotCostDensitySP(dtwAlignment, labelHeight = TRUE)

Run the code above in your browser using DataLab