From dbec5dfa0d8bf9029546030ae6a4f1383aa8e181 Mon Sep 17 00:00:00 2001 From: "Enrico R. Crema" Date: Wed, 19 Sep 2018 06:51:03 +0100 Subject: [PATCH] Updated documentation --- DESCRIPTION | 2 +- R/src.R | 15 ++++++++------- man/heteroPopTransmission.Rd | 6 +++--- man/transmission.Rd | 10 +++++----- 4 files changed, 17 insertions(+), 16 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 7cde6fb..b19d240 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -11,4 +11,4 @@ License: GPL (>= 2) Encoding: UTF-8 LazyData: true VignetteBuilder: knitr -RoxygenNote: 6.0.1 +RoxygenNote: 6.1.0 diff --git a/R/src.R b/R/src.R index 146e37d..f39c158 100644 --- a/R/src.R +++ b/R/src.R @@ -1,19 +1,19 @@ #' @title Simulating Unbiased and Frequency-Biased Cultural Transmission -#' @description Function for simulating unbiased and frequency-biased cultural transmission with and retrieving turn-over rates and diversity. +#' @description Function for simulating unbiased/frequency-biased cultural transmission. #' @param N Number of individuals. #' @param timesteps Number of generations (timesteps). #' @param mu Innovation rate. #' @param wamUp Number of generations executed to reach equilibrium conditions (discarded from analysis) -#' @param top Number indicating the most common variants considered for the turn-over rate analysis (e.g. if top is equal to 5 the turnover rate is computed as the average number of new variants introduced in the top 1, 2, 3, ,4 and 5 ranked variants). -#' @param bias Frequency bias parameter. Either a vector with length equal to the number of timesteps (to allow for a time-varying frequency bias), or single value (for a fixed frequency bias). +#' @param top Number indicating the most common variants considered for the turn-over rate analysis (e.g. if \code{top} is equal to 5 the turnover rate is computed as the average number of new variants introduced in the top 1, 2, 3, ,4 and 5 ranked variants at each timestep). +#' @param bias Frequency bias parameter. Either a vector with length equal to the number of timesteps (to allow for a time-varying frequency bias), or single value (for a fixed bias). #' @param raw Logical variable indicating whether the matrix of variants frequencies are returned or not. Default is FALSE. -#' @details The function simulates unbiased (\code{bias}=0), confomist (\code{bias}<0), and anti-conformist (\code{bias}>0) cultural transmission with a user defined population size and mutation rates, returning Simpson's diversity index of variants frequency, observed and expected turnover rates, and estimates of the exponent $b$ following the procedure described in Acerbi and Bentley 2014. Frequency bias is modelled using the following formula: +#' @details The function simulates unbiased (\code{bias}=0), confomist (\code{bias}<0), and anti-conformist (\code{bias}>0) cultural transmission with a user-defined population size and mutation rates, returning Simpson's diversity index of variants frequency, observed and expected turnover rates, and estimates of the exponent \eqn{x} following the procedure described in Acerbi and Bentley 2014 (notice that Acerbi and Bentley refer to this exponent as \eqn{b}). Frequency bias is modelled using the following formula: #' \deqn{\pi_i=\frac{\left(\frac{m_i}{N}\right)^{1-\beta}}{\sum\limits_{j=1}^k \left(\frac{m_j}{N}\right)^{1-\beta}}(1-\mu)} #' with \eqn{pi_i} equal to the probability of copying the variant \eqn{i}, \eqn{m_i} to the number of individuals possessing the variant \eqn{i}, \eqn{N} to the population size, \eqn{mu} to the mutation rate, and \eqn{\beta} to the frequency bias parameter (i.e. \code{bias}). -#' @return A list containing: 1) a matrix of variants frequencies, with rows equal to generations and columns to specific variants (\code{rawMatrix}, available on when the argument \code{raw} is set to \code{TRUE}.; 2) a data.frame with the observed turnover rates (column: \code{obs.z}), the expected rates according to Bentley et al 2007 (column: \code{exp.z.Bentley}) and Evans and Giometto 2012 (column: \code{exp.z.EvansGiometto}); 3) the fitted value for the parameter \code{b}; 4) a vector with a time-series of observed Simpson's diversity index (\code{obs.div}); and 5) the expected Simpson's diversity under neutrality, equal to \eqn{ 1 - (1/(2*N*\mu + 1))} (\code{exp.div}). +#' @return A list containing: 1) a matrix of variants frequencies, with rows equal to generations and columns to specific variants (\code{rawMatrix}, available on when the argument \code{raw} is set to \code{TRUE}.; 2) a data.frame with the observed turnover rates (column: \code{obs.z}), the expected rates according to Bentley et al 2007 (column: \code{exp.z.Bentley}) and Evans and Giometto 2012 (column: \code{exp.z.EvansGiometto}); 3) the fitted value for the parameter \code{x}; 4) a vector with a time-series of observed Simpson's diversity index (\code{obs.div}); and 5) the expected Simpson's diversity under neutrality, equal to \eqn{ 1 - (1/(2*N*\mu + 1))} (\code{exp.div}). #' @references #' Acerbi, A., Bentley, A.R., 2014. Biases in cultural transmission shape the turnover of populat traits. \emph{Evolution and Human Behavior}, 35, 228–236.\cr @@ -89,7 +89,7 @@ transmission<-function(N=500,timesteps=501,mu=0.01,warmUp=300,top=NA,bias=0,raw= return(list(rawMatrix=rawMatrix, z.frame = z.frame[,1:4], - b = b, + x = b, obs.div = obs.div, exp.div = exp.div)) } @@ -139,7 +139,7 @@ return(((hi-lo)/(max(x)-min(x)))*(x-max(x))+hi) #' @title Simulating Frequency-Biased Cultural Transmission with an Heterogenous Population. -#' @description Simulates biased and frequency-biased transmission with the frequency bias parameter of each individual randomly drawn from a normal distribution with user defined mean and standard deviation. +#' @description Simulates unbiased/frequency-biased transmission with the bias parameter of each individual randomly drawn from a normal distribution with user-defined mean and standard deviation. #' @param N Number of individuals. #' @param timesteps Number of generations (timesteps). #' @param mu Innovation rate. @@ -150,6 +150,7 @@ return(((hi-lo)/(max(x)-min(x)))*(x-max(x))+hi) #' \deqn{\pi_i=\frac{\left(\frac{m_i}{N}\right)^{1-\beta_x}}{\sum\limits_{j=1}^k \left(\frac{m_j}{N}\right)^{1-\beta_x}}(1-\mu)} #' where \eqn{\beta_x} is randomly drawn from a normal distribution with mean \code{bmean} and standard deviation \code{bsd}. +#' #' @return A vector containing the Simpson's diversity index at each timestep/generation. #' #' @import stats diff --git a/man/heteroPopTransmission.Rd b/man/heteroPopTransmission.Rd index f7d1f61..92f67d8 100644 --- a/man/heteroPopTransmission.Rd +++ b/man/heteroPopTransmission.Rd @@ -4,8 +4,8 @@ \alias{heteroPopTransmission} \title{Simulating Frequency-Biased Cultural Transmission with an Heterogenous Population.} \usage{ -heteroPopTransmission(N = 500, timesteps = 301, mu = 0.01, bmean = 0, - bsd = 0) +heteroPopTransmission(N = 500, timesteps = 301, mu = 0.01, + bmean = 0, bsd = 0) } \arguments{ \item{N}{Number of individuals.} @@ -22,7 +22,7 @@ heteroPopTransmission(N = 500, timesteps = 301, mu = 0.01, bmean = 0, A vector containing the Simpson's diversity index at each timestep/generation. } \description{ -Simulates biased and frequency-biased transmission with the frequency bias parameter of each individual randomly drawn from a normal distribution with user defined mean and standard deviation. +Simulates unbiased/frequency-biased transmission with the bias parameter of each individual randomly drawn from a normal distribution with user-defined mean and standard deviation. } \details{ The function simulates cultural transmission within a population of heterogenous learners, each with a different levels of frequency bias at each generation. More formally the probability of an individual $x$ copying a variant $i$ is given by the following equation. diff --git a/man/transmission.Rd b/man/transmission.Rd index 44b40bf..d93f19b 100644 --- a/man/transmission.Rd +++ b/man/transmission.Rd @@ -14,22 +14,22 @@ transmission(N = 500, timesteps = 501, mu = 0.01, warmUp = 300, \item{mu}{Innovation rate.} -\item{top}{Number indicating the most common variants considered for the turn-over rate analysis (e.g. if top is equal to 5 the turnover rate is computed as the average number of new variants introduced in the top 1, 2, 3, ,4 and 5 ranked variants).} +\item{top}{Number indicating the most common variants considered for the turn-over rate analysis (e.g. if \code{top} is equal to 5 the turnover rate is computed as the average number of new variants introduced in the top 1, 2, 3, ,4 and 5 ranked variants at each timestep).} -\item{bias}{Frequency bias parameter. Either a vector with length equal to the number of timesteps (to allow for a time-varying frequency bias), or single value (for a fixed frequency bias).} +\item{bias}{Frequency bias parameter. Either a vector with length equal to the number of timesteps (to allow for a time-varying frequency bias), or single value (for a fixed bias).} \item{raw}{Logical variable indicating whether the matrix of variants frequencies are returned or not. Default is FALSE.} \item{wamUp}{Number of generations executed to reach equilibrium conditions (discarded from analysis)} } \value{ -A list containing: 1) a matrix of variants frequencies, with rows equal to generations and columns to specific variants (\code{rawMatrix}, available on when the argument \code{raw} is set to \code{TRUE}.; 2) a data.frame with the observed turnover rates (column: \code{obs.z}), the expected rates according to Bentley et al 2007 (column: \code{exp.z.Bentley}) and Evans and Giometto 2012 (column: \code{exp.z.EvansGiometto}); 3) the fitted value for the parameter \code{b}; 4) a vector with a time-series of observed Simpson's diversity index (\code{obs.div}); and 5) the expected Simpson's diversity under neutrality, equal to \eqn{ 1 - (1/(2*N*\mu + 1))} (\code{exp.div}). +A list containing: 1) a matrix of variants frequencies, with rows equal to generations and columns to specific variants (\code{rawMatrix}, available on when the argument \code{raw} is set to \code{TRUE}.; 2) a data.frame with the observed turnover rates (column: \code{obs.z}), the expected rates according to Bentley et al 2007 (column: \code{exp.z.Bentley}) and Evans and Giometto 2012 (column: \code{exp.z.EvansGiometto}); 3) the fitted value for the parameter \code{x}; 4) a vector with a time-series of observed Simpson's diversity index (\code{obs.div}); and 5) the expected Simpson's diversity under neutrality, equal to \eqn{ 1 - (1/(2*N*\mu + 1))} (\code{exp.div}). } \description{ -Function for simulating unbiased and frequency-biased cultural transmission with and retrieving turn-over rates and diversity. +Function for simulating unbiased/frequency-biased cultural transmission. } \details{ -The function simulates unbiased (\code{bias}=0), confomist (\code{bias}<0), and anti-conformist (\code{bias}>0) cultural transmission with a user defined population size and mutation rates, returning Simpson's diversity index of variants frequency, observed and expected turnover rates, and estimates of the exponent $b$ following the procedure described in Acerbi and Bentley 2014. Frequency bias is modelled using the following formula: +The function simulates unbiased (\code{bias}=0), confomist (\code{bias}<0), and anti-conformist (\code{bias}>0) cultural transmission with a user-defined population size and mutation rates, returning Simpson's diversity index of variants frequency, observed and expected turnover rates, and estimates of the exponent \eqn{x} following the procedure described in Acerbi and Bentley 2014 (notice that Acerbi and Bentley refer to this exponent as \eqn{b}). Frequency bias is modelled using the following formula: \deqn{\pi_i=\frac{\left(\frac{m_i}{N}\right)^{1-\beta}}{\sum\limits_{j=1}^k \left(\frac{m_j}{N}\right)^{1-\beta}}(1-\mu)} with \eqn{pi_i} equal to the probability of copying the variant \eqn{i}, \eqn{m_i} to the number of individuals possessing the variant \eqn{i}, \eqn{N} to the population size, \eqn{mu} to the mutation rate, and \eqn{\beta} to the frequency bias parameter (i.e. \code{bias}). }