getTruncatedModelChoices: Lists currently available models for population dynamics
In AdrianTimpson/ADMUR: Ancient Demographic Modelling Using Radiocarbon

getTruncatedModelChoices

R Documentation

Lists currently available models for population dynamics

Description

Lists currently available models, the number of parameters, and a brief description \loadmathjax

Usage

getTruncatedModelChoices()

Details

All the following models are truncated, such that the the total area (probability mass) between \mjseqnx_min and \mjseqnx_max equals 1. These limits (\mjseqnx_min and \mjseqnx_max) are the date range of the argument 'years', which is specified by the user. The user is therefore free to specify any date range of interest in which to model the underlying popluation dynamics of the overall data. For example, the full radiocarbon dataset may cover a wide range, with dates between 30,000 BP and 500 BP, but the user may wish to model a narrow the model range, for several reasons, such as 1) the sampling intensity when accruing the dataset is only reliable over a narrow range (research bias); 2) to avoid edge effects.

As such, these models are not appropriate for modelling archaeological phases, which by their very nature have a start and end (or at least wax and wane into and out of existance).

'CPL' is a Continuous Piecewise Linear model. It must have an odd number of parameters, each with a value between 0 and 1. A n-CPL model has \mjseqn2n-1 parameters (\mjseqnn-1 x-parameters and \mjseqnn y-parameters) that are mapped to \mjseqnn+1 PD coordinates (x,y pairs) using a modified Stick Breaking Dirichlet Process. The first and last x-coordinate are set as \mjseqnx_min and \mjseqnx_max, and the remaining internal x-coordinates are converted from their respective x-parameters using the Beta distribution CDF (where \mjseqn\alpha = 1 and \mjseqn\beta = the number of pieces still to be broken). The y-parameters (between 0 and 1) are converted to y-coordinates in two steps. Firstly, they are mapped from the parameter range (0,1) to the coordinate range (0, \mjseqn\infty) using the formula \mjseqn\frac1(1 - y)^2 - 1, and the single remaining y-coordinate is set as \mjseqn\frac1(1 - 0.5)^2 - 1. Secondly, they are normalised by the total area under the curve, calculated as the sum of the areas under all \mjseqnn pieces: \mjsdeqnArea = \sum_i=1^n (\fracy_i + y_i+12)(x_i+1 - x_i)
'uniform' is a uniform model requiring no parameters. I.e. the argument pars must be NA, and trivially the PDF is: \mjsdeqn\frac1x_max - x_min
'norm' is a truncated Gaussian model. The two parameters are used as \mjseqn\mu and \mjseqn\sigma in the formula for a truncated Normal distribution, the PDF of which is calculated in two steps. Firstly, the PDF of an ordinary Normal distribution is calculated. Secondly, it is normalised by the area within the date range.
'exp' is a truncated exponential model of the form \mjseqnf(x)=ae^rx where \mjseqnx = years. The single parameter is used as the rate exponent \mjseqnr which gives growth through time if \mjseqnr > 0, decline if \mjseqnr < 0, and constant if \mjseqnr=0. The PDF is as follows. Note the \mjseqna parameter cancels out: \mjsdeqn\frac-re^-r xe^-rx_max - e^-rx_min
'logistic' is a truncated logistic model. The two parameters are used as the rate \mjseqnk and centre \mjseqnx_0 where the PDF is: \mjsdeqn\frack(e^-k(x_0 - x) + 1)\ln\Bigl(\frace^-k(x_0 - x_min) + 1e^-k(x_0 - x_max) + 1\Bigr)
'sine' is a truncated sinewave model. The usual function to describe a sine wave is \mjseqnf(x) = A\sin(2\pi f x + p), where \mjseqnA is the amplitude, \mjseqnf is the frequency (cycles per year), and \mjseqnp is the cycle position (in radians) at \mjseqnx = 0, and therefore oscillates above and below the x-axis.

However, a sinusoidal PDF must by definition always be non-negative, which can conceptually be considered as a sine wave stacked on top of a uniform distribution with a height \mjseqnA + k, where \mjseqnk >= 0. Since the PDF is \mjseqnf(x) divided by the area below the curve, A and k simplify to a single parameter \mjseqnr that determines the relative proportions of the uniform and sinusoidal components, such that:

when \mjseqnr = 0 the amplitude of the sine wave component is zero, and the overall PDF is just a uniform distribution between min and max.

when \mjseqnr = 1 the uniform component is zero, and the minima of the sine wave touches zero. This does not necessarily mean the PDF minimum equals zero, since a minimum point of the sine wave may not occur with PDF domain (truncated between min and max).

Therefore the formula for the PDF is:
\mjsdeqn\frac
1 + \sin(2\pi f x + p) - \ln(r)(x_max - x_min)(1 - \ln(r)) + (\frac12\pi f)[\cos(2\pi f x_min - p) - \cos(2\pi f x_max - p)] where \mjseqnx = years, and \mjseqnx_min and \mjseqnx_max determine the truncated date range;
\mjseqn
f determines the numeric frequency (cycles per unit \mjseqnx);
\mjseqn
p determines the cycle position (in radians) at \mjseqnx = 0, and must be a numeric between \mjseqn0 and \mjseqn2\pi;
\mjseqn
r determines how flat the distribution is, and must be a numeric between 0 and 1.
'cauchy' is a truncated Cauchy model. The two parameters are used as \mjseqnl (location) and \mjseqns (scale) in the formula for a truncated Cauchy distribution. The PDF is as follows where \mjseqnx = years: \mjsdeqn\frac1sa[1+(\fracx-ls)^2][\arctan(\fracl-x_mins)-\arctan(\fracl-x_maxs)]
'power' is a truncated Power function model of the form \mjseqnf(x)=a(b+x)^c where \mjseqnx = years. The PDF is as follows. Note the \mjseqna parameter cancels out: \mjsdeqn\frac(c+1)(b+x)^c(b+x_max)^(c+1) - (b+x_min)^(c+1)
'timeseries' is a custom model of any complexity, typically derived from an independent source. For example, a timeseries of the proportion of forest to grassland through time, derived from pollen data. This requires a single parameter \mjseqnr to scale the PDF.