Added build vignette by removing inst/doc from .gitignore. May not be…

… right approach, but easiest. See r-lib/devtools#584

inst/doc/localgrowth.R

@@ -0,0 +1,53 @@
+## ----setup, include = FALSE----------------------------------------------
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+
+## ------------------------------------------------------------------------
+library(localgrowth)
+data(TsimaneData)
+head(TsimaneData)
+
+## ------------------------------------------------------------------------
+HFA<-growthRef(Age,Height,Sex,data=TsimaneData,type="Height")
+head(HFA)
+
+## ------------------------------------------------------------------------
+WFH<-growthRef(Height,Weight,Sex,data=TsimaneData,type="WFH")
+head(WFH)
+
+## ------------------------------------------------------------------------
+HFA<-growthRef(Age,Height,Sex,data=TsimaneData,type="Height",pop=c("CDC","Tsimane"),z="centile")
+head(HFA)
+
+## ------------------------------------------------------------------------
+BFA<-growthRef(Age,BMI,Sex,data=TsimaneData,type="BMI",pop="CDC")
+head(BFA)
+
+## ------------------------------------------------------------------------
+WFH<-growthRef(Height,Weight,Sex,data=TsimaneData,LMS=CDC.WFH,z="centile")
+head(WFH)
+
+## ------------------------------------------------------------------------
+#Tsimane specific z-score for a single individual, age 2 yrs, 75 cm, male.
+getZ(2,75,"Male",Tsimane.Height)
+getCentile(2,75,"Male",Tsimane.Height)
+
+## ----fig1, fig.height = 4, fig.width = 5---------------------------------
+#Subset the observations for one individual 
+ind<-TsimaneData[TsimaneData$PID=='TGD0734',]
+#Get the 2.5, 50, and 97.5 centiles for age 2 to 7, for plotting
+cent<-centilesLMS(seq(2,7,0.1),"Female",Tsimane.Height,cent=c(0.025,0.5,0.975),xname="Age")
+plot(Height~Age,data=ind,ylim=range(cent[,2:4]),xlim=c(2,7),pch=19,main="Height growth for TGD0734")
+lines(cent$Age,cent$'0.5',col="red",lty=1)
+lines(cent$Age,cent$'0.025',col="red",lty=2)
+lines(cent$Age,cent$'0.975',col="red",lty=2)
+
+## ----eval=FALSE----------------------------------------------------------
+#  ?localgrowth
+#  ?growthRef
+#  ?centilesLMS
+#  ?ZfromLMS
+#  ?TsimaneData
+

inst/doc/localgrowth.Rmd

@@ -0,0 +1,118 @@
+---
+title: "Calulating growth z-scores"
+author: "Aaron D. Blackwell"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{localgrowth}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+The **localgrowth** package provides functions to calculate z-scores and centile values for measurements of height, weight, and BMI based on both widely used growth standards and references (CDC, WHO) and references from other populations. The included LMS files are for calculating height-for-age, weight-for-age, BMI-for-age, and weight-for-height z-scores.
+
+The primary function for **localgrowth** is `growthRef`, which provides an interface for calcualting z-scores or centiles from one or more growth references. Other functions include `centilesLMS` which generates centile tables for reference or plotting, and `ZfromLMS` which does simple calculations from LMS values.
+
+##Included growth standards and references
+Four sets of references/standards are currently including in **localgrowth**. These include references for the Tsimane and Shuar indigenous groups of Bolivia and Ecuador, which were developed as population specific references, but may be useful for other South American populations. See the papers under the [References](#references) section for further details on the development and use of these references.
+
+##Using 'growthRef' to calculate z-scores
+The included data set `TsimaneData` includes 200 measurements of height, weight, and BMI, taken from the Tsimane growth data set in Blackwell, et al (2017). further documentation can be found with `?TsimaneData`. We will use this data for examples:
+```{r}
+library(localgrowth)
+data(TsimaneData)
+head(TsimaneData)
+```
+
+To calculate z-scores based on all four references, for height-for-age: 
+```{r}
+HFA<-growthRef(Age,Height,Sex,data=TsimaneData,type="Height")
+head(HFA)
+```
+
+Similarly for weight-for-height:
+```{r}
+WFH<-growthRef(Height,Weight,Sex,data=TsimaneData,type="WFH")
+head(WFH)
+```
+Note that weight-for-height can only be calculated for selected ranges of heights, and is not available for the Shuar references at all. When a value is out of range of the reference, a `NA` is returned.
+
+We can also request just values based on CDC and Tsimane references, and format output as centiles instead of z-scores:
+```{r}
+HFA<-growthRef(Age,Height,Sex,data=TsimaneData,type="Height",pop=c("CDC","Tsimane"),z="centile")
+head(HFA)
+```
+
+When only a single type of score is requested, a vector rather than a data frame is returned:   
+```{r}
+BFA<-growthRef(Age,BMI,Sex,data=TsimaneData,type="BMI",pop="CDC")
+head(BFA)
+```
+
+##Referencing LMS tables directly
+Typically, `growthRef` will be used with the `type` and `pop` arguements which allow for multiple references to be returned simultaneously. However, sometimes it may be useful to call an LMS table directly. LMS tables internal to **localgrowth** are named after the population and type, i.e. `CDC.WFH` or `Tsimane.Weight`. These can be called by name with the `LMS` arguement. Note that other, non-internal LMS tables can also be used, provided they are in the right format.
+```{r}
+WFH<-growthRef(Height,Weight,Sex,data=TsimaneData,LMS=CDC.WFH,z="centile")
+head(WFH)
+```
+
+###The `getZ` function
+'growthRef' works by organizing the input and calling he function `getZ` to calculate Z-scores. `getZ` can also be called directly with an LMS table specified, as can 'getCentile':
+```{r}
+#Tsimane specific z-score for a single individual, age 2 yrs, 75 cm, male.
+getZ(2,75,"Male",Tsimane.Height)
+getCentile(2,75,"Male",Tsimane.Height)
+```
+
+##Showing reference values
+The function 'centilesLMS' allows for the production of custom centile tables from either internal or external LMS files. This can be useful for producing comparisons for plots. For example, we might want to show how a particular individuals growth compares to Tsimane standards:
+```{r fig1, fig.height = 4, fig.width = 5}
+#Subset the observations for one individual 
+ind<-TsimaneData[TsimaneData$PID=='TGD0734',]
+#Get the 2.5, 50, and 97.5 centiles for age 2 to 7, for plotting
+cent<-centilesLMS(seq(2,7,0.1),"Female",Tsimane.Height,cent=c(0.025,0.5,0.975),xname="Age")
+plot(Height~Age,data=ind,ylim=range(cent[,2:4]),xlim=c(2,7),pch=19,main="Height growth for TGD0734")
+lines(cent$Age,cent$'0.5',col="red",lty=1)
+lines(cent$Age,cent$'0.025',col="red",lty=2)
+lines(cent$Age,cent$'0.975',col="red",lty=2)
+```
+
+##Other options
+**localgrowth** functions contain additional options not documented here. Visit the help files for the respective functions for further details.
+```{r eval=FALSE}
+?localgrowth
+?growthRef
+?centilesLMS
+?ZfromLMS
+?TsimaneData
+```
+
+##References<a name="references"></a>
+The following growth references/standards are included in **localgrowth** and should be cited appropriately if used:
+
+###Tsimane
+Blackwell, AD, Urlacher, SS, Beheim, B, von Rueden, C, Jaeggi, A, Stieglitz, J, Tumble, BC, Gurven, MD, Kaplan, H. (2017) Growth references for Tsimane forager-horticulturalists of the Bolivian Amazon, American Journal of Physical Anthropology. 162(3) 441-461. DOI: 10.1002/ajpa.23128.
+
+###Shuar
+Urlacher, SS, Blackwell, AD, Liebert, MA, Madimenos, FC, Cepon-Robins, TJ, Gildner, TE, Snodgrass, JJ, Sugiyama, LS. (2016) Physical Growth of the Shuar: Height, Weight, and BMI Growth References for an Indigenous Amazonian Population, American Journal of Human Biology, 28(1): 16-30. DOI: 10.1002/ajhb.22747.
+
+###US Center for Disease Control (CDC)
+Kuczmarski, R. J., Ogden, C. L., Guo, S. S., Grummer-Strawn, L. M., Flegal, K. M., Mei, Z., Wei, R., Curtin, L. R., Roche, A. F., Johnson, C. L. (2002). 2000 CDC Growth Charts for the United States: Methods and development. Vital Health Statistics 11,1-190.
+https://www.cdc.gov/growthcharts/data_tables.htm
+
+###World Health Organization (WHO)
+
+World Health Organization. (2006). New child growth standards: Length/ height-for-age, weight-for-age, weight-for-length, weight-for-height and body mass index-for-age: Methods and development. Geneva: World Health Organization
+
+de Onis, M., Onyango, A., Borghi, E., Siyam, A., Nishida, C., & Siekman, J. (2007). Development of a WHO growth reference for school-aged children and adolescents. Bulletin of World Health Organization, 85, 660-667.
+
+http://www.who.int/childgrowth/en/
+http://www.who.int/growthref/en/
+