Package 'WARN'

Title: Weaning Age Reconstruction with Nitrogen Isotope Analysis
Description: This estimates precise weaning ages for a given skeletal population by analyzing the stable nitrogen isotope ratios of them. Bone collagen turnover rates estimated anew and the approximate Bayesian computation (ABC) were adopted in this package.
Authors: Takumi Tsutaya
Maintainer: Takumi Tsutaya <[email protected]>
License: GPL (>= 3)
Version: 1.2-4
Built: 2024-10-29 05:01:13 UTC
Source: https://github.com/tsutatsuta/warn

Help Index


Weaning Age Reconstruction with Nitrogen isotope analysis

Description

WARN is a package to estimate precise weaning ages for a given skeletal population by analyzing the measured stable nitrogen isotope ratios (d15Ns) of them. Bone collagen turnover rates in non-adults estimated anew and the approximate Bayesian computation (ABC) were adopted in the model.

Details

Package: WARN
Type: Package
Version: 1.2-4
Date: 2019-10-18
License: GPL (>= 3)

Function warn esimates the age at the start and end of weaning, enrichment of d15N through maternal to infant tissue, and d15N value of collagen synthesized entirely from weaning foods with their posterior probabilities. Other geochemical values that change with breastfeeding and weaning can also be analyzed (e.g., d18O, Sr/Ca, and Ba/Ca). The warn performs approximate Bayesian computation (ABC) for a given set of estimated ages and measured d15N of non-adults from the skeletal population. Function warnCI calculates credible intervals (CIs) of posterior probabilities under a given class "warn" object and a given threshold of CIs. Function warnProb calculate posterior probabilities under a given class "warn" object and given parameter ranges. This package adopts S3 class. The detail of mathematical models is described in Tsutaya and Yoneda (2013).

Author(s)

Takumi Tsutaya <[email protected]>

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

warn, warnCI, warnOptim, warnProb

Examples

## See ?warn, ?warnCI, and ?warnProb for examples.

Stable isotopic data of the Lerna population

Description

This data set gives the stable carbons and nitrogen isotope ratios of the 39 human bone samples from Middle Bronze Age (ca. 2100–1700 BC) Lerna, Greece reported in Triantaphyllou et al. (2008).

Usage

lerna

Format

lerna is a data frame with 39 individuals (rows) and 5 variables (columns) of ID (skeletal number), sex, estimated age at death, and carbon and nitrogen isotope ratios, named id, sex, age, d13C, and d15N, respectively. sex is a factor with levels f, m, and u, which corresponds to famale, male, unknown, respectively. The estimated ages at death were midpoint values.

Details

See detail for Triantaphyllou et al. (2008).

Source

Triantaphyllou, S., Richards, M. P., Zerner, C., and Voutsaki, S. (2008). Isotopic dietary reconstruction of humans from Middle Bronze Age Lerna, Argolid, Greece. J. Archaeol. Sci. 35, 3028–3034.


Plot for posterior weaning parameters

Description

plot.warn is a plotting utile for quick visualization of the result of weaning age reconstruction from an object of class "warn". The measured and modeled bone collagen nitrogen isotope ratios (d15Ns) are plotted ageinst estimated ages.

Usage

## S3 method for class 'warn'
plot(x, hline.female = TRUE, hline.adult = FALSE, 
  adult.mean = NA, adult.sd = 0,
  is.legend = TRUE, is.female = TRUE, plot = TRUE, ...)

Arguments

x

an object of class "warn" generated by warn.

hline.female, hline.adult

logical; if TRUE, horizontal dotted lines indicating one standard deviation ranges of adult females and all adults are plotted on the figure; the default is TRUE for female and FALSE for adult.

adult.mean

the mean d15N of all adults, an optional single value.

adult.sd

the one standard deviation of all adult d15N, an optional single value. Utilized later in plot.warn.

is.legend

logical; if TRUE (the default), legend is plotted on the figure.

is.female

logical; if TRUE (the default), female mean d15N is plotted on the figure.

plot

logical; if TRUE (the default), a figure is plotted, otherwise a list of d15N changes in modeled bone and modeled diet is returned.

...

additional arguments passed to plot.

Details

The following three results on d15N are plotted against age, the original measured ratios of non-adult bone collagen (Measured d15N), modeled ratios of non-adult bone collagen (Modeled d15N), and modeled ratios of collagen synthesized entirely from consumed foods in the last half year (Modeld diet). These results are calculated in warn. Mean d15Ns of adult females and all adults can also be plotted.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnCI, warnProb, summary.warn

Examples

## See ?warn for examples.

Plot for CI of posterior probabilities of weaning parameters

Description

plot.warnCI is a plotting utile for quick visualization of credible interval (CI) of posterior probabilities of the weaning parameters from an object of class "warnCI". Results of kernel density estimation for the posteriors are plotted as a form of contour or one-dimensional distribution with CIs.

Usage

## S3 method for class 'warnCI'
plot(x, weaning.par = "age", ...)

Arguments

x

an object of class "warnCI" generated by warnCI.

weaning.par

character for the intended weanig parameter. The allowed values are "age" (the default), "enrich", and "wnfood".

...

additional arguments passed to plot.warnProb.

Details

Values on the contour lines indicate relative probabilities based on that of the maximum density estimator.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnCI, warnProb, plot.warnProb

Examples

## See ?warnCI for examples.

Plot for probabilities of posterior weaning parameters

Description

plot.warnProb is a plotting utile for quick visualization of the posterior weaning parameters from an object of class "warnProb". Results of kernel density estimation for the posteriors are plotted as a form of contour with designated parameter ranges.

Usage

## S3 method for class 'warnProb'
plot(x, is.legend = TRUE, is.contour = TRUE,
  is.image = FALSE, is.prior = FALSE, ...)

Arguments

x

an object of class "warnProb" generated by warnProb.

is.legend

logical; if TRUE (the default), legend is plotted on the figure.

is.contour

logical; if TRUE (the default), contour lines corresponding to the probabilirties are plotted with contour. Only used if the intended weanig parameter is weaning ages (i.e., weaning.par = "age" in warnProb).

is.image

logical; if TRUE, grid of gray-scale rectangles with color strength corresponding to the probabilirties is plotted with image. The default is FALSE, and only used if the intended weanig parameter is weaning ages (i.e., weaning.par = "age" in warnProb).

is.prior

logical; if TRUE, prior density of the paramter is also plotted with dotted line. The default is FALSE, and only used if the intended weanig parameter is enrichment or weaning food (i.e., weaning.par = "enrich" or "wnfood" in warnProb).

...

additional arguments passed to plot.

Details

Values on the contour lines indicate relative probabilities based on that of the maximum density estimator.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnCI, warnProb, summary.warnProb

Examples

## See ?warnProb for examples.

Summaries of posterior weaning parameters

Description

summary.warn calculates simple summaries of posterior samples for the four weaning parameters, which is the maximum density estimators and its marginal probabilities, a joint probability for the combination of the maximum density weaning ages, mean squared distance between the measured and modeled nitrogen isotope ratio (d15N), number of non-adult individuals used, and number of particles used in sequential Monte Carlo (SMC) sampling.

Usage

## S3 method for class 'warn'
summary(object, ...)

Arguments

object

an object of class "warn" generated by warn.

...

additional arguments affecting the summary produced.

Value

summary.warn returns a list containing following components and those succeeded from "warn":

call

the matched call.

mde

the maximum density estimators and the marginal probabilities.

prob.2d.age

the joint probability for the combination of the maximum density weaning ages.

dist.mde

the mean squared distance between the measured and modeled d15Ns.

individual

the number of non-adult individuals used.

particle

the number of particles used in SMC sampling.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnCI, warnProb, plot.warn

Examples

## See ?warn for examples.

Summaries of probabilities of posterior weaning parameters

Description

summary.warnProb calculates simple summaries of probabilities of posterior samples for the four weaning parameters, which is the intended weaning paramter, designated parameter range, and calculate posterior probability of the weaning parameter that ranges between the range.

Usage

## S3 method for class 'warnProb'
summary(object, ...)

Arguments

object

an object of class "warnProb" generated by warnProb.

...

additional arguments affecting the summary produced.

Value

summary.warnProb returns a list containing following components and those succeeded from "warnProb":

call

the matched call.

range

a vector giving the range of the intended weanig parameter.

probability

posterior probability of parameter in the designated range.

weaning.par

a character indicating the weaning parameter used.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnCI, warnProb, plot.warnProb

Examples

## See ?warnProb for examples.

Weaning parameter estimation with approximate Bayesian computation

Description

warn estimates weaning parameters (i.e., weaning ages, enrichment factor, and nitrogen isotope ratio (d15N) of weaning food derived collagen) for a given skeletal population under the flamework of approximate Bayesian computation (ABC).

Usage

## Default S3 method:
warn(age, d15N, female.mean, female.sd = NA,
  fraction = "collagen",
  prior = c(0.5, 3, 3, 3, 1.9, 0.9, female.mean, 3, 0, 1),
  num.particle = 10000, form = "parabolic",
  tolerances = c(2.0, 1.0, 0.5, 0.25, 0.125, 0.0625, 0))

Arguments

age

a vector of estimated ages in year of the non-adult skeletons. Ages greater than 10 years are not allowed.

d15N

a vector of bone collagen d15N of non-adult skeletons. Other geochemical values (e.g., d18O, Sr/Ca, and Ba/Ca) can be used with this argument.

female.mean

the mean d15N of the adult females, single value.

female.sd

the one standard deviation of adult female d15Ns, an optional single value. Utilized later in plot.warn.

fraction

fraction of bone analyzed. The allowed values are collagen and mineral. The turnover rate specific to each fraction will be used.

prior

a vector of hyper parameter values for prior distributions of the weaning parameters and the individual error term. Mean and SD for t1 (age at the start of weaning), t2 (age at the end of weaning), enrichment of d15N, d15N of weaning food derived collagen, and sigma used in ABC-SMC, in sequence. The values are succeeded to mean and sd arguments of rnorm. The default is c(0.5, 3, 3, 3, 1.9, 0.9, female.mean, 3, 0, 1).

num.particle

number of particles in sequential Monte Carlo (SMC) sampling; defaults to 10000.

form

form of the model curve for the weaning process. The allowed values are "linear", "parabolic" (the default), "reverse", and "sigmoid".

tolerances

a vector of decreasing torelances used in the SMC sampling. The default is c(2.0, 1.0, 0.5, 0.25, 0.125, 0.0625, 0).

Details

The warn esimates the age at the start and end of weaning, enrichment of d15N through maternal to infant tissue, and d15N value of collagen synthesized entirely from weaning foods with their posterior probabilities. Other geochemical values that change with breastfeeding and weaning can also be analyzed (e.g., d18O, Sr/Ca, and Ba/Ca). Probabilities are estimated by SMC with partial rejection control, and the algorithm was derived from Sisson et al. (2007, 2009). The posterior probabilities are obtained as a result of kernel density estimation, a product of kde2d in MASS package for weaning ages, and density for enrichment and weaning foods. The model used to describe the change in d15N during weaning contains a new estimate of bone collagen turnover rates in non-adults, and is shown in Tsutaya and Yoneda (2013).

Value

warn returns an object of class "warn".
The function summary and plot are used to obtain and indicate a summary and figure of the results, respectively.
An object of class "warn" is a list containing at least the following components:

mde

the maximum density estimators and their marginal probabilities for the weaning parameters.

prob.2d.age

the joint probability for combination of the maximum density weaning ages.

dist.mde

the mean squared distance between the measured and modeled d15Ns of non-adults.

kde.age

two-dimensional kernel density estimates of the weaning ages. A product of kde2d in MASS package.

kde.enrich

kernel density estimates of the enrichment factor from mother to infant. A product of density.

kde.wnfood

kernel density estimates of the d15N of collagen synthesized entirely form weaning foods. A product of density.

posterior

a matrix of final particles in SMC sampling.

age

the non-adult ages used.

d15N

the measuerd d15Ns of non-adult bone collagen used.

female.mean

the mean d15N of adult females used.

female.sd

the one standard deviation of adult female d15Ns used.

fraction

the fraction of bone analyzed.

prior

a vector of the hyper parameter values for the prior distributions used.

particle

the number of particles used.

form

the form of the model curve used.

call

the matched call.


The band-width of kernel density estimation (i.e., h in kde2d and bw in density) is selected by SJ method, width.SJ in MASS, with "direct plug-in".

Author(s)

Takumi Tsutaya developed this model.

References

Sisson, S. A., Fan, Y., and Tanaka, M. M. (2007, 2009). Sequential Monte Carlo without likelihoods. Proc. Natl. Acad. Sci. 104, 1760–1765.

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warnCI, warnProb, summary.warn, plot.warn

Examples

## Data from the Lerna population.
nonadult <- subset(lerna, lerna$age <= 10)
adult <- subset(lerna, lerna$age > 17)
female <- subset(adult, adult$sex == "f")

## Calculate maximum density estimators using ABC.
warn.lerna <- warn(
  age = nonadult$age,
  d15N = nonadult$d15N,
  female.mean = mean(female$d15N),
  num.particle = 500,
  female.sd = sd(female$d15N),
  prior = c(0.2, 0.2, 1.6, 0.2, 2.5, 0.2, 8.1, 0.2, 0, 0.7),
  tolerances = c(1.5, 0.7))

## Indicate summary.
summary(warn.lerna)

## Plot.
plot(warn.lerna)

## Plot with adult mean.
plot(warn.lerna,
  hline.adult = TRUE,
  adult.mean = mean(adult$d15N),
  adult.sd = sd(adult$d15N),
  is.female = FALSE)

Calculate credible intervals for posterior probability of the weaning parameters

Description

warnCI calculate credible intervals (CIs) of posterior probabilities under a given class "warn" object and a given threshold of CIs.

Usage

## Default S3 method:
warnCI(object, threshold = 0.95)

Arguments

object

an object of class "warn".

threshold

numeric scalar or vector giving the threshold of CI for posterior probabilities of weaning ages, nitrogen isotope ratios (d15Ns) of enrichment factor, and d15Ns of collagen derived entirely from weaning foods. Minimum range with over (threshold * 100)% of summed posterior probability is calculated. If scalar is given, value is repeated. Values between 0 and 1 must be given.

Details

warnCI calculates minimum ranges with over (threshold * 100)% of summed posterior probability of the weaning parameters. Posterior probabilities are represented as the product of kernel density estimation performed in warn. CIs of weaning ages are obtained from two-dimensional probability distribution, and those of d15Ns of enrichment factor and collagen derived entirely from weaning foods are from one-dimensional. Posterior probability distributions with multiple notable peaks are not supported by warnCI.

Value

warnCI returns an object of class "warnCI" which is a subclass of "warn".
The function plot is used to indicate figures of the results.
An object of class "warnCI" has following list components in addition to those succeeded from "warn":

ci.age

a list containing the CIs for the combination of t1 and t2, and its summed posterior probability.

ci.enrich

a list containing the CI for the d15N-enrichment from mother to infant, and its summed posterior probability.

ci.wnfood

a list containing the CI for the d15N value of collagen derived entirelly from weaning foods, and its summed posterior probability.

ci.threshold

a vector showing the thresholds used to calculate the CIs.

Author(s)

Takumi Tsutaya developed this model.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnProb, plot.warnCI

Examples

## Data from the Lerna population.
nonadult <- subset(lerna, lerna$age <= 10)
adult <- subset(lerna, lerna$age > 17)
female <- subset(adult, adult$sex == "f")

## Calculate maximum density estimators using ABC.
warn.lerna <- warn(
  age = nonadult$age,
  d15N = nonadult$d15N,
  female.mean = mean(female$d15N),
  num.particle = 500,
  female.sd = sd(female$d15N),
  prior = c(0.2, 0.2, 1.6, 0.2, 2.5, 0.2, 8.1, 0.2, 0, 0.7),
  tolerances = c(1.5, 0.7))

## Calculate over (>=) 50% CIs.
warn.lerna.50ci <- warnCI(warn.lerna, 0.50)

## Indicate result.
warn.lerna.50ci

## Plot.
plot(warn.lerna.50ci, "age")
plot(warn.lerna.50ci, "enrich")

Optimize the weaning parameters

Description

warnOptim optimzes the weaning parameters for a given skeletal population. This function can be preliminaly used in order to set efficient priors of the weaning parameters.

Usage

## Default S3 method:
warnOptim(age, d15N, female.mean,
  fraction = "collagen",
  par.initial = c(0.5, 3, 1.9, female.mean), 
  form = "parabolic", ...)

Arguments

age

a vector of estimated ages of non-adult skeletons. Ages greater than 10 years are not allowed.

d15N

a vector of bone collagen nitrogen isotope ratio (d15N) of non-adult skeletons. Other geochemical values (e.g., d18O, Sr/Ca, and Ba/Ca) can be used with this argument.

fraction

fraction of bone analyzed. The allowed values are collagen and mineral.

par.initial

a vector of the initial parameter values for optimizetion: t1, t2, enrichment, and weaning food, in sequence. The values are succeeded to the par arguments of optim.

female.mean

the mean d15N (or other geochemical value) of adult females, single value.

form

form of the model curve for the weaning process. The allowed values are "linear", "parabolic" (the default), "reverse", and "sigmoid".

...

additional argunemts passed to optim.

Details

The warnOptim calculates the weaning parameters (i.e., weaning ages, enrichment factor, and d15N of bone collagen synthesized entirely from the weaning foods), which minimize the mean squared distance between the measured and modeled d15Ns using optim. Result of this function is just a rough indication and initial parameter dependent, and can be preliminaly used in order to set efficient priors of the weaning parameters.

Value

warnOptim directly returns a result list of optim.

See Also

WARN, warn, warnCI, warnProb

Examples

## Data from the Lerna population.
nonadult <- subset(lerna, lerna$age <= 10)
adult <- subset(lerna, lerna$age > 17)
female <- subset(adult, adult$sex == "f")

## Simple optimization without probability.
(opt.lerna <- warnOptim(
  age = nonadult$age,
  d15N = nonadult$d15N,
  female.mean = mean(female$d15N),
  control = list(maxit = 10000, ndeps = 1e-2, reltol = 1e-7)))

Calculate posterior probability of the weaning parameters

Description

warnProb calculate posterior probabilities under a given class "warn" object and a given parameter range.

Usage

## Default S3 method:
warnProb(object, weaning.par = "age", range.x, range.y = NA)

Arguments

object

an object of class "warn".

weaning.par

character for the intended weanig parameter. The allowed values are "age" (the default), "enrich", and "wnfood".

range.x, range.y

numeric vectors of length 2, giving the range of the intended weanig parameters. For example, range.x corresponds to the age at the start of weaning if weaning.par = "age". range.y is used only if weaning.par = "age", and corresponds to the age at the end of weaning. Fractional point lower than e-002 is rounded.

Details

warnProb calculates posterior probability of the weaning parameter that ranges between designated range. Parameter distribution is represented as the product of kernel density estimation performed in warn. Weaning ages are estimated from two-dimensional probability distribution, and nitrogen isotope ratios (d15Ns) of enrichment factor and weaning food derived collagen are from one-dimensional.

Value

warnProb returns an object of class "warnProb" which is a subclass of "warn".
The functions summary and plot are used to obtain and indicate a summary and figure of the results, respectively.
An object of class "warnProb" at least has following list components in addition to those succeeded from "warn":

probability

posterior probability of parameter that range between the designated range.

range

a vector giving the range of the intended weanig parameter.

weaning.par

a character indicating the weaning parameter used.

Author(s)

Takumi Tsutaya developed this model.

References

Tsutaya, T., and Yoneda, M. (2013). Quantitative reconstruction of weaning ages in archaeological human populations using bone collagen nitrogen isotope ratios and approximate Bayesian computation. PLoS ONE 8, e72327.

See Also

WARN, warn, warnCI, summary.warnProb, plot.warnProb

Examples

## Data from the Lerna population.
nonadult <- subset(lerna, lerna$age <= 10)
adult <- subset(lerna, lerna$age > 17)
female <- subset(adult, adult$sex == "f")

## Calculate maximum density estimators using ABC.
warn.lerna <- warn(
  age = nonadult$age,
  d15N = nonadult$d15N,
  female.mean = mean(female$d15N),
  num.particle = 500,
  female.sd = sd(female$d15N),
  prior = c(0.2, 0.2, 1.6, 0.2, 2.5, 0.2, 8.1, 0.2, 0, 0.7),
  tolerances = c(1.5, 0.7))

## Calculate probabilities for a given parameter range.
warnprob.age <- warnProb(warn.lerna, "age", c(0.0, 1.1), c(0.8, 2.3))
warnprob.enrich <- warnProb(warn.lerna, "enrich", c(1.5, 3.5))
warnprob.wnfood <- warnProb(warn.lerna, "wnfood", c(7.3, 8.8))

## Indicate summary.
summary(warnprob.age)
summary(warnprob.enrich)

## Plot.
plot(warnprob.age)
plot(warnprob.wnfood)

## Plot with image.
plot(warnprob.age, is.image = TRUE)