Package 'peditools2' reference manual

Title:	Pediatric and Neonatal Growth Chart Calculations and Parameters
Description:	Z-scores, probabilities and measurements for pediatric, neonatal and fetal growth charts and standards (CDC, WHO, INTERGROWTH-21st and others) from their published parameters, by the LMS method, the WHO restricted LMS method, the CDC extended BMI method and the INTERGROWTH-21st models. The parameter tables and their references are those of PediTools <https://peditools.org/>, where each chart's sources and methods are described.
Authors:	Joseph Chou [aut, cre]
Maintainer:	Joseph Chou <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.0
Built:	2026-10-24 21:34:38 UTC
Source:	https://github.com/jhchou/peditools2

Add your own charts for the session

Description

Makes charts of your own (e.g. parameter tables an author shared with you) available to every function of the package until the end of the R session, with the same checks and methods as the built-in charts. Nothing is saved: call it again in a new session (e.g. growth_add_chart(read.csv("my_chart.csv")) at the top of a script).

Usage

growth_add_chart(params, metadata = NULL, references = NULL, overwrite = FALSE)
growth_add_chart(params, metadata = NULL, references = NULL, overwrite = FALSE)

Arguments

params

A data frame of parameters, or a list of them (see Details).

metadata

A data frame of chart information (see Details), or NULL.

references

A data frame of the charts' publications (see Details), or NULL.

overwrite

TRUE to replace a chart of the same id (built-in, or added before); FALSE (default): an error.

Details

params is a data frame, or a list of data frames, in the layout of the PediTools parameter files, recognised by their columns:

LMS (the layout of growth_table()): chart, measure, sex (or gender; "m", "f", or NA for one table for both sexes), x (or age), L, M, S, and optionally x_units (or age_units) and measure_units.
ST3 (the layout of growth_table()): chart, measure, sex, x, mu, sigma, nu, tau, and optionally x_units and measure_units.
Equations of a normal model (the layout of growth_equations()): chart, measure, sex, x_from, param (mu or sigma), coef, power, log_power, male, x_scale, transform, y_scale, and optionally model ("normal"), x_units and measure_units.

A chart may combine an ST3 table and equations (parts used from their start, as INTERGROWTH-21st newborn size).

metadata (optional) is a data frame with a row per chart (measure NA), and optionally rows for one measure or one sex that override it: chart, measure, sex, x_label (default "age"), x_min and x_max (or age_min, age_max; the published coverage, by default the table's first and last rows; required for equations), z_method ("lms" (default) or "sd23" for LMS tables; "cdf" for the others), x_break (an x between two rows where the table steps), sources_url (a page describing the chart's sources and methods), and x_units, measure_units when params has none. These are the fields of growth_charts(); on_website and calculators describe the PediTools calculators, so they are FALSE and NA for added charts.

references (optional) is a data frame in the layout of growth_references(): chart, measure (NA: every measure of the chart), role ("clinical" (default), "lms_data", "method" or "resource"), citation (required), and optionally short (default: the citation), position (default: the order given within each role), id, doi, pmid and url.

As for the built-in charts, the coverage may reach at most half a row step beyond a table's end row (use extrapolate = "linear" to go further); rows must increase in x; M and S (sigma, nu, tau) must be positive.

Value

The added charts' rows of growth_charts(), invisibly.

Examples

# An LMS table of your own (here the first rows of CDC's, as an example)
my <- growth_table("cdc_2000_infant", "weight", "f")[1:12, ]
my$chart <- "my_infant_chart"
meta <- data.frame(chart = "my_infant_chart", x_units = "months", measure_units = "kg")
refs <- data.frame(chart = "my_infant_chart", citation = "Author A. My chart. J Growth 2026;1:9.")
growth_add_chart(my, meta, refs)
growth_z(4.1, 1.2, "f", "my_infant_chart", "weight")
growth_references("my_infant_chart")
growth_remove_chart("my_infant_chart")
# An LMS table of your own (here the first rows of CDC's, as an example)
my <- growth_table("cdc_2000_infant", "weight", "f")[1:12, ]
my$chart <- "my_infant_chart"
meta <- data.frame(chart = "my_infant_chart", x_units = "months", measure_units = "kg")
refs <- data.frame(chart = "my_infant_chart", citation = "Author A. My chart. J Growth 2026;1:9.")
growth_add_chart(my, meta, refs)
growth_z(4.1, 1.2, "f", "my_infant_chart", "weight")
growth_references("my_infant_chart")
growth_remove_chart("my_infant_chart")

Age in days between dates

Description

Whole days from the date of birth to the date of measurement, as PediTools counts them (calendar dates, so no daylight-saving effects). Negative when the date is before the birth.

Usage

growth_age_days(birth, date)
growth_age_days(birth, date)

Arguments

birth, date

Dates: Date vectors, or character in the form "YYYY-MM-DD" (each of length 1 or a common length). Date-times (POSIXct) are refused: convert them with as.Date() in the time zone of your data, so that a date does not shift by a day.

Value

Integer days; NA where a date is missing or not a valid date (with a warning).

Examples

growth_age_days("2024-02-10", c("2024-02-29", "2024-03-01", "2025-02-10"))
growth_age_days("2024-02-10", c("2024-02-29", "2024-03-01", "2025-02-10"))

The available charts

Description

One row per chart, measure and sex: everything needed to use a chart's parameters. A chart with one table for both sexes (e.g. fenton_2003, the INTERGROWTH-21st fetal standards) has one row with sex NA.

Usage

growth_charts(chart = NULL)
growth_charts(chart = NULL)

Arguments

chart

Chart ids to keep; NULL (default) for all.

Value

A data frame with columns:

chart, measure, sex: The ids used by every function of the package; sex is "m", "f", or NA for a table used for both sexes.
family: How the distribution is given: "lms" (an LMS table, growth_table()), or the INTERGROWTH-21st parts in order of x: "st3" (a skew t table, growth_table()) and "normal" (equations for the mean and SD, growth_equations()).
x_label: What x is: "age", "length", "height", "gestational age" or "gestational age at birth".
x_units, measure_units: The units of x and of the measurement.
x_min, x_max: The coverage: the range of x the chart is published for. It may reach beyond the first or last row by up to half a row step, for tables whose rows are the midpoints of bands.
z_method: The Z-score method the chart's authors prescribe: "lms", "sd23" (WHO's restricted LMS method beyond +-3 SD) or "cdf" (the inverse normal of the distribution function, INTERGROWTH-21st).
x_break: An x between two rows where the table steps (e.g. 730.5 days, where WHO's tables change from lying length to standing height), never interpolated across; NA for none.
n_rows: The number of rows of the table in growth_table() (0 for equations only).
on_website: Whether a PediTools calculator uses the chart.
calculators: The PediTools calculator ids that use it, separated by commas; NA for none.
sources_url: The chart's section of the PediTools Sources and methods page (for a chart with no calculator, the section on its method).
added: Whether the chart was added in the session (growth_add_chart()).

Examples

charts <- growth_charts()
head(charts[c("chart", "measure", "sex", "x_units", "x_min", "x_max")])

growth_charts("who_2006_infant")

# Charts not used by a PediTools calculator
unique(charts$chart[!charts$on_website])
charts <- growth_charts()
head(charts[c("chart", "measure", "sex", "x_units", "x_min", "x_max")])

growth_charts("who_2006_infant")

# Charts not used by a PediTools calculator
unique(charts$chart[!charts$on_website])

Convert units

Description

Converts values between units of the same kind, with the constants PediTools uses: mass ("g", "kg", "lb", "oz"), length ("mm", "cm", "m", "in", "ft"), time ("days", "weeks", "months", "years") and BMI ("kg/m2", and Olsen 2015's "g/cm2*10", numerically the same). The factors are exact by definition: 1 lb = 453.59237 g, 1 oz = 1/16 lb, 1 in = 2.54 cm, 1 week = 7 days, 1 month = 30.4375 days (365.25 / 12), 1 year = 365.25 days, as in the CDC and WHO tables.

Usage

growth_convert(x, from, to)
growth_convert(x, from, to)

Arguments

x

Numeric values.

from, to

Units (each of length 1 or the length of x).

Details

The calculation functions take values in the chart's own units only (growth_charts(): x_units, measure_units); convert before calling them.

Value

The values in to units.

Examples

growth_convert(c(30, 365), "days", "months")
growth_convert(7.5, "lb", "kg")

# Ages in days to the x of a chart in months
x_units <- growth_charts("cdc_2000_infant")$x_units[1]
growth_convert(c(14, 200, 400), "days", x_units)
growth_convert(c(30, 365), "days", "months")
growth_convert(7.5, "lb", "kg")

# Ages in days to the x of a chart in months
x_units <- growth_charts("cdc_2000_infant")$x_units[1]
growth_convert(c(14, 200, 400), "days", x_units)

Corrected age and postmenstrual age

Description

The corrected age (the age from the due date, 40 0/7 weeks) and the postmenstrual age (PMA: the gestational age at birth plus the age) of an infant born preterm, as PediTools calculates them: corrected age = age - (280 days - GA at birth), PMA = GA at birth + age.

Usage

growth_corrected_age(age_days, ga_weeks, ga_days = 0, units = "days")

growth_pma(age_days, ga_weeks, ga_days = 0, units = "weeks")
growth_corrected_age(age_days, ga_weeks, ga_days = 0, units = "days")

growth_pma(age_days, ga_weeks, ga_days = 0, units = "weeks")

Arguments

age_days

Chronological ages in days (e.g. from growth_age_days()).

ga_weeks, ga_days

The gestational age at birth: completed weeks and days (ga_days 0 to 6; default 0). A GA in days only can be given as ⁠ga_weeks = 0, ga_days = <days>⁠.

units

The units of the result: "days" (default for the corrected age) or "weeks" (default for the PMA, the x of the preterm charts), or "months", "years".

Details

Whether and until when to correct (e.g. to 2 years, and for which gestational ages) is a clinical convention left to you: the corrected age is calculated for any GA, and is negative before the due date.

Value

Numeric ages in units.

Examples

# Born at 28 3/7 weeks, 100 days old
growth_corrected_age(100, 28, 3)
growth_corrected_age(100, 28, 3, units = "months")
growth_pma(100, 28, 3)

# The x for Fenton 2013 from a GA at birth and a date
age <- growth_age_days("2026-01-05", "2026-02-20")
growth_pma(age, 26, 4)
# Born at 28 3/7 weeks, 100 days old
growth_corrected_age(100, 28, 3)
growth_corrected_age(100, 28, 3, units = "months")
growth_pma(100, 28, 3)

# The x for Fenton 2013 from a GA at birth and a date
age <- growth_age_days("2026-01-05", "2026-02-20")
growth_pma(age, 26, 4)

Percentile and Z-score curves

Description

The measurement at each percentile (or Z-score) along each chart's x, for plotting with any library: crossed over every chart, measure, sex, curve and x. The values are those of growth_y(), by the same methods. As on the website's charts, a curve breaks where the table steps (lying length to standing height), where the INTERGROWTH-21st parts change, and where a value is undefined (the segment column).

Usage

growth_curves(
  chart,
  measure,
  sex = NULL,
  p = c(0.03, 0.1, 0.5, 0.9, 0.97),
  z = NULL,
  labels = NULL,
  x = NULL,
  n = 300,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)
growth_curves(
  chart,
  measure,
  sex = NULL,
  p = c(0.03, 0.1, 0.5, 0.9, 0.97),
  z = NULL,
  labels = NULL,
  x = NULL,
  n = 300,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

Arguments

chart

Chart ids.

measure

Measures; NULL (default) for every measure of the charts. Every chart must have every measure given.

sex

"m", "f", "male" or "female"; NULL (default) for both. A table used for both sexes is always included (with sex NA).

p

Probabilities of the curves (the percentile / 100). Default: the 3rd, 10th, 50th, 90th and 97th percentiles.

z

Z-scores of the curves, instead of p.

labels

The curves' labels (the curve column): NULL (default) for "P3", "P50", ... (or "Z-2", "Z0", "Z+2", ...); a character vector with a label for each value of p (or z), in their order; or a function of p (or z) returning them, e.g. function(p) paste0(100 * p, "th"). Labels must be unique.

x

The x of the points, the same for every table; NULL (default): n + 1 points evenly over each table's coverage. Points outside the range allowed by extrapolate are NA.

n

The number of intervals of the default grid.

extrapolate

Which x are calculated: "coverage" (default) the chart's published coverage (x_min to x_max in growth_charts(), which may reach half a row step beyond the end rows of tables whose rows are band midpoints); "none" only between the table's first and last rows (for INTERGROWTH-21st charts, the coverage); "linear" any x, the parameters beyond the coverage on the line through the two end rows (for the INTERGROWTH-21st equations, the equations themselves). Outside: NA, with one warning per call.

sd23

NULL (default): WHO's restricted LMS method where the chart's authors prescribe it; TRUE: on every chart (beyond +-3 SD, the line whose spread is the distance between the 2 and 3 SD values of the chart's own distribution); FALSE: off.

cdc_bmi_ext

NULL (default) or TRUE: the CDC extended BMI method on cdc_2000_bmi (an error on any other chart with TRUE); FALSE: plain LMS.

Value

A data frame, one row per point: chart, measure, sex (NA for a table for both sexes), curve (a label: "P3", "P50", ... or "Z-2", "Z0", ...), p, z, x, y (NA where undefined or outside the allowed range), segment (a curve's pieces: a line connects only points of the same segment) and beyond_coverage (with extrapolate = "linear").

Examples

curves <- growth_curves("who_2006_infant", "weight", "f")
head(curves)

# Z-score lines at given ages, with labels of your own
growth_curves("cdc_2000_infant", "length", "m",
  z = -2:2, labels = c("-2 SD", "-1 SD", "median", "+1 SD", "+2 SD"), x = c(0, 12, 24)
)

# With base graphics
curves <- growth_curves("cdc_2000_bmi", "bmi", "m", p = c(0.05, 0.5, 0.85, 0.95))
plot(y ~ x, curves, type = "n", xlab = "age (months)", ylab = "BMI (kg/m2)")
for (k in split(curves, curves$curve)) lines(k$x, k$y)
curves <- growth_curves("who_2006_infant", "weight", "f")
head(curves)

# Z-score lines at given ages, with labels of your own
growth_curves("cdc_2000_infant", "length", "m",
  z = -2:2, labels = c("-2 SD", "-1 SD", "median", "+1 SD", "+2 SD"), x = c(0, 12, 24)
)

# With base graphics
curves <- growth_curves("cdc_2000_bmi", "bmi", "m", p = c(0.05, 0.5, 0.85, 0.95))
plot(y ~ x, curves, type = "n", xlab = "age (months)", ylab = "BMI (kg/m2)")
for (k in split(curves, curves$curve)) lines(k$x, k$y)

The version of the chart data

Description

The date and the commit of the last change to the PediTools parameter files the package's data were built from.

Usage

growth_data_version()
growth_data_version()

Value

A named character vector: date (YYYY-MM-DD) and commit.

Examples

growth_data_version()
growth_data_version()

Results in detail

Description

Everything about each value: the result, the parameters at x, the method applied and the status, for checking or studying how the methods behave. The arguments are those of growth_z() (a measurement y) or growth_y() (a Z-score z or a probability p); give exactly one of y, z, p. No warnings: the status says why a value is NA.

Usage

growth_detail(
  y = NULL,
  x,
  sex,
  chart,
  measure,
  z = NULL,
  p = NULL,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)
growth_detail(
  y = NULL,
  x,
  sex,
  chart,
  measure,
  z = NULL,
  p = NULL,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

Arguments

y

Measurements; or give z or p instead.

x

Ages, or lengths or heights for weight-for-length and weight-for-height, in the chart's x units (x_units in growth_charts(); to convert: growth_convert(), growth_age_days(), growth_pma(), growth_corrected_age()).

sex

"m", "f", "male" or "female", in any case; other values are NA (with a warning). Ignored for charts with one table for both sexes.

chart, measure

Chart and measure ids, as in growth_charts().

z

Z-scores.

p

Probabilities (the percentile / 100).

extrapolate

sd23

cdc_bmi_ext

NULL (default) or TRUE: the CDC extended BMI method on cdc_2000_bmi (an error on any other chart with TRUE); FALSE: plain LMS.

Value

A data frame, one row per element:

chart, measure, sex, x: The inputs (sex normalised to "m"/"f", NA for a chart with one table for both sexes).
y, z, p: The measurement, Z-score and probability: the one given as given, the others calculated.
method: "lms", "sd23" (the restricted method; also within +-3 SD, where it equals plain LMS) or "cdc_bmi_ext" (the CDC extended BMI method was used for this value).
status: "ok"; "missing" (an input is NA); "outside" (x outside the range allowed by extrapolate); "invalid" (a measurement not finite, or not positive on an LMS chart or an INTERGROWTH-21st equation on the log scale; an infinite Z; a probability not strictly between 0 and 1); "undefined" (the parameters or the method give no value there).
family, part, extrapolated, beyond_coverage: As in growth_params().
L, M, S, mu, sigma, nu, tau, y_scale: The parameters at x, as in growth_params().
p95, ext_sigma: On cdc_2000_bmi with the extended method: the BMI at the 95th percentile and the extension's sigma (NA otherwise), e.g. for the BMI as a percentage of P95.

Examples

growth_detail(c(3.5, 7.9, 12.5), 6, "m", "who_2006_infant", "weight")

# BMI as a percentage of the 95th percentile
d <- growth_detail(c(24, 30, 36), 150, "m", "cdc_2000_bmi", "bmi")
100 * d$y / d$p95
growth_detail(c(3.5, 7.9, 12.5), 6, "m", "who_2006_infant", "weight")

# BMI as a percentage of the 95th percentile
d <- growth_detail(c(24, 30, 36), 150, "m", "cdc_2000_bmi", "bmi")
100 * d$y / d$p95

A chart's equations

Description

The terms of the INTERGROWTH-21st equations, for the parts of a chart given by equations (family "normal" in growth_charts()), exactly as published (as in the gigs R package 0.5.2), for any number of charts, measures and sexes (crossed). Charts and parts given by tables are in growth_table().

Usage

growth_equations(chart, measure = NULL, sex = NULL)
growth_equations(chart, measure = NULL, sex = NULL)

Arguments

chart

Chart ids.

measure

Measures; NULL (default) for every measure of the charts. Every chart must have every measure given.

sex

"m", "f", "male" or "female"; NULL (default) for both. A table used for both sexes is always included (with sex NA).

Details

A parameter (param, mu or sigma) of the part starting at x_from is transform applied to the sum of its terms coef * t^power * log(t)^log_power, with t = x / x_scale; a term with male 1 applies to boys only. The distribution is normal on the y_scale of the measurement ("identity" or "log").

Value

A data frame with columns chart, measure, sex (NA: both sexes), x_from, param, coef, power, log_power, male, x_scale, transform, y_scale and model; no rows for charts given by tables.

Examples

growth_equations("intergrowth_png", "weight")
growth_equations("intergrowth_png", "weight")

The LMS method on your own parameters

Description

Z-scores of measurements, and measurements at Z-scores, from L, M and S given directly (e.g. from growth_params() or a table of your own), by the LMS method or WHO's restricted LMS method.

Usage

growth_lms_z(y, L, M, S, sd23 = FALSE)

growth_lms_y(z, L, M, S, sd23 = FALSE)
growth_lms_z(y, L, M, S, sd23 = FALSE)

growth_lms_y(z, L, M, S, sd23 = FALSE)

Arguments

y

Measurements (positive).

L, M, S

The LMS parameters (M and S positive).

sd23

TRUE for WHO's restricted LMS method; FALSE (default) for plain LMS.

z

Z-scores.

Details

The LMS method (Cole and Green 1992): $Z = ((y/M)^L - 1)/(L S)$ , or $\log(y/M)/S$ for $L = 0$ ; $y = M (1 + L S Z)^{1/L}$ , or $M e^{S Z}$ for $L = 0$ . The restricted method (WHO's "SD23") is the same within +-3 SD; beyond, the distribution is a straight line whose spread is the distance between the 2 and 3 SD values: $Z = 3 + (y - SD_3)/(SD_3 - SD_2)$ above, $-3 + (y - SD_{-3})/(SD_{-2} - SD_{-3})$ below.

Arguments are recycled: each has length 1 or the common length.

Value

A numeric vector: NA where the input is missing or not valid, or the value does not exist (e.g. $1 + L S Z \le 0$ ).

References

Cole TJ, Green PJ. Smoothing reference centile curves: the LMS method and penalized likelihood. Stat Med. 1992;11(10):1305-19.

WHO Multicentre Growth Reference Study Group. WHO 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; 2006 (chapter 7).

Examples

growth_lms_z(c(8.5, 10.2), L = -0.0757, M = 8.9014, S = 0.10846)
growth_lms_y(-2:2, L = -0.0757, M = 8.9014, S = 0.10846)

# Beyond +-3 SD the restricted method differs
growth_lms_z(14, L = -0.0757, M = 8.9014, S = 0.10846, sd23 = c(FALSE, TRUE))
growth_lms_z(c(8.5, 10.2), L = -0.0757, M = 8.9014, S = 0.10846)
growth_lms_y(-2:2, L = -0.0757, M = 8.9014, S = 0.10846)

# Beyond +-3 SD the restricted method differs
growth_lms_z(14, L = -0.0757, M = 8.9014, S = 0.10846, sd23 = c(FALSE, TRUE))

Parameters at any x

Description

A chart's parameters at each x: interpolated between the table's rows as for growth_z(), with the same extrapolate modes. Vectorised over every argument.

Usage

growth_params(x, sex, chart, measure, extrapolate = "coverage")
growth_params(x, sex, chart, measure, extrapolate = "coverage")

Arguments

x

sex

"m", "f", "male" or "female", in any case; other values are NA (with a warning). Ignored for charts with one table for both sexes.

chart, measure

Chart and measure ids, as in growth_charts().

extrapolate

Value

A data frame, one row per element: chart, measure, sex (NA for a chart with one table for both sexes), x, family (the chart's, as in growth_charts()), part (the distribution used at x: "lms", "st3" or "normal"), the parameters (L, M, S for LMS; mu, sigma, nu, tau for ST3; mu, sigma and y_scale for the INTERGROWTH-21st equations, where y_scale "log" means they are the mean and SD of log(y); only the columns of the families of the charts given), status ("ok", "missing", "outside" or "undefined"), extrapolated (the parameters are on the line beyond the end rows, or the equations beyond the coverage) and beyond_coverage (x is outside the published coverage, with extrapolate = "linear").

Examples

growth_params(c(9.5, 10, 10.5), "f", "cdc_2000_infant", "weight")

# Fenton 2003: published from 22 0/7 weeks, the first row at 22.5 weeks
growth_params(22.2, NA, "fenton_2003", "weight")
growth_params(c(9.5, 10, 10.5), "f", "cdc_2000_infant", "weight")

# Fenton 2003: published from 22 0/7 weeks, the first row at 22.5 weeks
growth_params(22.2, NA, "fenton_2003", "weight")

Plot growth charts with ggplot2

Description

Draws percentile (or Z-score) curves of one or more charts, optionally with measurements from a data frame, and returns a ggplot object (add + ggplot2::theme(...), + ggplot2::labs(...) and so on). Needs the ggplot2 package.

Usage

growth_plot(
  chart,
  measure,
  sex = NULL,
  data = NULL,
  x_col = NULL,
  y_col = NULL,
  id_col = NULL,
  sex_col = NULL,
  p = c(0.03, 0.1, 0.5, 0.9, 0.97),
  z = NULL,
  labels = NULL,
  xlim = NULL,
  n = 300,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)
growth_plot(
  chart,
  measure,
  sex = NULL,
  data = NULL,
  x_col = NULL,
  y_col = NULL,
  id_col = NULL,
  sex_col = NULL,
  p = c(0.03, 0.1, 0.5, 0.9, 0.97),
  z = NULL,
  labels = NULL,
  xlim = NULL,
  n = 300,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

Arguments

chart

Chart ids.

measure

Measures; NULL (default) for every measure of the charts. Every chart must have every measure given.

sex

"m", "f", "male" or "female"; NULL (default) for both. A table used for both sexes is always included (with sex NA).

data

A data frame of measurements to plot, or NULL.

x_col, y_col

The names of the columns of data with x and the measurement (see Details).

id_col

The name of a column of data identifying each person (their points are joined), or NULL.

sex_col

The name of a column of data with each point's sex ("m", "f", "male", "female"), or NULL: needed when both sexes are drawn.

p

Probabilities of the curves (the percentile / 100). Default: the 3rd, 10th, 50th, 90th and 97th percentiles.

z

Z-scores of the curves, instead of p.

labels

The labels at the right end of the curves: as in growth_curves() (NULL for "P3", ...; a label for each value of p or z; or a function of them), or FALSE for none.

xlim

The range of x to draw, or NULL for each chart's coverage.

n

The number of intervals of the default grid.

extrapolate

sd23, cdc_bmi_ext

As in growth_z(); c(FALSE, TRUE) draws both, to compare.

Details

Several measures are drawn one above the other, each with its own y axis; both sexes side by side.
Comparing charts or methods: several charts, or sd23 or cdc_bmi_ext given as c(FALSE, TRUE), are drawn in colours, one per chart and method. The charts compared must have the same x units.
Curves beyond the published coverage (with extrapolate = "linear") are dashed.
Measurements: data with the x and y columns named by x_col and y_col (for several measures, y_col names a column per measure: c(weight = "wt", length = "len")), in the charts' units. id_col joins each person's points by a line; sex_col puts each point on its sex's chart when both sexes are drawn.

Value

A ggplot object.

Examples


growth_plot("who_2006_infant", "weight", "f")

# A child's measurements, on weight and length
d <- data.frame(
  age = c(1, 3, 6, 9, 12), wt = c(4.1, 5.6, 7.0, 7.9, 8.6),
  len = c(54, 60, 65.5, 70, 74)
)
growth_plot("who_2006_infant", c("weight", "length"), "f",
  data = d, x_col = "age",
  y_col = c(weight = "wt", length = "len")
)

# CDC and WHO compared, Z-score lines
growth_plot(c("cdc_2000_infant", "who_2006_infant"), "weight", "m",
  z = c(-2, 0, 2), xlim = c(0, 24)
)

# Labels of your own, or none
growth_plot("who_2006_infant", "length", "m",
  p = c(0.03, 0.5, 0.97), labels = function(p) paste0(100 * p, "th")
)
growth_plot("who_2006_infant", "length", "m", labels = FALSE)

# WHO's restricted method beyond +-3 SD, on and off
growth_plot("who_2006_infant", "weight", "m", z = c(-4, -3, 3, 4), sd23 = c(FALSE, TRUE))

growth_plot("who_2006_infant", "weight", "f")

# A child's measurements, on weight and length
d <- data.frame(
  age = c(1, 3, 6, 9, 12), wt = c(4.1, 5.6, 7.0, 7.9, 8.6),
  len = c(54, 60, 65.5, 70, 74)
)
growth_plot("who_2006_infant", c("weight", "length"), "f",
  data = d, x_col = "age",
  y_col = c(weight = "wt", length = "len")
)

# CDC and WHO compared, Z-score lines
growth_plot(c("cdc_2000_infant", "who_2006_infant"), "weight", "m",
  z = c(-2, 0, 2), xlim = c(0, 24)
)

# Labels of your own, or none
growth_plot("who_2006_infant", "length", "m",
  p = c(0.03, 0.5, 0.97), labels = function(p) paste0(100 * p, "th")
)
growth_plot("who_2006_infant", "length", "m", labels = FALSE)

# WHO's restricted method beyond +-3 SD, on and off
growth_plot("who_2006_infant", "weight", "m", z = c(-4, -3, 3, 4), sd23 = c(FALSE, TRUE))

The publications behind each chart

Description

Each chart and measure's references, as on the PediTools Sources and methods page: the chart's publication, a separate source of its parameters, the source of its Z-score method, and more information.

Usage

growth_references(chart = NULL, measure = NULL)
growth_references(chart = NULL, measure = NULL)

Arguments

chart

Chart ids; NULL (default) for all.

measure

Measures; NULL (default) for every measure of the charts.

Value

A data frame, one row per chart, measure and reference, with columns:

chart, measure: The chart and measure.
role: "clinical" (the chart's publication), "lms_data" (a separate source of the parameters), "method" (the source prescribing its Z-score method) or "resource" (more information, the charts).
position: The order within the role.
id, short, citation: The reference's id, a short form and the full citation.
doi, pmid: Its DOI and PubMed id (NA when it has none).
url: Its PubMed page, or its web address.
sources_url: The chart's section of the PediTools Sources and methods page, where its sources and methods are described in full.

Examples

growth_references("who_2006_infant", "weight")[c("role", "short", "url")]
growth_references("who_2006_infant", "weight")[c("role", "short", "url")]

Remove added charts

Description

Removes charts added with growth_add_chart() in this session; a built-in chart they replaced is available again.

Usage

growth_remove_chart(chart)
growth_remove_chart(chart)

Arguments

chart

Chart ids added in the session.

Value

The ids removed, invisibly.

Examples

my <- growth_table("cdc_2000_infant", "weight", "f")[1:12, ]
my$chart <- "my_infant_chart"
growth_add_chart(my, data.frame(chart = "my_infant_chart", x_units = "months"))
growth_remove_chart("my_infant_chart")
my <- growth_table("cdc_2000_infant", "weight", "f")[1:12, ]
my$chart <- "my_infant_chart"
growth_add_chart(my, data.frame(chart = "my_infant_chart", x_units = "months"))
growth_remove_chart("my_infant_chart")

The ST3 distribution on your own parameters

Description

Z-scores of measurements, and measurements at Z-scores, by the skew t distribution "ST3" of the R package gamlss.dist (the INTERGROWTH-21st newborn size standards from 33+0 weeks), from mu, sigma, nu and tau given directly (e.g. from growth_params()).

Usage

growth_st3_z(y, mu, sigma, nu, tau)

growth_st3_y(z, mu, sigma, nu, tau)
growth_st3_z(y, mu, sigma, nu, tau)

growth_st3_y(z, mu, sigma, nu, tau)

Arguments

y

Measurements.

mu, sigma, nu, tau

The ST3 parameters (sigma, nu and tau positive).

z

Z-scores.

Details

ST3 is a Student t with tau degrees of freedom, scaled by sigma/nu below mu and by sigma nu above it: with T the t distribution function, $F(y) = 2 T(\nu (y - \mu)/\sigma)/(1 + \nu^2)$ for $y < \mu$ and $1 - F(y) = 2 \nu^2 (1 - T((y - \mu)/(\sigma \nu)))/(1 + \nu^2)$ for $y \ge \mu$ ; $Z = \Phi^{-1}(F(y))$ (from the smaller tail, so that Z stays accurate far into the tails). mu is not the median unless nu = 1.

Arguments are recycled: each has length 1 or the common length.

Value

A numeric vector; NA where an input is missing or not valid.

References

Rigby RA, Stasinopoulos DM, Heller GZ, De Bastiani F. Distributions for Modeling Location, Scale, and Shape: Using GAMLSS in R. Chapman and Hall/CRC; 2019.

Examples

# INTERGROWTH-21st newborn weight, boys, 231 days (33+0 weeks)
growth_st3_z(c(1.5, 2, 2.5), mu = 1.905973, sigma = 0.4027349, nu = 1.095261, tau = 17.05299)
growth_st3_y(c(-2, 0, 2), mu = 1.905973, sigma = 0.4027349, nu = 1.095261, tau = 17.05299)
# INTERGROWTH-21st newborn weight, boys, 231 days (33+0 weeks)
growth_st3_z(c(1.5, 2, 2.5), mu = 1.905973, sigma = 0.4027349, nu = 1.095261, tau = 17.05299)
growth_st3_y(c(-2, 0, 2), mu = 1.905973, sigma = 0.4027349, nu = 1.095261, tau = 17.05299)

A chart's parameter table

Description

The rows of the LMS tables (L, M, S) and of the INTERGROWTH-21st ST3 tables (mu, sigma, nu, tau), exactly as published, for any number of charts, measures and sexes (crossed). x and the measurement are in the units given by growth_charts(). Charts given by equations instead (the INTERGROWTH-21st "normal" parts) are in growth_equations().

Usage

growth_table(chart, measure = NULL, sex = NULL)
growth_table(chart, measure = NULL, sex = NULL)

Arguments

chart

Chart ids.

measure

Measures; NULL (default) for every measure of the charts. Every chart must have every measure given.

sex

"m", "f", "male" or "female"; NULL (default) for both. A table used for both sexes is always included (with sex NA).

Value

A data frame with columns chart, measure, sex (NA: both sexes), x, and the parameters: L, M, S for LMS tables, mu, sigma, nu, tau for ST3 tables (only the columns used by the rows returned).

Examples

head(growth_table("cdc_2000_infant", "weight", "f"))

# The ST3 rows of the INTERGROWTH-21st newborn size standards (from 231 days)
head(growth_table("intergrowth_nbs", "weight", "m"))
head(growth_table("cdc_2000_infant", "weight", "f"))

# The ST3 rows of the INTERGROWTH-21st newborn size standards (from 231 days)
head(growth_table("intergrowth_nbs", "weight", "m"))

Measurements at Z-scores or probabilities

Description

The measurement at each Z-score or probability on a chart: the inverse of growth_z() and growth_p(), by the same methods (the restricted LMS method beyond +-3 SD where it applies; on cdc_2000_bmi, from the 95th percentile, $BMI = P95 + \sigma \Phi^{-1}((p - 0.90)/0.10)$ ). Vectorised over every argument.

Usage

growth_y(
  z,
  x,
  sex,
  chart,
  measure,
  p = NULL,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)
growth_y(
  z,
  x,
  sex,
  chart,
  measure,
  p = NULL,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

Arguments

z

Z-scores. Give z or p, not both.

x

sex

"m", "f", "male" or "female", in any case; other values are NA (with a warning). Ignored for charts with one table for both sexes.

chart, measure

Chart and measure ids, as in growth_charts().

p

Probabilities (the percentile / 100), strictly between 0 and 1.

extrapolate

sd23

cdc_bmi_ext

NULL (default) or TRUE: the CDC extended BMI method on cdc_2000_bmi (an error on any other chart with TRUE); FALSE: plain LMS.

Value

A numeric vector of measurements in the chart's measure units; NA where an input is missing or not valid, x is outside the range allowed, or the method gives no value (e.g. the LMS curve has none at a very low Z when L > 0).

Examples

# The 3rd, 50th and 97th percentile weights of a girl of 9.5 months
growth_y(p = c(0.03, 0.5, 0.97), x = 9.5, sex = "f", chart = "cdc_2000_infant", measure = "weight")

# Expected growth: the weight at 12 months at the same Z-score as 8.2 kg at 9.5 months
z <- growth_z(8.2, 9.5, "f", "cdc_2000_infant", "weight")
growth_y(z, 12, "f", "cdc_2000_infant", "weight")
# The 3rd, 50th and 97th percentile weights of a girl of 9.5 months
growth_y(p = c(0.03, 0.5, 0.97), x = 9.5, sex = "f", chart = "cdc_2000_infant", measure = "weight")

# Expected growth: the weight at 12 months at the same Z-score as 8.2 kg at 9.5 months
z <- growth_z(8.2, 9.5, "f", "cdc_2000_infant", "weight")
growth_y(z, 12, "f", "cdc_2000_infant", "weight")

Z-scores and probabilities of measurements

Description

The Z-score (growth_z()) or the probability (growth_p(), the percentile / 100) of each measurement on a chart, by the chart's published method unless switched. Vectorised over every argument.

Usage

growth_z(
  y,
  x,
  sex,
  chart,
  measure,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

growth_p(
  y,
  x,
  sex,
  chart,
  measure,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)
growth_z(
  y,
  x,
  sex,
  chart,
  measure,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

growth_p(
  y,
  x,
  sex,
  chart,
  measure,
  extrapolate = "coverage",
  sd23 = NULL,
  cdc_bmi_ext = NULL
)

Arguments

y

Measurements, in the chart's measure units (measure_units in growth_charts()); positive on LMS charts and the INTERGROWTH-21st equations on the log scale.

x

sex

"m", "f", "male" or "female", in any case; other values are NA (with a warning). Ignored for charts with one table for both sexes.

chart, measure

Chart and measure ids, as in growth_charts().

extrapolate

sd23

cdc_bmi_ext

NULL (default) or TRUE: the CDC extended BMI method on cdc_2000_bmi (an error on any other chart with TRUE); FALSE: plain LMS.

Details

The parameters at x are interpolated linearly between the rows of the chart's table (never across its step, x_break in growth_charts()). Methods:

LMS (Cole and Green): every LMS chart.
WHO's restricted LMS method beyond +-3 SD ("SD23"): the charts whose authors prescribe it (z_method "sd23" in growth_charts()); sd23 = TRUE applies it to any LMS chart, FALSE turns it off.
CDC's extended BMI method at or above the 95th percentile of cdc_2000_bmi (CDC's recommendation, on by default): the probability is $0.90 + 0.10 \Phi((BMI - P95)/\sigma)$ , with $\sigma = 0.3728 + 0.5196 a - 0.0091 a^2$ (boys) or $0.8334 + 0.3712 a - 0.0011 a^2$ (girls), a the age in years, and $Z = \Phi^{-1}(p)$ . cdc_bmi_ext = FALSE gives the plain LMS values.
INTERGROWTH-21st (z_method "cdf"): $Z = \Phi^{-1}(F(y))$ from the distribution of the part used at x: the ST3 skew t (growth_st3_z()) or a normal distribution whose mean and SD are equations in x (of log(y) when y_scale is "log"). Newborn size uses the very preterm equations before 231 days and the ST3 table from 231 days; the parts are never mixed. sd23 = TRUE applies WHO's restricted method to these too.

Value

A numeric vector, as long as the longest argument (each has length 1 or that length). NA where an input is missing or not valid, or x is outside the range allowed by extrapolate (see growth_detail() for why).

Examples

# Weight 8.2 kg of a girl of 9.5 months, CDC 2000 infant chart
growth_z(8.2, 9.5, "f", "cdc_2000_infant", "weight")
growth_p(8.2, 9.5, "f", "cdc_2000_infant", "weight")

# Vectorised: one call for a data frame
d <- data.frame(wt = c(7.1, 9.8, 12.4), age = c(6, 12, 24), sex = c("m", "f", "m"))
growth_z(d$wt, d$age, d$sex, "who_2006_infant", "weight")

# WHO's restricted method beyond +-3 SD, and plain LMS
growth_z(3.5, 6, "m", "who_2006_infant", "weight")
growth_z(3.5, 6, "m", "who_2006_infant", "weight", sd23 = FALSE)

# CDC extended BMI above the 95th percentile (age in months)
growth_z(30, 150, "m", "cdc_2000_bmi", "bmi")
growth_z(30, 150, "m", "cdc_2000_bmi", "bmi", cdc_bmi_ext = FALSE)
# Weight 8.2 kg of a girl of 9.5 months, CDC 2000 infant chart
growth_z(8.2, 9.5, "f", "cdc_2000_infant", "weight")
growth_p(8.2, 9.5, "f", "cdc_2000_infant", "weight")

# Vectorised: one call for a data frame
d <- data.frame(wt = c(7.1, 9.8, 12.4), age = c(6, 12, 24), sex = c("m", "f", "m"))
growth_z(d$wt, d$age, d$sex, "who_2006_infant", "weight")

# WHO's restricted method beyond +-3 SD, and plain LMS
growth_z(3.5, 6, "m", "who_2006_infant", "weight")
growth_z(3.5, 6, "m", "who_2006_infant", "weight", sd23 = FALSE)

# CDC extended BMI above the 95th percentile (age in months)
growth_z(30, 150, "m", "cdc_2000_bmi", "bmi")
growth_z(30, 150, "m", "cdc_2000_bmi", "bmi", cdc_bmi_ext = FALSE)

Package 'peditools2'

Help Index

Add your own charts for the session

Description

Usage

Arguments

Details

Value

See Also

Examples

Age in days between dates

Description

Usage

Arguments

Value

Examples

The available charts

Description

Usage

Arguments

Value

See Also

Examples

Convert units

Description

Usage

Arguments

Details

Value

Examples

Corrected age and postmenstrual age

Description

Usage

Arguments

Details

Value

Examples

Percentile and Z-score curves

Description

Usage

Arguments

Value

See Also

Examples

The version of the chart data

Description

Usage

Value

Examples

Results in detail

Description

Usage

Arguments

Value

Examples

A chart's equations

Description

Usage

Arguments

Details

Value

Examples

The LMS method on your own parameters

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Parameters at any x

Description

Usage

Arguments

Value

See Also

Examples

Plot growth charts with ggplot2

Description