RXR 2396: update pct_weight_for_age() and related functions

.Rbuildignore

@@ -11,3 +11,4 @@ slack_notification.sh
 ^pkgdown$
 ^\.github$
 ^CRAN-SUBMISSION$
+^data-raw$

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: clinPK
 Type: Package
 Title: Clinical Pharmacokinetics Toolkit
-Version: 0.13.0
+Version: 0.14.0
 Date: 2024-02-22
 Authors@R: c(person("Ron", "Keizer", email = "ron@insight-rx.com", role
         = c("aut",  "cre")), person("Jasmine", "Hughes", email =
@@ -22,6 +22,10 @@ URL: https://github.com/InsightRX/clinPK,
         https://insightrx.github.io/clinPK/
 License: MIT + file LICENSE
 Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 Suggests: testthat (>= 3.0.0)
 Config/testthat/edition: 3
+Depends: 
+    R (>= 2.10)
+LazyData: true

NAMESPACE

@@ -44,12 +44,17 @@ export(inch2cm)
 export(kg2lbs)
 export(kg2oz)
 export(lbs2kg)
+export(median_bmi_for_age)
+export(median_height_for_age)
+export(median_weight_for_age)
+export(median_weight_for_height)
 export(mol2conc)
 export(nca)
 export(oz2kg)
 export(pct_bmi_for_age)
 export(pct_height_for_age)
 export(pct_weight_for_age)
+export(pct_weight_for_height)
 export(pk_1cmt_bolus)
 export(pk_1cmt_bolus_cmax_ss)
 export(pk_1cmt_bolus_cmin_ss)
@@ -79,7 +84,6 @@ export(pk_2cmt_inf_dose_from_cmin)
 export(pk_2cmt_inf_ss)
 export(pk_2cmt_t12)
 export(pk_2cmt_t12_interval)
-export(read_who_table)
 export(relative2absolute_bsa)
 export(time_to_ss)
 export(valid_units)

NEWS.md

@@ -1,3 +1,14 @@
+# clinPK 0.14.0
+
+## Major changes
+- Refactored `pct_*_for_*()` functions. As input, they now accept vectors of values. They now return either a vector of percentiles for the given physical measurement, or a data frame with the observed percentile for the given physical measurement, along with a select distribution of physical measurements at particular percentiles. These functions also use updated CDC growth charts instead of WHO growth charts.
+- Added `median_*_for_*()` functions for calculating median growth values for infants and children. These functions replace the now-deprecated `return_median` argument in the `pct_*_for_*()` functions.
+- Added CDC growth chart data sets as package data (see `?"growth-charts"`).
+- Removed `read_who_table()` function, as part of the refactor for the `pct_*_for_*()` functions.
+
+## Minor updates
+- Activated roxygen's markdown parser for improved function documentation
+
 # clinPK 0.13.0
 
 ## Major changes

R/calc_ibw.R

@@ -1,12 +1,13 @@
 #' Calculate ideal body weight in kg for children and adults
 #'
-#' Get an estimate of ideal body weight. This function allows several commonly used equations
+#' Get an estimate of ideal body weight. This function allows several commonly
+#' used equations
 #'
 #' Equations:
 #'
-#' <1yo Use actual body weight
+#' For <1yo Use actual body weight
 #'
-#' 1-17 years old ('standard'):
+#' For 1-17 years old ('standard'):
 #'   if height < 5ft:
 #'     IBW= (height in cm2 x 1.65)/1000
 #'   if height > 5ft:
@@ -21,7 +22,7 @@
 #'   BMI: IBW = 50th percentile of BMI for given age x (height in m)^2
 #'   ADA: IBW = 50th percentile of WT for given age
 #'
-#' >= 18 years old (Devine equation)
+#' For >= 18 years old (Devine equation)
 #'   IBW (male) = 50 + (2.3 x height in inches over 5 feet)
 #'   IBW (female) = 45.5 + (2.3 x height in inches over 5 feet)
 #'

R/data.R

@@ -0,0 +1,52 @@
+#' CDC Growth Charts
+#' 
+#' Data used to produce the United States Growth Charts smoothed percentile
+#' curves for infants and older children.
+#' 
+#' @details
+#' These data sets contain the L (power in the Box-Cox transformation), M
+#' (median), and S (generalized coefficient of variation) parameters needed to
+#' generate exact percentiles and z-scores for seven different growth charts,
+#' along with the 3rd, 5th, 10th, 25th, 50th, 75th, 90th, 95th, and 97th
+#' percentile values by sex (1 = male; 2 = female) and single month of age
+#' (listed at the half-month point for the entire month).
+#' 
+#' @source 
+#' National Center for Health Statistics. (n.d.). CDC Growth Charts Data Files.
+#' <https://www.cdc.gov/growthcharts/cdc-growth-charts.htm>
+#' @seealso Functions to calculate growth metrics: [pct_weight_for_age],
+#'   [pct_height_for_age], [pct_bmi_for_age], [pct_weight_for_height]
+#' @name growth-charts
+#' @aliases weight_for_age, height_for_age, bmi_for_age_children,
+#'   weight_for_height_infants, weight_for_height_children
+NULL
+
+#' @rdname growth-charts
+#' @format ## `weight_for_age`
+#' An object of class `data.frame` with `r nrow(weight_for_age)` rows
+#' and `r ncol(weight_for_age)` columns.
+"weight_for_age"
+
+#' @rdname growth-charts
+#' @format ## `height_for_age`
+#' An object of class `data.frame` with `r nrow(height_for_age)` rows
+#' and `r ncol(height_for_age)` columns.
+"height_for_age"
+
+#' @rdname growth-charts
+#' @format ## `bmi_for_age_children`
+#' An object of class `data.frame` with `r nrow(bmi_for_age_children)` rows
+#' and `r ncol(bmi_for_age_children)` columns.
+"bmi_for_age_children"
+
+#' @rdname growth-charts
+#' @format ## `weight_for_height_infants`
+#' An object of class `data.frame` with `r nrow(weight_for_height_infants)` rows
+#' and `r ncol(weight_for_height_infants)` columns.
+"weight_for_height_infants"
+
+#' @rdname growth-charts
+#' @format ## `weight_for_height_children`
+#' An object of class `data.frame` with `r nrow(weight_for_height_children)` rows
+#' and `r ncol(weight_for_height_children)` columns.
+"weight_for_height_children"

R/lms.R

@@ -0,0 +1,67 @@
+#' LMS growth chart equations
+#' 
+#' LMS equations to calculate z-scores, percentiles, and other metrics for
+#' infants and children.
+#'
+#' @param l The power in the Box-Cox transformation (L).
+#' @param m The median (M).
+#' @param s The generalized coefficient of variation (S)
+#' @param z,p The z-score (Z) or percentile to return the value of a given
+#'   physical measurement (X) at. Only one of `z` or `p` can be provided, not
+#'   both.
+#' @param x A given physical measurement (X) to return the corresponding z-score
+#'   (Z) or percentile for.
+#' @param value A character string determining whether to return the
+#'   corresponding z-score (Z) or percentile.
+#' 
+#' @source 
+#' National Center for Health Statistics. (n.d.). CDC Growth Charts Data Files.
+#' <https://www.cdc.gov/growthcharts/cdc-growth-charts.htm>
+#' @seealso
+#' CDC Growth Charts data with LMS parameters: [weight_for_age],
+#' [height_for_age], [bmi_for_age_children], [weight_for_height_infants],
+#' [weight_for_height_children]
+#' 
+#' Functions to calculate growth metrics: [pct_weight_for_age], [pct_height_for_age],
+#' [pct_bmi_for_age], [pct_weight_for_height]
+#' @returns `lms_for_x()` returns the value of a given physical measurement (X)
+#'   at a particular z-score (Z) or percentile. `lms_for_z()` returns the
+#'   z-score (Z) or corresponding percentile for a given measurement (X).
+#' @name lms
+#' @aliases lms_for_x, lms_for_z
+#' 
+#' @examples
+#' lms_for_x(l = -0.1600954, m = 9.476500305, s = 0.11218624, z = -1.645)
+#' 
+#' lms_for_z(
+#'   l = -0.1600954, m = 9.476500305, s = 0.11218624, x = 9.7, value = "p"
+#' )
+#' @noRd
+NULL
+
+# @rdname lms
+lms_for_x <- function(l, m, s, z = NULL, p = NULL) {
+  if (!is.null(z) & !is.null(p)) {
+    stop("Only one of `z` or `p` can be provided, not both.")
+  } else if (!is.null(p)) {
+    z <- stats::qnorm(p)
+  }
+  x <- ifelse(
+    l == 0,
+    m * exp(s * z),
+    m * (1 + l*s*z)**(1/l)
+  )
+  x
+}
+
+# @rdname lms
+lms_for_z <- function(l, m, s, x, value = c("z", "p")) {
+  value <- match.arg(value)
+  z <- ifelse(
+    l == 0,
+    log(x/m)/s,
+    (((x/m)^l) - 1) / (l*s)
+  )
+  if (value == "p") z <- stats::pnorm(z) * 100
+  z
+}

R/median_x_for_y.R

@@ -0,0 +1,112 @@
+#' Median growth values for infants and children
+#'
+#' Calculate median weight, height, and BMI for age/height for infants and
+#' children using CDC Growth Charts data and equations.
+#' 
+#' @inheritParams pct_weight_for_age
+#' @param height A numeric vector of heights in the unit specified in `height_units`.
+#' @param height_units A character string specifying the units of all `height` values.
+#' @param population A character string specifying the population table to use
+#'   for [median_weight_for_height()]. Either "infants" (birth to 36 months) or
+#'   "children" (2 to 20 years).
+#' 
+#' @seealso Functions to calculate growth metrics: [pct_weight_for_age],
+#'   [pct_height_for_age], [pct_bmi_for_age], [pct_weight_for_height]
+#'
+#' CDC Growth Charts data: [weight_for_age], [height_for_age],
+#' [bmi_for_age_children], [weight_for_height_infants],
+#' [weight_for_height_children]
+#' @returns A numeric vector of median weight, height, or BMI values for the
+#'   given ages/heights.
+#' @name median_x_for_y
+#'
+#' @examples
+#' median_weight_for_age(3.5, "months", sex = "male")
+NULL
+
+#' @rdname median_x_for_y
+#' @export
+median_weight_for_age <- function(
+    age,
+    age_units = c("years", "months", "weeks", "days"),
+    sex
+) {
+  age_units <- match.arg(age_units)
+  sex <- match.arg(sex, choices = c("male", "female"), several.ok = TRUE)
+  pct_growth_generic(
+    x = NULL,
+    y = age,
+    sex = sex,
+    growth_chart = clinPK::weight_for_age,
+    return_median = TRUE,
+    y_argname = "age",
+    y_units = age_units
+  )
+}
+
+#' @rdname median_x_for_y
+#' @export
+median_height_for_age <- function(
+    age,
+    age_units = c("years", "months", "weeks", "days"),
+    sex
+) {
+  age_units <- match.arg(age_units)
+  sex <- match.arg(sex, choices = c("male", "female"), several.ok = TRUE)
+  pct_growth_generic(
+    x = NULL,
+    y = age,
+    sex = sex,
+    growth_chart = clinPK::height_for_age,
+    return_median = TRUE,
+    y_argname = "age",
+    y_units = age_units
+  )
+}
+
+#' @rdname median_x_for_y
+#' @export
+median_bmi_for_age <- function(
+    age,
+    age_units = c("years", "months", "weeks", "days"),
+    sex
+) {
+  age_units <- match.arg(age_units)
+  sex <- match.arg(sex, choices = c("male", "female"), several.ok = TRUE)
+  pct_growth_generic(
+    x = NULL,
+    y = age,
+    sex = sex,
+    growth_chart = clinPK::bmi_for_age_children,
+    return_median = TRUE,
+    y_argname = "age",
+    y_units = age_units
+  )
+}
+
+#' @rdname median_x_for_y
+#' @export
+median_weight_for_height <- function(
+    height,
+    height_units = c("centimetres", "metres", "feet", "inches"),
+    sex,
+    population = c("infants", "children")
+) {
+  population <- match.arg(population)
+  if (population == "infants") {
+    growth_chart <- clinPK::weight_for_height_infants
+  } else if (population == "children") {
+    growth_chart <- clinPK::weight_for_height_children
+  }
+  height_units <- match.arg(height_units)
+  sex <- match.arg(sex, choices = c("male", "female"), several.ok = TRUE)
+  pct_growth_generic(
+    x = NULL,
+    y = height,
+    sex = sex,
+    growth_chart = growth_chart,
+    return_median = TRUE,
+    y_argname = "height",
+    y_units = height_units
+  )
+}