vignette-spinners/growth-standards.R

In dewittpe/pedbp: Pediatric Blood Pressure

#'---
#'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}
#'---
#'
#+ label = "setup", include = FALSE
#/*
devtools::load_all() # load the dev version while editing
#*/
################################################################################
#                        !!! 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)

#'
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
{{ "(" %s% qwraps2::backtick("q_<metric>", dequote = TRUE) %s% "),"}}
{{ "(" %s% qwraps2::backtick("p_<metric>", dequote = TRUE) %s% "), and"}}
{{ "(" %s% qwraps2::backtick("z_<metric>", dequote = TRUE) %s% "),"}}
#' respectively.
#'
#' Additionally, the function
{{ qwraps2::backtick(gs_chart) }}
#' for building growth standard charts with percentile curves, and
{{ 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
{{ "(" %s% as.character(13 * 12) %s% " month)" }}
#' old male with a BMI of 21.
#+ echo = FALSE, fig.width = 7, fig.height = 5
# /*
dev.new(width = 7, 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
#+ 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
#+ 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.
z_bmi_for_age(q = 21, male = 1, age = 13*12)

#'
#' Find the median BMI quantile for a 48 month old female is:
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"))

#'
#'
#/*
#' # References
#'<div id="refs"></div>
#'
#' # Session Info
#+ label = "sessioninfo"
sessionInfo()
#*/