Getting started with peditools2

peditools2 calculates Z-scores, percentiles and measurements on pediatric, neonatal and fetal growth charts from their published parameters: the charts of PediTools, with the same methods and the same results. It is written for data analysis: every function is vectorised, and the methods the website applies (and some it does not, such as extrapolation) can be switched.

library(peditools2)

Finding a chart

Every chart is identified by a chart id and a measure. growth_charts() lists them, one row per chart, measure and sex, with the units of x (age, length or height) and of the measurement, and the published coverage:

charts <- growth_charts()
head(charts[c("chart", "measure", "sex", "x_units", "measure_units", "x_min", "x_max", "z_method")])
#>               chart     measure sex x_units measure_units x_min x_max z_method
#> 1 abdel-rahman_2017    arm_circ   f  months            cm   2.0   222      lms
#> 2 abdel-rahman_2017    arm_circ   m  months            cm   2.0   222      lms
#> 3    addo_2010_skin subscapular   f   years            mm   1.5    20      lms
#> 4    addo_2010_skin subscapular   m   years            mm   1.5    20      lms
#> 5    addo_2010_skin     triceps   f   years            mm   1.5    20      lms
#> 6    addo_2010_skin     triceps   m   years            mm   1.5    20      lms
growth_charts("who_2006_infant")[c("measure", "sex", "x_units", "x_min", "x_max", "z_method")]
#>     measure sex x_units x_min x_max z_method
#> 1 head_circ   f  months     0    24      lms
#> 2 head_circ   m  months     0    24      lms
#> 3    length   f  months     0    24      lms
#> 4    length   m  months     0    24      lms
#> 5    weight   f  months     0    24     sd23
#> 6    weight   m  months     0    24     sd23

Units. The calculations take x and the measurement in the chart’s own units (x_units, measure_units): months for the CDC and WHO infant charts, weeks for the preterm charts, days for the INTERGROWTH-21st newborn standards, kg or g for weight. Convert first; the helpers below use PediTools’ constants.

Z-scores and percentiles

growth_z() and growth_p() take the measurement y, x, sex, chart and measure, each a single value or a vector of the common length. growth_p() gives the probability, the percentile divided by 100 (as pnorm()).

growth_z(8.2, 9.5, "f", "cdc_2000_infant", "weight")
#> [1] -0.5307598
growth_p(8.2, 9.5, "f", "cdc_2000_infant", "weight")
#> [1] 0.2977926

With a data frame (here made-up data):

set.seed(1)
d <- data.frame(
  id = rep(c("a", "b", "c"), each = 3),
  sex = rep(c("f", "m", "f"), each = 3),
  birth = rep(as.Date(c("2024-01-15", "2024-03-02", "2024-05-20")), each = 3),
  visit = as.Date("2024-06-01") + rep(c(0, 90, 180), 3),
  weight = round(c(6.2, 7.4, 8.3, 6.9, 8.4, 9.6, 4.6, 6.4, 7.6) + rnorm(9, 0, 0.1), 2)
)
d$age_days <- growth_age_days(d$birth, d$visit)
d$age_months <- growth_convert(d$age_days, "days", "months")
d$z <- growth_z(d$weight, d$age_months, d$sex, "who_2006_infant", "weight")
d$percentile <- 100 * growth_p(d$weight, d$age_months, d$sex, "who_2006_infant", "weight")
d[c("id", "sex", "age_days", "weight", "z", "percentile")]
#>   id sex age_days weight          z percentile
#> 1  a   f      138   6.14 -0.6807467   24.80159
#> 2  a   f      228   7.42 -0.4034449   34.33105
#> 3  a   f      318   8.22 -0.3585002   35.99845
#> 4  b   m       91   7.06  0.8872493   81.25277
#> 5  b   m      181   8.43  0.5814102   71.95180
#> 6  b   m      271   9.52  0.6481399   74.15528
#> 7  c   f       12   4.65  1.8816867   97.00607
#> 8  c   f      102   6.47  0.5372402   70.44492
#> 9  c   f      192   7.66  0.2790582   60.98999

sex accepts "m", "f", "male", "female" in any case. Charts can differ between rows too: chart and measure are vectorised like the rest.

Measurements at a Z-score or percentile

growth_y() is the inverse: the measurement at a Z-score z, or at a probability p.

growth_y(p = c(0.03, 0.5, 0.97), x = 12, sex = "m", chart = "who_2006_infant", measure = "weight")
#> [1]  7.845122  9.647900 11.832729

# Expected growth: the weight at 12 months at the Z-score of 7.1 kg at 6 months
z <- growth_z(7.1, 6, "m", "who_2006_infant", "weight")
growth_y(z, 12, "m", "who_2006_infant", "weight")
#> [1] 8.639894

Preterm infants: PMA and corrected age

The preterm charts take the postmenstrual age (PMA) in weeks; the infant charts can take a corrected age:

# Born at 27 2/7 weeks, 40 days old
growth_pma(40, 27, 2)
#> [1] 33
growth_z(1.25, growth_pma(40, 27, 2), "f", "fenton_2003", "weight")
#> [1] -1.799316

# Corrected age at 200 days old, in months
growth_corrected_age(200, 27, 2, units = "months")
#> [1] 3.646817

Why a value is NA: `growth_detail()`

Values outside the chart’s coverage, or that are not valid, are NA, with one warning per call. growth_detail() gives everything about each value: the parameters at x, the method used and a status.

growth_detail(c(7.9, 3.5, 8), c(6, 6, 30), "m", "who_2006_infant", "weight")[
  c("x", "y", "z", "method", "status", "L", "M", "S")
]
#>    x   y           z method  status      L     M       S
#> 1  6 7.9 -0.03918054   sd23      ok 0.1257 7.934 0.10958
#> 2  6 3.5 -6.18575454   sd23      ok 0.1257 7.934 0.10958
#> 3 30 8.0          NA   <NA> outside     NA    NA      NA

Methods and options

By default each chart is calculated as its authors prescribe and as PediTools does: WHO’s restricted LMS method beyond ±3 SD on the WHO charts, CDC’s extended method above the 95th percentile of CDC BMI-for-age. Three options change this for any call (vignette("methods", package = "peditools2") describes each method):

extrapolate: "coverage" (default), "none" (only between the table’s rows) or "linear" (beyond the coverage, on the line through the two end rows).
sd23: TRUE or FALSE to switch WHO’s restricted method on or off on any chart.
cdc_bmi_ext: FALSE for plain LMS on CDC BMI-for-age.

growth_z(3.5, 6, "m", "who_2006_infant", "weight", sd23 = FALSE)
#> [1] -7.097157
growth_z(30, 150, "m", "cdc_2000_bmi", "bmi", cdc_bmi_ext = FALSE)
#> [1] 2.20594
growth_z(0.4, 20, NA, "fenton_2003", "weight", extrapolate = "linear")
#> [1] 4.777173

Parameters and curves

growth_table() gives a chart’s published rows, growth_params() its parameters at any x, and growth_curves() percentile or Z-score curves as a data frame for any plotting library:

head(growth_table("cdc_2000_infant", "length", "f"))
#>             chart measure sex   x           L        M          S
#> 1 cdc_2000_infant  length   f 0.0 -1.29596086 49.28640 0.05008556
#> 2 cdc_2000_infant  length   f 0.5 -0.80924988 51.68358 0.04681855
#> 3 cdc_2000_infant  length   f 1.5 -0.05078299 55.28613 0.04344390
#> 4 cdc_2000_infant  length   f 2.5  0.47685141 58.09382 0.04171610
#> 5 cdc_2000_infant  length   f 3.5  0.84329961 60.45981 0.04070517
#> 6 cdc_2000_infant  length   f 4.5  1.09756226 62.53670 0.04007977
growth_params(c(9, 9.25, 9.5), "f", "cdc_2000_infant", "length")
#>             chart measure sex    x family part        L        M          S
#> 1 cdc_2000_infant  length   f 9.00    lms  lms 1.523626 69.89144 0.03922939
#> 2 cdc_2000_infant  length   f 9.25    lms  lms 1.529289 70.24154 0.03922553
#> 3 cdc_2000_infant  length   f 9.50    lms  lms 1.534951 70.59164 0.03922167
#>   status extrapolated beyond_coverage
#> 1     ok        FALSE           FALSE
#> 2     ok        FALSE           FALSE
#> 3     ok        FALSE           FALSE
head(growth_curves("cdc_2000_infant", "length", "f", z = c(-2, 0, 2)))
#>             chart measure sex curve          p  z    x        y segment
#> 1 cdc_2000_infant  length   f   Z-2 0.02275013 -2 0.00 44.85638       1
#> 2 cdc_2000_infant  length   f   Z-2 0.02275013 -2 0.12 45.42097       1
#> 3 cdc_2000_infant  length   f   Z-2 0.02275013 -2 0.24 45.98767       1
#> 4 cdc_2000_infant  length   f   Z-2 0.02275013 -2 0.36 46.55653       1
#> 5 cdc_2000_infant  length   f   Z-2 0.02275013 -2 0.48 47.12761       1
#> 6 cdc_2000_infant  length   f   Z-2 0.02275013 -2 0.60 47.56780       1
#>   beyond_coverage
#> 1           FALSE
#> 2           FALSE
#> 3           FALSE
#> 4           FALSE
#> 5           FALSE
#> 6           FALSE

Plots

growth_plot() draws the curves with ggplot2, with measurements if given:

growth_plot("who_2006_infant", "weight", c("m", "f"),
  data = d, x_col = "age_months", y_col = "weight", id_col = "id", sex_col = "sex", xlim = c(0, 12)
)

Your own charts

growth_add_chart() adds a parameter table of your own (for example one shared by its authors) for the session, with its metadata and references; every function then works on it:

my <- growth_table("cdc_2000_infant", "weight") # here a copy, as an example
my$chart <- "my_chart"
growth_add_chart(my,
  metadata = data.frame(chart = "my_chart", x_units = "months", measure_units = "kg"),
  references = data.frame(chart = "my_chart", citation = "Author A. My growth chart. J Growth 2026;1:1-9.")
)
growth_z(8.2, 9.5, "f", "my_chart", "weight")
#> [1] -0.5307598
growth_remove_chart("my_chart")

Sources, and citing

growth_references() lists each chart’s publications, with a link to its section of the PediTools Sources and methods page, where the sources and the checks of every table are described:

growth_references("who_2006_infant", "weight")[c("role", "short", "url")]
#>       role
#> 1 clinical
#> 2 lms_data
#> 3 lms_data
#> 4   method
#>                                                                                                         short
#> 1 WHO Multicentre Growth Reference Study Group. WHO Child Growth Standards: Methods and development. WHO 2006
#> 2                   WHO Child Growth Standards: standards and tables by indicator (World Health Organization)
#> 3                                                                         WHO growth charts: data files (CDC)
#> 4 WHO Multicentre Growth Reference Study Group. WHO Child Growth Standards: Methods and development. WHO 2006
#>                                                          url
#> 1         https://www.who.int/publications/i/item/924154693X
#> 2 https://www.who.int/tools/child-growth-standards/standards
#> 3        https://www.cdc.gov/growthcharts/who-data-files.htm
#> 4         https://www.who.int/publications/i/item/924154693X
growth_data_version()
#>         date       commit 
#> "2026-10-23"    "9de1349"

To cite the package: citation("peditools2").