Adjusted vignettes.

DESCRIPTION

@@ -3,16 +3,18 @@ Type: Package
 Title: Analysis of Archaeological Mortality Data
 Version: 1.1.7
 Authors@R: c(
-  person("Nils", "Mueller-Scheessel", email = "[email protected]", role = c("aut", "cre", "cph")), 
-  person("Martin", "Hinz", email = "[email protected]", role = c("aut")),
-  person("Clemens", "Schmid", email = "[email protected]", role = c("aut")),
-  person("Christoph", "Rinne", email = "[email protected]", role = c("aut")), 
-  person("Daniel", "Knitter", email = "[email protected]", role = c("aut")),
-  person("Wolfgang", "Hamer", email = "[email protected]", role = c("aut")),
-  person("Dirk", "Seidensticker", email = "[email protected]", role = c("aut")),
-  person("Franziska", "Faupel", email = "[email protected]", role = c("aut")),
-  person("Carolin", "Tietze", email = "[email protected]", role = c("aut")),
-  person("Nicole", "Grunert", email = "[email protected]", role = c("aut")))
+    person("Nils", "Mueller-Scheessel", , "[email protected]", role = c("aut", "cre", "cph"),
+           comment = c(ORCID = "0000-0001-7992-8722")),
+    person("Martin", "Hinz", , "[email protected]", role = "aut"),
+    person("Clemens", "Schmid", , "[email protected]", role = "aut"),
+    person("Christoph", "Rinne", , "[email protected]", role = "aut"),
+    person("Daniel", "Knitter", , "[email protected]", role = "aut"),
+    person("Wolfgang", "Hamer", , "[email protected]", role = "aut"),
+    person("Dirk", "Seidensticker", , "[email protected]", role = "aut"),
+    person("Franziska", "Faupel", , "[email protected]", role = "aut"),
+    person("Carolin", "Tietze", , "[email protected]", role = "aut"),
+    person("Nicole", "Grunert", , "[email protected]", role = "aut")
+  )
 Maintainer: Nils Mueller-Scheessel <[email protected]>
 Description: A collection of functions for the analysis of archaeological mortality
     data (on the topic see e.g. Chamberlain 2006 

_pkgdown.yml

@@ -1,6 +1,7 @@
 url: https://isaakiel.github.io/mortAAR/
 template:
   bootstrap: 5
+  light-switch: true
 
 reference:
 - title: "Basic functions"

vignettes/mortAAR.Rmd

@@ -0,0 +1,17 @@
+---
+title: "Introduction to mortAAR"
+output: rmarkdown::html_vignette
+bibliography: ../inst/REFERENCES.bib
+vignette: >
+  %\VignetteIndexEntry{Introduction to mortAAR}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Introduction
+
+##Work to do##
+
+---
+
+## References

vignettes/mortAAR_vignette_background.Rmd

@@ -0,0 +1,52 @@
+---
+title: "Background"
+output: rmarkdown::html_vignette
+bibliography: ../inst/REFERENCES.bib
+vignette: >
+  %\VignetteIndexEntry{Background}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Introduction
+
+Life tables have only a marginal position in archaeological research, for different reasons. Columns with rows of multidigit numbers carrying strange labels can be daunting, and indeed the mathematics behind the construction of life tables based on modern census data are not for the faint-of-heart. Compared to life tables based on real census data, archaeological ones are more straightforward, but their interpretation carries its own problems. First and foremost, they pretend to have a degree of exactness which is not supported by the underlying data. This is another reason why life-tables are considered with a certain degree of suspiciousness by archaeologists. And finally, despite the fact that the construction of archaeological life tables can be straightforward, it involves a lot of computation and number-crunching compared to other methods used in the archaeological discourse. To our current knowledge, an easy to use and accessible tool for computing life tables is missing. This is why we sat down and created mortAAR for R. We hope it will be of use for archaeologists world-wide.  
+
+From an outer appearance, life tables from modern census data and archaeological ones, like generated by mortAAR, look very similar. For modern census data, though, there are far more sophisticated measures available. We cannot go into more detail here but refer the reader to the abundant literature on demography and life table construction.
+
+However, perhaps even more important than the different methods of computing, are the differences in input data. Due to infrastructure, modern census data of developed countries can be regarded as fairly complete and comprehensive. This is, of course, not true for archaeological data. Life tables from modern census data are important tools for inferring the prospective development of a given population. This is, of course, not possible for archaeological data sets. Most of the time, we have to assume that we are dealing with a stationary population.
+
+---
+
+## Overview of features
+In our view, mortAAR shines in the following areas:
+
+### Ease and flexibility of the input
+We worked hard to allow the user as many customisations as feasible. First and foremost, the tables can have many different kinds of formatting. A single individual approach is supported as well as already pooled data (e.g., from an already existing life table). In the latter case, the user has to specify a numerical variable which defines the count of each age class.
+
+In most data sets, the date ranges are defined rather loosely, reflecting the belief that one year more or less does not count taking the basic methods of age estimation into account. However, for the construction of life tables it should be obvious that 20--40 is not the same as 20--39.In the former case the individual in question will also contribute to the age class of 40--44 (using 5-year-classes). Therefore, the user should check the methodology the data-set uses carefully - if they did not generate it themselves. To spare the user the possible inconvenience to transform the data to match any given methodology, both possibilities -- labelled „included“ (e.g., 20--39) and „excluded“ (e.g. 20--40) -- are made available.
+
+The custom method of constructing the life table follows the approach used in modern data. It uses 5 year-classes, except for the youngest class. Following Ascadi and Nemeskeri [-@acsadi_history_1970], for Central Europe it has become practice to publish either the full life table or a collapsed form with five year-intervals [@herrmann_prahistorische_1990, 304ff.; @kokkotidis_graberfeld-_1991]. However, in the international demographic discourse [e.g., @keyfitz_world_population_1968], the first 5-year-age group is subdivided into those having died in their first year of life (0) and those having died in the second to fifth year (1--4). Because the differences are highly relevant in many archaeological contexts and the information is also -- contrary to the possibilities in the higher age groups -- anthropologically available, we decided to choose this as default methodology. With that, we hope to enhance the comparability of historic or present-day demographic data with that of archaeological origin. However, if the user has good reasons to do it differently, they are also allowed to define their own age classes. Furthermore, the user is encouraged to define any possible variable as a grouping variable. For an individual cemetery, this will mostly include the sex of the deceased, but it might as well be defined as marking different populations.
+
+### Sophisticated means of computation
+To get discrete age classes from time spans of individuals or groups of individuals, as they are usually provided by anthropological studies, the time span is spread across single years; the individual values for these years are afterwards pooled together to whichever age class the user chose initially. It is tempting to define different kernels for the spreading process (e.g., Gaussian), but in our view this solution would not reflect the anthropological diagnosis correctly: An individual diagnosed of being of adult age in Central European terminology -- that is, 20 to 39 years old -- has the same chances of being in reality, say, 22 or 38. The Gaussian kernel, however, would imply the highest probability of it being 30 years. This is why we decided to follow an equi-divisional approach [called "proportional" by J. L. @boldsen_methods_1988]. Each year of the reported time interval of an individual or a group of individuals is assigned the same value, essentially the same probability of being the true age.  
+
+While the general steps for computing an archaeological life table are straightforward -- leaving idiosyncrasies like the choice of the size of the radix and the exact formulas aside --, that is: all formulas circulating in archaeological textbooks reach the same results (except possible rounding errors), one detail tends to be overlooked. This detail concerns the average number of years lived by an individual that died within a specific age class (here called A(x) following the UN tables, elsewhere specified as „nax“). A(x) is of importance for computing L(x), the overall number of years lived within an age class, ultimately used to calculate life expectancy and the reconstruction of population. In virtually all archaeological text books, A(x) is defined as a/2, essentially splitting the length of the age interval in question in half. As we cannot know the exact date of death, given the current set of age estimation methods, this method seems beneficial for the beginning. The verdict of N. Keyfitz [-@keyfitz_applied_1977, 13] -- „The uniform distribution of deaths […] leads to nax = n/2, but this is not acceptable when the age interval n is as wide as 5 years.“ -- has certainly its validity when dealing with modern census data, but might be disregarded for older individuals, as the empirical value for age classes > 5 years is very close to 2.5, the computed value (empirically, it mostly hovers between 2.45 and 2.65 as older individuals tend to die later than within the middle of their class. This is far more difficult to generalize than for the younger age classes [see below]). Interestingly, this problem is valid even for empiric modern life tables for the first age group (0-1 years) where the age of death is recorded only in years, not in months. It seems that Keyfitz [-@keyfitz_probabilities_1970, 31] was the first to assume a value for nax to overcome this problem. From empirical data, he came to the following values for the youngest age classes: $a_0 = 0.07 + 1.7M_0$, and for ages from 1 to 4 to $_4a_1 = 1.5$. Elsewhere [@keyfitz_applied_1977] he has called this the "separation factor". Contrary to intuition, this separation factor for the youngest age groups is relatively small in developed countries (e.g., ibid. p. 15), but large in developing countries or historical data (and, supposedly, also in prehistoric times). This means that if young children die at all in developed countries, they do this very young. In life tables of developing countries, the average of lived years for a=0 and a=1--4 hovers around 0.3 and 1.3, thus, we decided to approximate A(x) for age classes <5 with a/3, as we think that taking the separation factor into account is well backed by empirical data [also implied by @chamberlain_demography_2006, 30; for anthropological data already: @weiss_demography_1973, 37]. The computation with this factor is the default setting. However, if the user does not agree, she is, of course, able to supply her own factor values or to disregard the factor approach altogether.
+
+### Comprehensiveness of output
+mortAAR provides life tables for every group the user specified and on its own one table for all groups combined. Furthermore, it allows to visualize the resulting data sets via curve plots. The user can simply click through the plots for the different key values and thereby get a clear picture about the specificities of each data set, also -- if more than one category was specified -- about the differences between the data sets.  
+
+Finally, we added the reconstruction of age distribution of the given population as an additional column (rel_popx). This is usually not provided by modern standard life tables. Following Kokkotidis and Richter [-@kokkotidis_graberfeld-_1991, 227], this is achieved by dividing L(x) by T0 [for a different equation see @weiss_demography_1973, 38].
+
+### Many further functions
+mortAAR also provides tools to test life tables for their representativeness and to correct them if necessary. Furthermore, the package offers the computation of indices that provide information about different aspects of the reproduction of the population in question. 
+
+## Conclusion
+
+Currently, paleodemography seems to undergo a sea change. While the early criticism from the early 1980s about the representation of aging characteristics [@bocquet-appel_masset_farewell_1982] had been fervidly been rebutted [e.g., @van_gerven_armelagos_rumors_1983], the problems of getting to mortality patterns is now common knowledge. Some recent solutions by paleodemographers have been to remodel life tables, to introduce complex statistic measurements like Bayesian statistics or to revert the logic of aging skeletons [see the examples in @hoppa_vaupel_paleodemography_2002].  
+
+Our own attempt on life tables is (still) a far cry from the recent course of research. The reason why we still think this method is valid is simple: While we do not dismiss the problems of life tables with their assumption of stationary populations, we still think that even in their simple form they provide useful information, not necessarily for the paleodemographist, but for the archaeologist. What tends to be forgotten is that the treatment of the deceased is always a conscious decision of the surviving members of the society in question. Even the non-treatment of the dead, e.g., by excarnation, still demands a decision. Therefore, even if the age-pattern is as distorted as in the examples above -- and it remains the question if such a situation should not be regarded as the norm for much of prehistory --, it still provides highly relevant information about cultural behaviour and preferences. To elucidate even more hints on prehistoric practices it is of primordial importance that archaeologists, anthropologists and paleodemographers work closer together than they have in the past to get to grips with actual population developments, representation of burial data and possible sources of bias. If our package helps in this process, we would be more than happy.
+
+---
+
+## References

vignettes/mortAAR_vignette-1.Rmd → vignettes/mortAAR_vignette_example_1.Rmd

@@ -1,11 +1,11 @@
 ---
-title: "Vignette >Basic usage<"
+title: "Example: Neolithic Gallery graves"
 author: "Clemens Schmid"
 date: "March 2017"
 output: rmarkdown::html_vignette
 bibliography: ../inst/REFERENCES.bib
 vignette: >
-  %\VignetteIndexEntry{Vignette >Basic usage<}
+  %\VignetteIndexEntry{Example: Neolithic Gallery graves}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---