---
title: "Overview of Growth Standards"
output:
 rmarkdown::html_vignette:
   toc: true
   number_sections: true
bibliography: references.bib
vignette: >
 %\VignetteIndexEntry{Overview of Growth Standards}
 %\VignetteEngine{knitr::rmarkdown}
 %\VignetteEncoding{UTF-8}
---


```{r label = "setup", include = FALSE}
################################################################################
#                        !!! DO NOT EDIT .Rmd files !!!                        #
#                                                                              #
# .Rmd files are generated by their corresponding .R files found in the        #
# vignette-spinners/ directory.  Any changes needed to the .Rmd file need to   #
# be made in the .R file                                                       #
################################################################################
knitr::opts_chunk$set(collapse = TRUE, fig.align = "center")
library(qwraps2)
```



```{r}
library(pedbp)
```


# Introduction

Using the [Percentile Data Files with LMS values](https://www.cdc.gov/growthcharts/percentile_data_files.htm)
provided by the CDC, and [Child Growth
Standards](https://www.who.int/tools/child-growth-standards/standards)
provided by the World Health Organization (WHO),
we provide tools for finding quantiles, percentiles, or z-scores, for the
following metrics:

1. BMI for age
2. head circumference for age
3. stature for age
   a. height for age
   b. length for age
4. weight for age
5. weight for stature
   a. weight for height
   b. weight for length

All lengths/heights are in centimeters, ages in months, and weights in
kilograms.  Stature is used to refer both height and length; specific
methods are provided for each.

# Method - LMS

All methods use the published LMS parameters to define z-scores,
percentiles, and quantiles for skewed distributions.  L is a $\lambda$
parameter, the Box-Cox transformation power; $M$ the median value, and $S$ a
generalized coefficient of variation.  For a given percentile or z-score, the
corresponding physical measurement, $X,$ is defined as

$$X = \begin{cases}
   M \left(1 + \lambda S Z \right)^{\frac{1}{\lambda}} & \lambda \neq 0 \\
   M \exp\left( S Z \right) & \lambda = 0.
\end{cases}$$

From this we can get the z-score for a given measurement $X:$

$$ Z = \begin{cases}
  \frac{\left(\frac{X}{M}\right)^{\lambda} - 1}{\lambda S} & \lambda \neq 0 \\
  \frac{\log\left(\frac{X}{M}\right) }{ S } & \lambda = 0.
  \end{cases}$$

Percentiles are determined using the standard normal distribution of z-scores.

For all eight of the noted methods we provide a distribution function,
quantile function, and function that returns z-scores.

# Growth Standards

Each of the growth standard metrics have quantile,
distribution, and z-score function with the naming convention of
`r  "(" %s% qwraps2::backtick("q_<metric>", dequote = TRUE) %s% ")," `
`r  "(" %s% qwraps2::backtick("p_<metric>", dequote = TRUE) %s% "), and" `
`r  "(" %s% qwraps2::backtick("z_<metric>", dequote = TRUE) %s% ")," `
respectively.

Additionally, the function
`r  qwraps2::backtick(gs_chart)  `
for building growth standard charts with percentile curves, and
`r  qwraps2::backtick(gs_cdf)  `
for plotting the cumulative distribution function for a given set of inputs.

**Example**

Find the distribution value for a 13 year
`r  "(" %s% as.character(13 * 12) %s% " month)"  `
old male with a BMI of 21.

```{r echo = FALSE, fig.width = 7, fig.height = 5}
p_bmi_for_age(21, male = 1, age = 13 * 12) # default source is CDC
p_bmi_for_age(21, male = 1, age = 13 * 12, source = c("CDC", "WHO"))
```


An easy way to visualize the BMI distribution is to use the growth standard
chart

```{r fig.width = 7, fig.height = 5}
gs_chart(metric = "bmi_for_age", male = 1, source = "CDC") +
  ggplot2::geom_point(x = 13 * 12, y = 21, inherit.aes = FALSE)
```


and a cumulative distribution function

```{r fig.width = 7, fig.height = 5}
gs_cdf(metric = "bmi_for_age", male = 1, age = 13*12) +
   ggplot2::geom_point(x = 21, y = p_bmi_for_age(21, male = 1, age = 13*12))
```


You can also easily get the z-score instead of the distribution value.

```{r}
z_bmi_for_age(q = 21, male = 1, age = 13*12)
```


Find the median BMI quantile for a 48 month old female is:

```{r}
q_bmi_for_age(p = 0.5, male = 0, age = 48) # default is CDC
q_bmi_for_age(p = 0.5, male = 0, age = 48, source = c("CDC", "WHO"))
```