Learn R Programming
ADMUR (version 1.0.3)

convertPars: Converts parameters to x,y coordinates (date and pdf) that describe a model

Description

Converts either a vector of parameters, or a matrix of many parameter sets to model x,y coordinates (date and pdf)

Usage

convertPars(pars, years, type, taphonomy=FALSE)

Arguments

pars

Either a vector of one parameter set, or a matrix of several parameter sets (one set per row).

years

A vector of years.

type

Choose from 'CPL', 'exp', 'norm', 'cauchy', 'sine', 'uniform', 'logistic', 'power'.

taphonomy

If TRUE, the last two parameters determine the taphonomic loss rate.

Details

Parameter searches will yield either a single set of parameters, or a matrix with one parameter set per row (such as the 'res' value from mcmc) . Either can be handed directly to this function.

The structure of the output differs depending on if converting a vector or matrix.

All models are truncated, such that the total area between x_min and x_max (the date range of 'years') equals 1.

'CPL' is a Continuous Piecewise Linear model. Pars must be of odd length, each between 0 and 1. A n-CPL model has 2n-1 parameters (n-1 x-parameters and n y-parameters) that are mapped to n+1 PD coordinates (x,y pairs) using a modified Stick Breaking Dirichlet Process. The first and last x-coordinate are set as x_min and x_max, and the remaining internal x-coordinates are converted from their respective x-parameters using the Beta distribution CDF (where = 1 and = 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, ) using the formula 1(1 - y)^2 - 1, and the single remaining y-coordinate is set as 1(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 n pieces: Area = _i=1^n (y_i + y_i+12)(x_i+1 - x_i)

'exp' is a truncated exponential model of the form f(x)=ae^rx where x = years. The single parameter is used as the rate exponent r which gives growth through time if r > 0, decline if r < 0, and constant if r=0. The PDF is as follows. Note the a parameter cancels out: -re^-r xe^-rx_max - e^-rx_min

'logistic' is a truncated logistic model. The two parameters are used as the rate k and centre x_0 where the PDF is: k(e^-k(x_0 - x) + 1)(e^-k(x_0 - x_min) + 1e^-k(x_0 - x_max) + 1)

'norm' is a truncated Gaussian model. The two parameters are used as and 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.

'cauchy' is a truncated Cauchy model. The two parameters are used as x_0 (location) and (scale) in the formula for a truncated Cauchy distribution. The PDF is as follows where x = years: 1[1+(x-x_0)^2][(x_0-x_min)-(x_0-x_max)]

'power' is a truncated Power function model of the form f(x)=a(b+x)^c where x = years. The PDF is as follows. Note the a parameter cancels out: (c+1)(b+x)^c(b+x_max)^(c+1) - (b+x_min)^(c+1)

'sine' is a truncated sinewave model. The three parameters are used as specified in sinewavePDF

'uniform' is a uniform model requiring no parameters. I.e. the argument pars must be NULL or c(), and trivially the PDF is: 1x_max - x_min

If taphonomy is TRUE, the model PDF additionally includes taphonomic loss. The last two parameters are used to generate a taphonomic curve using the formula (b+x)^c and the remaining parameters are used in the appropriate model type above. Then the model PDF is multiplied by the taphonomic curve and normalised across the date range, to give the final model PDF that includes taphonomy.

Examples

Run this code
# NOT RUN {
	# convert a single random 6-CPL parameter set
	pars <- runif(11)
	x <- convertPars( pars=pars, years=5500:7500, type='CPL')

	# single random 6-CPL parameter set with taphonomy parameters (b,c)
	pars <- runif(13, c(rep(0,11),0,-3), c(rep(1,11),20000,0))
	x <- convertPars( pars=pars, years=5500:7500, type='CPL', taphonomy=TRUE)

	# convert a matrix of 5 random 6-CPL parameter sets
	pars <- matrix( runif(11*5), 5, 11 )
	x <- convertPars( pars=pars, years=5500:7500, type='CPL')

	# 5 random 6-CPL parameter sets with taphonomy parameters (b,c)
	pars <- t(matrix(runif(13*5, c(rep(0,11),0,-3), c(rep(1,11),20000,0)),13,5))
	x <- convertPars( pars=pars, years=5500:7500, type='CPL', taphonomy=TRUE)

	# convert a single random exponential parameter
	pars <- runif(1, -0.01, 0.01)
	x <- convertPars( pars=pars, years=5500:7500, type='exp')

	# single random exponential parameter with taphonomy parameters (b,c)
	pars <- runif(3, c(-0.01,0,-3), c(0.01,20000,0))
	x <- convertPars( pars=pars, years=5500:7500, type='exp', taphonomy=TRUE)
	
	# convert a matrix of 5 random exponential parameter sets
	pars <- matrix( runif(5, -0.01, 0.01), 5, 1 )
	x <- convertPars( pars=pars, years=5500:7500, type='exp')

	# 5 random exponential parameter sets with taphonomy parameters (b,c)
	pars <- t(matrix(runif(3*5, c(-0.01,0,-3), c(0.01,20000,0)),3,5))
	x <- convertPars( pars=pars, years=5500:7500, type='exp', taphonomy=TRUE)

	# convert a single random Gaussian parameter pair (mean, sd)
	pars <- runif(2, c(6000,200), c(7000,1000))
	x <- convertPars( pars=pars, years=5500:7500, type='norm')

	# single random Gaussian parameter pair (mean, sd) with taphonomy parameters (b,c)
	pars <- runif(4, c(6000,200,0,-3), c(7000,1000,20000,0))
	x <- convertPars( pars=pars, years=5500:7500, type='norm', taphonomy=TRUE)

	# convert a matrix of 5 random Gaussian parameter pairs (mean, sd)
	pars <- t(matrix(runif(2*5, c(6000,200), c(7000,1000)),2,5))
	x <- convertPars( pars=pars, years=5500:7500, type='norm')

	# 5 random Gaussian parameter pairs (mean, sd) with taphonomy parameters (b,c)
	pars <- t(matrix(runif(4*5, c(6000,200,0,-3), c(7000,1000,20000,0)),4,5))
	x <- convertPars( pars=pars, years=5500:7500, type='norm', taphonomy=TRUE)

	# convert a single random Cauchy parameter pair (location, scale)
	pars <- runif(2, c(6000,200), c(7000,1000))
	x <- convertPars( pars=pars, years=5500:7500, type='cauchy')

	# single random Cauchy parameter pair (location, scale) with taphonomy parameters (b,c)
	pars <- runif(4, c(6000,200,0,-3), c(7000,1000,20000,0))
	x <- convertPars( pars=pars, years=5500:7500, type='cauchy', taphonomy=TRUE)

	# convert a matrix of 5 random Cauchy parameter pairs (location, scale)
	pars <- t(matrix(runif(2*5, c(6000,200), c(7000,1000)),2,5))
	x <- convertPars( pars=pars, years=5500:7500, type='cauchy')

	# 5 random Cauchy parameter pairs (location, scale) with taphonomy parameters (b,c)
	pars <- t(matrix(runif(4*5, c(6000,200,0,-3), c(7000,1000,20000,0)),4,5))
	x <- convertPars( pars=pars, years=5500:7500, type='cauchy', taphonomy=TRUE)

	# convert a single random logistic parameter pair (k, x0)
	pars <- runif(2, c(0,6000), c(0.01,6500))
	x <- convertPars( pars=pars, years=5500:7500, type='logistic')

	# single random logistic parameter pair (k, x0) with taphonomy parameters (b,c)
	pars <- runif(4, c(0,6000,0,-3), c(0.01,6500,20000,0))
	x <- convertPars( pars=pars, years=5500:7500, type='logistic', taphonomy=TRUE)

	# convert a matrix of 5 random logistic parameter pairs(k, x0)
	pars <- t(matrix(runif(2*5, c(0,6000), c(0.01,6500)),2,5))
	x <- convertPars( pars=pars, years=5500:7500, type='logistic')

	#  5 random logistic parameter pairs(k, x0) with taphonomy parameters (b,c)
	pars <- t(matrix(runif(4*5, c(0,6000,0,-3), c(0.01,6500,20000,0)),4,5))
	x <- convertPars( pars=pars, years=5500:7500, type='logistic', taphonomy=TRUE)

	# convert a single random power function parameter pair (b, c)
	pars <- runif(2, c(2000,-1.7), c(4000,-1.2))
	x <- convertPars( pars=pars, years=5500:7500, type='power')

	# single random power function parameter pair (b, c) with taphonomy parameters 
	pars <- runif(4, c(2000,-1.7,0,-3), c(4000,-1.2,20000,0))
	x <- convertPars( pars=pars, years=5500:7500, type='power', taphonomy=TRUE)

	# convert a matrix of 5 random power function parameter pairs(b, c)
	pars <- t(matrix(runif(2*5, c(2000,-1.7), c(4000,-1.2)),2,5))
	x <- convertPars( pars=pars, years=5500:7500, type='power')

	#  5 random power function parameter pairs(b, c) with taphonomy parameters 
	pars <- t(matrix(runif(4*5, c(2000,-1.7,0,-3), c(4000,-1.2,20000,0)),4,5))
	x <- convertPars( pars=pars, years=5500:7500, type='power', taphonomy=TRUE)

	# convert a single random sinewave parameter set (f,p,r)
	f <- 1/runif(1,200,1000)
	p <- runif(1,0,2*pi)
	r <- runif(1,0,1)
	x <- convertPars( pars=c(f,p,r), years=5500:7500, type='sine')

	# single random sinewave parameter set (f,p,r) with taphonomy parameters (b,c)
	f <- 1/runif(1,200,1000)
	p <- runif(1,0,2*pi)
	r <- runif(1,0,1)
	b <- runif(1,0,20000)
	c <- runif(1,-3,0)
	x <- convertPars( pars=c(f,p,r,b,c), years=5500:7500, type='sine', taphonomy=TRUE)

	# convert a matrix of 5 random sinewave parameter sets (f,p,r)
	f <- 1/runif(5,200,1000)
	p <- runif(5,0,2*pi)
	r <- runif(5,0,1)
	x <- convertPars( pars=cbind(f,p,r), years=5500:7500, type='sine')

	# 5 random sinewave parameter sets (f,p,r) with taphonomy parameters (b,c)
	f <- 1/runif(5,200,1000)
	p <- runif(5,0,2*pi)
	r <- runif(5,0,1)
	b <- runif(5,0,20000)
	c <- runif(5,-3,0)
	x <- convertPars( pars=cbind(f,p,r,b,c), years=5500:7500, type='sine', taphonomy=TRUE)
	
	# although a uniform distribution has no parameters, a pdf can still be generated:
	x <- convertPars(pars=NULL, years=5500:7500, type='uniform')

	# and if taphonomy is included, it does have the taphonomy parameters (b,c)
	pars <- runif(2, c(0,-3), c(20000,0))
	x <- convertPars(pars=pars, years=5500:7500, type='uniform', taphonomy=TRUE)

	# likewise for a matrix of 5 random taphonomy parameters (b,c)
	pars <- t(matrix(runif(2*5, c(0,-3), c(20000,0)),2,5))
	x <- convertPars(pars=pars, years=5500:7500, type='uniform', taphonomy=TRUE)
	
# }

Run the code above in your browser using DataLab