surv.func: General survival analysis
In zooaRch: Analytical Tools for Zooarchaeological Data

Description Usage Arguments Details Value Author(s) References Examples

A general function to perform survival analysis of zooarchaeological data

1 2	surv.func(SurviveData, labels = NULL, models = NULL, ci = 95, plot = TRUE, iter = 1000, usermod = NULL)

`SurviveData`	This function inputs datasets composed of three columns. The first column denotes the genus; the second is the age class (this MUST be numeric) if data contains nominal age classes (e.g., 'A', 'B', 'C', etc.) these data must be converted to numbers (e.g., A = 1, B = 2, etc.).
`labels`	Character value indicating wether age class labels wishing to be displayed.
`models`	A numerical value (1-5) indiacting the models to compare the data to. Currently surv.func makes use of 5 survival models: 1) Security (ref); 2) Milk (ref); 3) Wool (ref); 4) Catastrophic (Stiner 1990); and 5) Attritional (Stiner 1990). More models will be added soon. An option to include user's own model will also be available.
`ci`	Numerical value indicating desired CI level (e.g., 90, 95, 99). Defaults to 95.
`plot`	A logical value indicating wether user wishes an output plot. Default = TRUE.
`iter`	A numeric value indicating the number of bootstrap iterations. Defaults to 1000.
`usermod`	numeric list (see help(list)) user-specified survivorship model. See example 3 below. Data must be entered as a list, else user will receive error.

The function constructs Kaplan-Meier Estimator (KME) Confidence Intervals Using Dental Eruption Wear Data

Function returns a matrix with the following components

`Lower and Upper CI`	typically the 97.5 and 2.5 percentile markers
`Point Value`	the y value on the survivorship curve

Jesse WolfHagen and Erik Otarola-Castillo.

Klein, R.G., Cruz-Uribe, K., 1983. The Analysis of Animal Bones from Archaeological Sites, University of Chicago Press, Chicago.

Stiner, M. C. 1990 The Use of Mortality Patterns in Archaeological Studies of Homonid Predatory Adaptations. Journal of Anthropological Archaeology 9:305 - 351.

Lyman, R.L., 1994. Vertebrate Taphonomy, Cambridge University Press, Cambridge.

Zeder, M.A., 2006. Reconciling Rates of Long Bone Fusion and Tooth Eruption in Sheep (Ovis) and Goat (Capra), in: Ruscillo, D. (Ed.), Recent Advances in Ageing and Sexing Animal Bones, Oxbow Books, Oxford.

Twiss, K.C., 2008. An Assessment of the Archaeological Applicability of Faunal Ageing Methods Based on Dental Wear, International Journal of Osteoarchaeology 18, 329-351.

# Example 1: Payne 1973
 data(marjRab)

# Inspect data structure  
 head(marjRab)
 
# create age-class labels: Payne 1973 uses ageclasses A-I
 Labels <-c('A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I')
 surv.func(SurviveData=marjRab,labels=Labels, models=1:3, ci=95, plot=TRUE, iter=1000)
 
# Example 2: Garnsey Site Bison Data (from Speth 1983)
 data(speth83)

# Inspect data structure  
 head(speth83)

# create age-class labels using the 13 age classes of Speth's (1983) scheme.
 Labels <-c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13)

# Use the catastrophic and attritional mortality curves (after Stiner 1990).
 surv.func(SurviveData=speth83,labels=Labels, models=4:5, ci=95, plot=TRUE, iter=1000)
 
# Example 3: marjRab, input user-defined survivorship models.
data(marjRab)
# extract age classes from marjRab
age<-unique(marjRab$Ageclass)
age
# model survivorship using an exponential decay function 
# with parameter b: survivorship = age^(-1/b)
# surv 1: b= .95 
surv1<-c(1.00, 0.48, 0.31, 0.23, 0.18, 0.15, 0.12, 0.11, 0.09)
# surv 2: b= .35
surv2<-c(1.00, 0.13, 0.04, 0.01, 0.01, 0.005, 0.003, 0.002, 0.001)

plot(age, surv1,type='l',xlim=range(age),ylim=c(0,1))
lines(age, surv2,col='red',)

# usermods in surv.func must be a list (if not a list, then user will receive error message)
mods<-list(surv1=surv1,surv2=surv2)

surv.func(marjRab,models=NULL,usermod=mods)

Loading required package: ggplot2
       Genus Ageclass
1 Ovis/Capra        1
2 Ovis/Capra        2
3 Ovis/Capra        3
4 Ovis/Capra        3
5 Ovis/Capra        3
6 Ovis/Capra        3
       Taxon AgeClassLabs  LowerCI PointValue  UpperCI
1 Ovis/Capra            A 0.928600     0.9762 1.000000
2 Ovis/Capra            B 0.881000     0.9524 1.000000
3 Ovis/Capra            C 0.571400     0.7143 0.833895
4 Ovis/Capra            D 0.404205     0.5476 0.714300
5 Ovis/Capra            E 0.261900     0.4048 0.547600
6 Ovis/Capra            F 0.142900     0.2619 0.404800
7 Ovis/Capra            G 0.023800     0.1190 0.214300
8 Ovis/Capra            H 0.000000     0.0476 0.119000
9 Ovis/Capra            I 0.000000     0.0000 0.000000
  Genus Ageclass
1 Bison        1
2 Bison        1
3 Bison        2
4 Bison        3
5 Bison        3
6 Bison        3
   Taxon AgeClassLabs LowerCI PointValue UpperCI
1  Bison            1  0.8333     0.9333  1.0000
2  Bison            2  0.7667     0.9000  1.0000
3  Bison            3  0.6333     0.7667  0.9000
4  Bison            4  0.4667     0.6333  0.8000
5  Bison            5  0.4333     0.6000  0.7667
6  Bison            6  0.3667     0.5333  0.7000
7  Bison            7  0.2667     0.4333  0.6000
8  Bison            8  0.1333     0.3000  0.4667
9  Bison            9  0.1000     0.2333  0.4000
10 Bison           10  0.0667     0.1667  0.3333
11 Bison           11  0.0000     0.1000  0.2333
12 Bison           12  0.0000     0.0333  0.1000
13 Bison           13  0.0000     0.0000  0.0000
[1] 1 2 3 4 5 6 7 8 9
       Taxon AgeClassLabs LowerCI PointValue UpperCI
1 Ovis/Capra            1  0.9286     0.9762  1.0000
2 Ovis/Capra            2  0.8810     0.9524  1.0000
3 Ovis/Capra            3  0.5714     0.7143  0.8571
4 Ovis/Capra            4  0.4048     0.5476  0.7143
5 Ovis/Capra            5  0.2619     0.4048  0.5476
6 Ovis/Capra            6  0.1429     0.2619  0.3810
7 Ovis/Capra            7  0.0238     0.1190  0.2143
8 Ovis/Capra            8  0.0000     0.0476  0.1190
9 Ovis/Capra            9  0.0000     0.0000  0.0000