averageSP: Average a group of snow profiles

Description Usage Arguments Value Functions Author(s) References See Also Examples

View source: R/averageSP.R

Description

The functions dbaSP and averageSP implement Dynamic Time Warping Barycenter Averaging of snow profiles. The convenient wrapper averageSP takes care of choosing several appropriate initial conditions and picking the optimal end result (by minimizing the mean squared error between the average profile and the profile set). To pay appropriate attention to (thin) weak layers, weak layers need to be labeled in the profiles. You can either do that manually before calling this routine to suit your personal needs, or you can provide specific properties (in classifyPWLs) so that weak layers be labeled according to these properties by sarp.snowprofile::labelPWL. For more details, refer to the reference paper.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
averageSP(
  SPx,
  n = 5,
  sm = summary(SPx),
  progressbar = require("progress", quietly = TRUE, character.only = TRUE),
  progressbar_pretext = NULL,
  classifyPWLs = list(pwl_gtype = c("SH", "DH")),
  classifyCRs = list(pwl_gtype = c("MFcr", "IF", "IFsc", "IFrc")),
  proportionPWL = 0.5,
  breakAtSim = 0.9,
  breakAfter = 2,
  verbose = FALSE,
  ...
)

dbaSP(
  SPx,
  Avg,
  sm = summary(SPx),
  resamplingRate = 0.5,
  proportionPWL = 0.3,
  maxiter = 10,
  breakAtSim = 0.99,
  breakAfter = 1,
  plotChanges = FALSE,
  verbose = TRUE,
  ...
)

Arguments

SPx

SPx a snowprofileSet object. Note that the profile layers need to contain a column called $layerOfInterest which classifies weak layers. While averageSP will label weak layers automatically if not done by the user beforehand, dbaSP won't do that but fail instead!; consider thinking about how you want to label weak layers, see Description, classifyPWLs below, and the references. Also note, that if you wish to average the rescaled profile set, do so manually before calling this function (see examples).

n

the number of initial conditions that will be used to run dbaSP; see also chooseICavg.

sm

a summary of SPx metadata

progressbar

should a progressbar be displayed (the larger n, the more meaningful the progressbar)

progressbar_pretext

a character string to be prepended to the progressbar (mainly used by higher level cluster function)

classifyPWLs

an argument list for a function call to sarp.snowprofile::findPWL which returns relevant PWLs for identifying initial conditions. Importantly, these arguments will also be used to label weak layers in the profiles, if these labels do not yet exist in the layers objects as column $layerOfInterest. Check out the documentation of findPWL to familiarize yourself with your manifold options!

classifyCRs

an argument list for a function call to sarp.snowprofile::findPWL which returns relevant crusts for identifying initial conditions.

proportionPWL

decimal number that specifies the proportion required to average an ensemble of grain types as weak layer type. A value of 0.3, for example, means that layers will get averaged to a PWL type if 30% of the layers are of PWL type. Meaningful range is between [0.1, 0.5]. Values larger than 0.5 get set to 0.5.

breakAtSim

stop iterations when simSP between the last average profiles is beyond that value. Can range between [0, 1]. Default values differ between dbaSP and averageSP.

breakAfter

integer specifying how many values of simSP need to be above breakAtSim to stop iterating. Default values differ between dbaSP and averageSP.

verbose

print similarities between old and new average in between iterations?

...

alignment configurations which are passed on to dbaSP and then further to dtwSP. Note, that you can't provide rescale2refHS, which is always set to FALSE. If you wish to rescale the profiles, read the description of the SPx parameter and the examples.

Avg

the initial average snow profile: either a snowprofile object or an index to an initial average profile in SPx

resamplingRate

Resampling rate for a regular depth grid among the profiles

maxiter

maximum number of iterations

plotChanges

specify whether and how you want to plot the dba process: either FALSE, 'TRUE=='iterations', or 'averages+last''

Value

A list of class avgSP that contains the fields

Functions

Author(s)

fherla

References

Herla, F., Haegeli, P., and Mair, P.: Brief communication: A numerical tool for averaging large data sets of snow stratigraphy profiles useful for avalanche forecasting, The Cryosphere Discuss., https://doi.org/10.5194/tc-2022-29, in review, 2022.

See Also

averageSPalongSeason

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
## EXAMPLES OF averageSP
this_example_runs_about_10s <- TRUE
if (!this_example_runs_about_10s) {  # exclude from cran checks

## compute the average profile of the demo object 'SPgroup'
## * by labeling SH/DH layers as weak layers,
##   - choosing 3 initial conditions with an above average number of weak layers
##   - in as many depth ranges as possible
## * and neglecting crusts for initial conditions

  avgList <- averageSP(SPgroup, n = 3,
                       classifyPWLs = list(pwl_gtype = c("SH", "DH")),
                       classifyCRs = NULL)

  opar <- par(mfrow = c(1, 2))
  plot(avgList$avg, ymax = max(summary(avgList$set)$hs))
  plot(avgList$set, SortMethod = "unsorted", xticklabels = "originalIndices")
  par(opar)


  ## compute the average profile of the demo object 'SPgroup'
## * by labeling SH/DH/FC/FCxr layers with an RTA threshold of 0.65 as weak layers,
## * otherwise as above

  SPx <- snowprofileSet(lapply(SPgroup, computeRTA))
  avgList <- averageSP(SPx, n = 3,
                       classifyPWLs = list(pwl_gtype = c("SH", "DH", "FC", "FCxr"),
                                           threshold_RTA = 0.65),
                       classifyCRs = NULL)

  opar <- par(mfrow = c(1, 2))
  plot(avgList$avg, ymax = max(summary(avgList$set)$hs))
  plot(avgList$set, SortMethod = "unsorted", xticklabels = "originalIndices")
  par(opar)

}



## EXAMPLES OF dbaSP
## either rescale profiles beforehand...
if (FALSE) {  # don't run in package check to save time
  SPx <- reScaleSampleSPx(SPgroup)$set          # rescale profiles
  SPx <- snowprofileSet(lapply(SPx, labelPWL))  # label PWLs
  DBA <- dbaSP(SPx, 5, plotChanges = TRUE)      # average profiles
}

## or use unscaled snow heights:
if (FALSE) {  # don't run in package check to save time
  SPx <- snowprofileSet(lapply(SPgroup, labelPWL))  # label PWLs
  DBA <- dbaSP(SPx, 5, plotChanges = TRUE)          # average profiles
}

sarp.snowprofile.alignment documentation built on Feb. 10, 2022, 5:07 p.m.