sarp.snowprofile (version 1.3.2)

snowprofileLayers: Constructor for a snowprofileLayers object

Description

Helper function to conveniently create a snowprofileLayers object, i.e. data.frame with mandatory column fields height (or depth) that provides vertical position of layers. Layers need to be ordered in a sequential manner, and the routine will rearrange the layers so that the last row of the resulting dataframe corresponds to the snow surface. If the vertical location of the layers is given by depth, make sure to provide hs if it's known. Otherwise, provide the field maxObservedDepth or layer thicknesses. Providing only depth will issue a warning and set the corresponding lowest layer thickness to NA. The resulting dataframe will contain all three fields height, depth, and thickness, which will be auto-filled if not provided (see format_snowprofileLayers). If the columns that describe layer properties are not of equal lengths, their values will be recycled (default data.frame mechanism). Instead of individual layer characteristics, a data.frame can be provided, which will be converted into a snowprofileLayers class. The constructor asserts correctness of the layers object by a call to validate_snowprofileLayers.

Usage

snowprofileLayers(
  height = as.double(NA),
  temperature = as.double(NA),
  density = as.double(NA),
  lwc = as.double(NA),
  gsize = as.double(NA),
  gsize_max = as.double(NA),
  gsize_avg = as.double(NA),
  gtype = as.factor(NA),
  gtype_sec = as.factor(NA),
  hardness = as.double(NA),
  ddate = as.POSIXct(NA),
  bdate = as.POSIXct(NA),
  datetag = as.Date(NA),
  ssi = as.double(NA),
  sphericity = as.double(NA),
  v_strain_rate = as.double(NA),
  crit_cut_length = as.double(NA),
  tsa = as.double(NA),
  tsa_interface = as.double(NA),
  rta = as.double(NA),
  rta_interface = as.double(NA),
  layerOfInterest = as.logical(NA),
  comment = as.character(NA),
  ...,
  hs = as.double(NA),
  maxObservedDepth = as.double(NA),
  layerFrame = NA,
  validate = TRUE,
  dropNAs = TRUE
)

Value

snowprofileLayers object as data.frame with strings as factors

Arguments

height

height vector (cm) referring to the top layer interface. Instead of height, depth can also be given and should be accompanied by an array specifying the thickness of the layers, or alternatively, the total snow depth hs and/or the maximum observed depth maxObservedDepth should be provided. Note, that also the depth refers to the top layer interface. See examples!

temperature

snow temperature (deg C)

density

layer density (kg/m3)

lwc

liquid water content (%)

gsize

grain size (mm)

gsize_max

maximum grain size (mm)

gsize_avg

average grain size (mm)

gtype

grain type (character or factor)

gtype_sec

secondary grain type (character or factor)

hardness

numeric hand hardness (use char2numHHI to convert from character hardness)

ddate

deposition date of layer (POSIXct format). WARNING: if you provide character format, the time zone of your computer system will be assumed.

bdate

burial date of layer (POSIXct format). WARNING: if you provide character format, the time zone of your computer system will be assumed.

datetag

of layer (i.e., usually corresponds to ddate for 'MFcr', and to bdate for all other grain types.)

ssi

snow stability index (numeric)

sphericity

between 0 and 1

v_strain_rate

viscous deformation rate (s^-1)

crit_cut_length

critical crack length (m)

tsa

threshold sum approach for structural instability (also called lemons); valid for the layer, i.e., the weakest interface adjacent to the layer. see computeTSA.

tsa_interface

same as tsa, but valid for top interface of corresponding layer

rta

relative threshold sum approach (following Monti et al 2013, ISSW paper); valid for the layer, i.e., the weakest interface adjacent to the layer. see computeRTA.

rta_interface

same as rta, but valid for top interface of corresponding layer

layerOfInterest

a boolean column to label specific layers of interest, e.g. weak layers. see labelPWL.

comment

character string

...

columns to include in the layers object. Note, that they need to correspond to the according height/depth array. e.g. hardness (can use character hardness or numeric hardness via char2numHHI), ddate (class POSIX), bdate (class Date) gtype (character or factor), density, temperature, gsize, lwc, gsize_max, gtype_sec, ssi, depth, thickness

hs

total snow height (cm), if not deductible from height vector. Particularly important when only a depth grid is provided!

maxObservedDepth

the observed depth of the profile from the snow surface downwards. Will only be used, if no height, thickness, or hs is given.

layerFrame

a data.frame that's converted to a snowprofileLayers class if no other layer characteristics are provided

validate

Validate obj with validate_snowprofileLayers?

dropNAs

Do you want to drop all columns consisting of NAs only?

Author

shorton, fherla

See Also

snowprofile

Examples

## Empty layers object:
snowprofileLayers()


## simple layers example that recycles the hardness 1F+: with warning issued!
## Try what happens if you provide ddate as character array without a timezone.
snowprofileLayers(height = c(10, 25, 50),
                  hardness = char2numHHI('1F+'),
                  gtype = c('FC', NA, 'PP'),
                  ddate = as.POSIXct(c(NA, NA, "2020-02-15 10:45:00"),
                                     tz = "Etc/GMT+7"))

## create snowprofileLayers object from data.frame
## and feed it into a snowprofile object:
df <- data.frame(height = c(10, 25, 50),
                  hardness = c(2, 3, 1),
                  gtype = c('FC', NA, 'PP'),
                  stringsAsFactors = TRUE)

spL <- snowprofileLayers(layerFrame = df)
(sp <- snowprofile(layers = spL))


##### Create top-down recorded snowprofileLayers ####
## check out how the fields 'hs' and 'maxObservedDepth' are auto-filled in the
## resulting snowprofile object!
## 1.) Specify depth and hs:
## In that case the routine will assume that the deepest layer extends down to the ground
(sp1 <- snowprofile(layers = snowprofileLayers(depth = c(40, 25, 0),
                                               hardness = c(2, 3, 1),
                                               gtype = c('FC', NA, 'PP'),
                                               hs = 50)))
## note that sp and sp1 are the same profiles:
all(sapply(names(sp$layers), function(cols) {sp$layers[cols] == sp1$layers[cols]}), na.rm = TRUE)

## 2.) Specify depth, hs and thickness or maxObservedDepth:
## This will include a basal layer of NAs to fill the unobserved space down to the ground.
(sp2 <- snowprofile(layers = snowprofileLayers(depth = c(40, 25, 0),
                                               hardness = c(2, 3, 1),
                                               gtype = c('FC', NA, 'PP'),
                                               hs = 70,
                                               maxObservedDepth = 50)))

## 3.) Specify depth and maxObservedDepth:
## This will include a basal layer of NAs which is 1 cm thick to flag the unknown basal layers.
(sp3 <- snowprofile(layers = snowprofileLayers(depth = c(40, 25, 0),
                         hardness = c(2, 3, 1),
                         gtype = c('FC', NA, 'PP'),
                         gsize = c(2, NA, NA),
                         maxObservedDepth = 50)))

## 4.) Specify depth and thickness:
## This is equivalent to the example spL3 above!
## This will include a basal layer of NAs which is 1 cm thick to flag the unknown basal layers.
(sp4 <- snowprofile(layers = snowprofileLayers(depth = c(40, 25, 0),
                         thickness = c(10, 15, 25),
                         hardness = c(2, 3, 1),
                         gtype = c('FC', NA, 'PP'))))

## 5.) Specify only depth: issues warning!
(sp5 <- snowprofile(layers = snowprofileLayers(depth = c(40, 25, 0),
                         hardness = c(2, 3, 1),
                         gtype = c('FC', NA, 'PP'))))

## plot all 5 top.down-recorded profiles:
set <- snowprofileSet(list(sp1, sp2, sp3, sp4, sp5))
plot(set, SortMethod = "unsorted", xticklabels = "originalIndices",
     hardnessResidual = 0.1, hardnessScale = 1.5, TopDown = TRUE,
     main = "TopDown Plot")

plot(set, SortMethod = "unsorted", xticklabels = "originalIndices",
     hardnessResidual = 0.1, hardnessScale = 1.5, TopDown = FALSE,
     main = "BottomUp Plot")