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 |
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.
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).
Takumi Tsutaya <[email protected]>
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.
warn
, warnCI
, warnOptim
, warnProb
## See ?warn, ?warnCI, and ?warnProb for examples.
## See ?warn, ?warnCI, and ?warnProb for examples.
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).
lerna
lerna
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.
See detail for Triantaphyllou et al. (2008).
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.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.
## 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, ...)
## 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, ...)
x |
an object of class |
hline.female , hline.adult
|
logical; if |
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 |
is.legend |
logical; if |
is.female |
logical; if |
plot |
logical; if |
... |
additional arguments passed to |
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.
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.
WARN
, warn
, warnCI
, warnProb
, summary.warn
## See ?warn for examples.
## See ?warn for examples.
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.
## S3 method for class 'warnCI' plot(x, weaning.par = "age", ...)
## S3 method for class 'warnCI' plot(x, weaning.par = "age", ...)
x |
an object of class |
weaning.par |
character for the intended weanig parameter. The allowed values are |
... |
additional arguments passed to |
Values on the contour lines indicate relative probabilities based on that of the maximum density estimator.
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.
WARN
, warn
, warnCI
, warnProb
, plot.warnProb
## See ?warnCI for examples.
## See ?warnCI for examples.
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.
## S3 method for class 'warnProb' plot(x, is.legend = TRUE, is.contour = TRUE, is.image = FALSE, is.prior = FALSE, ...)
## S3 method for class 'warnProb' plot(x, is.legend = TRUE, is.contour = TRUE, is.image = FALSE, is.prior = FALSE, ...)
x |
an object of class |
is.legend |
logical; if |
is.contour |
logical; if |
is.image |
logical; if |
is.prior |
logical; if |
... |
additional arguments passed to |
Values on the contour lines indicate relative probabilities based on that of the maximum density estimator.
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.
WARN
, warn
, warnCI
, warnProb
, summary.warnProb
## See ?warnProb for examples.
## See ?warnProb for examples.
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.
## S3 method for class 'warn' summary(object, ...)
## S3 method for class 'warn' summary(object, ...)
object |
an object of class |
... |
additional arguments affecting the summary produced. |
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. |
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.
WARN
, warn
, warnCI
, warnProb
, plot.warn
## See ?warn for examples.
## See ?warn for examples.
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.
## S3 method for class 'warnProb' summary(object, ...)
## S3 method for class 'warnProb' summary(object, ...)
object |
an object of class |
... |
additional arguments affecting the summary produced. |
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. |
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.
WARN
, warn
, warnCI
, warnProb
, plot.warnProb
## See ?warnProb for examples.
## See ?warnProb for examples.
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).
## 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))
## 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))
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 |
fraction |
fraction of bone analyzed. The allowed values are |
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 |
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 |
tolerances |
a vector of decreasing torelances used in the SMC sampling. The default is |
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).
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 |
kde.enrich |
kernel density estimates of the enrichment factor from mother to infant. A product of |
kde.wnfood |
kernel density estimates of the d15N of collagen synthesized entirely form weaning foods. A product of |
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".
Takumi Tsutaya developed this model.
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.
WARN
, warnCI
, warnProb
, summary.warn
, plot.warn
## 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)
## 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)
warnCI
calculate credible intervals (CIs) of posterior probabilities under a given class "warn"
object and a given threshold of CIs.
## Default S3 method: warnCI(object, threshold = 0.95)
## Default S3 method: warnCI(object, threshold = 0.95)
object |
an object of class |
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 ( |
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
.
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. |
Takumi Tsutaya developed this model.
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.
WARN
, warn
, warnProb
, plot.warnCI
## 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")
## 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")
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.
## Default S3 method: warnOptim(age, d15N, female.mean, fraction = "collagen", par.initial = c(0.5, 3, 1.9, female.mean), form = "parabolic", ...)
## Default S3 method: warnOptim(age, d15N, female.mean, fraction = "collagen", par.initial = c(0.5, 3, 1.9, female.mean), form = "parabolic", ...)
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 |
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 |
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 |
... |
additional argunemts passed to |
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.
warnOptim
directly returns a result list of optim
.
## 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)))
## 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)))
warnProb
calculate posterior probabilities under a given class "warn"
object and a given parameter range.
## Default S3 method: warnProb(object, weaning.par = "age", range.x, range.y = NA)
## Default S3 method: warnProb(object, weaning.par = "age", range.x, range.y = NA)
object |
an object of class |
weaning.par |
character for the intended weanig parameter. The allowed values are |
range.x , range.y
|
numeric vectors of length 2, giving the range of the intended weanig parameters. For example, |
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.
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. |
Takumi Tsutaya developed this model.
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.
WARN
, warn
, warnCI
, summary.warnProb
, plot.warnProb
## 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)
## 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)