shoreline_date {shoredate}

Shoreline date

Description

A function for shoreline dating Stone Age sites based on their present-day elevation, their likely elevation above sea-level when in use and the trajectory of past shoreline displacement. Details and caveats pertaining to the implemented method is given in Roalkvam (2023).

Usage

shoreline_date(
  sites,
  elevation = NA,
  elev_reso = 0.01,
  cal_reso = 10,
  isobase_direction = 327,
  sum_isobase_directions = FALSE,
  model = "gamma",
  model_parameters = c(0.286, 20.833),
  elev_fun = "mean",
  upper_temp_limit = -2500,
  target_curve = NA,
  hdr_prob = 0.95,
  normalise = TRUE,
  sparse = FALSE,
  verbose = FALSE
)

Arguments

sites

Vector giving one or more site names, or, if displacement curves are to be interpolated, objects of class sf representing the sites to be dated. In the case of a spatial geometry, the first column is taken as the site name.

elevation

Vector of numeric elevation values for each site or a an elevation raster of class SpatRaster from the package terra from where the elevation values are to be derived.

elev_reso

Numeric value specifying the resolution with which to step through the distribution representing the distance between site and shoreline. Defaults to 0.01m.

cal_reso

Numeric value specifying the resolution to use on the calendar scale. Defaults to 10.

isobase_direction

A vector of numeric values defining the direction(s) of the isobases. Defaults to 327.

sum_isobase_directions

Logical value indicating that if multiple isobase directions are specified in isobase_direction the results should be summed for each site using sum_shoredates. Defaults to FALSE.

model

Character vector specifying the statistical model with which to model the distance from site to shoreline. Currently accepts either "none" or "gamma". Defaults to "gamma".

model_parameters

Vector of numeric values specifying the parameters for the statistical model describing the distance between site and shoreline. Defaults to c(0.286, 20.833), denoting the shape and scale of the default gamma function, respectively.

elev_fun

Statistic to define site elevation if this is to be derived from an elevation raster. Uses terra::extract(). Defaults to mean.

upper_temp_limit

Numerical value giving the upper temporal limit. Dates with a start date after the limit are returned as NA. Defaults to -2500, i.e. 2500 BCE.

target_curve

Data frame holding pre-computed shoreline displacement curve. This has to have the same or higher resolution on the calendar scale as that specified with cal_reso. interpolate_curve() will be run if nothing is provided to target_curve. Defaults to NA.

hdr_prob

Numeric value specifying the coverage of the highest density region. Defaults to 0.95.

normalise

Logical value specifying whether the shoreline date should be normalised to sum to unity. Defaults to TRUE.

sparse

Logical value specifying if only site name and shoreline date should be returned. Defaults to FALSE. Note that of the functions for further treatment, sparse dates are only compatible with sum_shoredates().

verbose

Logical value indicating whether progress should be printed to console. Defaults to FALSE.

Value

A nested list of class shoreline_date holding the shoreline date results and associated metadata for each dated site for each isobase direction. The elements of each date is:

• site_name name of the site.

• site_elev elevation of the site.

• date data frame with the columns bce where negative values indicate years BCE and positive CE, as well as probability, which gives the probability mass for each year.

• weighted_mean the weighted mean date.

• hdr_start start values for the HDR ranges.

• hdr_end end values for the HDR ranges.

• hdr_prob probability level for the HDR.

• dispcurve data frame holding the displacement curve used for dating the site. This has the columns bce, giving years BCE/CE. lowerelev, the lower limit for the elevation of the shoreline for each year. upperelev, the upper limit for elevation of the shoreline for each year.

• dispcurve_direction direction of the isobases in use.

• model_parameters parameters for the statistical model.

• modeldat data frame holding the model distribution. The column offset denotes the vertical distance (m) from the shoreline, as specified by the elev_reso argument. px is the cumulative probability at each step of offset, and probs is the probability of each step found by subtracting the preceding value from each value of px.

• cal_reso resolution on the calendar scale.

References

Roalkvam, I. 2023. A simulation-based assessment of the relation between Stone Age sites and relative sea-level change along the Norwegian Skagerrak coast. Quaternary Science Reviews 299:107880. DOI: https://doi.org/10.1016/j.quascirev.2022.107880

Examples

# Create example point using the required CRS WGS84 UTM32N (EPSG: 32632)
target_point <- sf::st_sfc(sf::st_point(c(538310, 6544255)), crs = 32632)

# Date target point, manually specifying the elevation instead of providing
# an elevation raster. Reducing elev_reso and cal_reso for speed.
shoreline_date(sites = target_point,
               elevation = 80,
               elev_reso = 1,
               cal_reso = 400)