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

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

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

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.

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

```
# 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)
#> ===============
#> Site: 1
#> Elevation: 80
#>
#> 95% HDR:
#> 8850 BCE-7250 BCE
```