dtwSP function

Calculate DTW alignment of two snow profiles

Calculate DTW alignment of two snow profiles

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.

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,
  simType = "HerlaEtAl2021",
  ...
)

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?

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

  • ...: Arguments passed to distanceSPlayers , and dtw::dtw , and simSP e.g.

    • dims, weights (defaults specified in distanceSPlayers)
    • ddateNorm, numeric, normalize deposition date (default specified in distanceSPlayers)
    • windowFunction, default warpWindowSP
    • window.size, window.size.abs, ddate.window.size (defaults specified in warpWindowSP)
    • gtype_distMat, specific to profile alignment, see distanceSPlayers
    • gtype_distMat_simSP, specific to similarity measure in simSP
    • prefLayerWeights, weighting matrix for preferential layer matching, e.g. layerWeightingMat
    • 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.
    • apply_scalingFactor Setting for simSP in case simType is "layerwise" or "wsum_scaled".

Returns

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

  4. Match the layers of the profiles with a call to dtw::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

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.

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)

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

Author(s)

fherla

sarp.snowprofile.alignment packageRead PDF manual