dtwSP: Calculate DTW alignment of two snow profiles

In sarp.snowprofile.alignment: Snow Profile Alignment, Aggregation, and Clustering

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,
  ...
)

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

Details

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

1. (optional) Rescale the profiles to the same height (cf., scaleSnowHeight)

2. 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)

3. Compute a weighted local cost matrix from multiple layer characteristics (cf., distMatSP)

4. Match the layers of the profiles with a call to dtw (eponymous R package)

5. Align the profiles by warping the query profile onto the reference profile (cf., warpSP)

6. (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.

7. (optional) Compute a similarity score for the two profiles with simSP

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.

Note

Furthermore, the alignment based on grain type information is currently only possible for specific grain types. These grain types require a pre-defined distance or similarity, such as given by grainSimilarity_align. If your profile contains other grain types, you are required to define your custom grainSimilarity matrix.

The package used to require re-scaling of the profiles to identical snow heights. This requirement has been removed in v1.1.0. Profiles therefore can be resampled onto a regular grid, whilst keeping their original total snow heights. The alignment can then be carried out bottom.up or top.down with a relative or absolute window size. If the profiles have different snow heights and a relative window size is provided, the window size is computed using the larger snow height of the two profiles (e.g., Profile A HS 100 cm, Profile B HS 80 cm; window.size = 0.3 translates to an effective window size of +/- 33 cm). See examples for alignments without prior re-scaling.

Author(s)

fherla

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

See Also

plotSPalignment, simSP

Examples

## 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)

sarp.snowprofile.alignment documentation built on Aug. 8, 2022, 1:05 a.m.